hive-mcp-aml-screen

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

Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions.

Sources — daily-refreshed OFAC SDN list (treasury.gov), live Base mainnet RPC reads, conservative mixer-contract seed list
Scoring — 0–100 with bands (minimal, low, medium, high, critical)
Pricing — $0.03 per single address, $0.025 per address for bulk (10-address minimum), settled via x402 in USDC on Base
Cache — 24 hours per (chain, address)
Mode — inbound only, ENABLE=true by default

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

Endpoints

Method	Path	Cost	Purpose
`POST`	`/v1/aml/screen`	$0.03	Screen one address
`POST`	`/v1/aml/bulk`	$0.025/addr (min 10)	Screen many addresses in one call
`GET`	`/v1/aml/today`	free	UTC-day counters and OFAC list status
`GET`	`/health`	free	Liveness, OFAC list status, pricing
`POST`	`/mcp`	—	JSON-RPC 2.0 entry for MCP clients
`GET`	`/.well-known/mcp.json`	free	MCP descriptor
`POST`	`/v1/x402/submit`	—	Settle a 402 quote, mint an access token

MCP tools

Tool	Cost	Description
`aml_screen`	$0.03	Single-address screening
`aml_bulk_screen`	$0.025/addr	Bulk screening, 10-address minimum
`aml_today`	free	Counters and OFAC list status

Every response — JSON-RPC and REST alike — carries the disclaimer field:

"disclaimer": "Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions."

Quickstart

curl -sX POST https://hive-mcp-aml-screen.onrender.com/v1/aml/screen \
  -H 'content-type: application/json' \
  -d '{"address":"0x8589427373d6d84e98730d7795d8f6f8731fda16","chain":"base"}'

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

curl -sX POST https://hive-mcp-aml-screen.onrender.com/v1/x402/submit \
  -H 'content-type: application/json' \
  -d '{"nonce":"...","payer":"0x...","chain":"base","tx_hash":"0x..."}'

Response shape

{
  "ok": true,
  "address": "0x8589427373d6d84e98730d7795d8f6f8731fda16",
  "chain": "base",
  "risk_score": 100,
  "risk_band": "critical",
  "flags": [
    {"category": "ofac_sdn_match", "severity": "critical", "detail": "OFAC SDN list match: program=CYBER2 sdn_uid=12345"},
    {"category": "mixer_contract", "severity": "high", "detail": "address is a known mixer/sanctioned-protocol contract"}
  ],
  "sdn_match": true,
  "sdn_record": {"sdn_uid": "12345", "sdn_name": "TORNADO CASH", "program": "CYBER2"},
  "chain_detail": {"nonce": 0, "is_contract": true, "balance_wei": "0", "head_block": 12345678},
  "sources": {
    "ofac_sdn": {"list_size": 8421, "last_refresh_ms": 1745798400000},
    "heuristics": {"chain": "base", "version": "v1"}
  },
  "cache_hit": false,
  "cache_ttl_seconds": 86400,
  "screened_at": 1745875200000,
  "screening_id": "8a3f...",
  "disclaimer": "Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions."
}

Heuristics

For 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:

Category	Severity	Trigger
`ofac_sdn_match`	critical	Address appears in the daily OFAC SDN list
`mixer_contract`	high	Address is a known mixer/sanctioned-protocol contract
`very_new_wallet`	medium	First on-chain activity within 24 hours
`high_velocity`	medium	≥ 20 outbound tx per hour over wallet lifetime
`mixer_adjacent_balance`	low	Balance is exactly 0.1 / 1 / 10 / 100 ETH (Tornado pool denominations)
`no_outbound_history`	low	Address has never sent a transaction on this chain
`rpc_unavailable`	low	RPC read failed; SDN-only signal returned
`heuristic_error`	low	Internal heuristic error; SDN-only signal returned

Non-EVM chains return the SDN match signal only with a note in chain_detail.

Configuration

Env	Default	Purpose
`PORT`	`3000`	HTTP port
`ENABLE`	`true`	Master switch. Set `false` to short-circuit all paid endpoints with `503`
`WALLET_ADDRESS`	`0x15184bf50b3d3f52b60434f8942b7d52f2eb436e`	x402 settlement recipient (W1 MONROE)
`BASE_RPC_URL`	`https://mainnet.base.org`	Base mainnet RPC for chain heuristics
`OFAC_SDN_URL`	`https://www.treasury.gov/ofac/downloads/sdn.csv`	Source URL for the SDN list
`DB_PATH`	`/tmp/aml.db`	SQLite database file
`MIXER_ADDRESSES`	(empty)	Comma-separated list of extra mixer contract addresses to flag
`X402_BYPASS`	(unset)	Set to any value to bypass payment in development

Persistence

SQLite at /tmp/aml.db with WAL journaling.

ofac_sdn — (address PK, sdn_uid, sdn_name, program, list_type, inserted_at) — wiped and re-inserted on each refresh
ofac_meta — refresh timestamp, count, byte size, last error
screenings — every screen call, billed or cached
cache — (chain:address) → JSON payload, 24-hour TTL

Operational notes

The OFAC list is refreshed at boot and every 24 hours thereafter
Cache entries are pruned hourly
Body limit is 256 KB on JSON requests
Inbound only — the shim never initiates outbound calls beyond the OFAC fetch and Base RPC reads

License

MIT — see LICENSE.

Hive Aml Screen