Jede Wallet screenen.
$0.15 pro Prüfung.

# Didit Wallet Screening (KYT) — integrate in 5 minutes

You are integrating Didit's Wallet Screening / Know Your Transaction (KYT)
module into <my_stack>. Follow these steps exactly. Every URL, header,
and enum value below is canonical — do not paraphrase or "improve" them.

Wallet Screening produces a standardised risk payload regardless of
which underlying provider sits behind it:
  - Risk score 0-100 + severity (LOW, MEDIUM, HIGH, CRITICAL)
  - Source of funds breakdown across 14+ categories
  - Exposure table (counterparty entities, direct vs indirect hops)
  - Network graph metrics
  - Sanctions / darknet / mixer flags as discrete signals

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/

## 2. Choose a screening source
- Wallet Screening runs at $0.15 per check on Didit's own on-chain
  risk data — nothing to configure, it works out of the box.
- Or bring your own screening provider and run it inside Didit: open
  Transactions > Settings > Provider Preferences in the Business
  Console (https://business.didit.me) and paste your existing
  provider API key. The screening result payload is identical
  whichever source you use.

## 3. Two integration paths — pick one

### Path A — Workflow / Transactions API (recommended)
Best when you want Wallet Screening chained into the Transaction
Monitoring rules engine so flagged transactions automatically generate
review cases.

POST https://verification.didit.me/v3/transactions/
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json
Body (outbound pre-transfer screen, 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..."
      }
    }
  }

Direction rules — required:
  - INBOUND  pre-transfer  -> screens counterparty.payment_method.account_id
  - INBOUND  post-transfer -> screens the tx hash scoped to subject.payment_method.account_id
  - OUTBOUND pre-transfer  -> screens counterparty.payment_method.account_id
  - OUTBOUND post-transfer -> screens the tx hash scoped to counterparty.payment_method.account_id

For post-transfer screening, also include
  transaction_details.payment_reference_id  -> the blockchain tx hash

### Path B — Standalone wallet-screening API
Best when you want a one-off wallet-risk lookup without writing a full
transaction. Same screening source, same $0.15 per check price.

POST https://verification.didit.me/v3/transactions/
Headers:
  x-api-key: <your-api-key>
  Content-Type: application/json
Body:
  {
    "wallet_address": "0xRecipientWallet...",
    "currency": "ETH",
    "direction": "OUTBOUND"
  }

Synchronous JSON response — no webhook required for the standalone call.
Use Path A whenever the screening result needs to flow into the rules
engine, case management, or the auto-remediation loop.

## 4. Webhooks
Register one webhook destination per workspace:

POST https://verification.didit.me/v3/webhook/destinations/
Body: { "url": "https://yourapp.com/didit/webhooks",
        "events": ["transaction.status.updated"] }

Every delivery carries an X-Signature-V2 Hash-based Message Authentication
Code (HMAC) header.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Verify it before trusting the payload:

  signature = hmac_sha256(secret, raw_body).hex()
  if signature != request.headers["X-Signature-V2"]:
      return 401

## 5. Reading the result
Every screening returns a standardised risk object:
  - risk_score (0-100, higher = more exposure)
  - severity ("LOW", "MEDIUM", "HIGH", "CRITICAL")
  - source_of_funds (array of { category, percentage })
  - exposure (array of { entity, hop_distance, received, sent, risk })
  - flags (array including "sanctioned", "darknet_market", "mixer",
           "ransomware", "child_exploitation", "scam", and others)
  - network_graph (nodes, edges, centrality, depth)

Feed flagged transactions into the Transaction Monitoring rules engine
so high-risk hits automatically generate cases at the published
$0.02 per transaction inspection rate.

## 6. Travel Rule (FATF Recommendation 16)
For Virtual Asset Service Provider (VASP) to VASP transfers, include
the Travel Rule payload alongside the transaction body:

  "travel_rule": {
    "originator_vasp": {...},
    "beneficiary_vasp": {...},
    "originator": { "full_name", "date_of_birth", ... },
    "beneficiary": { "full_name", "wallet_address" }
  }

Didit handles the structured-message exchange with supported counterparty
VASPs. Reference: https://docs.didit.me/transaction-monitoring/travel-rule

## 7. Hard rules — do not change
- Base URL stays  https://verification.didit.me  (NOT apx.didit.me).
- Auth header stays  x-api-key  (lowercase, hyphenated).
- Webhook signature header stays  X-Signature-V2  (NOT X-Signature).
- currency_kind is always  "crypto"  for wallet screening.
- direction is always UPPERCASE  ("INBOUND" or "OUTBOUND").
- severity casing stays UPPERCASE: LOW, MEDIUM, HIGH, CRITICAL.

## 8. Pricing reference
- $0.15 per wallet screening on Didit's own on-chain risk data — or
  bring your own screening provider and run it inside Didit.
- $0.02 per transaction inspected by the Transaction Monitoring rule
  engine. AML on flagged transactions at $0.20 per check.
- 500 free verifications every month on every account, forever.
- No minimums, no contracts. Volume discounts above 100k screenings
  per month — see https://didit.me/pricing.

## 9. Verify your integration
1. Create a sandbox API key at https://business.didit.me.
2. Post the example outbound transaction above against a known-flagged
   tutorial wallet — the response should have severity "CRITICAL" and
   carry a "sanctioned" flag.
3. Confirm the webhook fires with transaction.status.updated and the
   X-Signature-V2 header verifies cleanly.
4. Open Case Management in the console — the transaction should land
   in the queue with source PROVIDER and severity CRITICAL.

Done. Wallet Screening is live. Reach out to support@didit.me with the
workspace id if you hit a wall.