# Bitpoort

> On-chain intelligence MCP for AI agents that act, not just read. 80 MCP tools and 338 REST paths (375 OpenAPI operations) live across Ethereum + Bitcoin + Hyperliquid. Free instant API key, no signup.

Three things you only get here:

1. **Screening & tracing workflow** — screen → assess → trace → monitor → signed report → public verify, across OFAC + UK + IL + JP (1,606 designated addresses), bridge-aware 3-hop tracing, retroactive sanctions exposure scanner.
2. **Agent-Safety contract** — pre-trade `validate_agent_action` + KYA signed agent identities + `dry_run` on every mutator + safety metadata on every response + per-customer audit log.
3. **Full Hyperliquid suite** — market, traders, funding arbs, liquidations, copy-trade, plus unique ETH ↔ HL cross-chain correlation that finds when on-chain whales front-run their own perp positions.

4,909 regression tests. 100% across correctness / freshness / provenance / cross-tool consistency.

## Get a key

`POST https://api.bitpoort.com/v1/keys` returns a free-tier `bp_` key in one request. No email, no signup, 1 req/sec (60/min sliding window), 10,000/day, 90-day expiry. 50 instant keys per IP per day. For test/CI workloads that need higher creation throughput, register a permanent key at `POST /v1/register` (no daily creation cap, no expiry).

## MCP endpoint

`https://mcp.bitpoort.com/` (Streamable HTTP, JSON-RPC over POST). Auth via `X-API-Key` header or `Authorization: Bearer`. OAuth 2.1 lane available with dynamic client registration at `https://api.bitpoort.com/.well-known/oauth-authorization-server`.

## Discovery

- [/.well-known/mcp.json](https://bitpoort.com/.well-known/mcp.json): MCP discovery manifest (endpoint, transport, auth, lanes, eval baseline, capability summary)
- [Agent integration guide](https://docs.bitpoort.com/agents): paste-ready config for Claude Code, Claude Desktop, Cursor, VS Code, Codex/OpenClaw, Anthropic SDK, OpenAI Agents SDK, JSON-RPC curl
- [Markdown integration guide](https://bitpoort.com/agents.md): same content, LLM-readable markdown
- [/tools.json](https://mcp.bitpoort.com/tools.json): full tool catalog with schemas (public, no auth)
- [/fixtures.json](https://mcp.bitpoort.com/fixtures.json): stable test fixtures for end-to-end agent tests
- [Documentation](https://docs.bitpoort.com): REST + MCP reference
- [OpenAPI 3.1 spec](https://api.bitpoort.com/openapi.json): full machine-readable schema (public, no auth)
- [ReDoc UI](https://api.bitpoort.com/redoc): interactive API browser (public, no auth)
- [Live trust + accuracy baseline](https://api.bitpoort.com/v1/trust): public, no auth — published evaluation results, sanctions counts, reproducibility chain, differentiators
- [Compliance Studio](https://compliance.bitpoort.com): no-code UI for generate_compliance_report + export_compliance_pdf (anonymous instant-key tier, signed screening reports in <30s, no Claude Desktop required)

## Health

`GET https://api.bitpoort.com/health` returns JSON: chain status, ingestion lag, pipeline health. Public.

## Standard query contract

Most list endpoints share: `chain` (chain ID or ALL), `limit` (max 100–200), `min_usd` (where applicable), `since` (ISO 8601 lower bound), `until` (ISO 8601 upper bound), `cursor` (opaque keyset paginator from a previous response's `next_cursor`). Responses include `next_cursor` and `has_more`.

## All 80 MCP tools (12 lanes)

Every tool description in `tools/list` is shaped as
`[Lane] WHAT. USE WHEN: ... DON'T USE FOR: ... RETURNS: ...` — agent-routing
infrastructure, not docs prose.

- **Forensic** (16): screen_address, assess_risk, detect_mixer_interactions, trace_flows, monitor_address, list_retroactive_alerts, dismiss_retroactive_alert, generate_compliance_report, export_compliance_pdf, analyze_source_of_funds, screen_pep_person, check_hack_incident, lookup_hack_incidents, lookup_bridge_transactions, trace_cross_chain_path, check_honeypot
- **KYA / Know Your Agent** (4): validate_agent_action, register_agent_identity, list_my_agent_identities, revoke_agent_identity
- **Whales & Entities** (5): get_whale_activity, get_btc_flows, get_entity_activity, get_wallet_profile, find_payment_clusters
- **Market signals** (8): get_trade_signals, get_conviction_signals, get_predictions, get_price_history, get_token_flows, get_exchange_flows, get_trending_tokens, get_emerging_tokens
- **Hyperliquid perps** (6): get_hl_market, get_hl_traders, get_hl_funding_arbs, get_hl_liquidation_heatmap, get_hl_copy_trade_alerts, get_cross_chain_signals
- **Alpha & smart money** (3): get_smart_wallets, get_mev_leaderboard, get_intelligence_feed
- **Analytics** (2): get_signal_accuracy, get_signal_history
- **Risk & alarms** (5): get_intent_detections, get_alarm_feed, get_alarm_categories, get_risk_briefing, check_abuse_status
- **Direct RPC** (7): rpc_get_balance, rpc_get_block, rpc_get_transaction, rpc_get_logs, rpc_get_contract_info, rpc_read_contract, rpc_trace_transaction
- **Data browsing** (3): query_blocks, query_transactions, inspect_block
- **System & observability** (5): get_system_status, get_health, get_pipeline_status, get_stats, get_logs
- **Q&A & overview** (3): ask_blockchain, get_network_summary, search_rag

Active total: 16+4+5+8+6+3+2+5+7+3+5+3 = **67**. Two deprecated (`get_alerts`, `get_chain_status`) still returned by `tools/list` for back-compat (replaced by `get_system_status(sections=[…])`, removed after 2026-09-01). Live count via `tools/list`: **69** (67 active + 2 deprecated).

## Compliance workflow (signed, hash-reproducible)

Three calls, end-to-end:

```
1. generate_compliance_report(address, chain, sections=[...]) →
   {report, body_sha256, signature, content_hash, public_verify_url}

2. export_compliance_pdf(content_hash, return_mode="binary") →
   {pdf_base64, filename, byte_size, sha256}

3. GET /v1/verify/{content_hash} (public, no auth) →
   {valid: true, signed_at, signing_key_id, attestation: {git_commit, alembic_head, eval_baseline}}
```

Stable test hash for end-to-end agent tests is exposed at `/mcp/fixtures.json` (`compliance_report_hashes.lazarus_full_sections`).

## Agent-Safety workflow

```
1. register_agent_identity(agent_name, public_key, capabilities) →
   {agent_id, agent_name, public_verify_url}

2. validate_agent_action(agent_name, action_type, counterparty_address, value_usd) →
   {verdict: allow|deny, reasons, checks: {sanctions, mixer, abuse, scope}}

3. GET /v1/agent-identity/{agent_name} (public, no auth) →
   {agent_name, public_key, capabilities, status: active|revoked}
```

## Smoke test (one-shot)

```bash
KEY=$(curl -s -X POST https://api.bitpoort.com/v1/keys | python3 -c "import sys,json;print(json.load(sys.stdin)['api_key'])")
# Expected: KEY starts with "bp_".

# 1. Auth identity
curl -H "X-API-Key: $KEY" https://api.bitpoort.com/v1/auth/me
# Expected: {"api_key_id":<int>, "name":"instant-agent", "role":"agent", "rate_limit":60, "scopes":[...]}

# 2. Sample REST query
curl -H "X-API-Key: $KEY" "https://api.bitpoort.com/v1/whales/recent?chain=ETH&limit=3"
# Expected: {"count":<=3>, "chain":"ETH", "next_cursor":<string|null>, "has_more":<bool>, "whales":[...]}

# 3. MCP initialize -- capture session id
SESSION=$(curl -sD - -X POST https://mcp.bitpoort.com/ \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id"{gsub(/\r/,"",$2);print $2}')

# 4. MCP tools/list
curl -X POST https://mcp.bitpoort.com/ \
  -H "X-API-Key: $KEY" -H "Mcp-Session-Id: $SESSION" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# Expected: result.tools length == 69.

# 5. MCP tool call (sanctions screen on a known-clean address)
curl -X POST https://mcp.bitpoort.com/ \
  -H "X-API-Key: $KEY" -H "Mcp-Session-Id: $SESSION" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"screen_address","arguments":{"address":"0xab5801a7d398351b8be11c439e05c5b3259aec9b","chain":"ETH"}}}'
# Expected: result.content[0].text → JSON with {sanctions_status:"CLEAR", matches:[], total_matches:0}.
```

## Pricing

| Tier | Price | Auth | Rate | Daily cap | LLM chat | MCP / REST |
|------|-------|------|------|-----------|----------|------------|
| Free | $0 | API key (no signup) | 60 req/min | 10,000 | BYOK | All 78 tools |
| Pro | $99/mo | API key + OAuth | 600 req/min | 1,000,000 | Managed (BYOK overflow) | All 78 tools |
| Enterprise | Custom | API key + OAuth + SSO/SAML | Unlimited | Unlimited | Custom managed | All 78 tools |

MCP tool calls are free in every tier. Heavy endpoints (deep historical scans, full compliance reports) are weighted lower than 1/sec on Free. Pro removes that throttle.

## Data coverage

- **Ethereum** — full pipeline, archive node, 500M+ transactions indexed
- **Bitcoin** — 359K+ entity flows, 2.3M labeled addresses, CIOH clustering
- **Hyperliquid** — native perp / funding / fills indexing, top traders, liquidation cascades
- **Sanctions** — 1,606 designated addresses across OFAC_SDN + UK_HMT + IL_NBCTF + JP_METI (daily refresh)
- **Mixers** — 80 contracts across 10 protocols (Tornado Cash, Railgun, ChipMixer, Sinbad, Wasabi, …)
- **Risk intelligence** — 23,542 community-reported abuse addresses across MEW darklist + ScamSniffer + FORTA