Crypto & Wallet Screening

For cryptocurrency transactions, Didit can screen wallet addresses and transaction hashes against blockchain analytics providers such as Merkle Science, Crystal, Chainalysis, Elliptic, and TRM Labs during transaction creation. Screening runs server-side — no additional API calls are needed from your side.

Need to screen an address without a transaction? Use the on-demand wallet screening endpoint (POST /v3/wallet-screening/) to get the same risk result for a single wallet with one API call.

How screening triggers

Crypto screening runs automatically when both conditions are met:

The transaction has currency_kind: "crypto" in its transaction details
Transaction monitoring is enabled in your application settings

You can override this default per transaction with include_crypto_screening in the create transaction payload:

Value	Behaviour
`true`	Run crypto screening even if the application-level default is disabled
`false`	Skip crypto screening even if the application-level default is enabled
omitted or `null`	Use the application-level default configured in the Console

The application-level default lives in Transactions > Settings in the Business Console. include_crypto_screening only overrides that default for the single transaction you are creating.

Asset and network selection

The asset and the network are separate fields. Set transaction_details.currency to the token symbol, transaction_details.currency_kind to crypto, and transaction_details.crypto_params.crypto_chain to the network. For example, this fragment records a custom token on Base:

{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}

Managed screening accepts BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP and ARB. BASE means Base, OP means Optimism and ARB means Arbitrum One. Celo, Mode and Plume are not currently supported by the managed integration. Connected providers have their own coverage; Lightning has additional requirements below. Always specify crypto_chain for a token, including USDT and USDC. Without it, the currency is used as the network; USDT and USDC default to Ethereum unless a transaction hash selects Tron or Solana. A 0x hash alone cannot distinguish Ethereum from another EVM network. Never substitute ETH for the actual network. Recording a custom token symbol does not guarantee that its transfers are indexed for transaction-hash screening. Token coverage must be checked using the token contract and network. A created transaction is not proof of successful screening: inspect the screening status and provider result before treating it as screened.

Inbound vs outbound

transaction_details.direction is required because it tells Didit which side of the transfer should be screened.

Direction	Before the on-chain transfer	After the on-chain transfer
Inbound (deposits)	Screen the counterparty sender wallet, if you provide it in `counterparty.payment_method.account_id`	Screen the transaction hash scoped to your service/customer deposit address in `subject.payment_method.account_id`
Outbound (withdrawals)	Screen the destination wallet in `counterparty.payment_method.account_id` before you send funds	Screen the transaction hash scoped to the same destination wallet in `counterparty.payment_method.account_id`

For pre-transfer screening, omit transaction_details.payment_reference_id; Didit runs wallet screening on the relevant wallet address. For post-transfer screening, include the blockchain transaction hash in transaction_details.payment_reference_id; Didit runs transaction screening and stores transaction summary data when on-chain enrichment is available.

Lightning Network

Set transaction_details.crypto_params.crypto_chain to LIGHTNING for Lightning Network screening. Lightning screening requires a connected Elliptic or Chainalysis BYOK provider in the console Marketplace. Managed Merkle Science, Crystal, and TRM Labs do not accept LIGHTNING; Didit rejects those requests with 400 before screening or billing. For Elliptic, Didit screens the supplied Lightning identifier through Elliptic’s BTC Lightning wallet analysis. For Chainalysis, Didit submits a Lightning transfer to KYT when transaction_details.payment_reference_id is present.

Required fields

For all crypto screening requests, send:

transaction_details.direction — INBOUND or OUTBOUND
transaction_details.currency_kind — crypto
transaction_details.currency — the asset symbol, for example BTC, ETH, USDC or your custom token
A wallet address in the participant selected by the direction rules above

For transaction-hash screening after the transfer is on-chain, also send:

transaction_details.payment_reference_id — the blockchain transaction hash

If crypto screening is enabled and the required wallet address for the direction is missing, the Create Transaction API rejects the request.

Example: pre-transfer outbound screening

Before sending funds, create an outbound crypto transaction without a transaction hash. Didit screens the destination wallet.

{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}

Example: post-transfer inbound screening

After receiving funds, include the transaction hash. Didit screens the transaction hash scoped to your deposit address and enriches the response with transaction summary information where available.

{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}

Supported providers

Provider	Status	Managed pricing	Connected-key pricing
Merkle Science	Available	$0.15/screening	$0.02/screening
Crystal	Connect a provider key via Marketplace	Not available	$0.02/screening
Chainalysis	Connect a provider key via Marketplace	Not available	$0.02/screening
Elliptic	Connect a provider key via Marketplace	Not available	$0.02/screening
TRM Labs	Connect a provider key via Marketplace	Not available	$0.02/screening

Configure your preferred provider in Transactions > Settings > Provider Preferences in the Business Console, or connect your own provider key from the console Marketplace (Crypto monitoring category). LIGHTNING is supported only by connected-key Chainalysis and Elliptic configurations.

With connected-key pricing, you connect an existing provider API key and pay the listed infrastructure fee per screening. Use this option when you already have a commercial agreement with a blockchain analytics provider.

Screening results

Each screening produces a standardised result regardless of which provider is used.

Risk score and severity

Every screened wallet or transaction receives:

Risk score (0–100) — higher scores indicate greater exposure to risky entities
Severity level — derived from the score: LOW, MEDIUM, HIGH, or CRITICAL

Source of funds analysis

A percentage breakdown of where the funds originated, categorised by entity type:

Category	Risk level	Description
`SANCTIONED`	Critical	Entities on international sanctions lists (OFAC, EU, UN)
`TERRORIST_FINANCING`	Critical	Addresses linked to terrorist financing
`CHILD_EXPLOITATION`	Critical	Addresses linked to child exploitation material
`RANSOMWARE`	High	Ransomware payment addresses
`STOLEN_FUNDS`	High	Addresses associated with known theft or hacks
`DARKNET_MARKET`	High	Darknet marketplace addresses
`MIXER`	High	Mixing or tumbling services used to obscure fund origins
`SCAM`	High	Known scam or fraud addresses
`HIGH_RISK_EXCHANGE`	Medium	Exchanges with weak KYC/AML controls
`HIGH_RISK_JURISDICTION`	Medium	Entities in FATF-listed high-risk jurisdictions
`GAMBLING_UNLICENSED`	Medium	Unlicensed gambling platforms
`P2P_EXCHANGE`	Low	Peer-to-peer exchange services
`EXCHANGE`	Low	Regulated cryptocurrency exchanges
`UNNAMED_SERVICE`	Low	Unidentified services

Each entity in the breakdown includes the percentage of funds, received and sent amounts, and whether the connection is direct or indirect.

Exposure table

An exposure table showing source, destination, and counterparty entities, including:

Entity name and category
Direct vs. indirect connection (hop distance)
Received and sent amounts
Risk level per entity

Network graph

A visual node-edge representation of the wallet’s transaction relationships:

Nodes represent wallets, exchanges, services, and other entities
Edges represent transactions between nodes, with amounts and transaction hashes
Metrics include graph-level statistics such as centrality and depth

The network graph is available in the Business Console as an interactive visualization.

Integration with rules

Screening results feed directly into the rules engine. Didit includes preset rules that fire automatically based on screening data:

Preset rule	Action
Sanctions counterparty	Immediate decline — any sanctions exposure
Terrorist financing / child exploitation	Immediate decline
Darknet market exposure	Add score + flag for review
Mixer/obfuscation service exposure	Add score + flag for review
High-risk source of funds (>30%)	Add score + flag for review
Multiple risky counterparties	Add score + flag for review
Medium wallet risk score	Add score + flag for review
Screening pending	Hold transaction until screening completes

After screening completes, Didit automatically re-evaluates all rules against the enriched transaction data and triggers any applicable webhooks.

Next steps

Submitting transactions

How to submit transactions including crypto wallet details.

Rules & scoring

How screening results feed into the rule engine.

Console guide

Viewing crypto screening analysis, source of funds, and network graphs in the console.

Getting Started

Features

Reference

Console

How screening triggers

Asset and network selection

Inbound vs outbound

Lightning Network

Required fields

Example: pre-transfer outbound screening

Example: post-transfer inbound screening

Supported providers

Screening results

Risk score and severity

Source of funds analysis

Exposure table

Network graph

Integration with rules

Next steps

Submitting transactions

Rules & scoring

Console guide

​How screening triggers

​Asset and network selection

​Inbound vs outbound

​Lightning Network

​Required fields

​Example: pre-transfer outbound screening

​Example: post-transfer inbound screening

​Supported providers

​Screening results

​Risk score and severity

​Source of funds analysis

​Exposure table

​Network graph

​Integration with rules

​Next steps

Submitting transactions

Rules & scoring

Console guide

How screening triggers

Asset and network selection

Inbound vs outbound

Lightning Network

Required fields

Example: pre-transfer outbound screening

Example: post-transfer inbound screening

Supported providers

Screening results

Risk score and severity

Source of funds analysis

Exposure table

Network graph

Integration with rules

Next steps