Vai al contenuto principale
A volte devi verificare il rischio AML di un wallet crypto prima che esista una transazione da registrare, ad esempio quando un cliente aggiunge un indirizzo di prelievo o quando il team di compliance vuole valutare un indirizzo in modo ad hoc. L’endpoint su richiesta per lo screening dei wallet analizza un singolo indirizzo e restituisce il risultato di rischio completo senza creare una transazione. Questo è il corrispettivo autonomo dello screening crypto automatico che viene eseguito durante l’invio di una transazione. Entrambi usano gli stessi provider di analisi della blockchain e la stessa struttura del risultato.

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 restituisce 409 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.
LIGHTNING è disponibile solo se l’applicazione ha un provider BYOK Elliptic o Chainalysis collegato nel Marketplace della console. Non è disponibile con il provider Merkle Science gestito né con Crystal o TRM Labs. Le richieste senza un provider collegato supportato restituiscono 400 e non vengono sottoposte a screening né addebitate.

Risposta

La risposta è il risultato di screening standardizzato, con la stessa struttura del risultato del provider WALLET_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 in source_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.
Non basare l’instradamento su counterparty_connections[].risk_level o counterparty_connections[].is_direct: per Merkle Science il primo ripete il grado di rischio dell’indirizzo (leggi risk_score) e il secondo è sempre true. Per l’esito usa sanctions_hit, dominant_risk_category e risk_factors[].is_high_risk, e per distinguere l’esposizione diretta da quella indiretta usa exposure_type in source_of_funds / destination_of_funds.

Esempio

Una risposta reale per un indirizzo presente nella lista OFAC delle sanzioni, analizzato con Merkle Science. Nella risposta reale, solo raw_response è stato accorciato e report_signature è stato sostituito:
Gli esempi illustrano la forma della risposta, non un esito garantito per un indirizzo reale. I punteggi di rischio e l’esposizione alle sanzioni dipendono dalla rete selezionata, dall’intelligence aggiornata e dalla politica di rischio configurata. Un’attribuzione a un exchange non implica un punteggio di rischio pari a zero: un wallet di exchange può avere un’esposizione alle sanzioni attraverso i propri flussi di fondi. 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, incluso report_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.
Vedi Screen Wallet PDF per lo schema completo di richiesta e risposta e per la forma degli errori.

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.
Ultima modifica il 7 novembre 2026