> ## 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 API: AML crypto on-demand
> Con Didit, screening AML di un indirizzo wallet crypto senza transazioni. Origine dei fondi, sanzioni, punteggio di rischio. Da $0.02 a chiamata.
Prompt dell'API per lo screening dei wallet
Copia il prompt negli appunti
\
\`Screen a single crypto wallet address for AML risk through the Didit Management API, without creating a transaction.
Endpoint:
POST https://verification.didit.me/v3/wallet-screening/
Authentication:
Use the x-api-key header with my Didit API key.
Goal:
\- Run on-demand AML screening on one crypto address and return a normalised risk result (risk_score, severity, sanctions_hit, source/destination of funds, counterparty connections). Nothing is written to the transactions table.
When to call:
\- Before onboarding a customer's deposit/withdrawal wallet, to pre-check exposure.
\- Any time you need a standalone risk read on an address and do NOT have (or do not want to record) a transaction.
\- For transaction-coupled monitoring instead, use POST /v3/transactions/ with currency_kind = "crypto".
Prerequisites:
\- Transaction monitoring must be configured for the application with a managed provider or an existing provider key. Otherwise the call returns 409.
Request body (application/json):
\{
"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", // required; alias: address
"blockchain": "ETH", // required; one of BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR, USDT, USDC, or a common network name such as POLYGON or BSC; alias: currency
"direction": "inbound" // optional; inbound | outbound | deposit | withdrawal
}
Example call:
curl -X POST "https://verification.didit.me/v3/wallet-screening/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"wallet_address":"0x94f1b9b64e2932f6a2db338f616844400cd58e8a","blockchain":"ETH"}'
What to read from the response:
\- risk_score (0-100, higher = riskier) and severity (UNKNOWN | LOW | MEDIUM | HIGH | CRITICAL).
\- sanctions_hit (boolean) and dominant_risk_category.
\- source_of_funds / destination_of_funds / counterparty_connections for the exposure breakdown.
Billing:
\- One AML monitoring usage is billed per successful screening. Sandbox applications are not billed.
Failure modes:
\- 400 - malformed wallet address, missing wallet_address, or unsupported blockchain.
\- 401 - missing or malformed x-api-key.
\- 409 - no AML provider configured for the application; configure transaction monitoring first.
\- 502 - provider could not complete the screening; retry later.
For automatic, transaction-coupled crypto screening, see /transaction-monitoring/aml-screening.`
\
Incolla in
## OpenAPI
````yaml it/openapi-25.json POST /v3/wallet-screening/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/wallet-screening/:
post:
tags:
- Transactions
summary: Esegui lo screening di un indirizzo
description: >-
Esegui lo screening AML su richiesta per un singolo wallet/indirizzo
crypto senza creare una transazione. Determina il provider di analisi
blockchain configurato per la tua applicazione, effettua lo screening
dell'indirizzo in modo sincrono e restituisce il risultato di rischio
normalizzato. LIGHTNING è disponibile solo con una connessione BYOK
Elliptic o Chainalysis aggiunta tramite il Marketplace. Non viene
scritto nulla nella tabella delle transazioni. Viene fatturato un
utilizzo di monitoraggio AML per ogni screening riuscito (le
applicazioni sandbox non vengono fatturate).
operationId: screenWallet
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- wallet_address
properties:
wallet_address:
type: string
description: >-
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`.
example: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
blockchain:
type: string
description: >-
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`.
enum:
- BTC
- LIGHTNING
- ETH
- LTC
- XRP
- BCH
- DOGE
- TRX
- SOL
- MATIC
- BNB
- USDT
- USDC
- BASE
- OP
- ARB
- AVAX
- ADA
- XLM
- HBAR
- CELO
- MODE
- PLUME
example: ETH
direction:
type: string
description: >-
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.
enum:
- inbound
- outbound
- deposit
- withdrawal
example:
wallet_address: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
blockchain: ETH
responses:
'200':
description: Il risultato normalizzato dello screening dei wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/WalletScreeningResult'
example:
provider: merklescience
screening_type: WALLET_SCREENING
risk_score: 95
severity: CRITICAL
status: SCREENED
summary: >-
Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant
risk: sanctioned. Driven by: the address is attributed to
Sanctions / OFAC (Example Sanctions)
wallet_address: '0x94f1b9b64e2932f6a2db338f616844400cd58e8a'
transaction_hash: null
blockchain: ETH
block_timestamp: null
total_value_usd: null
fee_usd: null
sender_rows: []
receiver_rows: []
transaction_flows: []
transaction_flows_status: null
transaction_flows_error: null
source_of_funds:
- category: sanctioned
percentage: 100
amount_usd: 9813695
entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
hops: null
description: Sanctions / OFAC
is_direct: true
exposure_direction: incoming
exposure_type: direct
provider_entity_id: '118885'
provider_entity_type_id: '30'
provider_entity_subtype_id: '125'
country: ''
raw_amount: null
raw_currency: null
destination_of_funds:
- category: defi
percentage: 84.824453
amount_usd: 7783414.38
entity_name: Example DeFi 7
entity_type: DeFi
entity_subtype: Bridges
hops: null
description: DeFi / Bridges
is_direct: false
exposure_direction: outgoing
exposure_type: indirect
provider_entity_id: '118459'
provider_entity_type_id: '33'
provider_entity_subtype_id: '143'
country: ''
raw_amount: null
raw_currency: null
- category: defi
percentage: 15.175547
amount_usd: 1392494.37
entity_name: Example DeFi 2
entity_type: DeFi
entity_subtype: Yield Aggregator
hops: null
description: DeFi / Yield Aggregator
is_direct: false
exposure_direction: outgoing
exposure_type: indirect
provider_entity_id: '90192'
provider_entity_type_id: '33'
provider_entity_subtype_id: '142'
country: ''
raw_amount: null
raw_currency: null
counterparty_connections:
- entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
risk_level: critical
categories:
- sanctioned
received_usd: null
sent_usd: null
received_hops: null
sent_hops: null
percentage: 0
is_direct: true
country: null
provider_entity_id: null
- entity_name: Example Sanctions
entity_type: Sanctions
entity_subtype: OFAC
risk_level: critical
categories:
- sanctioned
received_usd: null
sent_usd: null
received_hops: null
sent_hops: null
percentage: 0
is_direct: true
country: null
provider_entity_id: null
network_nodes: []
network_edges: []
sanctions_hit: true
pep_counterparty: null
dominant_risk_category: sanctioned
risk_factors:
- source: attribution
category: sanctioned
label: Sanctions / OFAC
entity_name: Example Sanctions
direction: attribution
exposure_type: attribution
amount_usd: null
percentage: 0
is_high_risk: true
description: >-
the address is attributed to Sanctions / OFAC (Example
Sanctions)
- source: exposure
category: sanctioned
label: Sanctions / OFAC
entity_name: Example Sanctions
direction: incoming
exposure_type: direct
amount_usd: 9813695
percentage: 51.679304
is_high_risk: true
description: >-
51.6793% direct incoming exposure to Sanctions / OFAC
(Example Sanctions)
- source: exposure
category: defi
label: DeFi / Bridges
entity_name: Example DeFi 7
direction: outgoing
exposure_type: indirect
amount_usd: 7783414.38
percentage: 40.987766
is_high_risk: false
description: >-
40.9878% indirect outgoing exposure to DeFi / Bridges
(Example DeFi 7)
- source: exposure
category: defi
label: DeFi / Yield Aggregator
entity_name: Example DeFi 2
direction: outgoing
exposure_type: indirect
amount_usd: 1392494.37
percentage: 7.33293
is_high_risk: false
description: >-
7.33293% indirect outgoing exposure to DeFi / Yield
Aggregator (Example DeFi 2)
raw_response:
...: provider-specific details
report_signature:
'400':
description: >-
Errore di validazione — indirizzo non valido, `wallet_address`
mancante, `blockchain` non supportata, `blockchain` omessa per un
indirizzo il cui formato non indica alcuna rete, oppure LIGHTNING
senza una connessione Marketplace BYOK di Elliptic o Chainalysis.
'401':
description: '`x-api-key` mancante o non valida.'
'409':
description: >-
Nessun provider AML è configurato per l'applicazione, oppure il
provider configurato non supporta ancora lo screening dei wallet.
Configura prima il monitoraggio delle transazioni.
'422':
description: >-
`blockchain` omesso per un indirizzo `0x`, condiviso da ogni rete
EVM. Non viene eseguito alcuno screening né addebitato alcun costo;
invia nuovamente impostando `blockchain` su una delle
`candidate_chains`.
content:
application/json:
schema:
type: object
properties:
blockchain:
type: array
items:
type: string
example:
- >-
A 0x address is valid on every EVM chain. Send
blockchain as one of: ETH, BNB, MATIC, BASE, ARB, OP,
CELO, MODE, PLUME.
candidate_chains:
type: array
items:
type: string
example:
- ETH
- BNB
- MATIC
- BASE
- ARB
- OP
- CELO
- MODE
- PLUME
'502':
description: >-
Il fornitore AML non è riuscito a completare lo screening. Riprova
più tardi.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
curl -X POST 'https://verification.didit.me/v3/wallet-screening/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
"blockchain": "ETH"
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.wallet_screening.screen(
wallet_address="0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain="ETH",
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.walletScreening.screen({
wallet_address: "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain: "ETH",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.WalletScreening.Screen(ctx, didit.WalletScreeningScreenParams{\n\tWalletAddress: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n\tBlockchain: didit.Some(didit.WalletScreeningScreenParamsBlockchain(\"ETH\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.WalletScreeningScreenParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.walletScreening().screen(WalletScreeningScreenParams.builder()
.walletAddress("0x94f1b9b64e2932f6a2db338f616844400cd58e8a")
.blockchain(WalletScreeningScreenParams.Blockchain.of("ETH"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
walletScreening->screen([
'wallet_address' => '0x94f1b9b64e2932f6a2db338f616844400cd58e8a',
'blockchain' => 'ETH',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.wallet_screening.screen(
wallet_address: "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
blockchain: "ETH"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.WalletScreening.ScreenAsync(new
WalletScreeningScreenParams
{
WalletAddress = "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
Blockchain = new WalletScreeningScreenParamsBlockchain("ETH"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
WalletScreeningResult:
type: object
properties:
provider:
type: string
description: >-
Provider che ha eseguito lo screening (ad es. `merklescience`,
`crystal`).
screening_type:
type: string
enum:
- WALLET_SCREENING
description: Sempre `WALLET_SCREENING` per questo endpoint.
risk_score:
type: integer
description: >-
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:
type: string
enum:
- UNKNOWN
- LOW
- MEDIUM
- HIGH
- CRITICAL
description: >-
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.
status:
type: string
enum:
- SCREENED
- PENDING
- ERROR
description: Stato dell'esito dello screening.
summary:
type: string
description: Riepilogo leggibile dall'utente del risultato dello screening.
wallet_address:
type: string
description: L'indirizzo sottoposto a screening, restituito come conferma.
transaction_hash:
type: string
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
blockchain:
type: string
description: La blockchain sottoposta a screening.
block_timestamp:
type: string
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
total_value_usd:
type: number
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
fee_usd:
type: number
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
sender_rows:
type: array
items:
type: object
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre vuoto nel risultato dello screening dei
wallet.
receiver_rows:
type: array
items:
type: object
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre vuoto nel risultato dello screening dei
wallet.
transaction_flows:
type: array
items:
type: object
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre vuoto nel risultato dello screening dei
wallet.
transaction_flows_status:
type: string
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
transaction_flows_error:
type: string
nullable: true
description: >-
Campo dello screening delle transazioni, condiviso con la struttura
del risultato. Sempre `null` nel risultato dello screening dei
wallet.
source_of_funds:
type: array
description: >-
Da dove l'indirizzo ha ricevuto fondi, attribuiti per entità. Ogni
voce rappresenta una suddivisione dell'esposizione.
items:
type: object
properties:
category:
type: string
description: >-
Categoria di rischio normalizzata, ad es. `exchange_licensed`,
`dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`,
`sanctioned`, `stolen_funds`, `high_risk_exchange`.
percentage:
type: number
description: Quota dell'esposizione totale della direzione, 0-100.
amount_usd:
type: number
nullable: true
description: Valore in USD attribuito a questa entità.
entity_name:
type: string
nullable: true
description: >-
Nome dell'entità attribuita, ad esempio un exchange, un mixer
o un gruppo sanzionato.
entity_type:
type: string
nullable: true
description: >-
Tipo di entità del provider (ad es. `Exchange`, `DeFi`,
`Sanctions`, `Theft`).
entity_subtype:
type: string
nullable: true
description: >-
Sottotipo più granulare (ad es. `Mandatory KYC and AML`,
`OFAC`, `Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Numero di passaggi (hop) verso l'entità (1 per una controparte
diretta), quando il provider ne segnala uno. Sempre `null` per
Merkle Science, che indica solo se l'esposizione è diretta o
indiretta: utilizza `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, come il provider etichetta
l'entità.
is_direct:
type: boolean
description: True quando `exposure_type` è `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Indica se i fondi provenivano da (`incoming`) o sono andati a
(`outgoing`) questa entità.
exposure_type:
type: string
enum:
- direct
- indirect
description: Esposizione `direct` (1 hop) o `indirect` (multi-hop).
provider_entity_id:
type: string
nullable: true
description: L'identificatore del provider per l'entità.
provider_entity_type_id:
type: string
nullable: true
description: L'identificatore del provider per `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: L'identificatore del provider per `entity_subtype`.
country:
type: string
nullable: true
description: >-
Paese principale ISO 3166-1 alpha-2 dell'entità. Vuoto o
`null` se il fornitore non lo conosce.
raw_amount:
type: number
nullable: true
description: Importo nell'unità dell'asset, quando il fornitore lo riporta.
raw_currency:
type: string
nullable: true
description: Unità di `raw_amount`, quando segnalata dal provider.
destination_of_funds:
type: array
description: >-
A chi l'indirizzo ha inviato fondi, attribuiti per entità. Stessa
struttura degli elementi di `source_of_funds` con
`exposure_direction` = `outgoing`.
items:
type: object
properties:
category:
type: string
description: >-
Categoria di rischio normalizzata, ad es. `exchange_licensed`,
`dex`, `defi`, `payment_processor`, `mixer`, `darknet_market`,
`sanctioned`, `stolen_funds`, `high_risk_exchange`.
percentage:
type: number
description: Quota dell'esposizione totale della direzione, 0-100.
amount_usd:
type: number
nullable: true
description: Valore in USD attribuito a questa entità.
entity_name:
type: string
nullable: true
description: >-
Nome dell'entità attribuita, ad esempio un exchange, un mixer
o un gruppo sanzionato.
entity_type:
type: string
nullable: true
description: >-
Tipo di entità del provider (ad es. `Exchange`, `DeFi`,
`Sanctions`, `Theft`).
entity_subtype:
type: string
nullable: true
description: >-
Sottotipo più granulare (ad es. `Mandatory KYC and AML`,
`OFAC`, `Yield Aggregator`).
hops:
type: integer
nullable: true
description: >-
Numero di passaggi (hop) verso l'entità (1 per una controparte
diretta), quando il provider ne segnala uno. Sempre `null` per
Merkle Science, che indica solo se l'esposizione è diretta o
indiretta: utilizza `exposure_type`.
description:
type: string
nullable: true
description: >-
`entity_type / entity_subtype`, come il provider etichetta
l'entità.
is_direct:
type: boolean
description: True quando `exposure_type` è `direct`.
exposure_direction:
type: string
enum:
- incoming
- outgoing
- connected
description: >-
Indica se i fondi provenivano da (`incoming`) o sono andati a
(`outgoing`) questa entità.
exposure_type:
type: string
enum:
- direct
- indirect
description: Esposizione `direct` (1 hop) o `indirect` (multi-hop).
provider_entity_id:
type: string
nullable: true
description: L'identificatore del provider per l'entità.
provider_entity_type_id:
type: string
nullable: true
description: L'identificatore del provider per `entity_type`.
provider_entity_subtype_id:
type: string
nullable: true
description: L'identificatore del provider per `entity_subtype`.
country:
type: string
nullable: true
description: >-
Paese principale ISO 3166-1 alpha-2 dell'entità. Vuoto o
`null` se il fornitore non lo conosce.
raw_amount:
type: number
nullable: true
description: Importo nell'unità dell'asset, quando il fornitore lo riporta.
raw_currency:
type: string
nullable: true
description: Unità di `raw_amount`, quando segnalata dal provider.
counterparty_connections:
type: array
description: >-
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.
items:
type: object
properties:
entity_name:
type: string
nullable: true
description: Nome dell'entità attribuita.
entity_type:
type: string
nullable: true
description: Tipo di entità del provider.
entity_subtype:
type: string
nullable: true
description: Sottotipo di entità del provider.
risk_level:
type: string
description: >-
In lettere minuscole e dipendente dal provider. Per Merkle
Science corrisponde al livello di rischio 0-5 dell'indirizzo
stesso (`no_risk`, `low`, `medium_low`, `medium`, `high`,
`critical`), innalzato ad `high` quando la categoria
dell'entità è ad alto rischio; non si tratta di una
valutazione separata dell'entità.
categories:
type: array
items:
type: string
description: Categorie di rischio normalizzate dell'entità.
received_usd:
type: number
nullable: true
description: USD ricevuti dall'entità, quando comunicati dal provider.
sent_usd:
type: number
nullable: true
description: USD inviati all'entità, quando comunicati dal provider.
received_hops:
type: integer
nullable: true
description: >-
Salti verso l'entità sul lato ricevente, quando il provider li
segnala.
sent_hops:
type: integer
nullable: true
description: >-
Salti verso l'entità sul lato mittente, quando il provider li
segnala.
percentage:
type: number
description: >-
Quota dell'esposizione dell'indirizzo, quando riportata dal
fornitore; altrimenti 0.
is_direct:
type: boolean
description: >-
Sempre `true` per Merkle Science, le cui connessioni sono
attribuzioni anziché controparti.
country:
type: string
nullable: true
description: Paese dell'entità, se noto.
provider_entity_id:
type: string
nullable: true
description: L'identificatore del provider per l'entità.
network_nodes:
type: array
items:
type: object
description: >-
Nodi del grafo di esposizione per lo screening delle transazioni.
Vuoto nei risultati dello screening dei wallet.
network_edges:
type: array
items:
type: object
description: >-
Archi del grafo di esposizione per lo screening delle transazioni.
Vuoto nel risultato dello screening dei wallet.
sanctions_hit:
type: boolean
description: >-
True se l'indirizzo ha un'esposizione diretta o indiretta a
sanzioni.
pep_counterparty:
type: boolean
description: >-
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.
nullable: true
dominant_risk_category:
type: string
nullable: true
description: >-
Categoria ad alto rischio con il peso maggiore, o `null` quando
nessuna è dominante (ad es. `sanctioned`, `mixer`, `stolen_funds`).
risk_factors:
type: array
description: >-
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.
items:
type: object
properties:
source:
type: string
enum:
- attribution
- exposure
description: >-
`attribution` indica ciò che il provider afferma essere
l'indirizzo stesso (il suo tag o cluster); `exposure` indica
dove si sono effettivamente spostati i suoi fondi.
category:
type: string
description: >-
Categoria di rischio normalizzata, stesso vocabolario del
dettaglio dell'esposizione.
label:
type: string
description: >-
La dicitura originale del provider per il driver (ad es.
`Gambling / Crypto only`), che corrisponde a quanto
visualizzato anche nella console del provider.
entity_name:
type: string
nullable: true
description: >-
Entità attribuita all'origine del driver, ad esempio un sito
di scommesse o un exchange.
direction:
type: string
enum:
- incoming
- outgoing
- connected
- unknown
- attribution
description: >-
Direzione del flusso di fondi, `attribution` quando il fattore
determinante è il tag dell'indirizzo stesso, o `unknown`
quando il fornitore non ha riportato una direzione.
exposure_type:
type: string
enum:
- direct
- indirect
- unknown
- attribution
description: >-
`direct` (1 hop) o `indirect` (multi-hop), `attribution` per
il tag dell'indirizzo stesso, oppure `unknown` quando il
provider non ha specificato a quanti hop di distanza si trova
la controparte. Considera `unknown` come non classificato, non
come `direct`.
amount_usd:
type: number
format: float
nullable: true
description: Valore in USD attribuito a questo driver.
percentage:
type: number
format: float
description: >-
Quota del volume TOTALE analizzato dell'indirizzo, entrambe le
direzioni combinate - a differenza di `percentage` all'interno
di `source_of_funds`/`destination_of_funds`, che è
normalizzato per direzione. Confrontabile e sommabile
nell'intero elenco.
is_high_risk:
type: boolean
description: >-
Indica se la categoria è tra quelle che Didit tratta come ad
alto rischio (`sanctioned`, `mixer`, `stolen_funds`,
`ransomware`, `scam`, `darknet_market`, `terrorist_financing`,
`child_exploitation`, `hacked_exchange`, `high_risk_exchange`,
`seized_funds`).
description:
type: string
description: >-
Rappresentazione su una riga del driver, ad es. `9.01%
indirect outgoing exposure to Gambling / Crypto only (Example
Gambling)`.
raw_response:
type: object
additionalProperties: true
description: >-
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.
report_signature:
type: string
description: >-
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.
required:
- provider
- screening_type
- risk_score
- severity
- status
- summary
- wallet_address
- blockchain
- sanctions_hit
- dominant_risk_category
- source_of_funds
- destination_of_funds
- counterparty_connections
- report_signature
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.