> ## 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.
# On-demand Wallet Screening
> Screen a single crypto wallet address for AML risk without creating a transaction. Source of funds, sanctions exposure, and risk score on demand.
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](/transaction-monitoring/aml-screening) that runs during [transaction submission](/transaction-monitoring/transactions). 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](/transaction-monitoring/transactions) 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](/transaction-monitoring/aml-screening#supported-providers) key. Configure it in **Transactions** > **Settings** > **Provider Preferences** in the [Business Console](https://business.didit.me). 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](#response)). |
```bash theme={null}
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. |
```json theme={null}
{
"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](/transaction-monitoring/aml-screening#screening-results) 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](/transaction-monitoring/aml-screening#supported-providers)). 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. |
## Next steps
Full request and response schema for the Screen Wallet endpoint.
Automatic screening during transaction creation and the result model.