Vai al contenuto principale
POST
curl

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json
wallet_address
string
obbligatorio

L'indirizzo crypto o l'identificatore di rete da sottoporre a screening. Deve corrispondere alla rete selezionata (ad es. un indirizzo di 40 caratteri esadecimali con prefisso 0x per le blockchain EVM). Alias: address.

Esempio:

"0x94f1b9b64e2932f6a2db338f616844400cd58e8a"

blockchain
enum<string>

Identificatore di rete opzionale. Se omesso, la rete viene ricavata dal formato dell'indirizzo: gli indirizzi bc1, 1 e 3 sono Bitcoin (BTC), gli indirizzi T sono Tron (TRX) e le chiavi pubbliche base58 sono Solana (SOL). Un indirizzo 0x è valido su ogni rete EVM, quindi l'omissione di blockchain per tale indirizzo restituisce 422 con le reti candidate in candidate_chains. Lo screening gestito supporta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE (Base), OP (Optimism), ARB (Arbitrum One), AVAX (Avalanche C-Chain), ADA (Cardano), XLM (Stellar) e HBAR (Hedera). USDT e USDC sono alias legacy di Ethereum, non ricerche multirete. La copertura dei provider connessi varia. LIGHTNING richiede un provider connesso supportato. CELO (Celo), MODE (Mode) e PLUME (Plume) vengono sottoposti a screening tramite un account TRM Labs connesso; lo screening gestito restituisce 400 per questi ultimi. Alias: currency.

Opzioni disponibili:
BTC,
LIGHTNING,
ETH,
LTC,
XRP,
BCH,
DOGE,
TRX,
SOL,
MATIC,
BNB,
USDT,
USDC,
BASE,
OP,
ARB,
AVAX,
ADA,
XLM,
HBAR,
CELO,
MODE,
PLUME
Esempio:

"ETH"

direction
enum<string>

Opzionale. Indica se l'indirizzo viene sottoposto a screening come controparte in entrata (deposito) o in uscita (prelievo). Accetta inbound, outbound, deposit o withdrawal. Se omesso, il valore predefinito è uno screening neutro precedente al trasferimento. Questo dato viene passato al provider esclusivamente come contesto; non modifica il risk_score, la severity o le suddivisioni di source_of_funds/destination_of_funds restituite, che vengono sempre fornite entrambe indipendentemente da direction. La modifica o l'omissione di direction non richiede pertanto un nuovo screening dell'indirizzo.

Opzioni disponibili:
inbound,
outbound,
deposit,
withdrawal

Risposta

Il risultato normalizzato dello screening dei wallet.

provider
string
obbligatorio

Provider che ha eseguito lo screening (ad es. merklescience, crystal).

screening_type
enum<string>
obbligatorio

Sempre WALLET_SCREENING per questo endpoint.

Opzioni disponibili:
WALLET_SCREENING
risk_score
integer
obbligatorio

Punteggio di rischio normalizzato da 0 a 100. Un valore più alto indica una maggiore esposizione a entità a rischio. Merkle Science assegna a un indirizzo un punteggio da 0 a 5, mappato su 0, 15, 35, 55, 75 o 95.

severity
enum<string>
obbligatorio

Fascia di rischio derivata da risk_score: 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 assenza di dati: un risk_score pari a 0 (il caso comune di indirizzo pulito) indica l'assenza di valutazioni avverse, mentre un punteggio diverso da zero compreso tra 1 e 9 è un segnale reale ma inferiore a LOW: leggi il risk_score, non solo la fascia. Non considerare mai UNKNOWN come una valutazione affermativa di basso rischio o di esito positivo; non visualizzarlo come superato.

Opzioni disponibili:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
status
enum<string>
obbligatorio

Stato dell'esito dello screening.

Opzioni disponibili:
SCREENED,
PENDING,
ERROR
summary
string
obbligatorio

Riepilogo leggibile dall'utente del risultato dello screening.

wallet_address
string
obbligatorio

L'indirizzo sottoposto a screening, restituito come conferma.

blockchain
string
obbligatorio

La blockchain sottoposta a screening.

source_of_funds
object[]
obbligatorio

Da dove l'indirizzo ha ricevuto fondi, attribuiti per entità. Ogni voce rappresenta una suddivisione dell'esposizione.

destination_of_funds
object[]
obbligatorio

A chi l'indirizzo ha inviato fondi, attribuiti per entità. Stessa struttura degli elementi di source_of_funds con exposure_direction = outgoing.

counterparty_connections
object[]
obbligatorio

Entità a cui il provider attribuisce l'indirizzo esaminato. Per Merkle Science queste provengono dai tag di proprietario e utente dell'indirizzo stesso, quindi la stessa entità può comparire due volte, e non riportano flussi di fondi: received_usd, sent_usd, received_hops e sent_hops sono null e percentage è 0. Non indirizzare qui in base a risk_level o is_direct: usa sanctions_hit, dominant_risk_category e risk_factors[].is_high_risk per l'esito, e exposure_type in source_of_funds/destination_of_funds per verificare se l'esposizione sia diretta.

sanctions_hit
boolean
obbligatorio

True se l'indirizzo ha un'esposizione diretta o indiretta a sanzioni.

dominant_risk_category
string | null
obbligatorio

Categoria ad alto rischio con il peso maggiore, o null quando nessuna è dominante (ad es. sanctioned, mixer, stolen_funds).

report_signature
string
obbligatorio

Firma HMAC-SHA256 opaca su questo risultato esatto, limitata alla tua applicazione. Non ha significato da sola: invia nuovamente il corpo completo della risposta, non modificato e includendo questo campo, a POST /v3/wallet-screening/pdf/ per generarlo come PDF. L'endpoint PDF rifiuta la richiesta con 400 se report_signature manca o se qualsiasi campo firmato (ad es. risk_score, severity, sanctions_hit) è stato modificato prima del nuovo invio.

transaction_hash
string | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

block_timestamp
string | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

total_value_usd
number | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

fee_usd
number | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

sender_rows
object[]

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet.

receiver_rows
object[]

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet.

transaction_flows
object[]

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre vuoto nel risultato dello screening dei wallet.

transaction_flows_status
string | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

transaction_flows_error
string | null

Campo dello screening delle transazioni, condiviso con la struttura del risultato. Sempre null nel risultato dello screening dei wallet.

network_nodes
object[]

Nodi del grafo di esposizione per lo screening delle transazioni. Vuoto nei risultati dello screening dei wallet.

network_edges
object[]

Archi del grafo di esposizione per lo screening delle transazioni. Vuoto nel risultato dello screening dei wallet.

pep_counterparty
boolean | null

Esposizione come persona politicamente esposta. null quando non è disponibile alcun riscontro PEP, il che corrisponde a ogni risultato attuale poiché nessun provider ne segnala uno; false solo per un risultato esplicito negativo dello screening. Non interpretare null come un controllo PEP completato.

risk_factors
object[]

Spiegazione ordinata di risk_score: cosa ha determinato questo verdetto. I fornitori valutano un indirizzo in base al proprio modello e restituiscono solo un verdetto (Merkle Science restituisce un numero intero da 0 a 5), quindi il punteggio da solo non è utilizzabile a livello operativo. Ordinata prima in base al rischio elevato, poi per il valore transitato attraverso ciascun fattore, limitata ai cinque più rilevanti; source_of_funds e destination_of_funds contengono sempre il dettaglio completo. Un valore elevato di risk_score senza alcuna voce is_high_risk significa che il fornitore non ha segnalato corrispondenze con sanzioni o entità associate e ha valutato l'indirizzo esclusivamente sul proprio modello di esposizione: summary lo indica esplicitamente.

raw_response
object

Il payload proprietario del provider. La sua struttura è specifica del provider e può cambiare senza preavviso: leggi i campi normalizzati invece di effettuarne il parsing.

Ultima modifica il 7 novembre 2026