crypto-aml — Crypto AML / KYT Python SDK

Author: AnChain.AI, San Jose, California, 2026

Open-source Python SDK for crypto AML / KYT: a reusable crypto_aml client plus step-by-step examples that call the AnChain.AI Data API. Screen wallets, score blockchain risk, run OFAC SDN checks by name / passport / crypto address, and block high-risk transactions — patterns VASPs use for AML compliance, sanctions exposure, and Slack / email / custom alerts.

Topics: crypto-aml · crypto AML · KYT SDK · Know Your Transaction · AML compliance · FATF / Travel Rule · FinCEN · OFAC sanctions screening · crypto tracing · blockchain analytics · wallet screening · transaction monitoring · VASP compliance

Key terms

Why crypto AML matters

Anti-Money Laundering (AML) and Counter-Terrorist Financing (CFT) are the laws, controls, and processes that stop criminals from disguising illicit funds as legitimate. In traditional finance that means KYC (know your customer), transaction monitoring, sanctions screening, and suspicious-activity reporting. In crypto, the same AML compliance obligations apply — but value moves across blockchains in minutes, often without a central intermediary, so crypto KYT (wallet and transaction screening) and crypto tracing / blockchain investigation become first-line controls.

Crypto AML is critical because virtual assets are widely used for payments, remittances, trading, and regulated products (stablecoins, RWAs, payment apps). Without blockchain analytics and address screening, VASPs and fintechs risk facilitating sanctions evasion, ransomware cash-out, fraud proceeds, or terrorist financing — and face enforcement, banking-partner loss, and license risk. Real-time address labels, risk scores, and optional crypto tracing graphs help you decide whether to allow, review, or block a counterparty before funds leave your platform.

Key AML compliance frameworks and supervisors to know (non-exhaustive):

• FATF (Financial Action Task Force) — global AML/CFT standards; Recommendation 15 and the Travel Rule for VASPs
• FinCEN (U.S. Treasury) — BSA/AML rules for money services businesses and crypto intermediaries in the United States
• OFAC (U.S. Treasury) — sanctions lists (e.g. SDN) used for crypto sanctions screening of addresses and entities
• EU / EBA / national FIUs — AMLD/AMLR and MiCA-era expectations for crypto-asset service providers
• Monetary Authority of Singapore (MAS) — payment services and digital-token AML/CFT requirements
• Other major regimes: FCA (UK), AUSTRAC (Australia), FINTRAC (Canada), JFSA (Japan), and local FIUs worldwide

This SDK shows how to call AnChain.AI risk APIs for crypto AML / KYT flows. It is not legal advice. Always consult your local jurisdiction and compliance counsel for AML policy, thresholds, and reporting duties — or schedule a call with AnChain.AI for production AML compliance, screening, and investigations.

What you will learn

1. Get a free API key for crypto AML screening from data.anchainai.com (anchain.ai/data)
2. Call the core Intelligence endpoints for wallet screening and blockchain risk scoring:
   • Address Label — category / entity (GET /api/intel/address/label, 5 credits)
   • Address Risk Score — score, level, breakdown (GET /api/intel/address/score, 10 credits)
3. Call OFAC sanctions endpoints for KYC + crypto-ID screening:
   • OFAC search — name / passport / ID (POST /api/sanctions/ofac/search, 10 credits)
   • OFAC address — crypto wallet → SDN owner (GET /api/sanctions/ofac/address, 5 credits)
4. Try Bitcoin (BTC), Ethereum (ETH), and Solana (SOL) examples across high / medium / low risk
5. Hook transaction monitoring alerts and block high-risk withdrawals in your payment flow
6. Monitor API credits via GET /credits/balance and X-Credits-* response headers
7. Apply an exchange whitelist policy (high score + exchange label) — see example 06 + CISO crypto tracing graph
8. Screen KYC name + passport and compare OFAC vs risk score for the same wallet — examples 07–08
9. Build a Travel Rule IVMS 101 payload and gate it on KYT sanctions — example 09

Install

pip install crypto-aml

from crypto_aml import AnChainClient, screen_and_decide

client = AnChainClient()  # reads ANCHAIN_API_KEY from env / .env
result = screen_and_decide(client, "eth", "0x2f389ce8bd8ff92de3402ffce4691d17fc4f6535")
print(result.decision, result.score, result.categories)

# OFAC: KYC name / passport / crypto address
ofac_name = client.search_ofac(name="chen zhi", type="individual")
ofac_id = client.search_ofac(id="K00395168", type="individual")
ofac_wallet = client.screen_ofac_address("bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw")

PyPI distribution name is crypto-aml; the import package is crypto_aml (hyphens → underscores), same pattern as packages like ofac-sanctions-screening → ofac_sanctions_screening.

Quick start (examples)

# 1) Clone / enter this repo
git clone https://github.com/AnChainAI/crypto-aml.git
cd crypto-aml

# 2) Create a virtualenv and install (editable or from PyPI)
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .                   # or: pip install crypto-aml
# alternatively: pip install -r requirements.txt

# 3) Add your free API key (+ optional email for /credits/balance)
cp .env.example .env
# edit .env → ANCHAIN_API_KEY=...
# optional:     ANCHAIN_EMAIL=you@example.com

# 4) Verify key + credits
python examples/01_get_started.py

# 5) Screen the OFAC example from the docs (expect BLOCK)
python examples/02_screen_address.py

# 6) Full KYT demo across risk bands (BTC / ETH / SOL)
python examples/03_kyt_block_txn.py

# 7) Compare credit balance methods
python examples/04_check_credits.py

# 8) High / medium / low risk band summary
python examples/05_risk_bands.py

# 9) Exchange whitelist policy (high score + exchange label)
python examples/06_exchange_whitelist_policy.py

# 10) OFAC sanctions screen by KYC person name (+ passport ID)
python examples/07_ofac_kyc_name_screen.py
#    python examples/07_ofac_kyc_name_screen.py "chen zhi" --passport K00395168
#    python examples/07_ofac_kyc_name_screen.py --screen-wallets

# 11) Same crypto wallet: OFAC owner lookup vs address risk score
python examples/08_ofac_crypto_address_screen.py
#    python examples/08_ofac_crypto_address_screen.py bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw

# 12) Travel Rule IVMS 101 data frame + KYT sanctions gate
python examples/09_travel_rule_ivms_kyt.py
#    python examples/09_travel_rule_ivms_kyt.py --only sanction

Each examples/0N_*.py file includes expected sample output from a live API run (scores can drift over time).

Important example: exchange whitelist policy

Some customers define a whitelist rule: if AnChain's address label includes exchange, allow the transaction even when the risk score is elevated/high.

Policy rule (customer-defined):

IF label.category contains "exchange"
  AND no hard-block category (sanction, mixer, ransomware, …)
THEN ALLOW   # ignore elevated/high risk score
ELSE use normal score thresholds (REVIEW / BLOCK)

This is a common VASP/payment integration pattern, but it is a weaker AML posture — exchange hot wallets can still touch illicit funds. Prefer combining label + score + risk_vasp, and always hard-block sanction / mixer / etc. even when an exchange tag co-occurs.

python examples/06_exchange_whitelist_policy.py

Inspect this counterparty with free crypto tracing / graph visualization: CISO graph

Important example: OFAC screen by KYC name

Wallet KYT is not enough for onboarding — screen the customer legal name (and passport / national ID) against OFAC SDN before you open an account.

python examples/07_ofac_kyc_name_screen.py
python examples/07_ofac_kyc_name_screen.py "chen zhi" --passport K00395168 --screen-wallets

Name search (filters.name):

POST /api/sanctions/ofac/search
{"filters": {"name": "chen zhi", "type": "individual"}, "page": 1, "limit": 10}

Passport / national ID (filters.id — not filters.country):

POST /api/sanctions/ofac/search
{"filters": {"id": "K00395168", "type": "individual"}, "page": 1, "limit": 10}

Do not put the passport issuing country in filters.country for ID screens — that filter targets address/nationality fields and can return zero hits. Country appears on the matched identifications row instead.

Tutorial policy: strong name-token hit → BLOCK onboarding; exact ID hit → BLOCK; weak name hits → REVIEW; no hits → continue KYC (still screen wallets). SDN records may also list linked BTC wallets under identifications_dc — follow up with example 08.

Important example: OFAC + risk score for a crypto address

Two APIs screen the same wallet — use both:

python examples/08_ofac_crypto_address_screen.py
python examples/08_ofac_crypto_address_screen.py bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw

GET /api/sanctions/ofac/address?address=bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw
GET /api/intel/address/score?proto=btc&address=bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw

Alternate OFAC form (same owner hit, 10 credits): POST /api/sanctions/ofac/search with {"filters": {"id": "<wallet>"}}.

Takeaway: risk score is enough for a fast payment decision but returns less information than the OFAC sanctions API when investigators need the person name, passport IDs, linked company names, or other wallets on the same SDN record. Prefer OFAC for the compliance dossier; prefer score for KYT policy thresholds.

Important example: Travel Rule (IVMS 101) + KYT gate

FATF Travel Rule (Rec. 16) requires VASPs to exchange originator / beneficiary identity for qualifying transfers. IVMS 101 is the common JSON data model. Building the IVMS payload is not enough — you must still KYT-screen the beneficiary wallet before transmitting Travel Rule data or broadcasting on-chain.

python examples/09_travel_rule_ivms_kyt.py
python examples/09_travel_rule_ivms_kyt.py --only sanction

Build IVMS 101 (originator KYC + beneficiary + VASPs)
        │
        ▼
KYT screen beneficiary wallet  ── BLOCK ──► status=BLOCKED (no IVMS send, no broadcast)
        │
     REVIEW ──────────────────────────────► HELD_FOR_REVIEW
        │
      ALLOW ──────────────────────────────► READY_TO_SEND → Travel Rule network SDK

Optional: enrich with GET /api/sanctions/ofac/address so the case shows the SDN owner name next to the customer-declared beneficiary (mismatch is a strong red flag).

Risk score reference

SDK default policy (crypto_aml/risk.py):

1. BLOCK if category ∈ {sanction, mixer, ransomware, terrorism, darknet market, hacker, scam, malware, blackmail}
2. ALLOW trusted labels such as exchange / miner / defi (even if exposure score is high) — disable with ANCHAIN_TRUST_EXCHANGES=0
3. BLOCK if score ≥ 80 (ANCHAIN_BLOCK_SCORE_THRESHOLD)
4. REVIEW if score ≥ 51 (ANCHAIN_REVIEW_SCORE_THRESHOLD)
5. ALLOW otherwise

Busy exchange hot wallets often show elevated exposure scores because they touch many counterparties. The SDK trusts the exchange label by default and prints optional risk_vasp from the score payload for VASP-oriented scoring.

Example addresses (for learning)

Exchange category is “good,” but raw exposure scores may be high — demos print categories + risk_vasp so you can see why. See exchange whitelist policy for the full rule and caveats.

Scores and SDN lists drift as intel updates; re-run the scripts for live verdicts.

Example API calls

Address risk score (KYT — less identifying detail)

curl 'https://api.anchainai.com/api/intel/address/score?proto=btc&address=bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'

Typical intelligence: category: ["sanction"], detail: ["sanction:OFAC_SDN"], score: 100 — may include a short information[] name string, but not passports, program codes, or sibling SDN wallets.

→ SDK policy: BLOCK (hard-block category sanction + severe score).

Label-only (cheaper first pass, 5 credits):

curl 'https://api.anchainai.com/api/intel/address/label?proto=btc&address=1ECeZBxCVJ8Wm2JSN3Cyc6rge2gnvD3W5K' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'

OFAC crypto address → SDN owner (rich KYC)

curl 'https://api.anchainai.com/api/sanctions/ofac/address?address=bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw' \
  --header 'x-api-key: YOUR_SECRET_TOKEN'

→ Owner Zhi CHEN, list SDN, program TCO, passports, linked org remarks, other listed wallets.

OFAC KYC name / passport search

curl -X POST 'https://api.anchainai.com/api/sanctions/ofac/search' \
  --header 'x-api-key: YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"filters":{"name":"chen zhi","type":"individual"},"page":1,"limit":10}'

curl -X POST 'https://api.anchainai.com/api/sanctions/ofac/search' \
  --header 'x-api-key: YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"filters":{"id":"K00395168","type":"individual"},"page":1,"limit":10}'

Project layout

crypto-aml/                 # Crypto AML / KYT Python SDK (PyPI: crypto-aml)
├── crypto_aml/             # Import package: from crypto_aml import ...
│   ├── client.py           # HTTP client: label, score, OFAC search/address, credits
│   ├── risk.py             # Score → ALLOW / REVIEW / BLOCK
│   ├── travel_rule.py      # IVMS 101 Identity Payload + KYT gate helpers
│   ├── alerts.py           # Console + stubs for Slack / email / webhook
│   └── examples_data.py    # Curated BTC / ETH / SOL samples
├── aml_kyt/                # Deprecated import shim → crypto_aml
├── examples/               # Step-by-step tutorials
│   ├── 01_get_started.py
│   ├── 02_screen_address.py
│   ├── 03_kyt_block_txn.py
│   ├── 04_check_credits.py
│   ├── 05_risk_bands.py
│   ├── 06_exchange_whitelist_policy.py
│   ├── 07_ofac_kyc_name_screen.py      # OFAC by name + passport
│   ├── 08_ofac_crypto_address_screen.py # OFAC owner vs risk score
│   └── 09_travel_rule_ivms_kyt.py       # Travel Rule IVMS + KYT gate
├── tests/
│   ├── test_risk_policy.py
│   └── test_travel_rule.py
├── .github/workflows/publish.yml
├── pyproject.toml
├── .env.example
└── requirements.txt

Use the SDK

from crypto_aml import AnChainClient, ConsoleAlertHook, screen_and_decide
from crypto_aml.alerts import maybe_alert

client = AnChainClient()
result = screen_and_decide(client, "btc", "1ECeZBxCVJ8Wm2JSN3Cyc6rge2gnvD3W5K")
maybe_alert(result, ConsoleAlertHook())

if result.should_block:
    raise SystemExit("Refuse withdrawal")

# Onboarding: OFAC name + passport
name_hits = client.search_ofac(name="chen zhi", type="individual")
id_hits = client.search_ofac(id="K00395168", type="individual")

# Payment: OFAC owner dossier for a wallet (richer than score alone)
owner = client.screen_ofac_address("bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw")

Wire your own alerts

Edit crypto_aml/alerts.py:

• SlackAlertHook — Slack incoming webhook
• EmailAlertHook — SMTP / SES / SendGrid
• WebhookAlertHook — SIEM / case management
• CompositeAlertHook — fan-out to several sinks

Checking API credits

python examples/04_check_credits.py
# compares GET /credits/balance vs X-Credits-* headers
# exits with code 2 when remaining < ANCHAIN_LOW_CREDIT_THRESHOLD (default 100)

Method A — secret balance route (0 credits): set ANCHAIN_EMAIL (same email as data.anchainai.com) plus ANCHAIN_API_KEY:

POST /users/token          # username=email, password=api_key  → Bearer JWT
GET  /credits/balance      # Authorization: Bearer <token>     → { balance, total, expire_at }

Method B — response headers (no email needed; a label probe costs 5 credits):

Both methods read the same credit pool (header value ≈ /credits/balance minus credits spent by the probe).

Suggested production crypto AML / KYT flow

Consult your AML compliance team for jurisdiction-specific policy (FATF Travel Rule, FinCEN, MAS, etc.), or schedule a call with AnChain.AI.

Onboarding (KYC)
  Name  → POST /api/sanctions/ofac/search  (filters.name)
  ID    → POST /api/sanctions/ofac/search  (filters.id = passport / national ID)
          hit? ──► BLOCK / REVIEW + escalate

Withdrawal / deposit (KYT + Travel Rule)
  User requests transfer
        │
        ├─► Build IVMS 101 Identity Payload (originator KYC + beneficiary + VASPs)
        │
        ├─► GET /api/sanctions/ofac/address  ── hit? ──► BLOCK + owner dossier
        │
        ▼
  Label (5 cr)  ─── sanction/mixer/…? ──► BLOCK + alert  (do not send IVMS / broadcast)
        │
        ▼
  Score (10 cr) ─── score ≥ 80? ───────► BLOCK + alert
        │
        ├── score ≥ 51? ───────────────► REVIEW + hold IVMS
        │
        └── else ──► READY_TO_SEND IVMS → Travel Rule network → broadcast on-chain

OFAC address screening returns the SDN owner KYC packet; address risk score returns the 0–100 KYT signal with less identifying detail — call both when investigating sanctions hits (example 08). Gate Travel Rule IVMS transmission on that decision (example 09).

Also call client.credits_low() (or run 04_check_credits.py in cron) so screening does not silently fail when the credit pack runs out.

Resources

• AnChain.AI Data — crypto AML / KYT API & MCP, free API key
• Data API docs — address label, risk score, sanctions, analytics
• CISO — crypto tracing, blockchain investigation & graph UI (example share)
• Supported chains for wallet screening include Bitcoin, Ethereum, Solana, and many more (see docs)

crypto-aml is an open-source Crypto AML / KYT Python SDK for prototyping compliance workflows. Validate policy with your compliance team before production use.

Schedule a consultation: anchain.ai/demo
Email: info AT anchain.ai

Publish to PyPI

Preferred: GitHub Trusted Publishing (no API token). On PyPI, add a trusted publisher with:

Then bump version in pyproject.toml, push, and create a GitHub Release (or run the Publish to PyPI workflow manually). The workflow lives at .github/workflows/publish.yml.

Manual upload (API token) still works:

python3 -m pip install -U build twine
python3 -m build
twine check dist/*
# optional dry-run: twine upload --repository testpypi dist/*
twine upload dist/*

License

Copyright 2026 AnChain.AI

Licensed under the Apache License, Version 2.0. See NOTICE for attribution.