> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtrage des portefeuilles crypto et adresses : API KYT

> Didit filtre les adresses crypto et les hash de transaction pour le risque AML : score, exposition, sanctions. Dès $0.15 par contrôle.

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.

> [!TIP]
>
> Vous souhaitez filtrer une adresse **sans** transaction ? Utilisez l'endpoint [filtrage des portefeuilles à la demande](https://docs.didit.me/fr/transaction-monitoring/wallet-screening.md) (`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 :

1. La transaction contient `currency_kind: "crypto"` dans ses détails de transaction
2. La surveillance des transactions est activée dans vos [paramètres d'application](https://docs.didit.me/fr/transaction-monitoring/settings.md)

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 |

> [!TIP]
>
> 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 :

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://business.didit.me), 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.

> [!TIP]
>
> 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](https://docs.didit.me/fr/transaction-monitoring/console.md) sous forme de visualisation interactive.

## Intégration avec les règles

Les résultats du filtrage alimentent directement le [moteur de règles](https://docs.didit.me/fr/transaction-monitoring/rules.md). 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

> [card] [Soumettre des transactions](https://docs.didit.me/fr/transaction-monitoring/transactions.md)
>
> Comment soumettre des transactions, y compris les détails des portefeuilles crypto.

> [card] [Règles et notation](https://docs.didit.me/fr/transaction-monitoring/rules.md)
>
> Comment les résultats du filtrage alimentent le moteur de règles.

> [card] [Guide de la console](https://docs.didit.me/fr/transaction-monitoring/console.md)
>
> Consulter l'analyse de filtrage crypto, l'origine des fonds et les graphes de réseau dans la console.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.