Skip to main content
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 caseEndpoint
Pre-check an address with no transaction to recordWallet screening — POST /v3/wallet-screening/
Screen a wallet as part of a recorded deposit/withdrawalCreate 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.
FieldTypeRequiredDescription
wallet_addressstringYesThe address to screen. Must match the format of the chosen chain (e.g. 0x + 40 hex chars for EVM chains). Alias: address.
blockchainstringYesAsset / chain identifier: BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, USDT, USDC. Alias: currency.
directionstringNoinbound, outbound, deposit, or withdrawal. Optional context for the provider; omit for a neutral pre-transfer screen.
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.
FieldTypeDescription
providerstringProvider that screened the address (merklescience, crystal).
screening_typestringAlways WALLET_SCREENING.
risk_scoreintegerNormalised 0–100 risk score.
severitystringUNKNOWN, LOW, MEDIUM, HIGH, or CRITICAL.
statusstringSCREENED, PENDING, or ERROR.
summarystringHuman-readable summary.
wallet_addressstringThe screened address.
blockchainstringThe screened chain.
sanctions_hitbooleanDirect or indirect sanctions exposure.
dominant_risk_categorystring | nullHighest-weighted high-risk category, or null.
source_of_fundsarrayWhere funds were received from, by category.
destination_of_fundsarrayWhere funds were sent to, by category.
counterparty_connectionsarrayDirect/indirect counterparties with amounts and risk levels.
{
  "provider": "merklescience",
  "screening_type": "WALLET_SCREENING",
  "risk_score": 15,
  "severity": "LOW",
  "status": "SCREENED",
  "summary": "Merkle Science risk: Low (1/5). Dominant risk: exchange_licensed",
  "wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "blockchain": "ETH",
  "sanctions_hit": false,
  "dominant_risk_category": null,
  "source_of_funds": [],
  "destination_of_funds": [],
  "counterparty_connections": []
}
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

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

​
Next steps

API reference

Full request and response schema for the Screen Wallet endpoint.

Crypto & wallet screening

Automatic screening during transaction creation and the result model.