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=trueby 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 refreshofac_meta— refresh timestamp, count, byte size, last errorscreenings— every screen call, billed or cachedcache—(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 Civilization Directory
Part of the Hive Civilization — agent-native financial infrastructure.
- Endpoint Directory: https://thehiveryiq.com
- Live Leaderboard: https://hive-a2amev.onrender.com/leaderboard
- Revenue Dashboard: https://hivemine-dashboard.onrender.com
- Other MCP Servers: https://github.com/srotzin?tab=repositories&q=hive-mcp
Brand: #C08D23
<!-- /hive-footer -->