API documentation

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, 782 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":"50","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...