# SanctionsAI - Complete Documentation

> OFAC sanctions screening, transaction risk scoring, and Know-Your-Agent verification for AI agents that transact autonomously.

## Overview

agentmail gives AI agents a 1-call OFAC sanctions check they run before paying anyone. If your agent is moving money - over x402, AP2, Coinbase AgentKit, or any payment rail - this is the compliance layer it needs.

The service is built on public data (US Treasury OFAC SDN list, vile/ofac-sdn-list crypto wallets, embargoed jurisdictions), runs in under 100ms, and is MIT-licensed for self-hosting.

## Hosted API (sanctionsai.dev)

Base URL: https://sanctionsai.dev

### Authentication
- Free tier: 5 checks/day, no API key, metered by IP
- Paid tiers: Pass your key in X-API-Key header or Authorization: Bearer

### Endpoints

#### GET /sanctions - Screen a counterparty
Query params: name, wallet, country (at least one required)
curl "https://sanctionsai.dev/sanctions?wallet=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"
Response: {"matches": [...], "clean": bool, "checked_at": int}

#### POST /risk - Transaction risk score
Body: {"counterparty_id": str, "amount": str, "currency": str, "rail": str, "category": str}
Returns: allow, review, or decline with scored reasons

#### POST /kya - Know Your Agent
Body: {"agent_id": str, "evidence": {wallet_address, wallet_age_days, domain, pubkey, owner_email, declared_country}}
Returns: {agent_id, kya_score, verdict}

#### POST /disputes - Open a dispute
Body: {"transaction_id": str, "reason": str, "evidence": dict}
Returns: {dispute_id, status, escalates_at}

### Pricing
- Free: 5 checks/day
- Dev: $19/mo, 10,000 checks/month, all 4 tools
- Pro: $99/mo, 100,000 checks/month, all 4 tools, 4h support

### Self-host
pip install sanctions-mcp
MIT license. All four tools run locally for free.

### MCP Server
MCP-compatible agents get native tool access. Install:
pip install sanctions-mcp
Then add to your MCP client (Claude Code, Cursor, Windsurf).

The server exposes four tools (call by these exact names):
- sanctions_check(name="", wallet="", country="") - Screen a counterparty against OFAC/EU/UN/UK sanctions lists. Cheapest check, call first. Returns {matches, clean}.
- risk_score(counterparty_id, amount, currency="USDC", rail="x402", category="digital_goods") - Score a transaction's fraud risk before authorizing payment. Returns {score, recommendation: allow|review|decline, reasons, screen_id}.
- kya_verify(agent_id, evidence) - Know Your Agent: verify a counterparty agent before transacting. Returns {trust_score, verified, flags, recommendation}.
- dispute_open(transaction_id, reason, evidence=None) - Open a dispute when an agent-paid transaction goes bad. Returns {dispute_id, status, escalation_at}.

## Data Coverage
- 782 OFAC-listed crypto wallet addresses (EVM, Bitcoin, Tron)
- 19,086 OFAC SDN names
- 16 embargoed/restricted jurisdictions
- Refreshed daily from primary sources

## Links
- GitHub: https://github.com/kindrat86/agentmail
- PyPI: https://pypi.org/project/sanctions-mcp/
- Website: https://sanctionsai.dev
- MCP Registry: https://mcp.so/server/agentmail