> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto & Wallet Screening

> Automated wallet and transaction-hash screening via Crystal, Merkle Science, Chainalysis, Elliptic, TRM Labs. BYOK at $0.02 per transaction, no contracts.

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.

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

## How screening triggers

Crypto screening runs automatically when both conditions are met:

1. The transaction has `currency_kind: "crypto"` in its transaction details
2. Transaction monitoring is enabled in your [application settings](/transaction-monitoring/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            |

<Tip>
  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.
</Tip>

## 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.

## Required fields

For all crypto screening requests, send:

* `transaction_details.direction` — `INBOUND` or `OUTBOUND`
* `transaction_details.currency_kind` — `crypto`
* `transaction_details.currency` — the asset or chain identifier, for example `BTC`, `ETH`, or `SOL`
* 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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  | BYOK pricing     |
| ------------------ | -------------------- | ---------------- | ---------------- |
| **Merkle Science** | Available            | \$0.15/screening | \$0.02/screening |
| **Crystal**        | BYOK via Marketplace | —                | \$0.02/screening |
| **Chainalysis**    | BYOK via Marketplace | —                | \$0.02/screening |
| **Elliptic**       | BYOK via Marketplace | —                | \$0.02/screening |
| **TRM Labs**       | BYOK via Marketplace | —                | \$0.02/screening |

Configure your preferred provider in **Transactions** > **Settings** > **Provider Preferences** in the [Business Console](https://business.didit.me), or connect your own provider key from the console **Marketplace** (Crypto monitoring category).

<Tip>
  With **BYOK (Bring Your Own Key)** pricing, you connect your existing provider API key and pay a reduced per-screening fee. This is useful if you already have a commercial agreement with a blockchain analytics provider.
</Tip>

## 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](/transaction-monitoring/console) as an interactive visualization.

## Integration with rules

Screening results feed directly into the [rules engine](/transaction-monitoring/rules). 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

<CardGroup cols={2}>
  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    How to submit transactions including crypto wallet details.
  </Card>

  <Card title="Rules & scoring" icon="scale-balanced" href="/transaction-monitoring/rules">
    How screening results feed into the rule engine.
  </Card>

  <Card title="Console guide" icon="gauge" href="/transaction-monitoring/console">
    Viewing crypto screening analysis, source of funds, and network graphs in the console.
  </Card>
</CardGroup>