API de cribratge de carteres crypto i adreces (KYT)

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.

Necessites cribrar una adreça sense una transacció? Utilitza l’endpoint de cribratge de cartera sota demanda (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:

La transacció té currency_kind: "crypto" als seus detalls de transacció
El monitoratge de transaccions està habilitat a la teva configuració de l’aplicació

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

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:

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

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

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

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 com a visualització interactiva.

Integració amb les regles

Els resultats del cribratge alimenten directament el motor de regles. 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

Enviament de transaccions

Com enviar transaccions, incloent-hi les dades de la cartera de criptoactius.

Regles i puntuació

Com els resultats del cribratge alimenten el motor de regles.

Guia de la consola

Com consultar l’anàlisi de cribratge de criptoactius, l’origen dels fons i els grafs de xarxa a la consola.

Primers passos

Funcionalitats

Referència

Consola

API de cribratge de carteres crypto i adreces (KYT)

Com s’activa el cribratge

Selecció d’actiu i xarxa

Entrant vs sortint

Lightning Network

Camps obligatoris

Exemple: cribratge sortint previ a la transferència

Exemple: cribratge entrant posterior a la transferència

Proveïdors compatibles

Resultats del cribratge

Estat del cribratge

Hashes de transacció que encara no s’han indexat

Puntuació de risc i gravetat

Anàlisi de l’origen dels fons

Taula d’exposició

Graf de xarxa

Integració amb les regles

Camps de cribratge per a regles

Següents passos

Enviament de transaccions

Regles i puntuació

Guia de la consola

​Com s’activa el cribratge

​Selecció d’actiu i xarxa

​Entrant vs sortint

​Lightning Network

​Camps obligatoris

​Exemple: cribratge sortint previ a la transferència

​Exemple: cribratge entrant posterior a la transferència

​Proveïdors compatibles

​Resultats del cribratge

​Estat del cribratge

​Hashes de transacció que encara no s’han indexat

​Puntuació de risc i gravetat

​Anàlisi de l’origen dels fons

​Taula d’exposició

​Graf de xarxa

​Integració amb les regles

​Camps de cribratge per a regles

​Següents passos

Enviament de transaccions

Regles i puntuació

Guia de la consola

Com s’activa el cribratge

Selecció d’actiu i xarxa

Entrant vs sortint

Lightning Network

Camps obligatoris

Exemple: cribratge sortint previ a la transferència

Exemple: cribratge entrant posterior a la transferència

Proveïdors compatibles

Resultats del cribratge

Estat del cribratge

Hashes de transacció que encara no s’han indexat

Puntuació de risc i gravetat

Anàlisi de l’origen dels fons

Taula d’exposició

Graf de xarxa

Integració amb les regles

Camps de cribratge per a regles

Següents passos