Quando usarlo
Lo screening dei wallet non scrive nulla nella tabella delle transazioni. Se ti serve lo screening collegato a una transazione monitorata (con regole, alert e webhook), invia una transazione.
Prerequisiti
Il monitoraggio delle transazioni deve essere configurato per l’applicazione, con un provider gestito o una chiave di un provider esistente. Configuralo in Transazioni > Impostazioni > Provider Preferences nella Business Console. Se non è configurato alcun provider, l’endpoint restituisce409 Conflict.
Richiesta
POST https://verification.didit.me/v3/wallet-screening/
Autentica la richiesta con l’header x-api-key.
Copertura delle reti
Lo screening gestito copre Base (BASE), Optimism (OP) e Arbitrum One (ARB), sia per lo screening dei wallet sia per quello degli hash delle transazioni.
I provider collegati possono avere una copertura diversa; una rete deve essere supportata anche dal provider e dall’account selezionati.
Le reti Celo (CELO), Mode (MODE) e Plume (PLUME) sono sottoposte a screening tramite un account TRM Labs collegato (Marketplace, con chiave propria); lo screening gestito non le copre e risponde 400.
Non inviare ETH per un’altra rete EVM: lo stesso indirizzo può avere attività e rischio diversi su ogni rete.
Con lo screening gestito, USDT e USDC sono alias legacy per Ethereum, non una ricerca su tutte le reti in cui esistono questi token.
Usa l’identificativo di rete (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR, oppure con TRM Labs CELO, MODE o PLUME) per la rete effettiva del wallet.
Per i token nelle transazioni registrate, mantieni il token in transaction_details.currency e specifica la rete separatamente in transaction_details.crypto_params.crypto_chain.
Vedi selezione di asset e rete.
Risposta
La risposta è il risultato di screening standardizzato, con la stessa struttura del risultato del providerWALLET_SCREENING restituito dallo screening delle transazioni.
Come viene impostato
severity. severity è la fascia del risk_score normalizzato: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN è la fascia più bassa, non uno stato separato di “nessun dato”: risk_score: 0 (il caso comune di indirizzo pulito) significa che il provider non ha restituito alcuna valutazione negativa, mentre un punteggio diverso da zero nell’intervallo 1-9 è un segnale reale ma inferiore alla fascia LOW. Leggi quindi il risk_score stesso, non solo la fascia. In ogni caso, non mostrare UNKNOWN come un esito positivo di “nessun rischio” o come un superamento dei controlli.direction non modifica il modello di rischio. Il campo facoltativo direction viene passato al provider solo come contesto. Non influisce su risk_score, severity né su quali liste di dettaglio vengono restituite: sia source_of_funds sia destination_of_funds vengono sempre restituite. Modificare od omettere direction non richiede quindi di rieseguire lo screening di un indirizzo già sottoposto a screening.Fattori di rischio
risk_factors è la risposta ordinata alla domanda “perché questo indirizzo ha questo punteggio”. I provider valutano un indirizzo con il proprio modello e restituiscono solo un giudizio (Merkle Science restituisce un intero 0-5), quindi il solo risk_score non permette di agire. Ogni voce indica un fattore; le voci sono ordinate prima con i fattori ad alto rischio e poi in base al valore dei fondi che vi sono transitati.
Un punteggio alto senza un fattore
is_high_risk è un esito reale e significativo. Significa che il provider ha valutato l’indirizzo secondo il proprio modello di esposizione senza segnalare una corrispondenza con sanzioni, PEP o entità attribuite: i fattori elencati sono i flussi di fondi alla base del giudizio. summary lo dichiara esplicitamente, quindi tratta questi indirizzi come “da verificare nei flussi”, non come un riscontro confermato. risk_factors è limitato ai cinque fattori più rilevanti; source_of_funds e destination_of_funds riportano sempre il dettaglio completo.risk_factors è un campo di primo livello, non annidato. I risultati analizzati prima che esistesse questo campo non includono affatto la chiave: leggila come un elenco vuoto, senza presumere una spiegazione vuota.Dettaglio dell’esposizione
Ogni voce insource_of_funds / destination_of_funds descrive un’entità con cui l’indirizzo ha scambiato fondi:
Connessioni con le controparti
counterparty_connections elenca le entità a cui il provider attribuisce l’indirizzo analizzato. Per Merkle Science queste derivano dai tag di proprietario e di utente dell’indirizzo stesso, quindi la stessa entità può comparire due volte, e non portano alcun flusso di fondi: received_usd, sent_usd, received_hops e sent_hops sono null, e percentage è 0.0. Leggi i flussi di fondi da source_of_funds e destination_of_funds.
Esempio
Una risposta reale per un indirizzo presente nella lista OFAC delle sanzioni, analizzato con Merkle Science. Nella risposta reale, soloraw_response è stato accorciato e report_signature è stato sostituito:
sanctions_hit: true può indicare che il wallet stesso è sanzionato oppure solo che i suoi fondi hanno un’esposizione alle sanzioni, quindi di per sé non significa che il titolare del wallet analizzato sia sanzionato.
Quando la stessa analisi viene eseguita su una transazione registrata, le regole possono leggere anche custom_values.wallet_sanctioned, che è true solo quando il provider attribuisce il wallet stesso a un’entità sanzionata, e custom_values.aml_sanctions_exposure_pct.
Vedi Campi di screening per le regole.
Leggi risk_factors, source_of_funds e destination_of_funds per distinguere l’attribuzione dall’esposizione.
Vedi Crypto & Wallet Screening per una guida passo passo.
Report PDF
Per ottenere un PDF con il marchio Didit di un risultato di screening, invia di nuovo il corpo esatto della risposta, inclusoreport_signature, a POST /v3/wallet-screening/pdf/. La chiamata è senza stato: nessuna chiamata al provider, nessun addebito aggiuntivo, nulla viene salvato. Modificare un campo firmato (risk_score, severity, sanctions_hit, …) prima del nuovo invio restituisce 400.
Fatturazione
Ogni utilizzo del monitoraggio AML viene fatturato per ogni screening riuscito, alla stessa tariffa dello screening delle criptovalute associato alle transazioni. Consulta i prezzi per le tariffe gestite e con chiave collegata. Le applicazioni sandbox non vengono fatturate. Gli errori di validazione (400) e quelli relativi a un provider non configurato (409) non vengono mai fatturati.
Errori
Passaggi successivi
Riferimento API
Schema completo della richiesta e della risposta per l’endpoint Screen Wallet.
PDF di Screen Wallet
Genera un risultato di screening come PDF con il branding Didit.
Screening delle criptovalute e dei wallet
Screening automatico durante la creazione della transazione e modello del risultato.