Filtrage des portefeuilles crypto et adresses : API KYT

Le filtrage des portefeuilles crypto de Didit, aussi appelé filtrage d’adresses ou KYT (know your transaction), contrôle les adresses de portefeuilles et les hash de transaction de chaque transfert de cryptomonnaie pour détecter un risque AML. Il renvoie un score de risque, l’exposition à des sources à risque et les correspondances de sanctions éventuelles. Pour les transactions en cryptomonnaies, Didit peut filtrer les adresses de portefeuilles et les hash de transaction auprès de fournisseurs d’analyse de blockchain tels que Merkle Science, Crystal, Chainalysis, Elliptic et TRM Labs, lors de la création de la transaction. Le filtrage s’exécute côté serveur : aucun appel d’API supplémentaire n’est nécessaire de votre part.

Vous souhaitez filtrer une adresse sans transaction ? Utilisez l’endpoint filtrage des portefeuilles à la demande (POST /v3/wallet-screening/) pour obtenir le même résultat de risque pour un seul portefeuille, en un seul appel d’API.

Déclenchement du filtrage

Le filtrage crypto s’exécute automatiquement lorsque les deux conditions suivantes sont remplies :

La transaction contient currency_kind: "crypto" dans ses détails de transaction
La surveillance des transactions est activée dans vos paramètres d’application

Vous pouvez remplacer cette valeur par défaut pour chaque transaction avec include_crypto_screening dans le payload de création de transaction :

Valeur	Comportement
`true`	Exécuter le filtrage crypto même si la valeur par défaut au niveau de l’application est désactivée
`false`	Ignorer le filtrage crypto même si la valeur par défaut au niveau de l’application est activée
omis ou `null`	Utiliser la valeur par défaut au niveau de l’application configurée dans la Console

La valeur par défaut au niveau de l’application se trouve dans Transactions > Paramètres dans la Business Console. include_crypto_screening ne remplace cette valeur par défaut que pour la seule transaction que vous créez.

Sélection de l’actif et du réseau

L’actif et le réseau sont deux champs distincts. Renseignez transaction_details.currency avec le symbole du token, transaction_details.currency_kind avec crypto, et transaction_details.crypto_params.crypto_chain avec le réseau. Par exemple, ce fragment enregistre un token personnalisé sur Base :

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

Le filtrage géré accepte BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM et HBAR. BASE désigne Base, OP désigne Optimism, ARB désigne Arbitrum One, AVAX désigne Avalanche C-Chain, ADA désigne Cardano, XLM désigne Stellar et HBAR désigne Hedera. Les noms de réseaux courants sont acceptés également, par exemple POLYGON ou POL pour MATIC, BSC pour BNB et TRON pour TRX. Celo, Mode et Plume ne sont pas couverts par l’intégration gérée : ils sont filtrés via un compte TRM Labs connecté (CELO, MODE, PLUME). La couverture des fournisseurs connectés dépend de chacun d’eux ; Lightning a des exigences supplémentaires décrites plus bas. Indiquez toujours crypto_chain pour un token, y compris USDT et USDC. Sans lui, la devise est utilisée comme réseau, et USDT et USDC tirent leur réseau du hash de transaction ou, à défaut de hash, de l’adresse du portefeuille. Un hash Tron ou Solana sélectionne Tron ou Solana. Un hash 0x a la même forme sur tous les réseaux EVM : pour USDT, USDC et ETH, Didit le recherche donc sur Ethereum, BNB Chain, Polygon, Base, Arbitrum et Optimism, puis filtre la transaction sur le réseau où il est trouvé. ETH est inclus car il est natif sur Ethereum, Base, Arbitrum et Optimism, et il est aussi transféré sur BNB Chain sous forme de jeton BEP-20 ponté. Si aucun réseau ne contient le hash, ou si les réseaux ne peuvent pas être vérifiés à ce moment-là, la transaction n’est pas filtrée et le filtrage n’est pas facturé. custom_values.aml_screening_status vaut alors FAILED, custom_values.aml_screening_error indique la raison, et une transaction approuvée passe en examen. Une transaction USDT ou USDC sans hash filtre un portefeuille, et l’adresse du portefeuille sélectionne le réseau. Une adresse Tron est filtrée sur Tron et une adresse Solana sur Solana. Une adresse 0x est filtrée sur le premier réseau, parmi Ethereum, BNB Chain, Polygon, Base, Arbitrum et Optimism, où elle a envoyé une transaction ou détient le token. Une adresse 0x sans activité sur aucun de ces réseaux, ou dont les réseaux ne peuvent pas être vérifiés à ce moment-là, est filtrée sur Ethereum. Envoyer crypto_chain évite cette recherche. Ne remplacez jamais le réseau réel par ETH. Enregistrer un symbole de token personnalisé ne garantit pas que ses transferts sont indexés pour le filtrage par hash de transaction. La couverture d’un token doit être vérifiée à partir de son contrat et du réseau. Une transaction créée ne prouve pas un filtrage réussi : vérifiez le statut du filtrage et le résultat du fournisseur avant de considérer la transaction comme filtrée.

Entrant ou sortant

transaction_details.direction est obligatoire, car il indique à Didit quel côté du transfert doit faire l’objet du filtrage.

Sens	Avant le transfert on-chain	Après le transfert on-chain
Entrant (dépôts)	Filtrer le portefeuille de l’expéditeur (contrepartie), si vous le fournissez dans `counterparty.payment_method.account_id`	Filtrer le hash de transaction rattaché à l’adresse de dépôt de votre service ou de votre client dans `subject.payment_method.account_id`
Sortant (retraits)	Filtrer le portefeuille de destination dans `counterparty.payment_method.account_id` avant d’envoyer les fonds	Filtrer le hash de transaction rattaché au même portefeuille de destination dans `counterparty.payment_method.account_id`

Pour le filtrage avant transfert, omettez transaction_details.payment_reference_id ; Didit exécute un filtrage du portefeuille sur l’adresse concernée. Pour le filtrage après transfert, incluez le hash de transaction blockchain dans transaction_details.payment_reference_id ; Didit exécute un filtrage de transaction et enregistre les données récapitulatives de la transaction lorsque l’enrichissement on-chain est disponible.

Lightning Network

Définissez transaction_details.crypto_params.crypto_chain sur LIGHTNING pour le filtrage Lightning Network. Le filtrage Lightning exige un fournisseur Elliptic ou Chainalysis BYOK connecté dans le Marketplace de la console. Merkle Science, Crystal et TRM Labs en mode géré n’acceptent pas LIGHTNING ; Didit rejette ces requêtes avec 400 avant le filtrage ou la facturation. Pour Elliptic, Didit filtre l’identifiant Lightning fourni via l’analyse de portefeuille BTC Lightning d’Elliptic. Pour Chainalysis, Didit soumet un transfert Lightning à KYT lorsque transaction_details.payment_reference_id est présent.

Champs obligatoires

Pour toutes les requêtes de filtrage crypto, envoyez :

transaction_details.direction — INBOUND ou OUTBOUND
transaction_details.currency_kind — crypto
transaction_details.currency — le symbole de l’actif, par exemple BTC, ETH, USDC ou votre token personnalisé
Une adresse du participant sélectionné selon les règles de direction ci-dessus

Pour le filtrage par hash de transaction une fois le transfert inscrit sur la blockchain, envoyez également :

transaction_details.payment_reference_id — le hash de transaction blockchain

Si le filtrage crypto est activé et que l’adresse requise pour le sens est absente, l’API Create Transaction rejette la requête.

Exemple de filtrage sortant avant transfert

Avant d’envoyer les fonds, créez une transaction crypto sortante sans hash de transaction. Didit filtre le portefeuille de destination.

{
  "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..."
    }
  }
}

Exemple de filtrage entrant après transfert

Après réception des fonds, incluez le hash de transaction. Didit filtre le hash rattaché à votre adresse de dépôt et enrichit la réponse avec les informations récapitulatives de la transaction lorsqu’elles sont disponibles.

{
  "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"
  }
}

Fournisseurs pris en charge

Fournisseur	Statut	Tarifs gérés	Tarifs avec clé connectée
Merkle Science	Disponible	$0.15/filtrage	$0.02/filtrage
Crystal	Connectez une clé de fournisseur via le Marketplace	Non disponible	$0.02/filtrage
Chainalysis	Connectez une clé de fournisseur via le Marketplace	Non disponible	$0.02/filtrage
Elliptic	Connectez une clé de fournisseur via le Marketplace	Non disponible	$0.02/filtrage
TRM Labs	Connectez une clé de fournisseur via le Marketplace	Non disponible	$0.02/filtrage

Configurez votre fournisseur préféré dans Transactions > Paramètres > Provider Preferences dans la Business Console, ou connectez votre propre clé de fournisseur depuis le Marketplace de la console (catégorie Crypto monitoring). LIGHTNING est pris en charge uniquement avec les configurations Chainalysis et Elliptic à clé connectée.

Avec les tarifs avec clé connectée, vous connectez une clé API de fournisseur existante et payez par filtrage les frais d’infrastructure indiqués. Utilisez cette option si vous avez déjà un accord commercial avec un fournisseur d’analyse blockchain.

Résultats du filtrage

Chaque filtrage produit un résultat standardisé, quel que soit le fournisseur utilisé.

Statut du filtrage

custom_values.aml_screening_status indique si une transaction a été filtrée.

Valeur	Signification
`COMPLETED`	Le filtrage est terminé. Le résultat figure dans `provider_results` et dans les autres champs de filtrage de `custom_values`.
`PENDING`	Le filtrage n’est pas encore terminé : le fournisseur est toujours en train de l’analyser, ou Didit refiltre le hachage de la transaction plus tard (voir ci-dessous).
`ERROR`	Le fournisseur a répondu, mais indique que sa propre analyse a échoué.
`FAILED`	La transaction n’a pas été filtrée. `custom_values.aml_screening_error` en indique la raison. Le filtrage géré par Didit n’est pas facturé ; une requête à laquelle votre fournisseur connecté a répondu compte comme une requête fournisseur.

Une transaction qui serait autrement approuvée passe à IN_REVIEW tant que son filtrage n’est pas COMPLETED.

Hachages de transaction non encore indexés

Un fournisseur d’analyse blockchain peut mettre quelques minutes à indexer un transfert qui vient d’être miné ; jusque-là, il ne peut pas le filtrer. Lorsque le fournisseur indique qu’il n’a pas encore indexé un hachage de transaction, et que le réseau lui-même confirme que la transaction existe, Didit refiltre celle-ci en arrière-plan au lieu de la faire échouer :

La réponse de création affiche déjà custom_values.aml_screening_status comme étant PENDING, avec la raison dans custom_values.aml_screening_error. Une transaction approuvée est maintenue IN_REVIEW avec decision_reason_code aml_screening_pending.
Didit refiltre le hachage de la transaction environ 2, 12 et 42 minutes après la création de la transaction.
Lorsqu’une nouvelle tentative réalise le filtrage, le résultat est enregistré comme tout autre filtrage, et celui-ci n’est facturé qu’une fois. Vos règles s’exécutent à nouveau sur les données de filtrage, la mise en attente est levée, et vous recevez un seul webhook transaction.status.updated, avec le statut que la transaction a après l’application des règles, qu’il ait changé ou non. Une transaction refusée ou résolue par un réviseur entre-temps conserve son statut.
Si le fournisseur n’a toujours pas indexé le hachage de la transaction après la dernière tentative, le filtrage se termine en FAILED, comme il l’aurait fait à la création : la transaction reste IN_REVIEW avec decision_reason_code aml_screening_failed, et elle est facturée comme elle l’aurait été à la création en cas d’échec : rien pour le filtrage géré par Didit, une requête fournisseur si la dernière tentative a atteint votre fournisseur connecté. Les tentatives précédentes, qui ont été réessayées, ne sont jamais facturées.
Si votre solde ne couvre plus le filtrage au moment d’une nouvelle tentative, le filtrage se termine en FAILED et rien n’est facturé.

Les nouvelles tentatives s’appliquent aux hachages de transaction sur Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism et Tron. Un hachage inconnu de son réseau, ou un hachage d’un autre réseau, n’est pas réessayé : le filtrage échoue immédiatement.

Score de risque et gravité

Chaque portefeuille ou transaction filtré reçoit :

Score de risque (0–100) : plus le score est élevé, plus l’exposition à des entités risquées est importante
Niveau de gravité : dérivé du score, LOW, MEDIUM, HIGH ou CRITICAL

Analyse de l’origine des fonds

Une répartition en pourcentage de l’origine des fonds, catégorisée par type d’entité :

Catégorie	Niveau de risque	Description
`SANCTIONED`	Critique	Entités figurant sur les listes de sanctions internationales (OFAC, UE, ONU)
`TERRORIST_FINANCING`	Critique	Adresses liées au financement du terrorisme
`CHILD_EXPLOITATION`	Critique	Adresses liées à des contenus d’exploitation d’enfants
`RANSOMWARE`	Élevé	Adresses de paiement de rançongiciels
`STOLEN_FUNDS`	Élevé	Adresses associées à des vols ou piratages connus
`DARKNET_MARKET`	Élevé	Adresses de marchés du darknet
`MIXER`	Élevé	Services de mixage ou de brassage utilisés pour masquer l’origine des fonds
`SCAM`	Élevé	Adresses d’arnaques ou de fraudes connues
`HIGH_RISK_EXCHANGE`	Moyen	Plateformes d’échange aux contrôles KYC/AML faibles
`HIGH_RISK_JURISDICTION`	Moyen	Entités situées dans des juridictions à haut risque figurant sur la liste FATF
`GAMBLING_UNLICENSED`	Moyen	Plateformes de jeux d’argent non agréées
`P2P_EXCHANGE`	Faible	Services d’échange pair à pair
`EXCHANGE`	Faible	Plateformes d’échange de cryptomonnaies réglementées
`UNNAMED_SERVICE`	Faible	Services non identifiés

Chaque entité de la répartition comprend le pourcentage des fonds, les montants reçus et envoyés, et indique si le lien est direct ou indirect.

Tableau d’exposition

Un tableau d’exposition présentant les entités source, destination et contrepartie, comprenant :

Le nom et la catégorie de l’entité
La connexion directe ou indirecte (distance en sauts)
Les montants reçus et envoyés
Le niveau de risque par entité

Graphe de réseau

Une représentation visuelle en nœuds et arêtes des relations de transactions du portefeuille :

Nœuds : représentent les portefeuilles, plateformes d’échange, services et autres entités
Arêtes : représentent les transactions entre les nœuds, avec les montants et les hachages de transaction
Indicateurs : comprennent des statistiques au niveau du graphe, comme la centralité et la profondeur

Le graphe de réseau est disponible dans la Business Console sous forme de visualisation interactive.

Intégration avec les règles

Les résultats du filtrage alimentent directement le moteur de règles. Didit inclut des règles prédéfinies qui se déclenchent automatiquement à partir des données de filtrage :

Règle prédéfinie	Action
Sanctions counterparty	Refus immédiat - le portefeuille analysé est lui-même attribué à une entité sanctionnée (`custom_values.wallet_sanctioned`)
Sanctions exposure	Ajouter un score et signaler le dossier pour examen - le portefeuille a envoyé des fonds à des entités sanctionnées ou en a reçu de leur part, sans être lui-même sanctionné (`sanctions_hit` à true, `wallet_sanctioned` non true)
Terrorist financing / child exploitation	Refus immédiat
Darknet market exposure	Ajouter un score et signaler le dossier pour examen
Mixer/obfuscation service exposure	Ajouter un score et signaler le dossier pour examen
High-risk source of funds (>30%)	Ajouter un score et signaler le dossier pour examen
Multiple risky counterparties	Ajouter un score et signaler le dossier pour examen
Medium wallet risk score	Ajouter un score et signaler le dossier pour examen
Filtrage en attente	Mettre la transaction en attente jusqu’à la fin du filtrage

Champs de filtrage pour les règles

Le filtrage crypto écrit ces clés dans le custom_values de la transaction, afin que les règles puissent les utiliser sous la forme custom_values.<key> :

Champ	Type	Description
`sanctions_hit`	boolean	`true` lorsque le portefeuille lui-même est sanctionné, ou lorsque les fonds de l’une de ses contreparties proviennent d’entités sanctionnées (exposition). Les grandes plateformes d’échange sont souvent `true` par simple exposition.
`wallet_sanctioned`	boolean	`true` uniquement lorsque le fournisseur de filtrage attribue le portefeuille analysé lui-même à une entité sanctionnée (désignations OFAC, UE, ONU ou HMT). L’exposition seule ne le met jamais à true.
`aml_sanctions_exposure_pct`	number (0-100)	Part du volume analysé du portefeuille qui a touché des entités sanctionnées. Elle est calculée comme `aml_high_risk_exposure_pct`, en se limitant aux sanctions.

Utilisez wallet_sanctioned pour bloquer les transferts vers un portefeuille sanctionné, sans refuser les transferts vers les grandes plateformes d’échange qui ne présentent qu’une exposition indirecte. Utilisez sanctions_hit ou aml_sanctions_exposure_pct pour examiner ou noter l’exposition. La règle prédéfinie Sanctions counterparty refuse la transaction lorsque wallet_sanctioned vaut true, et la règle prédéfinie Sanctions exposure envoie en examen les portefeuilles dont l’exposition est seule en cause. Les deux ne correspondent jamais à la même transaction : un portefeuille sanctionné est donc toujours refusé. Si vous aviez installé Sanctions counterparty avant cette modification, Didit l’a migrée vers wallet_sanctioned pour vous et a ajouté Sanctions exposure dans le même mode. Un transfert que l’ancienne règle refusait pour simple exposition est désormais envoyé en examen. Une fois le filtrage terminé, Didit réévalue automatiquement toutes les règles à partir des données de transaction enrichies et déclenche les webhooks applicables.

Étapes suivantes

Soumettre des transactions

Comment soumettre des transactions, y compris les détails des portefeuilles crypto.

Règles et notation

Comment les résultats du filtrage alimentent le moteur de règles.

Guide de la console

Consulter l’analyse de filtrage crypto, l’origine des fonds et les graphes de réseau dans la console.

Prise en main

Fonctionnalités

Référence

Console

Filtrage des portefeuilles crypto et adresses : API KYT

Déclenchement du filtrage

Sélection de l’actif et du réseau

Entrant ou sortant

Lightning Network

Champs obligatoires

Exemple de filtrage sortant avant transfert

Exemple de filtrage entrant après transfert

Fournisseurs pris en charge

Résultats du filtrage

Statut du filtrage

Hachages de transaction non encore indexés

Score de risque et gravité

Analyse de l’origine des fonds

Tableau d’exposition

Graphe de réseau

Intégration avec les règles

Champs de filtrage pour les règles

Étapes suivantes

Soumettre des transactions

Règles et notation

Guide de la console

​Déclenchement du filtrage

​Sélection de l’actif et du réseau

​Entrant ou sortant

​Lightning Network

​Champs obligatoires

​Exemple de filtrage sortant avant transfert

​Exemple de filtrage entrant après transfert

​Fournisseurs pris en charge

​Résultats du filtrage

​Statut du filtrage

​Hachages de transaction non encore indexés

​Score de risque et gravité

​Analyse de l’origine des fonds

​Tableau d’exposition

​Graphe de réseau

​Intégration avec les règles

​Champs de filtrage pour les règles

​Étapes suivantes

Soumettre des transactions

Règles et notation

Guide de la console

Déclenchement du filtrage

Sélection de l’actif et du réseau

Entrant ou sortant

Lightning Network

Champs obligatoires

Exemple de filtrage sortant avant transfert

Exemple de filtrage entrant après transfert

Fournisseurs pris en charge

Résultats du filtrage

Statut du filtrage

Hachages de transaction non encore indexés

Score de risque et gravité

Analyse de l’origine des fonds

Tableau d’exposition

Graphe de réseau

Intégration avec les règles

Champs de filtrage pour les règles

Étapes suivantes