Real-time AML and sanctions screening for agent-to-agent transactions
io.github.srotzin/hive-mcp-aml-screen (MCP) Server
This MCP server provides real-time AML and sanctions screening for agent-to-agent (A2A) transactions. It acts as an AML screening broker: you send an address and a chain, and it returns an observational risk score plus sanctions-related match information.
🛠️ Key Features
Real-time AML and sanctions screening for A2A network transactions
Input: address and chain
Output: 0–100 observational risk score
Output: OFAC SDN match flag
Output: chain-heuristic categories
24-hour cached results
Uses a daily-refreshed OFAC SDN list (treasury.gov)
🚀 Use Cases
Screen transaction participant addresses for sanctions risk in agent-commerce flows
Generate AML-related context for downstream compliance decisions (non-blocking)
⚡ Developer Benefits
Standardized results for MCP-based agent workflows (risk score, match flag, categories)
Cached lookups to reduce repeated screening overhead
⚠️ Limitations
Observational data only; Hive does not block, freeze, or settle
Compliance decisions remain the customer’s responsibility
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:
json
"disclaimer":"Hive does not block, freeze, or settle. This is observational AML data only. Customer is responsible for compliance decisions."
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>.
{"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