> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Screening dei wallet e degli indirizzi crypto: API KYT

> Didit fa lo screening di indirizzi wallet e hash delle transazioni per rischio AML: punteggio, esposizione e sanzioni. Da $0.15 a controllo.

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.

> [!TIP]
>
> Devi verificare un indirizzo **senza** una transazione? Usa lo [screening dei wallet on demand](https://docs.didit.me/it/transaction-monitoring/wallet-screening.md), 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:

1. La transazione ha `currency_kind: "crypto"` nei dettagli della transazione
2. Il monitoraggio delle transazioni è attivo nelle tue [impostazioni dell'applicazione](https://docs.didit.me/it/transaction-monitoring/settings.md)

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 |

> [!TIP]
>
> 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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://business.didit.me), 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.

> [!TIP]
>
> 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](https://docs.didit.me/it/transaction-monitoring/console.md) come visualizzazione interattiva.

## Integrazione con le regole

I risultati dello screening alimentano direttamente il [motore delle regole](https://docs.didit.me/it/transaction-monitoring/rules.md). 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

> [card] [Invio delle transazioni](https://docs.didit.me/it/transaction-monitoring/transactions.md)
>
> Come inviare le transazioni, compresi i dettagli del wallet crypto.

> [card] [Regole e punteggi](https://docs.didit.me/it/transaction-monitoring/rules.md)
>
> Come i risultati dello screening alimentano il motore delle regole.

> [card] [Guida alla console](https://docs.didit.me/it/transaction-monitoring/console.md)
>
> Visualizzazione nella console dell'analisi crypto, dell'origine dei fondi e dei grafici di rete.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.