On-demand Wallet Screening API: No Transaction Required

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`, `BASE`, `OP`, `ARB`, `CELO`, `MODE`, `PLUME`, `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).

Chain coverage

Managed screening supports Base (BASE), Optimism (OP) and Arbitrum One (ARB) for both wallet and transaction-hash screening. Connected providers may have different coverage; a chain must also be supported by your selected provider and account. Celo (CELO), Mode (MODE) and Plume (PLUME) are screened through a connected TRM Labs account (Marketplace, bring your own key); managed screening does not cover them and answers 400. Do not submit ETH for another EVM network: the same address can have different activity and risk on each chain. With managed screening, USDT and USDC are legacy aliases for Ethereum, not a search across every network where those tokens exist. Use the network identifier (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, or with TRM Labs CELO, MODE or PLUME) for the wallet’s actual chain. For tokens in recorded transactions, keep the token in transaction_details.currency and specify the network separately in transaction_details.crypto_params.crypto_chain. See asset and network selection.

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": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
    "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. Merkle Science grades an address `0-5`, which maps to `0`, `15`, `35`, `55`, `75` or `95`.
`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	`true` when the screened wallet is sanctioned, or when any of its counterparties’ funds came from sanctioned entities (exposure). It does not distinguish the two.
`pep_counterparty`	boolean \| null	Politically exposed person exposure. `null` when no PEP finding is available, which is every result today because no provider reports one; `false` only for an explicit negative screening result. Do not read `null` as a completed PEP check.
`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 entity. See Exposure breakdown.
`destination_of_funds`	array	Where funds were sent to, by entity. Same entry shape as `source_of_funds`.
`counterparty_connections`	array	Entities the provider attributes the address to. See Counterparty connections.
`network_nodes`, `network_edges`	array	Graph of the exposure for transaction screening. Empty on a wallet screening result.
`transaction_hash`, `block_timestamp`, `total_value_usd`, `fee_usd`, `transaction_flows_status`, `transaction_flows_error`	null	Transaction screening fields, shared with the result shape. Always `null` on a wallet screening result.
`sender_rows`, `receiver_rows`, `transaction_flows`	array	Transaction screening fields. Always empty on a wallet screening result.
`raw_response`	object	The provider’s own payload. Its shape is provider-specific and can change without notice: read the normalised fields above instead of parsing it.
`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, for example a gambling site or an exchange. The examples on this page use placeholders such as `Example Gambling`.
`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 (Example Gambling)`.

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.

Exposure breakdown

Each entry in source_of_funds / destination_of_funds describes one entity the address exchanged funds with:

Field	Type	Description
`category`	string	Normalised risk category (`exchange_licensed`, `dex`, `defi`, `mixer`, `sanctioned`, `darknet_market`, `stolen_funds`, …).
`entity_name`	string \| null	Attributed entity, for example an exchange, a mixer or a sanctioned group. The examples on this page use placeholders.
`entity_type`	string \| null	Provider entity type (`Exchange`, `DeFi`, `Sanctions`).
`entity_subtype`	string \| null	Granular subtype (`Mandatory KYC and AML`, `OFAC`).
`description`	string \| null	`entity_type / entity_subtype`, as the provider labels the entity.
`exposure_direction`	string	`incoming`, `outgoing`, or `connected`.
`exposure_type`	string	`direct` (1 hop) or `indirect` (multi-hop).
`is_direct`	boolean	`true` when `exposure_type` is `direct`.
`amount_usd`	number \| null	USD value attributed to the entity.
`percentage`	number	Share of the direction’s total exposure (0–100).
`hops`	integer \| null	Number of hops to the entity (`1` for a direct counterparty), when the provider reports one. Always `null` for Merkle Science, which reports only whether exposure is direct or indirect: use `exposure_type`.
`country`	string \| null	Primary ISO 3166-1 alpha-2 country of the entity. Empty or `null` when the provider does not know it.
`provider_entity_id`, `provider_entity_type_id`, `provider_entity_subtype_id`	string \| null	The provider’s own identifiers for the entity and its type.
`raw_amount`, `raw_currency`	number \| null, string \| null	Amount in the asset’s own unit, when the provider reports it.

Counterparty connections

counterparty_connections lists the entities the provider attributes the screened address to. For Merkle Science these come from the address’s own owner and user tags, so the same entity can appear twice, and they carry no fund flows: received_usd, sent_usd, received_hops and sent_hops are null, and percentage is 0.0. Read the fund flows from source_of_funds and destination_of_funds.

Field	Type	Description
`entity_name`	string \| null	Attributed entity.
`entity_type`	string \| null	Provider entity type.
`entity_subtype`	string \| null	Granular subtype.
`categories`	array	Normalised risk categories of the entity.
`risk_level`	string	Lowercase, provider-dependent. For Merkle Science it is the address’s own 0-5 risk grade (`no_risk`, `low`, `medium_low`, `medium`, `high`, `critical`), raised to `high` when the entity’s category is high risk; it is not a separate grade of the entity.
`is_direct`	boolean	Always `true` for Merkle Science, whose connections are attributions rather than counterparties.
`received_usd`, `sent_usd`	number \| null	USD received from and sent to the entity, when the provider reports it.
`received_hops`, `sent_hops`	integer \| null	Hops to the entity in each direction, when the provider reports them.
`percentage`	number	Share of the address’s exposure, when the provider reports it; otherwise `0.0`.
`country`	string \| null	Country of the entity, when known.
`provider_entity_id`	string \| null	The provider’s own identifier for the entity.

Do not route on counterparty_connections[].risk_level or counterparty_connections[].is_direct: for Merkle Science the first repeats the address’s own grade (read risk_score) and the second is always true. Use sanctions_hit, dominant_risk_category and risk_factors[].is_high_risk for the verdict, and exposure_type in source_of_funds / destination_of_funds for directness.

Example

A real response for an address on the OFAC sanctions list, screened with Merkle Science. Only raw_response is shortened and report_signature replaced:

{
  "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.0,
      "amount_usd": 9813695.0,
      "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.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.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.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.0,
      "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": "<hmac-sha256 over the result, scoped to your application>"
}

The examples illustrate the response shape, not a guaranteed verdict for a real address. Risk scores and sanctions exposure depend on the selected network, current intelligence and the configured risk policy. An exchange attribution does not imply a zero risk score: an exchange wallet can have sanctions exposure through its fund flows. sanctions_hit: true can indicate that the wallet itself is sanctioned or only that its funds have sanctions exposure, so it does not by itself mean the screened wallet owner is sanctioned. When the same screening runs on a recorded transaction, rules can also read custom_values.wallet_sanctioned, which is true only when the provider attributes the wallet itself to a sanctioned entity, and custom_values.aml_sanctions_exposure_pct. See Screening fields for rules. Read risk_factors, source_of_funds and destination_of_funds to distinguish attribution from exposure. See Crypto & Wallet Screening for a walkthrough.

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": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "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.
`409`	The provider rejected the API key you connected (`wallet_screening_provider_credentials_rejected`) - update the key on the Marketplace connection, or in the transaction monitoring settings for a key configured there. Retrying with the same key does not help.
`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

On-demand Wallet Screening API: No Transaction Required

When to use it

Prerequisites

Request

Chain coverage

Response

Risk factors

Exposure breakdown

Counterparty connections

Example

PDF report

Billing

Errors

Next steps

API reference

Screen Wallet PDF

Crypto & wallet screening

​When to use it

​Prerequisites

​Request

​Chain coverage

​Response

​Risk factors

​Exposure breakdown

​Counterparty connections

​Example

​PDF report

​Billing

​Errors

​Next steps

API reference

Screen Wallet PDF

Crypto & wallet screening

When to use it

Prerequisites

Request

Chain coverage

Response

Risk factors

Exposure breakdown

Counterparty connections

Example

PDF report

Billing

Errors

Next steps