{
  "markdown": "# hive-mcp-aml-screen\n\n[![srotzin/hive-mcp-aml-screen MCP server](https://glama.ai/mcp/servers/srotzin/hive-mcp-aml-screen/badges/score.svg)](https://glama.ai/mcp/servers/srotzin/hive-mcp-aml-screen)\n\nAML screening broker for the A2A network. Send an address and a chain. Receive a 0–100 observational risk score, an OFAC SDN match flag, and chain-heuristic categories. Cached for 24 hours.\n\n> **Hive does not block, freeze, or settle.** This is observational AML data only. Customer is responsible for compliance decisions.\n\n- **Sources** — daily-refreshed OFAC SDN list (treasury.gov), live Base mainnet RPC reads, conservative mixer-contract seed list\n- **Scoring** — 0–100 with bands (`minimal`, `low`, `medium`, `high`, `critical`)\n- **Pricing** — $0.03 per single address, $0.025 per address for bulk (10-address minimum), settled via x402 in USDC on Base\n- **Cache** — 24 hours per `(chain, address)`\n- **Mode** — inbound only, `ENABLE=true` by default\n\nThe shim is a broker. It returns observational data. It never blocks, freezes, or settles on behalf of a customer, and it never replaces a regulated KYC/AML provider.\n\n## Endpoints\n\n| Method | Path | Cost | Purpose |\n| --- | --- | --- | --- |\n| `POST` | `/v1/aml/screen` | $0.03 | Screen one address |\n| `POST` | `/v1/aml/bulk` | $0.025/addr (min 10) | Screen many addresses in one call |\n| `GET` | `/v1/aml/today` | free | UTC-day counters and OFAC list status |\n| `GET` | `/health` | free | Liveness, OFAC list status, pricing |\n| `POST` | `/mcp` | — | JSON-RPC 2.0 entry for MCP clients |\n| `GET` | `/.well-known/mcp.json` | free | MCP descriptor |\n| `POST` | `/v1/x402/submit` | — | Settle a 402 quote, mint an access token |\n\n## MCP tools\n\n| Tool | Cost | Description |\n| --- | --- | --- |\n| `aml_screen` | $0.03 | Single-address screening |\n| `aml_bulk_screen` | $0.025/addr | Bulk screening, 10-address minimum |\n| `aml_today` | free | Counters and OFAC list status |\n\nEvery response — JSON-RPC and REST alike — carries the disclaimer field:\n\n```json\n\"disclaimer\": \"Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions.\"\n```\n\n## Quickstart\n\n```bash\ncurl -sX POST https://hive-mcp-aml-screen.onrender.com/v1/aml/screen \\\n  -H 'content-type: application/json' \\\n  -d '{\"address\":\"0x8589427373d6d84e98730d7795d8f6f8731fda16\",\"chain\":\"base\"}'\n```\n\nThe first call returns a 402 envelope with a quote. Settle on Base in USDC, then resubmit the proof to `/v1/x402/submit` to mint an access token, and replay the request with `X-Hive-Access: <token>`.\n\n```bash\ncurl -sX POST https://hive-mcp-aml-screen.onrender.com/v1/x402/submit \\\n  -H 'content-type: application/json' \\\n  -d '{\"nonce\":\"...\",\"payer\":\"0x...\",\"chain\":\"base\",\"tx_hash\":\"0x...\"}'\n```\n\n## Response shape\n\n```json\n{\n  \"ok\": true,\n  \"address\": \"0x8589427373d6d84e98730d7795d8f6f8731fda16\",\n  \"chain\": \"base\",\n  \"risk_score\": 100,\n  \"risk_band\": \"critical\",\n  \"flags\": [\n    {\"category\": \"ofac_sdn_match\", \"severity\": \"critical\", \"detail\": \"OFAC SDN list match: program=CYBER2 sdn_uid=12345\"},\n    {\"category\": \"mixer_contract\", \"severity\": \"high\", \"detail\": \"address is a known mixer/sanctioned-protocol contract\"}\n  ],\n  \"sdn_match\": true,\n  \"sdn_record\": {\"sdn_uid\": \"12345\", \"sdn_name\": \"TORNADO CASH\", \"program\": \"CYBER2\"},\n  \"chain_detail\": {\"nonce\": 0, \"is_contract\": true, \"balance_wei\": \"0\", \"head_block\": 12345678},\n  \"sources\": {\n    \"ofac_sdn\": {\"list_size\": 8421, \"last_refresh_ms\": 1745798400000},\n    \"heuristics\": {\"chain\": \"base\", \"version\": \"v1\"}\n  },\n  \"cache_hit\": false,\n  \"cache_ttl_seconds\": 86400,\n  \"screened_at\": 1745875200000,\n  \"screening_id\": \"8a3f...\",\n  \"disclaimer\": \"Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions.\"\n}\n```\n\n## Heuristics\n\nFor EVM chains the shim performs four real Base RPC reads — `getTransactionCount`, `getCode`, `getBalance`, `getBlockNumber` — plus a binary search over historical blocks to estimate the wallet's earliest activity. Categories returned in `flags`:\n\n| Category | Severity | Trigger |\n| --- | --- | --- |\n| `ofac_sdn_match` | critical | Address appears in the daily OFAC SDN list |\n| `mixer_contract` | high | Address is a known mixer/sanctioned-protocol contract |\n| `very_new_wallet` | medium | First on-chain activity within 24 hours |\n| `high_velocity` | medium | ≥ 20 outbound tx per hour over wallet lifetime |\n| `mixer_adjacent_balance` | low | Balance is exactly 0.1 / 1 / 10 / 100 ETH (Tornado pool denominations) |\n| `no_outbound_history` | low | Address has never sent a transaction on this chain |\n| `rpc_unavailable` | low | RPC read failed; SDN-only signal returned |\n| `heuristic_error` | low | Internal heuristic error; SDN-only signal returned |\n\nNon-EVM chains return the SDN match signal only with a `note` in `chain_detail`.\n\n## Configuration\n\n| Env | Default | Purpose |\n| --- | --- | --- |\n| `PORT` | `3000` | HTTP port |\n| `ENABLE` | `true` | Master switch. Set `false` to short-circuit all paid endpoints with `503` |\n| `WALLET_ADDRESS` | `0x15184bf50b3d3f52b60434f8942b7d52f2eb436e` | x402 settlement recipient (W1 MONROE) |\n| `BASE_RPC_URL` | `https://mainnet.base.org` | Base mainnet RPC for chain heuristics |\n| `OFAC_SDN_URL` | `https://www.treasury.gov/ofac/downloads/sdn.csv` | Source URL for the SDN list |\n| `DB_PATH` | `/tmp/aml.db` | SQLite database file |\n| `MIXER_ADDRESSES` | _(empty)_ | Comma-separated list of extra mixer contract addresses to flag |\n| `X402_BYPASS` | _(unset)_ | Set to any value to bypass payment in development |\n\n## Persistence\n\nSQLite at `/tmp/aml.db` with WAL journaling.\n\n- `ofac_sdn` — `(address PK, sdn_uid, sdn_name, program, list_type, inserted_at)` — wiped and re-inserted on each refresh\n- `ofac_meta` — refresh timestamp, count, byte size, last error\n- `screenings` — every screen call, billed or cached\n- `cache` — `(chain:address) → JSON payload`, 24-hour TTL\n\n## Operational notes\n\n- The OFAC list is refreshed at boot and every 24 hours thereafter\n- Cache entries are pruned hourly\n- Body limit is 256 KB on JSON requests\n- Inbound only — the shim never initiates outbound calls beyond the OFAC fetch and Base RPC reads\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Hive Civilization Directory\n\nPart of the Hive Civilization — agent-native financial infrastructure.\n\n- Endpoint Directory: https://thehiveryiq.com\n- Live Leaderboard: https://hive-a2amev.onrender.com/leaderboard\n- Revenue Dashboard: https://hivemine-dashboard.onrender.com\n- Other MCP Servers: https://github.com/srotzin?tab=repositories&q=hive-mcp\n\nBrand: #C08D23\n<!-- /hive-footer -->\n",
  "bytes": 6670,
  "sha": "a9071dcbd8f085fddefeff42774e36396d5424a5504ffa354aeebd4637070a4a",
  "repo_slug": "srotzin/hive-mcp-aml-screen",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_srotzin_hive_mcp_aml_screen_cbda0981/readme"
}