crypto-aml 0.2.0

Crypto AML / KYT Python SDK for AnChain.AI Data API

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

Term	Meaning
AML	Anti-Money Laundering — laws and controls that stop criminals from hiding illicit funds as legitimate money.
CFT (also CTF)	Counter-Terrorist Financing — stopping funds from reaching terrorists or terrorist groups (often paired with AML as AML/CFT).
KYC	Know Your Customer — verifying who a customer is (identity, ownership) before or while providing services.
KYT	Know Your Transaction — screening wallets and transfers for risk (sanctions, mixers, scam exposure) before you allow, review, or block them.
VASP	Virtual Asset Service Provider — an exchange, custodian, wallet provider, or similar business that deals in crypto for customers.
Sanctions screening	Checking addresses/entities against government blocklists (e.g. OFAC SDN) so you do not send or receive prohibited funds.
OFAC / SDN	U.S. Treasury’s Office of Foreign Assets Control; SDN = Specially Designated Nationals (a major sanctions list).
FATF	Financial Action Task Force — sets global AML/CFT standards that countries and VASPs are expected to follow.
Travel Rule	FATF requirement that VASPs share originator/beneficiary info with each other for qualifying transfers.
Transaction monitoring	Ongoing checks of payment activity for unusual or high-risk patterns (alerts, review queues, blocks).
Blockchain analytics	Using on-chain data and labels to score risk, attribute wallets, and investigate fund flows (crypto tracing).
Address label	A category/tag for a wallet (e.g. exchange, sanction, mixer) from threat intel / analytics.
Risk score	A numeric risk rating for an address (this SDK uses AnChain’s 0–100 score and allow / review / block policy).

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

API base	https://api.anchainai.com
Auth	x-api-key: <YOUR_KEY>
Docs	address score · address label · OFAC search · OFAC address

---

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=[e-mail]

# 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

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.

Field	Value
Chain	ETH
Address	0x167a9333bf582556f35bd4d16a7e80e191aa6476
Label	exchange:Coinone
Typical score	Elevated / high exposure (often ~70–90)
Code	[examples/06_exchange_whitelist_policy.py](examples/06_exchange_whitelist_policy.py)
Free graph view	Open in AnChain.AI CISO

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.

Field	Value
Endpoint	POST /api/sanctions/ofac/search (10 credits)
Demo name	chen zhi → often Zhi CHEN (SDN / TCO, Prince Group)
Demo passport	K00395168 (Cyprus) → exact hit Zhi CHEN
Code	examples/07_ofac_kyc_name_screen.py

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:

API	Endpoint	Credits	What you get	What you don’t
OFAC sanctions	GET /api/sanctions/ofac/address	5	Rich owner KYC: legal name, DOB, nationality, passports, company/org remarks, sibling SDN wallets, program/list codes	Risk score 0–100 / breakdown
Address risk score	GET /api/intel/address/score	10	Score, level, categories (sanction), detail tags, KYT ALLOW / REVIEW / BLOCK	Full SDN dossier (structured name / passport / company linkage)

Field	Value
Demo BTC	bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw
OFAC owner	Zhi CHEN — SDN / TCO (Prince Group)
Risk score	typically sanction / severe (~100)
Code	examples/08_ofac_crypto_address_screen.py

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.

---

Risk score reference

Risk score	Risk level	Description
0–29	1 GREEN / LOW	Established low-risk history
30–50	2 BLUE / GUARDED	Guarded risk; no confirmed major impact
51–79	3 ORANGE / ELEVATED	Elevated / indirect exposure
80–100	4 RED / SEVERE	Established illicit history — block

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)

Band	Chain	Address / ID	Notes
High	BTC	1ECeZBxCVJ8Wm2JSN3Cyc6rge2gnvD3W5K	OFAC SDN / SUEX — score ~100 · CISO graph
High	ETH	0x2f389ce8bd8ff92de3402ffce4691d17fc4f6535	Sanction / SUEX-linked
High (Prince Group)	BTC	bc1qeth6n6ryxexvkx34wnx3nuynun4474h3j0gkhw	OFAC owner Zhi CHEN · 08_…
KYC name	—	chen zhi	OFAC search → Zhi CHEN · 07_…
KYC passport	—	K00395168 (Cyprus)	filters.id exact hit → Zhi CHEN · 07_…
Medium	SOL	GJRs5Fw3jtyLbakCo6MeTmqnKjGwj3GTW4PPok4qwGuS	Unaffiliated / guarded
Low	SOL	9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM	Labeled Binance
Low*	ETH	0x28C6c06298d514Db089934071355E5743bf21d60	Binance hot wallet (see exposure note)
Low*	BTC	1NDyJtNTjmwk5xPNhjgAMu4HDHigtobu1s	Binance (see exposure note)
High score + exchange	ETH	0x167a9333bf582556f35bd4d16a7e80e191aa6476	Coinone — CISO graph · 06_…

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
│   ├── 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
├── tests/
│   └── test_risk_policy.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):

Header	Meaning
X-Credits-Remaining	Credits left
X-Credits-Expires-At	Pack expiry (ISO 8601)

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)
  User requests transfer
        │
        ├─► GET /api/sanctions/ofac/address  ── hit? ──► BLOCK + owner dossier (name, passport, org)
        │
        ▼
  Label (5 cr)  ─── sanction/mixer/…? ──► BLOCK + alert
        │
        ▼
  Score (10 cr) ─── score ≥ 80? ───────► BLOCK + alert
        │
        ├── score ≥ 51? ───────────────► REVIEW + alert
        │
        └── else ──────────────────────► ALLOW / send

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

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:

Field	Value
Owner	AnChainAI
Repository	crypto-aml
Workflow	publish.yml
Environment	pypi

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.