Saltar al contingut principal

Quan utilitzar-ho

De vegades cal verificar el risc AML d’una cartera de criptomonedes abans que hi hagi cap transacció per registrar, per exemple quan un client afegeix una adreça de retirada o quan el teu equip de compliment vol revisar una adreça puntualment. L’endpoint de cribratge de carteres sota demanda cribra una única adreça i retorna el resultat de risc complet sense crear cap transacció. És l’equivalent independent del cribratge automàtic de criptomonedes que s’executa durant l’enviament de la transacció. Tots dos comparteixen els mateixos proveïdors d’analítica de blockchain i la mateixa estructura de resultat. El cribratge de carteres no escriu res a la taula de transaccions. Si necessites que el cribratge quedi associat a una transacció monitoritzada (amb regles, alertes i webhooks), envia una transacció.

Requisits previs

El monitoratge de transaccions s’ha de configurar per a l’aplicació amb un proveïdor gestionat o amb una clau de proveïdor existent. Configura’l a Transaccions > Configuració > Provider Preferences a la Business Console. Si no hi ha cap proveïdor configurat, l’endpoint retorna 409 Conflict.

Sol·licitud

POST https://verification.didit.me/v3/wallet-screening/ Autentica’t amb la capçalera x-api-key.

Cobertura de cadenes

El cribratge gestionat admet Base (BASE), Optimism (OP) i Arbitrum One (ARB), tant per al cribratge de carteres com per al de hashes de transacció. La cobertura dels proveïdors connectats pot ser diferent; una cadena també ha de ser compatible amb el proveïdor i el compte que hagis seleccionat. Celo (CELO), Mode (MODE) i Plume (PLUME) es cribren a través d’un compte connectat de TRM Labs (Marketplace, amb clau pròpia); el cribratge gestionat no les cobreix i respon 400. No enviïs ETH per a una altra xarxa EVM: una mateixa adreça pot tenir activitat i risc diferents a cada cadena. Amb el cribratge gestionat, USDT i USDC són àlies antics per a Ethereum, no una cerca a totes les xarxes on existeixen aquests tokens. Utilitza l’identificador de xarxa (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR, o, amb TRM Labs, CELO, MODE o PLUME) per a la cadena real de la cartera. Per als tokens de transaccions registrades, mantén el token a transaction_details.currency i indica la xarxa per separat a transaction_details.crypto_params.crypto_chain. Consulta selecció d’actiu i xarxa.
LIGHTNING només està disponible quan l’aplicació té un proveïdor BYOK connectat d’Elliptic o de Chainalysis al Marketplace de la consola. No està disponible amb Merkle Science gestionat, ni amb Crystal o TRM Labs. Les sol·licituds sense un proveïdor connectat compatible retornen 400 i no es cribren ni es facturen.

Resposta

La resposta és el resultat estandarditzat del cribratge. Té la mateixa estructura que el resultat del proveïdor WALLET_SCREENING que retorna el cribratge de transaccions.
Com es defineix severity. severity és la franja del risk_score normalitzat: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN és la franja més baixa, no un estat separat de «sense dades»: risk_score: 0 (el cas habitual d’una adreça neta) vol dir que el proveïdor no ha retornat cap avaluació adversa, mentre que una puntuació diferent de zero dins del rang 1-9 és un senyal real però inferior a LOW. Per tant, llegeix el risk_score en si, no només la franja. En qualsevol cas, no mostris UNKNOWN com a «net» ni com a aprovació.direction no canvia el model de risc. El camp opcional direction es passa al proveïdor només com a context. No afecta risk_score, severity ni les llistes del desglossament que es retornen: source_of_funds i destination_of_funds es retornen sempre, independentment del valor. Per tant, canviar o ometre direction no obliga a tornar a analitzar una adreça ja analitzada.

Factors de risc

risk_factors és la resposta ordenada a «per què aquesta adreça té aquesta puntuació». Els proveïdors puntuen una adreça amb el seu propi model i només retornen un veredicte: Merkle Science retorna un enter de 0-5, de manera que risk_score per si sol no permet actuar. Cada entrada indica un factor concret, ordenat primer pels factors de risc alt i després pel valor que hi ha circulat.
Una puntuació alta sense cap factor is_high_risk és un resultat real i significatiu. Vol dir que el proveïdor ha puntuat l’adreça amb el seu propi model d’exposició sense informar de cap coincidència amb sancions, PEP o entitats atribuïdes. Els factors que sí que apareixen són els fluxos de fons que hi ha darrere de la puntuació. summary ho indica explícitament, així que tracta aquestes adreces com a «revisar els fluxos», no com a coincidència confirmada. risk_factors es limita als cinc factors més rellevants, mentre que source_of_funds i destination_of_funds sempre contenen el desglossament complet.risk_factors és un camp de primer nivell, no un camp niat. Els resultats cribrats abans que existís l’ometen per complet: llegeix-lo com una llista buida en lloc de suposar una explicació buida.

Desglossament de l’exposició

Cada entrada de source_of_funds / destination_of_funds descriu una entitat amb la qual l’adreça ha intercanviat fons:

Connexions amb contraparts

counterparty_connections enumera les entitats que el proveïdor atribueix a l’adreça analitzada. Per a Merkle Science, provenen de les etiquetes de propietari i d’usuari de la mateixa adreça, de manera que una mateixa entitat pot aparèixer dues vegades, i no contenen flux de fons: received_usd, sent_usd, received_hops i sent_hops són null, i percentage és 0.0. Llegeix els fluxos de fons des de source_of_funds i destination_of_funds.
No prenguis decisions a partir de counterparty_connections[].risk_level ni de counterparty_connections[].is_direct: per a Merkle Science, el primer repeteix la qualificació pròpia de l’adreça (consulta risk_score) i el segon és sempre true. Fes servir sanctions_hit, dominant_risk_category i risk_factors[].is_high_risk per al veredicte, i exposure_type dins de source_of_funds / destination_of_funds per determinar si és directa.

Exemple

Una resposta real per a una adreça inclosa a la llista de sancions de l’OFAC, analitzada amb Merkle Science. Només s’ha escurçat raw_response i s’ha substituït report_signature:
Els exemples il·lustren l’estructura de la resposta, no un veredicte garantit per a una adreça real. Les puntuacions de risc i l’exposició a sancions depenen de la xarxa seleccionada, de la intel·ligència vigent i de la política de risc configurada. Una atribució a una plataforma d’intercanvi no implica una puntuació de risc zero: una cartera d’una plataforma d’intercanvi pot tenir exposició a sancions a través dels seus fluxos de fons. sanctions_hit: true pot indicar que la cartera en si està sancionada o només que els seus fons tenen exposició a sancions, de manera que, per si sol, no vol dir que el titular de la cartera analitzada estigui sancionat. Quan el mateix cribratge s’executa sobre una transacció registrada, les regles també poden llegir custom_values.wallet_sanctioned, que és true només quan el proveïdor atribueix la cartera en si a una entitat sancionada, i custom_values.aml_sanctions_exposure_pct. Consulta Camps de cribratge per a regles. Llegeix risk_factors, source_of_funds i destination_of_funds per distingir l’atribució de l’exposició. Consulta Cribratge de criptomonedes i carteres per a una guia pas a pas.

Informe PDF

Per obtenir un PDF amb la marca de Didit d’un resultat de cribratge, torna a enviar el cos exacte de la resposta, incloent-hi report_signature, a POST /v3/wallet-screening/pdf/. Aquesta operació és sense estat: no fa cap crida al proveïdor, no genera cap cost addicional i no es desa res. Si edites qualsevol camp signat (risk_score, severity, sanctions_hit, …) abans de tornar a enviar-lo, la petició falla amb 400.
Consulta Screen Wallet PDF per a l’esquema complet de la petició i de la resposta, i per als formats d’error.

Facturació

Es factura un ús de monitoratge AML per cribratge satisfactori, a la mateixa tarifa que el cribratge de criptoactius vinculat a transaccions. Consulta els preus per a les tarifes gestionades i per a les claus connectades. Les aplicacions de sandbox no es facturen. Els errors de validació (400) i els errors de proveïdor no configurat (409) mai no es facturen.

Errors

Següents passos

Referència de l'API

Esquema complet de la sol·licitud i de la resposta de l’endpoint Screen Wallet.

PDF de Screen Wallet

Genera un resultat de cribratge com a PDF amb la marca de Didit.

Cribratge de criptoactius i carteres

Cribratge automàtic durant la creació de transaccions i el model de resultat.
Darrera modificació el 7 de novembre del 2026