On-demand Wallet Screening

Sometimes you need to check a crypto wallet’s AML risk before there is any transaction to record — for example, when a customer adds a withdrawal address, or when your compliance team wants to vet an address ad hoc. The on-demand wallet screening endpoint screens a single address and returns the full risk result without creating a transaction. This is the standalone counterpart to the automatic crypto screening that runs during transaction submission. Both share the same blockchain analytics providers and the same result shape.

When to use it

Use case	Endpoint
Pre-check an address with no transaction to record	Wallet screening — `POST /v3/wallet-screening/`
Screen a wallet as part of a recorded deposit/withdrawal	Create Transaction with `currency_kind: "crypto"`

Wallet screening writes nothing to the transactions table. If you need the screening attached to a monitored transaction (with rules, alerts, and webhooks), submit a transaction instead.

Prerequisites

Transaction monitoring must be configured for the application — a provider with a managed key or your own BYOK key. Configure it in Transactions > Settings > Provider Preferences in the Business Console. If no provider is configured, the endpoint returns 409 Conflict.

Request

POST https://verification.didit.me/v3/wallet-screening/ Authenticate with the x-api-key header.

Field	Type	Required	Description
`wallet_address`	string	Yes	The address to screen. Must match the format of the chosen chain (e.g. `0x` + 40 hex chars for EVM chains). Alias: `address`.
`blockchain`	string	Yes	Asset / chain identifier: `BTC`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `USDT`, `USDC`. Alias: `currency`.
`direction`	string	No	`inbound`, `outbound`, `deposit`, or `withdrawal`. Optional context for the provider; omit for a neutral pre-transfer screen. It does not change the returned `risk_score`, `severity`, or the funds-flow breakdowns (see the note under Response).

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": "0x28c6c06298d514db089934071355e5743bf21d60",
    "blockchain": "ETH"
  }'

Response

The response is the standardised screening result — identical in shape to the WALLET_SCREENING provider result returned by transaction screening.

Field	Type	Description
`provider`	string	Provider that screened the address (`merklescience`, `crystal`, `chainalysis`, `elliptic`, `trmlabs`).
`screening_type`	string	Always `WALLET_SCREENING`.
`risk_score`	integer	Normalised 0–100 risk score.
`severity`	string	Risk bucket derived from `risk_score` (see note below): `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.
`status`	string	`SCREENED`, `PENDING`, or `ERROR`.
`summary`	string	Human-readable summary.
`wallet_address`	string	The screened address.
`blockchain`	string	The screened chain.
`sanctions_hit`	boolean	Direct or indirect sanctions exposure.
`dominant_risk_category`	string \| null	Highest-weighted high-risk category, or `null`.
`source_of_funds`	array	Where funds were received from, by category.
`destination_of_funds`	array	Where funds were sent to, by category.
`counterparty_connections`	array	Direct/indirect counterparties with amounts and risk levels.

How severity is set. severity is the band of the normalised risk_score: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN is the lowest band, not a separate “no data” state: risk_score: 0 (the common clean-address case) means the provider returned no adverse assessment, while a non-zero score in the 1-9 range is a real but sub-LOW signal - so read the risk_score itself, not just the band. Either way, do not render UNKNOWN as an affirmative “clear” or pass.direction does not change the risk model. The optional direction field is passed to the provider as context only. It does not affect risk_score, severity, or which breakdown lists are returned: both source_of_funds and destination_of_funds are always returned regardless. Changing or omitting direction therefore does not require re-screening a previously screened address.

Each entry in source_of_funds / destination_of_funds is an exposure breakdown with these fields:

Field	Type	Description
`category`	string	Normalised risk category (`exchange_licensed`, `dex`, `defi`, `mixer`, `sanctioned`, `darknet_market`, `stolen_funds`, …).
`entity_name`	string	Attributed entity (e.g. `Binance.com`, `Tornado Cash`).
`entity_type`	string	Provider entity type (`Exchange`, `Mixer`, `DeFi`, `Sanctions`).
`entity_subtype`	string	Granular subtype (`Mandatory KYC and AML`, `OFAC SDN`).
`exposure_direction`	string	`incoming`, `outgoing`, or `connected`.
`exposure_type`	string	`direct` (1 hop) or `indirect` (multi-hop).
`amount_usd`	number	USD value attributed to the entity.
`percentage`	number	Share of the direction’s total exposure (0–100).
`hops`	integer	Hops to the entity (0 for direct).
`country`	string	Primary ISO 3166-1 alpha-2 country of the entity.

{
  "provider": "merklescience",
  "screening_type": "WALLET_SCREENING",
  "risk_score": 72,
  "severity": "HIGH",
  "status": "SCREENED",
  "summary": "Merkle Science risk: High (4/5). Dominant risk: mixer",
  "wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "blockchain": "ETH",
  "sanctions_hit": true,
  "dominant_risk_category": "mixer",
  "source_of_funds": [
    {
      "category": "exchange_licensed",
      "entity_name": "Binance.com",
      "entity_type": "Exchange",
      "entity_subtype": "Mandatory KYC and AML",
      "exposure_direction": "incoming",
      "exposure_type": "direct",
      "is_direct": true,
      "amount_usd": 18420.55,
      "percentage": 61.4,
      "hops": 0,
      "country": "SC"
    },
    {
      "category": "mixer",
      "entity_name": "Tornado Cash",
      "entity_type": "Mixer",
      "entity_subtype": "OFAC SDN",
      "exposure_direction": "incoming",
      "exposure_type": "indirect",
      "is_direct": false,
      "amount_usd": 11580.20,
      "percentage": 38.6,
      "hops": 2,
      "country": "RU"
    }
  ],
  "destination_of_funds": [
    {
      "category": "exchange_licensed",
      "entity_name": "Coinbase",
      "entity_type": "Exchange",
      "entity_subtype": "Mandatory KYC and AML",
      "exposure_direction": "outgoing",
      "exposure_type": "direct",
      "is_direct": true,
      "amount_usd": 30000.75,
      "percentage": 100.0,
      "hops": 0,
      "country": "US"
    }
  ],
  "counterparty_connections": [
    {
      "entity_name": "Tornado Cash",
      "entity_type": "Mixer",
      "entity_subtype": "OFAC SDN",
      "risk_level": "CRITICAL",
      "categories": ["mixer"],
      "received_usd": 11580.20,
      "sent_usd": 0.0,
      "received_hops": 2,
      "sent_hops": 0,
      "percentage": 38.6,
      "is_direct": false,
      "country": "RU"
    }
  ]
}

A clean address returns the same shape with risk_score near 0, sanctions_hit: false, dominant_risk_category: null, and licensed-exchange-only entries. See Crypto & Wallet Screening for a full walkthrough of the risk categories, exposure table, and network graph.

Billing

One AML monitoring usage is billed per successful screening, at the same per-screening rate as transaction-coupled crypto screening (managed or BYOK — see pricing). Sandbox applications are not billed. Validation errors (400) and unconfigured-provider errors (409) are never billed.

Errors

Status	Meaning
`400`	Malformed wallet address, missing `wallet_address`, or unsupported `blockchain`.
`401`	Missing or invalid `x-api-key`.
`409`	No AML provider configured for the application — configure transaction monitoring first.
`502`	The provider could not complete the screening; retry later.

Getting Started

Features

Reference

Console

When to use it

Prerequisites

Request

Response

Billing

Errors

Next steps

API reference

Crypto & wallet screening

​When to use it

​Prerequisites

​Request

​Response

​Billing

​Errors

​Next steps

API reference

Crypto & wallet screening

When to use it

Prerequisites

Request

Response

Billing

Errors

Next steps