Vai al contenuto principale
POST
curl

Perché è senza stato

Lo screening autonomo dei wallet non scrive nulla nella tabella delle transazioni, quindi non esiste un record salvato da cui questo endpoint possa generare il report. Invece, ripubblichi il JSON esatto che POST /v3/wallet-screening/ ti ha già restituito, e Didit trasforma quel payload in un PDF senza richiamare di nuovo un provider.

Il campo report_signature

Ogni risposta di POST /v3/wallet-screening/ ora include un campo report_signature: una firma opaca limitata alla tua applicazione. Questo endpoint la verifica prima di generare il PDF, così un chiamante non può modificare risk_score, severity, sanctions_hit o qualsiasi altro campo e ottenere un PDF dall’aspetto pulito, con il marchio Didit, per un risultato che Didit non ha mai prodotto. Ripubblica sempre il corpo completo della risposta senza modifiche, incluso report_signature. Riordinare le chiavi è consentito; modificare qualsiasi valore firmato no.

Fatturazione

Non viene effettuata alcuna chiamata al provider e non viene addebitato nulla: questo endpoint genera di nuovo il PDF di un risultato per cui hai già pagato quando hai chiamato POST /v3/wallet-screening/.

Errori

Passaggi successivi

Screening dei wallet

Esegui lo Screening dei wallet su richiesta sottostante e ottieni il risultato JSON da ripubblicare qui.

Screening on-demand del wallet

Panoramica dell’endpoint autonomo di Screening dei wallet e del modello del risultato.

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

L'oggetto JSON non modificato restituito da POST /v3/wallet-screening/, incluso report_signature.

Stessa struttura della risposta di POST /v3/wallet-screening/ — restituisci quel corpo della risposta esattamente così com'è, incluso report_signature.

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.

Risposta

Il documento PDF renderizzato, restituito direttamente come binario application/pdf — non è presente alcun wrapper JSON.

The response is of type file.

Ultima modifica il 7 novembre 2026