Krypto-Wallet- und Adress-Screening-API (KYT)

Das Krypto-Wallet-Screening von Didit, auch Adress-Screening oder KYT (Know Your Transaction) genannt, prüft die Adressen und Transaktions-Hashes jedes Krypto-Transfers auf AML-Risiken und liefert einen Risiko-Score, die Exposition gegenüber riskanten Quellen und etwaige Sanktionstreffer. Für Kryptotransaktionen kann Didit Adressen und Transaktions-Hashes während der Transaktionserstellung gegen Anbieter für Blockchain-Analyse wie Merkle Science, Crystal, Chainalysis, Elliptic und TRM Labs prüfen. Das Screening läuft serverseitig; zusätzliche API-Aufrufe von Ihrer Seite sind nicht erforderlich.

Möchten Sie eine Adresse ohne Transaktion screenen? Verwenden Sie den On-Demand-Wallet-Screening-Endpoint (POST /v3/wallet-screening/), um mit einem einzigen API-Aufruf dasselbe Risikoergebnis für eine einzelne Wallet zu erhalten.

Wie das Screening ausgelöst wird

Das Krypto-Screening läuft automatisch, wenn beide Bedingungen erfüllt sind:

Die Transaktion hat currency_kind: "crypto" in ihren Transaktionsdetails
Die Transaktionsüberwachung ist in Ihren Anwendungseinstellungen aktiviert

Sie können diesen Standardwert pro Transaktion mit include_crypto_screening im Payload der Transaktionserstellung überschreiben:

Wert	Verhalten
`true`	Krypto-Screening ausführen, auch wenn der Standardwert auf Anwendungsebene deaktiviert ist
`false`	Krypto-Screening überspringen, auch wenn der Standardwert auf Anwendungsebene aktiviert ist
weggelassen oder `null`	Den in der Console konfigurierten Standardwert auf Anwendungsebene verwenden

Der Standardwert auf Anwendungsebene befindet sich in der Business Console unter Transaktionen > Einstellungen. include_crypto_screening überschreibt diesen Standardwert nur für die einzelne Transaktion, die Sie gerade erstellen.

Asset- und Netzwerkauswahl

Asset und Netzwerk sind getrennte Felder. Setzen Sie transaction_details.currency auf das Token-Symbol, transaction_details.currency_kind auf crypto und transaction_details.crypto_params.crypto_chain auf das Netzwerk. Das folgende Fragment erfasst beispielsweise einen benutzerdefinierten Token auf Base:

{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}

Das verwaltete Screening akzeptiert BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM und HBAR. BASE steht für Base, OP für Optimism, ARB für Arbitrum One, AVAX für Avalanche C-Chain, ADA für Cardano, XLM für Stellar und HBAR für Hedera. Gängige Netzwerknamen werden ebenfalls akzeptiert, zum Beispiel POLYGON oder POL für MATIC, BSC für BNB und TRON für TRX. Celo, Mode und Plume werden von der verwalteten Integration nicht abgedeckt; ihr Screening erfolgt über ein verbundenes TRM-Labs-Konto (CELO, MODE, PLUME). Verbundene Anbieter haben ihre eigene Abdeckung; für Lightning gelten unten zusätzliche Anforderungen. Geben Sie für einen Token immer crypto_chain an, auch für USDT und USDC. Ohne diese Angabe wird die Währung als Netzwerk verwendet; USDT und USDC beziehen ihr Netzwerk aus dem Transaktions-Hash oder, ohne Hash, aus der Adresse. Ein Tron- oder Solana-Hash wählt Tron bzw. Solana aus. Ein 0x-Hash sieht in jedem EVM-Netzwerk gleich aus. Daher sucht Didit bei USDT, USDC und ETH auf Ethereum, BNB Chain, Polygon, Base, Arbitrum und Optimism danach und führt das Screening der Transaktion auf dem Netzwerk durch, in dem sie gefunden wird. ETH ist enthalten, weil es auf Ethereum, Base, Arbitrum und Optimism nativ ist und auf der BNB Chain zusätzlich als gebrückter BEP-20-Token übertragen wird. Wenn kein Netzwerk den Hash enthält oder die Netzwerke in diesem Moment nicht geprüft werden können, wird die Transaktion nicht gescreent und das Screening nicht berechnet. Dann ist custom_values.aml_screening_status FAILED, custom_values.aml_screening_error gibt den Grund an, und eine genehmigte Transaktion wird in die Prüfung verschoben. Eine USDT- oder USDC-Transaktion ohne Hash wird als Wallet gescreent, und die Adresse bestimmt das Netzwerk. Eine Tron-Adresse wird auf Tron gescreent, eine Solana-Adresse auf Solana. Eine 0x-Adresse wird auf dem ersten der Netzwerke Ethereum, BNB Chain, Polygon, Base, Arbitrum und Optimism gescreent, auf dem sie eine Transaktion gesendet hat oder den Token hält. Eine 0x-Adresse ohne Aktivität auf allen diesen Netzwerken oder eine Adresse, deren Netzwerke in diesem Moment nicht geprüft werden können, wird auf Ethereum gescreent. Wenn Sie crypto_chain senden, entfällt die Suche. Verwenden Sie ETH niemals als Ersatz für das tatsächliche Netzwerk. Die Erfassung eines benutzerdefinierten Token-Symbols garantiert nicht, dass seine Transfers für das Screening anhand des Transaktions-Hashes indexiert sind. Die Abdeckung des Tokens muss anhand des Token-Vertrags und des Netzwerks geprüft werden. Eine angelegte Transaktion ist kein Nachweis für ein erfolgreiches Screening: Prüfen Sie den Screening-Status und das Ergebnis des Anbieters, bevor Sie die Transaktion als gescreent behandeln.

Eingehend vs. ausgehend

transaction_details.direction ist erforderlich, weil Didit damit festlegt, auf welcher Seite der Übertragung das Screening erfolgen soll.

Richtung	Vor der On-Chain-Übertragung	Nach der On-Chain-Übertragung
Eingehend (Einzahlungen)	Screening der Absender-Wallet der Gegenpartei, sofern Sie sie in `counterparty.payment_method.account_id` angeben	Screening des Transaktions-Hashs, bezogen auf die Einzahlungsadresse Ihres Dienstes oder Kunden in `subject.payment_method.account_id`
Ausgehend (Auszahlungen)	Screening der Ziel-Wallet in `counterparty.payment_method.account_id`, bevor Sie Gelder senden	Screening des Transaktions-Hashs für dieselbe Ziel-Wallet in `counterparty.payment_method.account_id`

Für das Screening vor der Übertragung lassen Sie transaction_details.payment_reference_id weg; Didit führt dann ein Wallet-Screening für die relevante Wallet-Adresse durch. Für das Screening nach der Übertragung geben Sie den Blockchain-Transaktions-Hash in transaction_details.payment_reference_id an; Didit führt dann ein Transaktions-Screening durch und speichert Daten zur Transaktionszusammenfassung, sofern die On-Chain-Anreicherung verfügbar ist.

Lightning-Netzwerk

Setzen Sie transaction_details.crypto_params.crypto_chain auf LIGHTNING, um ein Lightning-Netzwerk-Screening durchzuführen. Für das Lightning-Screening ist ein verbundener API-Schlüssel des Anbieters von Elliptic oder Chainalysis (BYOK) in der Konsole unter Marketplace erforderlich. Die verwalteten Dienste von Merkle Science, Crystal und TRM Labs akzeptieren LIGHTNING nicht; Didit lehnt solche Anfragen mit 400 ab, bevor ein Screening erfolgt oder eine Abrechnung stattfindet. Bei Elliptic prüft Didit die übermittelte Lightning-Kennung über die BTC-Lightning-Wallet-Analyse von Elliptic. Bei Chainalysis übermittelt Didit eine Lightning-Übertragung an KYT, sofern transaction_details.payment_reference_id vorhanden ist.

Pflichtfelder

Für alle Krypto-Screening-Anfragen senden Sie:

transaction_details.direction: INBOUND oder OUTBOUND
transaction_details.currency_kind: crypto
transaction_details.currency: das Asset-Symbol, zum Beispiel BTC, ETH, USDC oder Ihr eigenes Token
Eine Wallet-Adresse des Teilnehmers, der nach den obigen Richtungsregeln ausgewählt wird

Für das Transaktions-Hash-Screening, nachdem die Übertragung On-Chain erfolgt ist, senden Sie außerdem:

transaction_details.payment_reference_id: der Blockchain-Transaktions-Hash

Wenn das Krypto-Screening aktiviert ist und die für die Richtung erforderliche Wallet-Adresse fehlt, lehnt die Create-Transaction-API die Anfrage ab.

Beispiel: ausgehendes Screening vor der Übertragung

Erstellen Sie vor dem Senden von Geldern eine ausgehende Krypto-Transaktion ohne Transaktions-Hash. Didit führt das Screening der Ziel-Wallet durch.

{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}

Beispiel: eingehendes Screening nach der Übertragung

Geben Sie nach Eingang der Gelder den Transaktions-Hash an. Didit führt das Screening des Transaktions-Hashs, bezogen auf Ihre Einzahlungsadresse, durch und reichert die Antwort, sofern verfügbar, mit Informationen zur Transaktionszusammenfassung an.

{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}

Unterstützte Anbieter

Anbieter	Status	Preise für verwaltete Anbieter	Preise für verbundene Schlüssel
Merkle Science	Verfügbar	$0.15/Screening	$0.02/Screening
Crystal	API-Schlüssel des Anbieters über den Marketplace verbinden	Nicht verfügbar	$0.02/Screening
Chainalysis	API-Schlüssel des Anbieters über den Marketplace verbinden	Nicht verfügbar	$0.02/Screening
Elliptic	API-Schlüssel des Anbieters über den Marketplace verbinden	Nicht verfügbar	$0.02/Screening
TRM Labs	API-Schlüssel des Anbieters über den Marketplace verbinden	Nicht verfügbar	$0.02/Screening

Konfigurieren Sie Ihren bevorzugten Anbieter unter Transaktionen > Einstellungen > Provider Preferences in der Business Console oder verbinden Sie Ihren eigenen API-Schlüssel des Anbieters über den Marketplace (Kategorie für Kryptoüberwachung). LIGHTNING wird nur mit Konfigurationen mit verbundenem Schlüssel von Chainalysis und Elliptic unterstützt.

Bei Preisen für verbundene Schlüssel verbinden Sie einen bestehenden API-Schlüssel des Anbieters und zahlen die aufgeführte Infrastrukturgebühr pro Screening. Nutzen Sie diese Option, wenn Sie bereits eine kommerzielle Vereinbarung mit einem Anbieter für Blockchain-Analysen haben.

Screening-Ergebnisse

Jedes Screening liefert unabhängig vom verwendeten Anbieter ein standardisiertes Ergebnis.

Screening-Status

custom_values.aml_screening_status zeigt an, ob eine Transaktion geprüft wurde.

Wert	Bedeutung
`COMPLETED`	Das Screening ist abgeschlossen. Das Ergebnis steht in `provider_results` und in den übrigen Screening-Feldern unter `custom_values`.
`PENDING`	Das Screening ist noch nicht abgeschlossen: Der Anbieter analysiert die Transaktion noch, oder Didit prüft den Transaktions-Hash später erneut (siehe unten).
`ERROR`	Der Anbieter hat geantwortet, meldet aber, dass seine eigene Analyse fehlgeschlagen ist.
`FAILED`	Die Transaktion wurde nicht geprüft. `custom_values.aml_screening_error` nennt den Grund. Bei von Didit verwaltetem Screening wird dafür nichts berechnet. Eine Anfrage, die Ihr angebundener Anbieter beantwortet hat, zählt als Anbieteranfrage.

Eine Transaktion, die sonst genehmigt würde, wechselt zu IN_REVIEW, solange sich ihr Screening in einem anderen Status als COMPLETED befindet.

Transaktions-Hashes noch nicht indexiert

Ein Anbieter für Blockchain-Analysen kann einige Minuten brauchen, um eine gerade bestätigte Überweisung zu indexieren. Bis dahin kann er sie nicht prüfen. Antwortet der Anbieter, dass er einen Transaktions-Hash noch nicht indexiert hat, und bestätigt das Netzwerk selbst, dass die Transaktion existiert, prüft Didit den Hash im Hintergrund erneut, anstatt das Screening fehlschlagen zu lassen:

Die Antwort auf die Erstellung zeigt bereits custom_values.aml_screening_status als PENDING, den Grund in custom_values.aml_screening_error. Eine genehmigte Transaktion wird mit decision_reason_code aml_screening_pending auf IN_REVIEW gehalten.
Didit prüft den Transaktions-Hash etwa 2, 12 und 42 Minuten nach Erstellung der Transaktion erneut.
Wenn ein Wiederholungsversuch das Screening erfolgreich durchführt, wird das Ergebnis wie jedes andere Screening gespeichert, und das Screening wird einmal berechnet. Ihre Regeln werden erneut auf die Screening-Daten angewendet, die Sperre wird aufgehoben, und Sie erhalten einen Webhook transaction.status.updated mit dem Status, den die Transaktion nach den Regeln hat, unabhängig davon, ob er sich geändert hat. Eine Transaktion, die in der Zwischenzeit abgelehnt oder von einem Prüfer entschieden wurde, behält ihren Status.
Wenn der Anbieter den Transaktions-Hash nach dem letzten Versuch immer noch nicht indexiert hat, endet das Screening mit FAILED, wie es bei der Erstellung geendet hätte. Die Transaktion bleibt IN_REVIEW mit decision_reason_code aml_screening_failed. Sie wird wie ein Fehler bei der Erstellung berechnet: bei von Didit verwaltetem Screening nichts, bei einer Anbieteranfrage eine Anfrage, wenn der letzte Versuch Ihren angebundenen Anbieter erreicht hat. Die früheren, wiederholten Versuche werden nie berechnet.
Wenn Ihr Guthaben beim Ausführen eines erneuten Versuchs das Screening nicht mehr deckt, endet das Screening mit FAILED, und nichts wird berechnet.

Wiederholungen gelten für Transaktions-Hashes in den Netzwerken Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism und Tron. Ein Hash, den sein Netzwerk nicht kennt, oder ein Hash aus einem anderen Netzwerk wird nicht erneut geprüft: Das Screening schlägt sofort fehl.

Risiko-Score und Schweregrad

Jede geprüfte Wallet oder Transaktion erhält:

Risiko-Score (0–100): höhere Werte zeigen eine größere Risikoexposition gegenüber riskanten Entitäten an
Schweregradstufe: aus dem Wert abgeleitet: LOW, MEDIUM, HIGH oder CRITICAL

Analyse der Mittelherkunft

Eine prozentuale Aufschlüsselung, woher die Gelder stammen, kategorisiert nach Entitätstyp:

Kategorie	Risikostufe	Beschreibung
`SANCTIONED`	Kritisch	Entitäten auf internationalen Sanktionslisten (OFAC, EU, UN)
`TERRORIST_FINANCING`	Kritisch	Adressen, die mit Terrorismusfinanzierung in Verbindung stehen
`CHILD_EXPLOITATION`	Kritisch	Adressen, die mit Material zur Ausbeutung von Kindern in Verbindung stehen
`RANSOMWARE`	Hoch	Zahlungsadressen für Ransomware
`STOLEN_FUNDS`	Hoch	Adressen, die mit bekanntem Diebstahl oder Hacks in Verbindung stehen
`DARKNET_MARKET`	Hoch	Adressen von Darknet-Marktplätzen
`MIXER`	Hoch	Mixing- oder Tumbling-Dienste, die zur Verschleierung der Mittelherkunft genutzt werden
`SCAM`	Hoch	Bekannte Betrugs- oder Scam-Adressen
`HIGH_RISK_EXCHANGE`	Mittel	Börsen mit schwachen KYC/AML-Kontrollen
`HIGH_RISK_JURISDICTION`	Mittel	Entitäten in FATF-gelisteten Hochrisikojurisdiktionen
`GAMBLING_UNLICENSED`	Mittel	Nicht lizenzierte Glücksspielplattformen
`P2P_EXCHANGE`	Niedrig	Peer-to-Peer-Austauschdienste
`EXCHANGE`	Niedrig	Regulierte Kryptowährungsbörsen
`UNNAMED_SERVICE`	Niedrig	Nicht identifizierte Dienste

Jede Entität in der Aufschlüsselung enthält den Prozentsatz der Gelder, die empfangenen und gesendeten Beträge sowie die Angabe, ob die Verbindung direkt oder indirekt ist.

Exposure-Tabelle

Eine Exposure-Tabelle mit Quell-, Ziel- und Gegenparteientitäten, die Folgendes enthält:

Name und Kategorie der Entität
Direkte vs. indirekte Verbindung (Hop-Distanz)
Empfangene und gesendete Beträge
Risikostufe je Entität

Netzwerkgraph

Eine visuelle Knoten-Kanten-Darstellung der Transaktionsbeziehungen der Wallet:

Knoten stellen Wallets, Börsen, Dienste und andere Entitäten dar
Kanten stellen Transaktionen zwischen Knoten dar, mit Beträgen und Transaktions-Hashes
Kennzahlen umfassen graphbezogene Statistiken wie Zentralität und Tiefe

Der Netzwerkgraph ist in der Business Console als interaktive Visualisierung verfügbar.

Integration in die Regeln

Screening-Ergebnisse fließen direkt in die Regel-Engine. Didit enthält vordefinierte Regeln, die auf Basis der Screening-Daten automatisch ausgelöst werden:

Vordefinierte Regel	Aktion
Sanctions counterparty	Sofortige Ablehnung - das geprüfte Wallet selbst wird einer sanktionierten Stelle zugeordnet (`custom_values.wallet_sanctioned`)
Sanktionsexposition	Score hinzufügen + zur Prüfung markieren - das Wallet hat Geld von sanktionierten Stellen empfangen oder an sie gesendet, ist selbst aber nicht sanktioniert (`sanctions_hit` gleich true, `wallet_sanctioned` nicht true)
Terrorist financing / child exploitation	Sofortige Ablehnung
Darknet market exposure	Score hinzufügen + zur Prüfung markieren
Mixer/obfuscation service exposure	Score hinzufügen + zur Prüfung markieren
High-risk source of funds (>30%)	Score hinzufügen + zur Prüfung markieren
Multiple risky counterparties	Score hinzufügen + zur Prüfung markieren
Medium wallet risk score	Score hinzufügen + zur Prüfung markieren
Prüfung ausstehend	Transaktion anhalten, bis das Screening abgeschlossen ist

Screening-Felder für Regeln

Das Crypto-Screening schreibt die folgenden Schlüssel in die custom_values der Transaktion, damit Regeln sie als custom_values.<key> verwenden können:

Feld	Typ	Beschreibung
`sanctions_hit`	boolean	`true`, wenn das Wallet selbst sanktioniert ist oder wenn Gelder einer seiner Gegenparteien von sanktionierten Stellen stammen (Exposition). Große Börsen sind häufig allein aufgrund von Exposition `true`.
`wallet_sanctioned`	boolean	`true` nur dann, wenn der Screening-Anbieter das geprüfte Wallet selbst einer sanktionierten Stelle zuordnet (Benennungen durch OFAC, EU, UN oder HMT). Exposition allein setzt diesen Wert nie.
`aml_sanctions_exposure_pct`	number (0-100)	Anteil des geprüften Volumens des Wallets, das mit sanktionierten Stellen in Berührung kam. Er wird wie `aml_high_risk_exposure_pct` berechnet, jedoch auf Sanktionen beschränkt.

Verwenden Sie wallet_sanctioned, um Transfers an ein sanktioniertes Wallet zu blockieren, ohne Transfers an große Börsen abzulehnen, die nur indirekte Exposition aufweisen. Verwenden Sie sanctions_hit oder aml_sanctions_exposure_pct, um Exposition zu prüfen oder zu bewerten. Die vordefinierte Regel Sanctions counterparty lehnt ab, wenn wallet_sanctioned gleich true ist. Die vordefinierte Regel Sanktionsexposition leitet Wallets, die nur Exposition aufweisen, zur Prüfung weiter. Beide Regeln treffen nie auf dieselbe Transaktion zu, sodass ein sanktioniertes Wallet immer abgelehnt wird. Falls Sie Sanctions counterparty vor dieser Änderung installiert haben, hat Didit die Regel für Sie auf wallet_sanctioned umgestellt und Sanktionsexposition im selben Modus hinzugefügt. Eine Transaktion, die die alte Regel allein wegen Exposition abgelehnt hat, wird daher nun zur Prüfung weitergeleitet. Nachdem das Screening abgeschlossen ist, bewertet Didit alle Regeln automatisch erneut anhand der angereicherten Transaktionsdaten und löst alle zutreffenden Webhooks aus.

Nächste Schritte

Transaktionen einreichen

So reichen Sie Transaktionen einschließlich der Krypto-Wallet-Details ein.

Regeln & Scoring

So fließen Screening-Ergebnisse in die Regel-Engine ein.

Konsolenanleitung

Krypto-Screening-Analyse, Mittelherkunft und Netzwerkgraphen in der Konsole einsehen.

Erste Schritte

Funktionen

Referenz

Konsole

Krypto-Wallet- und Adress-Screening-API (KYT)

Wie das Screening ausgelöst wird

Asset- und Netzwerkauswahl

Eingehend vs. ausgehend

Lightning-Netzwerk

Pflichtfelder

Beispiel: ausgehendes Screening vor der Übertragung

Beispiel: eingehendes Screening nach der Übertragung

Unterstützte Anbieter

Screening-Ergebnisse

Screening-Status

Transaktions-Hashes noch nicht indexiert

Risiko-Score und Schweregrad

Analyse der Mittelherkunft

Exposure-Tabelle

Netzwerkgraph

Integration in die Regeln

Screening-Felder für Regeln

Nächste Schritte

Transaktionen einreichen

Regeln & Scoring

Konsolenanleitung

​Wie das Screening ausgelöst wird

​Asset- und Netzwerkauswahl

​Eingehend vs. ausgehend

​Lightning-Netzwerk

​Pflichtfelder

​Beispiel: ausgehendes Screening vor der Übertragung

​Beispiel: eingehendes Screening nach der Übertragung

​Unterstützte Anbieter

​Screening-Ergebnisse

​Screening-Status

​Transaktions-Hashes noch nicht indexiert

​Risiko-Score und Schweregrad

​Analyse der Mittelherkunft

​Exposure-Tabelle

​Netzwerkgraph

​Integration in die Regeln

​Screening-Felder für Regeln

​Nächste Schritte

Transaktionen einreichen

Regeln & Scoring

Konsolenanleitung

Wie das Screening ausgelöst wird

Asset- und Netzwerkauswahl

Eingehend vs. ausgehend

Lightning-Netzwerk

Pflichtfelder

Beispiel: ausgehendes Screening vor der Übertragung

Beispiel: eingehendes Screening nach der Übertragung

Unterstützte Anbieter

Screening-Ergebnisse

Screening-Status

Transaktions-Hashes noch nicht indexiert

Risiko-Score und Schweregrad

Analyse der Mittelherkunft

Exposure-Tabelle

Netzwerkgraph

Integration in die Regeln

Screening-Felder für Regeln

Nächste Schritte