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 with either a managed provider or an existing provider 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 or network identifier to screen. Must match the chosen network, such as `0x` + 40 hex characters for EVM chains or a Lightning identifier accepted by your provider. Alias: `address`.
`blockchain`	string	Yes	Asset / network identifier: `BTC`, `LIGHTNING`, `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).

LIGHTNING is available only when the application has a connected Elliptic or Chainalysis BYOK provider in the console Marketplace. It is not available with managed Merkle Science or with Crystal or TRM Labs. Requests without a supported connected provider return 400 and are not screened or billed.

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`.
`risk_factors`	array	Ranked explanation of `risk_score` — what produced this verdict. See Risk factors.
`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.
`report_signature`	string	Opaque signature over this result, scoped to your application. Repost the response unmodified, including this field, to render it as a PDF.

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.

Risk factors

risk_factors is the ranked answer to “why is this address scored the way it is”. Providers grade an address on their own model and return only a verdict — Merkle Science returns an integer 0-5 — so risk_score alone cannot be actioned. Each entry names one driver, ordered high-risk first and then by the value that moved through it.

Field	Type	Description
`source`	string	`attribution` (what the provider says the address is — its own tag or cluster) or `exposure` (where its funds actually moved).
`category`	string	Normalised risk category, same vocabulary as the exposure breakdown.
`label`	string	The provider’s own wording, e.g. `Gambling / Crypto only`. Use this in a UI — it matches what you would see in the provider’s console.
`entity_name`	string \| null	Attributed entity, e.g. `Nitrogen Sports EU`.
`direction`	string	`incoming`, `outgoing`, `connected`, `attribution` (the address’s own tag), or `unknown` when the provider did not report a direction.
`exposure_type`	string	`direct` (1 hop), `indirect` (multi-hop), `attribution` (the address’s own tag), or `unknown` when the provider did not state how many hops away the counterparty is. Treat `unknown` as unclassified, never as `direct`.
`amount_usd`	number \| null	USD value attributed to this driver.
`percentage`	number	Share of the address’s total screened volume, both directions combined — unlike `percentage` inside `source_of_funds` / `destination_of_funds`, which is normalised per direction. Comparable and summable across the whole list.
`is_high_risk`	boolean	Whether the category is one Didit treats as high risk (`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`, `darknet_market`, `terrorist_financing`, `child_exploitation`, `hacked_exchange`, `high_risk_exchange`, `seized_funds`).
`description`	string	One-line rendering of the driver, e.g. `9.01% indirect outgoing exposure to Gambling / Crypto only (Nitrogen Sports EU)`.

A high score with no is_high_risk factor is a real, meaningful outcome. It means the provider graded the address on its own exposure model without reporting a sanctions, PEP or attributed-entity match — the factors that are listed are the fund flows behind the grade. summary states this explicitly, so treat these addresses as “review the flows”, not as a confirmed hit. risk_factors is capped at the five strongest drivers; source_of_funds and destination_of_funds always carry the complete breakdown.risk_factors is a top-level field, not a nested one. Results screened before it existed omit the key entirely — read it as an empty list rather than assuming an empty explanation.

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). SANCTIONS HIT. Dominant risk: mixer. Driven by: 38.6% indirect incoming exposure to Mixer / OFAC SDN (Tornado Cash); 61.4% direct incoming exposure to Exchange / Mandatory KYC and AML (Binance.com)",
  "wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "blockchain": "ETH",
  "sanctions_hit": true,
  "dominant_risk_category": "mixer",
  "risk_factors": [
    {
      "source": "exposure",
      "category": "mixer",
      "label": "Mixer / OFAC SDN",
      "entity_name": "Tornado Cash",
      "direction": "incoming",
      "exposure_type": "indirect",
      "amount_usd": 11580.20,
      "percentage": 19.16,
      "is_high_risk": true,
      "description": "19.16% indirect incoming exposure to Mixer / OFAC SDN (Tornado Cash)"
    },
    {
      "source": "exposure",
      "category": "exchange_licensed",
      "label": "Exchange / Mandatory KYC and AML",
      "entity_name": "Coinbase",
      "direction": "outgoing",
      "exposure_type": "direct",
      "amount_usd": 30000.75,
      "percentage": 49.64,
      "is_high_risk": false,
      "description": "49.64% direct outgoing exposure to Exchange / Mandatory KYC and AML (Coinbase)"
    }
  ],
  "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"
    }
  ],
  "report_signature": "3f9c2e1a7b4d6f80c5e9a1b2d3f4e5061728394a5b6c7d8e9f0a1b2c3d4e5f6"
}

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

PDF report

To get a Didit-branded PDF of a screening result, repost the exact response body — including report_signature — to POST /v3/wallet-screening/pdf/. This is stateless: no provider call, no additional billing, nothing persisted. Editing any signed field (risk_score, severity, sanctions_hit, …) before reposting fails with 400.

RESULT=$(curl -s -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"}')

curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$RESULT" \
  -o wallet_screening_report.pdf

See Screen Wallet PDF for the full request/response schema and error shapes.

Billing

One AML monitoring usage is billed per successful screening at the same rate as transaction-coupled crypto screening. See pricing for managed and connected-key rates. 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

API reference

Full request and response schema for the Screen Wallet endpoint.

Screen Wallet PDF

Render a screening result as a Didit-branded PDF.

Crypto & wallet screening

Automatic screening during transaction creation and the result model.

Getting Started

Features

Reference

Console

When to use it

Prerequisites

Request

Response

Risk factors

PDF report

Billing

Errors

Next steps

API reference

Screen Wallet PDF

Crypto & wallet screening

​When to use it

​Prerequisites

​Request

​Response

​Risk factors

​PDF report

​Billing

​Errors

​Next steps

API reference

Screen Wallet PDF

Crypto & wallet screening

When to use it

Prerequisites

Request

Response

Risk factors

PDF report

Billing

Errors

Next steps