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 retorna409 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.
Resposta
La resposta és el resultat estandarditzat del cribratge. Té la mateixa estructura que el resultat del proveïdorWALLET_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 desource_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.
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çatraw_response i s’ha substituït report_signature:
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-hireport_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.
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.