Wallet Screening API: On-Chain Risk at $0.02 (BYOK)

A KYC check tells you a wallet's owner is a real person. It tells you nothing about where the coins in that wallet have been. On-chain, a wallet that looks ordinary can be one hop from a sanctioned address, two hops from a darknet market, or fresh out of a mixer. Wallet screening — Know Your Transaction (KYT) — is the layer that reads that history before you let the value move.

Didit's Wallet Screening API scores any crypto wallet address or transaction hash against on-chain risk intelligence. You send an address, it returns a 0–100 risk score, a LOW/MEDIUM/HIGH/CRITICAL band, and a breakdown of which risk categories the funds are exposed to — sanctions, mixers, darknet markets, ransomware, stolen funds, and more. It costs $0.02 per screening with bring-your-own-key (BYOK), roughly 10× cheaper than buying a blockchain-analytics subscription direct.

This guide covers what the API screens for, how the scoring works, and how to wire it into a deposit or withdrawal flow.

Key takeaways

• One call, on-chain risk. Send a wallet address (pre-transfer) or a transaction hash (post-transfer) and get a risk verdict back.
• 0–100 risk score mapped to four bands — LOW / MEDIUM / HIGH / CRITICAL — so policy is a single threshold, not a research project.
• 14+ source-of-funds categories — SANCTIONED, TERRORIST_FINANCING, RANSOMWARE, DARKNET_MARKET, MIXER, STOLEN_FUNDS, SCAM, and more — each shown by exposure type.
• Exposure table + network graph — direct and indirect (multi-hop) exposure so you see not just the counterparty but where its funds came from.
• BYOK at $0.02 per screening. Bring your own Crystal or Merkle Science key; Chainalysis and Elliptic are coming soon. Managed pricing is also available.
• Built into Transaction Monitoring — crypto transactions can trigger wallet screening automatically, with no extra plumbing.

What wallet screening does

Blockchains are public ledgers, but raw transaction data is not risk data. Turning an address into a risk verdict requires a clustering and labeling layer that maps addresses to real-world entities — exchanges, mixers, sanctioned wallets, ransomware operators, darknet markets — and then traces how value flows between them.

Didit's Wallet Screening API sits on top of that intelligence. Give it a wallet address and it analyzes the address's exposure: how much of its inbound and outbound value connects to risky entities, directly or through intermediary hops. It returns a single risk score, the band that score falls into, and the categories driving the risk — so a compliance policy can be expressed as "block CRITICAL, review HIGH, pass the rest."

Why it matters

For any business that touches crypto — an exchange, an on/off-ramp, a custodian, a wallet, a VASP — accepting funds is accepting their history. Sanctions exposure is the sharpest edge: moving value to or from a wallet on a sanctions list is a violation regardless of intent. But the practical risk is broader. Funds laundered through a mixer, proceeds of a ransomware payment, or coins drained in an exploit all surface as on-chain exposure long before they show up anywhere else.

The classic problem is cost. Blockchain-analytics platforms are sold as enterprise subscriptions with five- and six-figure annual minimums — a real barrier for a team that just needs to screen wallets at the point of deposit. Didit removes that barrier with BYOK: you bring your own provider key, pay $0.02 per screening through Didit's unified API, and skip the seat licenses entirely.

Technical details

Wallet screening runs inside Transaction Monitoring on the unified /v3/ API. When you submit a crypto transaction, the engine can screen the counterparty automatically; you can also screen explicitly by setting currency_kind: "crypto" with a direction.

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_5b21fa",
    "category": "finance",
    "amount": 12500,
    "currency": "USDT",
    "currency_kind": "crypto",
    "direction": "INBOUND",
    "wallet_address": "0x9f1c...e3a2",
    "include_crypto_screening": true,
    "subject": { "vendor_data": "user_7781", "role": "RECEIVER" }
  }'

The response carries the screening verdict — a numeric score, the band, and the exposure breakdown:

{
  "transaction_id": "txn_5b21fa",
  "status": "IN_REVIEW",
  "wallet_screening": {
    "risk_score": 78,
    "risk_band": "HIGH",
    "provider": "crystal",
    "exposure": [
      { "category": "MIXER", "type": "INDIRECT", "hops": 2, "share": 0.34 },
      { "category": "DARKNET_MARKET", "type": "INDIRECT", "hops": 3, "share": 0.11 }
    ]
  }
}

Risk score and bands. Every screening returns a 0–100 score mapped to four bands:

Band	Score	Typical policy
LOW	0–24	Pass
MEDIUM	25–49	Pass with logging / soft review
HIGH	50–79	Hold for analyst review
CRITICAL	80–100	Decline / freeze

Source-of-funds categories. Exposure is attributed to specific categories — SANCTIONED, TERRORIST_FINANCING, CHILD_EXPLOITATION, RANSOMWARE, STOLEN_FUNDS, DARKNET_MARKET, MIXER, SCAM, HIGH_RISK_EXCHANGE, HIGH_RISK_JURISDICTION, GAMBLING_UNLICENSED, P2P_EXCHANGE, EXCHANGE, and UNNAMED_SERVICE — so you see the reason for a score, not just the number.

Exposure type and network graph. Each category is reported as direct (the wallet transacted with the risky entity) or indirect (value reached it through intermediary hops), with the hop count. A network graph traces the path so an analyst can see how the funds connect.

Price. $0.02 per screening with BYOK (Crystal or Merkle Science). Managed pricing — where Didit provides the data — is $0.18 per screening with Crystal and $0.15 with Merkle Science.

Pre-transfer and post-transfer screening

Wallet screening works at two points in the flow. Pre-transfer screening takes a wallet address and assesses its risk before you accept a deposit or release a withdrawal — the decision happens before value moves. Post-transfer screening takes a transaction hash (passed as payment_reference_id) and assesses a settled transaction after the fact, for record-keeping and ongoing review. Most teams run both: pre-transfer to gate the flow, post-transfer to keep an auditable trail.

Use cases

• Crypto exchanges — screen every deposit address on the way in and every withdrawal destination on the way out; auto-decline CRITICAL, route HIGH to an analyst.
• On/off-ramps — gate fiat-to-crypto and crypto-to-fiat conversions on the counterparty wallet's exposure before settling.
• Custodians — screen wallets at intake and re-screen on movement, with the network graph as evidence for any frozen asset.
• Wallets — protect users by warning or blocking transfers to addresses with high sanctions or scam exposure.
• VASPs — combine wallet screening with FATF Travel Rule data exchange so counterparty and origin risk are assessed together.

How to integrate with Didit

1. Set your provider and default. In the Business Console under Transactions → Settings, choose Crystal or Merkle Science, add your BYOK key, and set whether crypto transactions screen by default.
2. Send crypto transactions. POST /v3/transactions/ with currency_kind: "crypto" and a direction. Use include_crypto_screening to override the default per call.
3. Read the verdict. Act on risk_band and the exposure breakdown — pass LOW/MEDIUM, hold HIGH, decline CRITICAL.
4. Work alerts in the Console. A high-risk screening opens an alert with the network graph attached, ready for investigation and SAR filing.

Because it's all on the unified /v3/ API, wallet screening, transaction monitoring, KYC, and AML compose into one identity-and-fraud platform — a flagged wallet can pause a transaction and trigger a remediation step automatically.

Frequently asked questions

How much does wallet screening cost?

$0.02 per screening with bring-your-own-key (Crystal or Merkle Science) — roughly 10× cheaper than buying a blockchain-analytics subscription direct. Managed pricing is $0.18 (Crystal) or $0.15 (Merkle Science) per screening.

Which blockchain-analytics providers are supported?

Crystal and Merkle Science today, via BYOK or managed. Chainalysis and Elliptic are coming soon, also at $0.02 BYOK.

What's the difference between the risk score and the risk band?

The score is a 0–100 number; the band (LOW/MEDIUM/HIGH/CRITICAL) is the bucket it falls into, so you can write policy against a label instead of tuning numeric thresholds yourself.

Can I screen a wallet without sending money?

Yes. Pre-transfer screening takes a wallet address and returns risk before any value moves, so you can decide whether to accept a deposit or release a withdrawal.

Does it cover indirect exposure, not just the direct counterparty?

Yes. Exposure is reported as direct or indirect with hop counts, and a network graph traces how funds reached a risky entity through intermediaries.

Ready to get started?

Read the Wallet Screening overview in the docs, see how it fits the platform on the Wallet Screening product page, and check transparent per-call pricing on the pricing page. When you're ready, start free — 500 free KYC checks every month, and wallet screening at $0.02 per screening with BYOK.