> ## 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.

# API de cribratge de carteres crypto i adreces (KYT)

> Didit cribra les adreces de cartera crypto i els hashes de transacció per risc AML, exposició i sancions. Des de $0.15 per consulta.

El cribratge de carteres de criptoactius de Didit, també anomenat cribratge d'adreces o KYT (coneix la teva transacció), comprova les adreces de cartera i els hashes de transacció de cada transferència de criptoactius per detectar risc AML, i retorna una puntuació de risc, l'exposició a fonts de risc i qualsevol coincidència amb sancions.

Per a les transaccions amb criptoactius, Didit pot cribrar les adreces de cartera i els hashes de transacció contra proveïdors d'analítica de blockchain com Merkle Science, Crystal, Chainalysis, Elliptic i TRM Labs durant la creació de la transacció. El cribratge s'executa al servidor: no cal fer cap crida addicional a l'API per part teva.

> [!TIP]
>
> Necessites cribrar una adreça **sense** una transacció? Utilitza l'endpoint de [cribratge de cartera sota demanda](https://docs.didit.me/ca/transaction-monitoring/wallet-screening.md) (`POST /v3/wallet-screening/`) per obtenir el mateix resultat de risc per a una sola cartera amb una única crida API.

## Com s'activa el cribratge

El cribratge de criptoactius s'executa automàticament quan es compleixen les dues condicions següents:

1. La transacció té `currency_kind: "crypto"` als seus detalls de transacció
2. El monitoratge de transaccions està habilitat a la teva [configuració de l'aplicació](https://docs.didit.me/ca/transaction-monitoring/settings.md)

Pots sobreescriure aquest valor per defecte per transacció amb `include_crypto_screening` al payload de creació de la transacció:

| Valor | Comportament |
| - | - |
| `true` | Executa el cribratge de criptoactius encara que el valor per defecte a nivell d'aplicació estigui desactivat |
| `false` | Omet el cribratge de criptoactius encara que el valor per defecte a nivell d'aplicació estigui activat |
| omès o `null` | Utilitza el valor per defecte a nivell d'aplicació configurat a la Console |

> [!TIP]
>
> El valor per defecte a nivell d'aplicació es troba a **Transactions** > **Settings** a la Business Console. `include_crypto_screening` només sobreescriu aquest valor per defecte per a la transacció única que estàs creant.

## Selecció d'actiu i xarxa

L'actiu i la xarxa són camps separats.
Estableix `transaction_details.currency` amb el símbol del token, `transaction_details.currency_kind` amb `crypto` i `transaction_details.crypto_params.crypto_chain` amb la xarxa.
Per exemple, aquest fragment registra un token personalitzat a Base:

```json theme={null}
{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}
```

El cribratge gestionat accepta `BTC`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `BASE`, `OP`, `ARB`, `AVAX`, `ADA`, `XLM` i `HBAR`.
`BASE` vol dir Base, `OP` vol dir Optimism, `ARB` vol dir Arbitrum One, `AVAX` vol dir Avalanche C-Chain, `ADA` vol dir Cardano, `XLM` vol dir Stellar i `HBAR` vol dir Hedera.
També s'accepten noms de xarxa habituals, per exemple `POLYGON` o `POL` per a `MATIC`, `BSC` per a `BNB` i `TRON` per a `TRX`.
Celo, Mode i Plume no estan cobertes per la integració gestionada; es cribren a través d'un compte connectat de TRM Labs (`CELO`, `MODE`, `PLUME`).
Els proveïdors connectats tenen la seva pròpia cobertura; Lightning té requisits addicionals més avall.

Especifica sempre `crypto_chain` per a un token, inclosos USDT i USDC.
Sense aquest camp, la moneda s'utilitza com a xarxa, i USDT i USDC prenen la xarxa del hash de la transacció o, sense hash, de l'adreça de la cartera.
Un hash de Tron o de Solana selecciona Tron o Solana.
Un hash `0x` és igual en totes les xarxes EVM, de manera que, per a USDT, USDC i ETH, Didit el busca a Ethereum, BNB Chain, Polygon, Base, Arbitrum i Optimism, i cribra la transacció a la xarxa on es troba.
ETH s'hi inclou perquè és nadiu a Ethereum, Base, Arbitrum i Optimism, i també es transfereix a BNB Chain com a token BEP-20 transferit mitjançant un pont.
Si cap xarxa no té el hash, o si les xarxes no es poden comprovar en aquell moment, la transacció no es cribra i el cribratge no es cobra.
Llavors `custom_values.aml_screening_status` és `FAILED`, `custom_values.aml_screening_error` indica el motiu i una transacció aprovada passa a revisió.

Una transacció USDT o USDC sense hash cribra una cartera, i l'adreça de la cartera selecciona la xarxa.
Una adreça Tron es cribra a Tron, i una adreça Solana, a Solana.
Una adreça `0x` es cribra a la primera de Ethereum, BNB Chain, Polygon, Base, Arbitrum i Optimism on hagi enviat una transacció o tingui el token.
Una adreça `0x` sense activitat a cap d'aquestes xarxes, o una adreça les xarxes de la qual no es poden comprovar en aquell moment, es cribra a Ethereum.

Enviar `crypto_chain` evita la cerca.
Mai substitueixis `ETH` per la xarxa real.

Registrar un símbol de token personalitzat no garanteix que les seves transferències estiguin indexades per al cribratge pel hash de la transacció.
La cobertura del token s'ha de comprovar amb el contracte del token i la xarxa.
Una transacció creada no és una prova de cribratge satisfactori: inspecciona l'estat del cribratge i el resultat del proveïdor abans de considerar-la cribrada.

## Entrant vs sortint

`transaction_details.direction` és obligatori perquè indica a Didit quina part de la transferència s'ha de cribrar.

| Direcció | Abans de la transferència on-chain | Després de la transferència on-chain |
| - | - | - |
| **Entrant** (dipòsits) | Fes el cribratge de la cartera del remitent de la contrapart, si la proporciones a `counterparty.payment_method.account_id` | Fes el cribratge del hash de la transacció limitat a l'adreça de dipòsit del teu servei/client a `subject.payment_method.account_id` |
| **Sortint** (retirades) | Fes el cribratge de la cartera de destinació a `counterparty.payment_method.account_id` abans d'enviar fons | Fes el cribratge del hash de la transacció limitat a la mateixa cartera de destinació a `counterparty.payment_method.account_id` |

Per al cribratge previ a la transferència, omet `transaction_details.payment_reference_id`; Didit executa el cribratge de cartera sobre l'adreça corresponent. Per al cribratge posterior a la transferència, inclou el hash de la transacció de blockchain a `transaction_details.payment_reference_id`; Didit executa el cribratge de transaccions i guarda les dades de resum de la transacció quan l'enriquiment on-chain estigui disponible.

### Lightning Network

Estableix `transaction_details.crypto_params.crypto_chain` a `LIGHTNING` per al cribratge de Lightning Network.
El cribratge Lightning requereix un proveïdor BYOK d'Elliptic o Chainalysis connectat a la consola, a **Marketplace**.
Merkle Science, Crystal i TRM Labs gestionats no accepten `LIGHTNING`; Didit rebutja aquestes sol·licituds amb `400` abans de fer el cribratge o la facturació.

Per a Elliptic, Didit fa el cribratge de l'identificador Lightning proporcionat mitjançant l'anàlisi de cartera BTC Lightning d'Elliptic.
Per a Chainalysis, Didit envia una transferència Lightning a KYT quan `transaction_details.payment_reference_id` està present.

## Camps obligatoris

Per a totes les sol·licituds de cribratge de criptoactius, envia:

* `transaction_details.direction`: `INBOUND` o `OUTBOUND`
* `transaction_details.currency_kind`: `crypto`
* `transaction_details.currency`: el símbol de l'actiu, per exemple `BTC`, `ETH`, `USDC` o el teu token personalitzat
* Una adreça de cartera del participant seleccionat segons les regles de direcció anteriors

Per al cribratge de hash de transacció després que la transferència s'hagi registrat on-chain, envia també:

* `transaction_details.payment_reference_id`: el hash de la transacció de blockchain

Si el cribratge de criptoactius està activat i falta l'adreça requerida per a la direcció, l'API Create Transaction rebutja la sol·licitud.

## Exemple: cribratge sortint previ a la transferència

Abans d'enviar fons, crea una transacció criptogràfica sortint sense hash de transacció. Didit fa el cribratge de la cartera de destinació.

```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: cribratge entrant posterior a la transferència

Després de rebre fons, inclou el hash de la transacció. Didit fa el cribratge del hash de la transacció limitat a la teva adreça de dipòsit i enriqueix la resposta amb informació de resum de la transacció quan estigui disponible.

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

## Proveïdors compatibles

| Proveïdor | Estat | Preus gestionats | Preus amb clau connectada |
| - | - | - | - |
| **Merkle Science** | Disponible | \$0.15/cribratge | \$0.02/cribratge |
| **Crystal** | Connecta una clau de proveïdor des de Marketplace | No disponible | \$0.02/cribratge |
| **Chainalysis** | Connecta una clau de proveïdor des de Marketplace | No disponible | \$0.02/cribratge |
| **Elliptic** | Connecta una clau de proveïdor des de Marketplace | No disponible | \$0.02/cribratge |
| **TRM Labs** | Connecta una clau de proveïdor des de Marketplace | No disponible | \$0.02/cribratge |

Configura el proveïdor que prefereixis a **Transaccions** > **Configuració** > **Provider Preferences** a la [Business Console](https://business.didit.me), o connecta la teva pròpia clau de proveïdor des de **Marketplace** (categoria Crypto monitoring).

`LIGHTNING` només és compatible amb configuracions de Chainalysis i Elliptic amb clau connectada.

> [!TIP]
>
> Amb **preus amb clau connectada**, connectes una clau d'API de proveïdor existent i pagues la tarifa d'infraestructura indicada per cada cribratge. Fes servir aquesta opció quan ja tinguis un acord comercial amb un proveïdor d'analítica de blockchain.

## Resultats del cribratge

Cada cribratge produeix un resultat estandarditzat, independentment del proveïdor que s'utilitzi.

### Estat del cribratge

`custom_values.aml_screening_status` et indica si una transacció s'ha cribrat.

| Valor | Significat |
| - | - |
| `COMPLETED` | El cribratge ha acabat. El resultat és a `provider_results` i als altres camps de cribratge de `custom_values`. |
| `PENDING` | El cribratge encara no ha acabat: el proveïdor encara l'està analitzant, o Didit tornarà a cribrar el hash de la transacció més tard (vegeu més avall). |
| `ERROR` | El proveïdor ha respost, però ha informat que la seva pròpia anàlisi ha fallat. |
| `FAILED` | La transacció no s'ha cribrat. `custom_values.aml_screening_error` indica el motiu. El cribratge gestionat per Didit no cobra res per això; una sol·licitud a la qual ha respost el teu proveïdor connectat compta com a sol·licitud al proveïdor. |

Una transacció que altrament s'aprovaria passa a `IN_REVIEW` mentre el seu cribratge no estigui en estat `COMPLETED`.

### Hashes de transacció que encara no s'han indexat

Un proveïdor d'analítica de blockchain pot trigar uns minuts a indexar una transferència que acaba de ser minada, i fins aleshores no la pot cribrar.
Quan el proveïdor respon que encara no ha indexat un hash de transacció, i la mateixa xarxa confirma que la transacció existeix, Didit la torna a cribrar en segon pla en lloc de fer-la fallar:

* La resposta de creació ja mostra `custom_values.aml_screening_status` com a `PENDING`, amb el motiu a `custom_values.aml_screening_error`.
  Una transacció aprovada queda retinguda com a `IN_REVIEW` amb `decision_reason_code` `aml_screening_pending`.
* Didit torna a cribrar el hash de la transacció aproximadament 2, 12 i 42 minuts després que la transacció es creés.
* Quan un reintent la cribra, el resultat s'emmagatzema com qualsevol altre cribratge i el cribratge es cobra una sola vegada.
  Les teves regles tornen a executar-se sobre les dades del cribratge, s'allibera la retenció i reps un únic webhook `transaction.status.updated` amb l'estat que té la transacció després de les regles, tant si ha canviat com si no.
  Una transacció que hagi estat rebutjada o resolta per un revisor entretant conserva el seu estat.
* Si el proveïdor encara no ha indexat el hash de la transacció després de l'últim reintent, el cribratge acaba en `FAILED` com hauria acabat en crear-se: la transacció queda `IN_REVIEW` amb `decision_reason_code` `aml_screening_failed`, i se li aplica el mateix càrrec que si hagués fallat en crear-se: res en el cribratge gestionat per Didit, i una sol·licitud al proveïdor connectat si el darrer intent hi va arribar. Els intents anteriors que s'han reintentat no es cobren mai.
* Si el teu saldo ja no pot cobrir el cribratge quan s'executa un reintent, el cribratge acaba en `FAILED` i no es cobra res.

Els reintents s'apliquen als hashes de transacció a Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism i Tron.
Un hash que la xarxa corresponent no coneix, o un hash d'una altra xarxa, no es reintenta: el cribratge falla de seguida.

### Puntuació de risc i gravetat

Cada cartera o transacció cribrada rep:

* **Puntuació de risc** (0–100): puntuacions més altes indiquen més exposició a entitats de risc
* **Nivell de gravetat**: es deriva de la puntuació: `LOW`, `MEDIUM`, `HIGH` o `CRITICAL`

### Anàlisi de l'origen dels fons

Un desglossament percentual d'on provenen els fons, classificat per tipus d'entitat:

| Categoria | Nivell de risc | Descripció |
| - | - | - |
| `SANCTIONED` | Crític | Entitats incloses a llistes internacionals de sancions (OFAC, UE, ONU) |
| `TERRORIST_FINANCING` | Crític | Adreces vinculades al finançament del terrorisme |
| `CHILD_EXPLOITATION` | Crític | Adreces vinculades a material d'explotació infantil |
| `RANSOMWARE` | Alt | Adreces de pagament de ransomware |
| `STOLEN_FUNDS` | Alt | Adreces associades a robatoris o pirateries conegudes |
| `DARKNET_MARKET` | Alt | Adreces de mercats de la darknet |
| `MIXER` | Alt | Serveis de barreja utilitzats per ocultar l'origen dels fons |
| `SCAM` | Alt | Adreces conegudes d'estafes o de frau |
| `HIGH_RISK_EXCHANGE` | Mitjà | Plataformes d'intercanvi amb controls KYC/AML febles |
| `HIGH_RISK_JURISDICTION` | Mitjà | Entitats en jurisdiccions d'alt risc incloses a la llista de la FATF |
| `GAMBLING_UNLICENSED` | Mitjà | Plataformes de jocs d'atzar sense llicència |
| `P2P_EXCHANGE` | Baix | Serveis d'intercanvi entre iguals |
| `EXCHANGE` | Baix | Plataformes d'intercanvi de criptomonedes regulades |
| `UNNAMED_SERVICE` | Baix | Serveis no identificats |

Cada entitat del desglossament inclou el percentatge de fons, els imports rebuts i enviats, i si la connexió és directa o indirecta.

### Taula d'exposició

Una taula d'exposició que mostra les entitats d'origen, de destinació i de contrapart, amb:

* Nom de l'entitat i categoria
* Connexió directa o indirecta (distància en salts)
* Imports rebuts i enviats
* Nivell de risc per entitat

### Graf de xarxa

Una representació visual de nodes i arestes de les relacions de transaccions de la cartera:

* **Nodes** representen carteres, plataformes d'intercanvi, serveis i altres entitats
* **Arestes** representen transaccions entre nodes, amb imports i hashes de transacció
* **Mètriques** inclouen estadístiques a nivell de graf, com la centralitat i la profunditat

El graf de xarxa està disponible a la [Business Console](https://docs.didit.me/ca/transaction-monitoring/console.md) com a visualització interactiva.

## Integració amb les regles

Els resultats del cribratge alimenten directament el [motor de regles](https://docs.didit.me/ca/transaction-monitoring/rules.md). Didit inclou regles predefinides que s'activen automàticament segons les dades del cribratge:

| Regla predefinida | Acció |
| - | - |
| **Contrapart sancionada** | Rebuig immediat - la pròpia cartera analitzada s'atribueix a una entitat sancionada (`custom_values.wallet_sanctioned`) |
| **Exposició a sancions** | Afegir puntuació i marcar per revisar - la cartera ha enviat fons a entitats sancionades o n'ha rebut, sense estar sancionada ella mateixa (`sanctions_hit` true, `wallet_sanctioned` no true) |
| **Finançament del terrorisme / explotació infantil** | Rebuig immediat |
| **Exposició a mercats de la darknet** | Afegir puntuació i marcar per revisar |
| **Exposició a serveis de mescla o ofuscació** | Afegir puntuació i marcar per revisar |
| **Origen dels fons d'alt risc (>30%)** | Afegir puntuació i marcar per revisar |
| **Múltiples contraparts de risc** | Afegir puntuació i marcar per revisar |
| **Puntuació de risc mitjà de la cartera** | Afegir puntuació i marcar per revisar |
| **Cribratge pendent** | Retenir la transacció fins que el cribratge es completi |

### Camps de cribratge per a regles

El cribratge de criptoactius escriu aquestes claus al `custom_values` de la transacció, perquè les regles les puguin fer servir com a `custom_values.<key>`:

| Camp | Tipus | Descripció |
| - | - | - |
| `sanctions_hit` | booleà | `true` quan la cartera està sancionada ella mateixa, o quan els fons d'alguna de les seves contraparts procedeixen d'entitats sancionades (exposició). Les grans plataformes d'intercanvi solen ser `true` només per exposició. |
| `wallet_sanctioned` | booleà | `true` només quan el proveïdor de cribratge atribueix la pròpia cartera analitzada a una entitat sancionada (designacions OFAC, UE, ONU o HMT). L'exposició per si sola no l'estableix mai. |
| `aml_sanctions_exposure_pct` | nombre (0-100) | Percentatge del volum de la cartera sotmès a cribratge que ha estat en contacte amb entitats sancionades. Es calcula igual que `aml_high_risk_exposure_pct`, però limitat a sancions. |

Fes servir `wallet_sanctioned` per bloquejar les transferències a una cartera sancionada sense rebutjar les transferències a grans plataformes d'intercanvi que només tenen exposició indirecta.
Fes servir `sanctions_hit` o `aml_sanctions_exposure_pct` per revisar o puntuar l'exposició.

La regla predefinida **Contrapart sancionada** rebutja la transacció quan `wallet_sanctioned` és `true`, i la regla predefinida **Exposició a sancions** envia a revisió les carteres amb exposició però sense sanció.
Les dues no coincideixen mai en la mateixa transacció, de manera que una cartera sancionada sempre es rebutja.
Si havies configurat **Contrapart sancionada** abans d'aquest canvi, Didit l'ha migrat automàticament a `wallet_sanctioned` i ha afegit **Exposició a sancions** en el mateix mode, de manera que una transferència que la regla anterior rebutjava només per exposició ara passa a revisió.

Quan el cribratge es completa, Didit reavalua automàticament totes les regles amb les dades de la transacció enriquida i activa els webhooks que corresponguin.

## Següents passos

> [card] [Enviament de transaccions](https://docs.didit.me/ca/transaction-monitoring/transactions.md)
>
> Com enviar transaccions, incloent-hi les dades de la cartera de criptoactius.

> [card] [Regles i puntuació](https://docs.didit.me/ca/transaction-monitoring/rules.md)
>
> Com els resultats del cribratge alimenten el motor de regles.

> [card] [Guia de la consola](https://docs.didit.me/ca/transaction-monitoring/console.md)
>
> Com consultar l'anàlisi de cribratge de criptoactius, l'origen dels fons i els grafs de xarxa a la consola.


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