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

# Screen Wallet

> Run on-demand AML screening for a single crypto wallet/address without creating a transaction. Resolves your application's configured blockchain analytics provider (Merkle Science or Crystal), screens the address synchronously, and returns the normalised risk result. Nothing is written to the transactions table. One AML monitoring usage is billed per successful screening (sandbox applications are not billed).

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Screen Wallet API Prompt"
  prompt={`Screen a single crypto wallet address for AML risk through the Didit Management API, without creating a transaction.

Endpoint:
POST https://verification.didit.me/v3/wallet-screening/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
- Run on-demand AML screening on one crypto address and return a normalised risk result (risk_score, severity, sanctions_hit, source/destination of funds, counterparty connections). Nothing is written to the transactions table.

When to call:
- Before onboarding a customer's deposit/withdrawal wallet, to pre-check exposure.
- Any time you need a standalone risk read on an address and do NOT have (or do not want to record) a transaction.
- For transaction-coupled monitoring instead, use POST /v3/transactions/ with currency_kind = "crypto".

Prerequisites:
- Transaction monitoring must be configured for the application (a provider with a managed or BYOK key). Otherwise the call returns 409.

Request body (application/json):
{
"wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",  // required; alias: address
"blockchain": "ETH",   // required; one of BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, USDT, USDC; alias: currency
"direction": "inbound" // optional; inbound | outbound | deposit | withdrawal
}

Example call:
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"}'

What to read from the response:
- risk_score (0-100, higher = riskier) and severity (UNKNOWN | LOW | MEDIUM | HIGH | CRITICAL).
- sanctions_hit (boolean) and dominant_risk_category.
- source_of_funds / destination_of_funds / counterparty_connections for the exposure breakdown.

Billing:
- One AML monitoring usage is billed per successful screening. Sandbox applications are not billed.

Failure modes:
- 400 - malformed wallet address, missing wallet_address, or unsupported blockchain.
- 401 - missing or malformed x-api-key.
- 409 - no AML provider configured for the application; configure transaction monitoring first.
- 502 - provider could not complete the screening; retry later.

For automatic, transaction-coupled crypto screening, see /transaction-monitoring/aml-screening.`}
/>


## OpenAPI

````yaml POST /v3/wallet-screening/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/wallet-screening/:
    post:
      tags:
        - Transactions
      summary: Screen a wallet address
      description: >-
        Run on-demand AML screening for a single crypto wallet/address without
        creating a transaction. Resolves your application's configured
        blockchain analytics provider (Merkle Science or Crystal), screens the
        address synchronously, and returns the normalised risk result. Nothing
        is written to the transactions table. One AML monitoring usage is billed
        per successful screening (sandbox applications are not billed).
      operationId: screenWallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wallet_address
                - blockchain
              properties:
                wallet_address:
                  type: string
                  description: >-
                    The crypto address to screen. Must match the format of the
                    selected blockchain (e.g. a `0x`-prefixed 40-hex-char
                    address for EVM chains). Alias: `address`.
                  example: '0x28c6c06298d514db089934071355e5743bf21d60'
                blockchain:
                  type: string
                  description: >-
                    Asset / chain identifier. One of: BTC, ETH, LTC, XRP, BCH,
                    DOGE, TRX, SOL, MATIC, BNB, USDT, USDC. Alias: `currency`.
                  enum:
                    - BTC
                    - ETH
                    - LTC
                    - XRP
                    - BCH
                    - DOGE
                    - TRX
                    - SOL
                    - MATIC
                    - BNB
                    - USDT
                    - USDC
                  example: ETH
                direction:
                  type: string
                  description: >-
                    Optional. Whether the address is being screened as an
                    inbound (deposit) or outbound (withdrawal) counterparty.
                    Accepts `inbound`, `outbound`, `deposit`, or `withdrawal`.
                    Defaults to a neutral pre-transfer screen when omitted.
                  enum:
                    - inbound
                    - outbound
                    - deposit
                    - withdrawal
      responses:
        '200':
          description: The normalised wallet screening result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider:
                    type: string
                    description: >-
                      Provider that performed the screening (e.g.
                      `merklescience`, `crystal`).
                  screening_type:
                    type: string
                    enum:
                      - WALLET_SCREENING
                    description: Always `WALLET_SCREENING` for this endpoint.
                  risk_score:
                    type: integer
                    description: >-
                      Normalised 0-100 risk score. Higher means greater exposure
                      to risky entities.
                  severity:
                    type: string
                    enum:
                      - UNKNOWN
                      - LOW
                      - MEDIUM
                      - HIGH
                      - CRITICAL
                    description: Severity bucket derived from `risk_score`.
                  status:
                    type: string
                    enum:
                      - SCREENED
                      - PENDING
                      - ERROR
                    description: Screening outcome status.
                  summary:
                    type: string
                    description: Human-readable summary of the screening result.
                  wallet_address:
                    type: string
                    description: The screened address, echoed back.
                  blockchain:
                    type: string
                    description: The blockchain that was screened.
                  sanctions_hit:
                    type: boolean
                    description: >-
                      True if the address has direct or indirect sanctions
                      exposure.
                  dominant_risk_category:
                    type: string
                    nullable: true
                    description: >-
                      Highest-weighted high-risk category, or `null` when none
                      is dominant (e.g. `sanctioned`, `mixer`, `stolen_funds`).
                  source_of_funds:
                    type: array
                    description: >-
                      Where the address received funds from, attributed by
                      entity. Each entry is an exposure breakdown.
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                          description: >-
                            Normalised risk category, e.g. `exchange_licensed`,
                            `dex`, `defi`, `payment_processor`, `mixer`,
                            `darknet_market`, `sanctioned`, `stolen_funds`,
                            `high_risk_exchange`.
                        entity_name:
                          type: string
                          description: >-
                            Name of the attributed entity (e.g. `Binance.com`,
                            `Tornado Cash`).
                        entity_type:
                          type: string
                          description: >-
                            Provider entity type (e.g. `Exchange`, `Mixer`,
                            `DeFi`, `Sanctions`, `Theft`).
                        entity_subtype:
                          type: string
                          description: >-
                            More granular subtype (e.g. `Mandatory KYC and AML`,
                            `OFAC SDN`, `Yield Aggregator`).
                        exposure_direction:
                          type: string
                          enum:
                            - incoming
                            - outgoing
                            - connected
                          description: >-
                            Whether the funds came from (`incoming`) or went to
                            (`outgoing`) this entity.
                        exposure_type:
                          type: string
                          enum:
                            - direct
                            - indirect
                          description: '`direct` (1 hop) or `indirect` (multi-hop) exposure.'
                        is_direct:
                          type: boolean
                          description: True when the exposure is direct (0 hops).
                        amount_usd:
                          type: number
                          description: USD value attributed to this entity.
                        percentage:
                          type: number
                          description: Share of the direction's total exposure, 0-100.
                        hops:
                          type: integer
                          description: >-
                            Number of hops to the entity (0 for direct
                            exposure).
                        risk_level:
                          type: string
                          enum:
                            - UNKNOWN
                            - LOW
                            - MEDIUM
                            - HIGH
                            - CRITICAL
                          description: Risk level of the entity.
                        country:
                          type: string
                          description: >-
                            Primary ISO 3166-1 alpha-2 country of the entity,
                            when known.
                  destination_of_funds:
                    type: array
                    description: >-
                      Where the address sent funds to, attributed by entity.
                      Same item shape as `source_of_funds` with
                      `exposure_direction` = `outgoing`.
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                        entity_name:
                          type: string
                        entity_type:
                          type: string
                        entity_subtype:
                          type: string
                        exposure_direction:
                          type: string
                          enum:
                            - incoming
                            - outgoing
                            - connected
                        exposure_type:
                          type: string
                          enum:
                            - direct
                            - indirect
                        is_direct:
                          type: boolean
                        amount_usd:
                          type: number
                        percentage:
                          type: number
                        hops:
                          type: integer
                        risk_level:
                          type: string
                          enum:
                            - UNKNOWN
                            - LOW
                            - MEDIUM
                            - HIGH
                            - CRITICAL
                        country:
                          type: string
                  counterparty_connections:
                    type: array
                    description: >-
                      Direct and indirect counterparty entities with
                      received/sent amounts and risk levels.
                    items:
                      type: object
                      properties:
                        entity_name:
                          type: string
                          description: Counterparty entity name.
                        entity_type:
                          type: string
                          description: Counterparty entity type.
                        entity_subtype:
                          type: string
                          description: Counterparty entity subtype.
                        risk_level:
                          type: string
                          enum:
                            - UNKNOWN
                            - LOW
                            - MEDIUM
                            - HIGH
                            - CRITICAL
                        categories:
                          type: array
                          items:
                            type: string
                          description: Risk categories attributed to the counterparty.
                        received_usd:
                          type: number
                          description: USD received from the counterparty.
                        sent_usd:
                          type: number
                          description: USD sent to the counterparty.
                        received_hops:
                          type: integer
                        sent_hops:
                          type: integer
                        percentage:
                          type: number
                        is_direct:
                          type: boolean
                        country:
                          type: string
              example:
                provider: merklescience
                screening_type: WALLET_SCREENING
                risk_score: 72
                severity: HIGH
                status: SCREENED
                summary: 'Merkle Science risk: High (4/5). Dominant risk: mixer'
                wallet_address: '0x28c6c06298d514db089934071355e5743bf21d60'
                blockchain: ETH
                sanctions_hit: true
                dominant_risk_category: mixer
                source_of_funds:
                  - category: exchange_licensed
                    entity_name: Binance.com
                    entity_type: Exchange
                    entity_subtype: Mandatory KYC and AML
                    exposure_direction: incoming
                    exposure_type: direct
                    is_direct: true
                    amount_usd: 18420.55
                    percentage: 61.4
                    hops: 0
                    risk_level: LOW
                    country: SC
                  - category: mixer
                    entity_name: Tornado Cash
                    entity_type: Mixer
                    entity_subtype: OFAC SDN
                    exposure_direction: incoming
                    exposure_type: indirect
                    is_direct: false
                    amount_usd: 11580.2
                    percentage: 38.6
                    hops: 2
                    risk_level: CRITICAL
                    country: RU
                destination_of_funds:
                  - category: exchange_licensed
                    entity_name: Coinbase
                    entity_type: Exchange
                    entity_subtype: Mandatory KYC and AML
                    exposure_direction: outgoing
                    exposure_type: direct
                    is_direct: true
                    amount_usd: 30000.75
                    percentage: 100
                    hops: 0
                    risk_level: LOW
                    country: US
                counterparty_connections:
                  - entity_name: Tornado Cash
                    entity_type: Mixer
                    entity_subtype: OFAC SDN
                    risk_level: CRITICAL
                    categories:
                      - mixer
                    received_usd: 11580.2
                    sent_usd: 0
                    received_hops: 2
                    sent_hops: 0
                    percentage: 38.6
                    is_direct: false
                    country: RU
        '400':
          description: >-
            Validation error — malformed wallet address, missing
            `wallet_address`, or unsupported `blockchain`.
        '401':
          description: Missing or invalid `x-api-key`.
        '409':
          description: >-
            No AML provider is configured for the application, or the configured
            provider does not support wallet screening yet. Configure
            transaction monitoring first.
        '502':
          description: The AML provider could not complete the screening. Retry later.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            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"
              }'
        - lang: python
          label: Python
          source: >-
            import os


            import requests


            resp = requests.post(
                'https://verification.didit.me/v3/wallet-screening/',
                headers={'x-api-key': os.environ['DIDIT_API_KEY']},
                json={
                    'wallet_address': '0x28c6c06298d514db089934071355e5743bf21d60',
                    'blockchain': 'ETH',
                },
                timeout=20,
            )

            resp.raise_for_status()

            result = resp.json()

            print(result['risk_score'], result['severity'],
            result['sanctions_hit'])
        - lang: javascript
          label: JavaScript
          source: >-
            const result = await
            fetch('https://verification.didit.me/v3/wallet-screening/', {
              method: 'POST',
              headers: {
                'x-api-key': process.env.DIDIT_API_KEY,
                'Content-Type': 'application/json',
              },
              body: JSON.stringify({
                wallet_address: '0x28c6c06298d514db089934071355e5743bf21d60',
                blockchain: 'ETH',
              }),
            }).then((r) => r.json());

            console.log(result.risk_score, result.severity,
            result.sanctions_hit);
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````