Screening dei wallet e degli indirizzi crypto: API KYT

Lo screening dei wallet crypto di Didit, chiamato anche screening degli indirizzi o KYT (conosci la tua transazione), verifica gli indirizzi dei wallet e gli hash delle transazioni di ogni trasferimento crypto per il rischio AML. Restituisce un punteggio di rischio, l’esposizione a fonti rischiose e gli eventuali riscontri nelle sanzioni. Per le transazioni in criptovalute, Didit può verificare gli indirizzi dei wallet e gli hash delle transazioni rispetto a provider di analisi blockchain come Merkle Science, Crystal, Chainalysis, Elliptic e TRM Labs, durante la creazione della transazione. Lo screening viene eseguito lato server: non sono necessarie chiamate API aggiuntive da parte tua.

Devi verificare un indirizzo senza una transazione? Usa lo screening dei wallet on demand, cioè l’endpoint (POST /v3/wallet-screening/), per ottenere lo stesso risultato relativo al rischio per un singolo wallet con una sola chiamata API.

Come viene attivato lo screening

Lo screening crypto viene eseguito automaticamente quando sono soddisfatte entrambe le condizioni:

La transazione ha currency_kind: "crypto" nei dettagli della transazione
Il monitoraggio delle transazioni è attivo nelle tue impostazioni dell’applicazione

Puoi sovrascrivere questo valore predefinito per singola transazione con include_crypto_screening nel payload di creazione della transazione:

Valore	Comportamento
`true`	Esegui lo screening crypto anche se il valore predefinito a livello di applicazione è disattivato
`false`	Salta lo screening crypto anche se il valore predefinito a livello di applicazione è attivato
omesso o `null`	Usa il valore predefinito a livello di applicazione configurato nella Console

Il valore predefinito a livello di applicazione si trova in Transazioni > Impostazioni nella Business Console. include_crypto_screening sovrascrive quel valore predefinito solo per la singola transazione che stai creando.

Selezione dell’asset e della rete

L’asset e la rete sono campi separati. Imposta transaction_details.currency al simbolo del token, transaction_details.currency_kind a crypto e transaction_details.crypto_params.crypto_chain alla rete. Ad esempio, questo frammento registra un token personalizzato su Base:

{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}

Lo screening gestito accetta BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM e HBAR. BASE indica Base, OP indica Optimism, ARB indica Arbitrum One, AVAX indica Avalanche C-Chain, ADA indica Cardano, XLM indica Stellar e HBAR indica Hedera. Sono accettati anche i nomi comuni delle reti, ad esempio POLYGON o POL per MATIC, BSC per BNB e TRON per TRX. Celo, Mode e Plume non sono coperti dall’integrazione gestita: vengono sottoposti a screening tramite un account TRM Labs collegato (CELO, MODE, PLUME). I provider collegati hanno una copertura propria; Lightning ha requisiti aggiuntivi, descritti più avanti. Specifica sempre crypto_chain per un token, inclusi USDT e USDC. Se manca, la valuta viene usata come rete, e USDT e USDC ricavano la rete dall’hash della transazione o, in assenza di hash, dall’indirizzo del wallet. Un hash Tron o Solana seleziona Tron o Solana. Un hash 0x è identico su ogni rete EVM, quindi per USDT, USDC ed ETH Didit lo cerca su Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism ed esegue lo screening della transazione sulla rete in cui viene trovato. ETH è incluso perché è nativo su Ethereum, Base, Arbitrum e Optimism ed è trasferito anche su BNB Chain come token BEP-20 con bridging. Se nessuna rete contiene l’hash, oppure se le reti non possono essere verificate in quel momento, la transazione non viene sottoposta a screening e lo screening non viene addebitato. In questo caso custom_values.aml_screening_status assume il valore FAILED, custom_values.aml_screening_error spiega il motivo e una transazione approvata passa in revisione. Una transazione USDT o USDC senza hash sottopone a screening un wallet, e l’indirizzo del wallet seleziona la rete. Un indirizzo Tron viene sottoposto a screening su Tron e un indirizzo Solana su Solana. Un indirizzo 0x viene sottoposto a screening sulla prima rete, tra Ethereum, BNB Chain, Polygon, Base, Arbitrum e Optimism, in cui ha inviato una transazione o detiene il token. Un indirizzo 0x senza attività su nessuna di queste reti, oppure uno le cui reti non possono essere verificate in quel momento, viene sottoposto a screening su Ethereum. Inviare crypto_chain evita questa ricerca. Non sostituire mai ETH con la rete effettiva. Registrare un simbolo di token personalizzato non garantisce che i suoi trasferimenti siano indicizzati per lo screening tramite hash della transazione. La copertura del token deve essere verificata usando il contratto del token e la rete. Una transazione creata non è la prova di uno screening riuscito: controlla lo stato dello screening e il risultato del provider prima di considerarla sottoposta a screening.

In entrata vs in uscita

transaction_details.direction è obbligatorio perché indica a Didit quale lato del trasferimento deve essere sottoposto a screening.

Direzione	Prima del trasferimento on-chain	Dopo il trasferimento on-chain
In entrata (depositi)	Effettua lo screening del wallet del mittente della controparte, se lo fornisci in `counterparty.payment_method.account_id`	Effettua lo screening dell’hash della transazione limitato all’indirizzo di deposito del tuo servizio o cliente in `subject.payment_method.account_id`
In uscita (prelievi)	Effettua lo screening del wallet di destinazione in `counterparty.payment_method.account_id` prima di inviare i fondi	Effettua lo screening dell’hash della transazione limitato allo stesso wallet di destinazione in `counterparty.payment_method.account_id`

Per lo screening prima del trasferimento, ometti transaction_details.payment_reference_id: Didit esegue lo screening del wallet sull’indirizzo pertinente. Per lo screening dopo il trasferimento, includi l’hash della transazione blockchain in transaction_details.payment_reference_id: Didit esegue lo screening della transazione e memorizza i dati di riepilogo della transazione quando è disponibile l’arricchimento on-chain.

Rete Lightning

Imposta transaction_details.crypto_params.crypto_chain su LIGHTNING per lo screening sulla rete Lightning. Lo screening Lightning richiede un provider BYOK Elliptic o Chainalysis collegato nel Marketplace della console. I provider gestiti Merkle Science, Crystal e TRM Labs non accettano LIGHTNING: Didit rifiuta queste richieste con 400 prima dello screening o della fatturazione. Con Elliptic, Didit effettua lo screening dell’identificatore Lightning fornito tramite l’analisi dei wallet Lightning BTC di Elliptic. Con Chainalysis, Didit invia un trasferimento Lightning a KYT quando è presente transaction_details.payment_reference_id.

Campi obbligatori

Per tutte le richieste di screening crypto, invia:

transaction_details.direction: INBOUND oppure OUTBOUND
transaction_details.currency_kind: crypto
transaction_details.currency: il simbolo dell’asset, per esempio BTC, ETH, USDC o il tuo token personalizzato
Un indirizzo nel partecipante selezionato in base alle regole di direzione sopra riportate

Per lo screening dell’hash della transazione dopo che il trasferimento è on-chain, invia anche:

transaction_details.payment_reference_id: l’hash della transazione blockchain

Se lo screening crypto è abilitato e manca l’indirizzo wallet richiesto per la direzione, l’API Create Transaction rifiuta la richiesta.

Esempio: screening in uscita prima del trasferimento

Prima di inviare i fondi, crea una transazione crypto in uscita senza hash della transazione. Didit esegue lo screening del wallet di destinazione.

{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}

Esempio: screening in entrata dopo il trasferimento

Dopo aver ricevuto i fondi, includi l’hash della transazione. Didit esegue lo screening dell’hash limitato al tuo indirizzo di deposito e arricchisce la risposta con le informazioni di riepilogo della transazione, quando disponibili.

{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}

Provider supportati

Provider	Stato	Prezzi gestiti	Prezzi con chiave connessa
Merkle Science	Disponibile	$0.15/screening	$0.02/screening
Crystal	Collega una chiave del provider tramite Marketplace	Non disponibile	$0.02/screening
Chainalysis	Collega una chiave del provider tramite Marketplace	Non disponibile	$0.02/screening
Elliptic	Collega una chiave del provider tramite Marketplace	Non disponibile	$0.02/screening
TRM Labs	Collega una chiave del provider tramite Marketplace	Non disponibile	$0.02/screening

Configura il provider preferito in Transazioni > Impostazioni > Provider Preferences nella Business Console, oppure collega la tua chiave del provider dal Marketplace della console (categoria Crypto monitoring). LIGHTNING è supportato solo dalle configurazioni Chainalysis ed Elliptic con chiave connessa.

Con i prezzi con chiave connessa, colleghi una chiave API di un provider esistente e paghi la commissione infrastrutturale indicata per ogni screening. Usa questa opzione se hai già un accordo commerciale con un provider di analisi blockchain.

Risultati dello screening

Ogni screening produce un risultato standardizzato, indipendentemente dal provider utilizzato.

Stato dello screening

custom_values.aml_screening_status indica se una transazione è stata sottoposta a screening.

Valore	Significato
`COMPLETED`	Lo screening è terminato. Il risultato si trova in `provider_results` e negli altri campi di screening di `custom_values`.
`PENDING`	Lo screening non è ancora terminato: il provider sta ancora analizzando la transazione, oppure Didit ripete lo screening dell’hash della transazione più tardi (vedi sotto).
`ERROR`	Il provider ha risposto, ma ha segnalato che la propria analisi è fallita.
`FAILED`	La transazione non è stata sottoposta a screening. `custom_values.aml_screening_error` indica il motivo. Lo screening gestito da Didit non comporta alcun addebito per questo caso; una richiesta a cui ha risposto il provider collegato conta come richiesta al provider.

Una transazione che altrimenti verrebbe approvata passa a IN_REVIEW finché il suo screening non è COMPLETED.

Hash delle transazioni non ancora indicizzati

Un provider di analisi blockchain può impiegare alcuni minuti per indicizzare un trasferimento appena minato e, fino a quel momento, non può sottoporlo a screening. Quando il provider risponde che non ha ancora indicizzato un hash di transazione e la rete stessa conferma che la transazione esiste, Didit ripete lo screening in background invece di far fallire lo screening:

La risposta alla creazione mostra già custom_values.aml_screening_status come PENDING, con il motivo in custom_values.aml_screening_error. Una transazione approvata viene trattenuta in IN_REVIEW con decision_reason_code aml_screening_pending.
Didit ripete lo screening dell’hash della transazione circa 2, 12 e 42 minuti dopo la creazione della transazione.
Quando un nuovo tentativo completa lo screening, il risultato viene salvato come qualsiasi altro screening e lo screening viene addebitato una sola volta. Le regole vengono eseguite di nuovo sui dati dello screening, il blocco viene rimosso e ricevi un webhook transaction.status.updated con lo stato che la transazione ha dopo le regole, che sia cambiato o no. Una transazione rifiutata o risolta da un revisore nel frattempo mantiene il suo stato.
Se il provider non ha ancora indicizzato l’hash della transazione dopo l’ultimo nuovo tentativo, lo screening termina con FAILED, come sarebbe accaduto alla creazione: la transazione resta IN_REVIEW con decision_reason_code aml_screening_failed, e lo screening viene addebitato come sarebbe stato addebitato un fallimento alla creazione: nessun costo per lo screening gestito da Didit, una richiesta al provider se l’ultimo tentativo ha raggiunto il provider collegato. I tentativi precedenti, sottoposti a nuovo tentativo, non vengono mai addebitati.
Se il saldo non è più sufficiente a coprire lo screening quando viene eseguito un nuovo tentativo, lo screening termina con FAILED e nulla viene addebitato.

I nuovi tentativi si applicano agli hash delle transazioni su Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism e Tron. Un hash che la rete corrispondente non riconosce, oppure un hash appartenente a un’altra rete, non viene sottoposto a nuovo tentativo: lo screening fallisce subito.

Punteggio di rischio e gravità

Ogni wallet o transazione sottoposti a screening riceve:

Punteggio di rischio (0–100): punteggi più alti indicano una maggiore esposizione a entità rischiose
Livello di gravità: derivato dal punteggio, LOW, MEDIUM, HIGH o CRITICAL

Analisi dell’origine dei fondi

Una suddivisione percentuale dell’origine dei fondi, classificata per tipo di entità:

Categoria	Livello di rischio	Descrizione
`SANCTIONED`	Critico	Entità presenti nelle liste delle sanzioni internazionali (OFAC, UE, ONU)
`TERRORIST_FINANCING`	Critico	Indirizzi collegati al finanziamento del terrorismo
`CHILD_EXPLOITATION`	Critico	Indirizzi collegati a materiale di sfruttamento minorile
`RANSOMWARE`	Alto	Indirizzi di pagamento di ransomware
`STOLEN_FUNDS`	Alto	Indirizzi associati a furti o attacchi informatici noti
`DARKNET_MARKET`	Alto	Indirizzi di mercati del dark web
`MIXER`	Alto	Servizi di mixing o tumbling utilizzati per oscurare l’origine dei fondi
`SCAM`	Alto	Indirizzi di truffe o frodi note
`HIGH_RISK_EXCHANGE`	Medio	Exchange con controlli KYC/AML deboli
`HIGH_RISK_JURISDICTION`	Medio	Entità in giurisdizioni ad alto rischio incluse nell’elenco del FATF
`GAMBLING_UNLICENSED`	Medio	Piattaforme di gioco d’azzardo senza licenza
`P2P_EXCHANGE`	Basso	Servizi di exchange peer-to-peer
`EXCHANGE`	Basso	Exchange di criptovalute regolamentati
`UNNAMED_SERVICE`	Basso	Servizi non identificati

Ogni entità della suddivisione include la percentuale di fondi, gli importi ricevuti e inviati e se la connessione è diretta o indiretta.

Tabella dell’esposizione

Una tabella dell’esposizione che mostra le entità di origine, destinazione e controparte, includendo:

Nome e categoria dell’entità
Connessione diretta o indiretta (distanza in hop)
Importi ricevuti e inviati
Livello di rischio per entità

Grafo della rete

Una rappresentazione visiva a nodi e archi delle relazioni di transazione del wallet:

Nodi rappresentano wallet, exchange, servizi e altre entità
Archi rappresentano le transazioni tra i nodi, con importi e hash delle transazioni
Metriche includono statistiche a livello di grafo, come centralità e profondità

Il grafo della rete è disponibile nella Business Console come visualizzazione interattiva.

Integrazione con le regole

I risultati dello screening alimentano direttamente il motore delle regole. Didit include regole predefinite che si attivano automaticamente in base ai dati dello screening:

Regola predefinita	Azione
Controparte sanzionata	Rifiuto immediato - il wallet analizzato è attribuito a un’entità sanzionata (`custom_values.wallet_sanctioned`)
Esposizione a sanzioni	Aggiunge un punteggio e segnala per la revisione - il wallet ha movimentato fondi da o verso entità sanzionate senza essere a sua volta sanzionato (`sanctions_hit` true, `wallet_sanctioned` non true)
Finanziamento del terrorismo / sfruttamento minorile	Rifiuto immediato
Esposizione a mercati darknet	Aggiunge un punteggio e segnala per la revisione
Esposizione a servizi mixer/offuscamento	Aggiunge un punteggio e segnala per la revisione
Origine dei fondi ad alto rischio (>30%)	Aggiunge un punteggio e segnala per la revisione
Più controparti rischiose	Aggiunge un punteggio e segnala per la revisione
Punteggio di rischio del wallet medio	Aggiunge un punteggio e segnala per la revisione
Screening in attesa	Blocca la transazione fino al completamento dello screening

Campi dello screening per le regole

Lo screening crypto scrive queste chiavi nei custom_values della transazione, così le regole possono usarle come custom_values.<key>:

Campo	Tipo	Descrizione
`sanctions_hit`	boolean	`true` quando il wallet stesso è sanzionato, oppure quando i fondi di una sua controparte provengono da entità sanzionate (esposizione). Le grandi piattaforme di scambio risultano comunemente `true` per la sola esposizione.
`wallet_sanctioned`	boolean	`true` solo quando il provider di screening attribuisce lo stesso wallet analizzato a un’entità sanzionata (designazioni OFAC, UE, ONU o HMT). La sola esposizione non lo imposta mai.
`aml_sanctions_exposure_pct`	number (0-100)	Quota del volume analizzato del wallet che è entrato in contatto con entità sanzionate. Viene calcolata come `aml_high_risk_exposure_pct`, limitata alle sanzioni.

Usa wallet_sanctioned per bloccare i trasferimenti verso un wallet sanzionato senza rifiutare i trasferimenti verso le grandi piattaforme di scambio che hanno solo un’esposizione indiretta. Usa sanctions_hit o aml_sanctions_exposure_pct per sottoporre a revisione o assegnare un punteggio all’esposizione. La regola predefinita Controparte sanzionata rifiuta quando wallet_sanctioned è true, mentre la regola predefinita Esposizione a sanzioni invia alla revisione i wallet con sola esposizione. Le due non si applicano mai alla stessa transazione, quindi un wallet sanzionato viene sempre rifiutato. Se hai installato Controparte sanzionata prima di questa modifica, Didit l’ha spostata su wallet_sanctioned per te e ha aggiunto Esposizione a sanzioni nella stessa modalità, quindi un trasferimento che la vecchia regola rifiutava per la sola esposizione ora va in revisione. Al termine dello screening, Didit rivaluta automaticamente tutte le regole sui dati arricchiti della transazione e attiva gli eventuali webhook applicabili.

Prossimi passi

Invio delle transazioni

Come inviare le transazioni, compresi i dettagli del wallet crypto.

Regole e punteggi

Come i risultati dello screening alimentano il motore delle regole.

Guida alla console

Visualizzazione nella console dell’analisi crypto, dell’origine dei fondi e dei grafici di rete.

Primi passi

Funzionalità

Riferimento

Console

Screening dei wallet e degli indirizzi crypto: API KYT

Come viene attivato lo screening

Selezione dell’asset e della rete

In entrata vs in uscita

Rete Lightning

Campi obbligatori

Esempio: screening in uscita prima del trasferimento

Esempio: screening in entrata dopo il trasferimento

Provider supportati

Risultati dello screening

Stato dello screening

Hash delle transazioni non ancora indicizzati

Punteggio di rischio e gravità

Analisi dell’origine dei fondi

Tabella dell’esposizione

Grafo della rete

Integrazione con le regole

Campi dello screening per le regole

Prossimi passi

Invio delle transazioni

Regole e punteggi

Guida alla console

​Come viene attivato lo screening

​Selezione dell’asset e della rete

​In entrata vs in uscita

​Rete Lightning

​Campi obbligatori

​Esempio: screening in uscita prima del trasferimento

​Esempio: screening in entrata dopo il trasferimento

​Provider supportati

​Risultati dello screening

​Stato dello screening

​Hash delle transazioni non ancora indicizzati

​Punteggio di rischio e gravità

​Analisi dell’origine dei fondi

​Tabella dell’esposizione

​Grafo della rete

​Integrazione con le regole

​Campi dello screening per le regole

​Prossimi passi

Invio delle transazioni

Regole e punteggi

Guida alla console

Come viene attivato lo screening

Selezione dell’asset e della rete

In entrata vs in uscita

Rete Lightning

Campi obbligatori

Esempio: screening in uscita prima del trasferimento

Esempio: screening in entrata dopo il trasferimento

Provider supportati

Risultati dello screening

Stato dello screening

Hash delle transazioni non ancora indicizzati

Punteggio di rischio e gravità

Analisi dell’origine dei fondi

Tabella dell’esposizione

Grafo della rete

Integrazione con le regole

Campi dello screening per le regole

Prossimi passi