API documentation

TL;DR: This is a REST API with four endpoints. GET /sanctions screens a name, wallet, or country against the OFAC SDN list (947 crypto addresses + 19,218 names + 16 embargoed jurisdictions). POST /risk scores transaction fraud risk. POST /kya verifies an AI agent's identity. POST /disputes opens a dispute record. All return JSON, run in under 100ms, and work with or without an API key. Start with the free tier: 5 checks/day, no signup.

By agentmail team · Reviewed against OFAC SDN list (July 2026, 19,218 entries) · Updated July 18, 2026 · Data sourced from US Treasury OFAC sdn.csv and vile/ofac-sdn-list

Quick start — screen a wallet in one call

Screen any crypto wallet against the full OFAC list with a single GET request. No API key needed on the free tier:

curl "https://sanctionsai.dev/sanctions?wallet=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"

{
  "matches": [
    {"list": "OFAC_SDN", "match_type": "wallet", "confidence": 1.0}
  ],
  "clean": false,
  "checked_at": 1718000000
}

The clean boolean is your go/no-go signal: true means the counterparty is not on any sanctions list, false means a match was found and your agent should halt the payment.

Authentication

Pass your API key in the X-API-Key header (or as Authorization: Bearer <key>). The free tier needs no key - requests are metered by IP.

curl -H "X-API-Key: am_live_xxx" "https://sanctionsai.dev/sanctions?wallet=0x098B..."

1. Sanctions screening - GET /sanctions

Screen a counterparty by name, crypto wallet, or country against the OFAC SDN list, 947 crypto wallets, and 16 embargoed jurisdictions. At least one of name / wallet / country is required.

curl "https://sanctionsai.dev/sanctions?wallet=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"

{
  "matches": [
    {"list": "OFAC_SDN", "match_type": "wallet", "confidence": 1.0}
  ],
  "clean": false,
  "checked_at": 1718000000
}

2. Transaction risk score - POST /risk

Score a transaction's fraud risk before authorizing payment. Returns a recommendation of allow, review, or decline.

curl -X POST https://sanctionsai.dev/risk \
  -H "Content-Type: application/json" \
  -d '{"counterparty_id":"bot-42","amount":"5","currency":"USDC","rail":"x402"}'

{
  "risk_score": 0.82,
  "recommendation": "decline",
  "reasons": ["sanctions_match", "high_amount"]
}

3. Know Your Agent - POST /kya

Verify an AI counterparty's trustworthiness from evidence: wallet address and age, domain, public key, owner email, declared country.

curl -X POST https://sanctionsai.dev/kya \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"bot-42","evidence":{"wallet_address":"0x...","wallet_age_days":310,"domain":"example.com"}}'

{
  "agent_id": "bot-42",
  "kya_score": 0.74,
  "verdict": "review"
}

4. Open a dispute - POST /disputes

Record a disputed agent-paid transaction (non-delivery, fraud). Auto-escalates after 7 days.

curl -X POST https://sanctionsai.dev/disputes \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"tx_123","reason":"non_delivery"}'

{"dispute_id":"dsp_abc","status":"open","escalates_at":1718604800}

5. Health - GET /health

Service status, SMS provider, compliance provider, and x402 status.

curl https://sanctionsai.dev/health

6. Verification inboxes - POST /inboxes

Create a disposable inbox, then poll for the latest message (useful for OTP / signup verification).

curl -X POST https://sanctionsai.dev/inboxes -d '{"label":"signup","prefix":"bot"}'
curl "https://sanctionsai.dev/inboxes/signup/latest?wait=60"

MCP & CLI

Expose the same tools to an MCP client (Claude Code, Cursor) or call them from the CLI:

# Self-host MCP server
uv run --with sanctions-mcp[mcp] python -m agentmail.mcp_server

# CLI
pip install sanctions-mcp
python -m agentmail.cli sanctions --wallet 0x098B...