# Bitpoort

> On-chain data for AI agents. REST API + MCP server.

Bitpoort provides real-time and historical blockchain data through a REST API and MCP (Model Context Protocol) server. AI agents can autonomously query on-chain activity live across Ethereum, Bitcoin, and Hyperliquid (Polygon node coverage in progress) using 61 structured JSON tools — no scraping, indexing, or node operation required.

## MCP Server

- Endpoint (primary): `https://mcp.bitpoort.com/` — Streamable HTTP, stateless JSON-RPC
- Endpoint (legacy SSE, sunset 2026-08-01): `https://api.bitpoort.com/mcp/sse` — kept for older MCP clients that don't speak Streamable HTTP yet. New integrations should use the Streamable HTTP endpoint above.
- Protocol: Model Context Protocol (version 2024-11-05)
- Auth: API key via `x-api-key` header (instant key: `POST https://api.bitpoort.com/v1/keys`)
- Cost: $0 per tool call — MCP usage included in every tier
- Max concurrent sessions: 50
- Tool timeout: 30s
- All tools return structured JSON (no markdown, no prose)

---

## MCP Tools (61)

### Blockchain Data (3)

**query_blocks** — Get recent blocks for a specific blockchain. Returns block number, hash, timestamp, tx count, and gas used.

**query_transactions** — Get transactions for a chain, optionally filtered by block number. Returns tx hash, from/to addresses, USD value, type, method name, and per-tx forensic enrichment (`sanctions_match`, `mixer_match`).

**inspect_block** — Get full detail for a specific block including all transactions, whale activity, and RAG chunks. Per-tx sanctions and mixer enrichment included.

### Whale & Entity Tracking (5)

**get_whale_activity** — Get recent whale (high-value) transactions. Returns tx_hash, from/to addresses and labels, value_usd, tier (MID/LARGE/MEGA), and description.

**get_entity_activity** — Get activity history for a named entity (e.g. 'Binance', 'Wintermute') or wallet address. Returns structured periods with tx_count, total_value_usd, net_flow_usd, and tx_types breakdown.

**get_exchange_flows** — Get exchange inflow/outflow data. Returns aggregate net flow with direction, per-exchange breakdown, and per-token flows. Excludes exchange-to-exchange transfers.

**get_token_flows** — Get tokens ranked by net buying or selling pressure. Returns sellers[] and buyers[] arrays with token, buy_usd, sell_usd, net_usd, buy_ratio, and swap_count. Based on DEX swap data, excludes stablecoins.

**get_wallet_profile** — Complete wallet profile for an Ethereum address: label, classification, risk score, volume, transaction count, top tokens, top counterparties, cluster membership, plus `sanctions_status` (OFAC) and `mixer_status` (Tornado/Railgun). Cached 300s.

### Intelligence & Signals (7)

**get_intent_detections** — Get detected behavioral patterns (accumulation, distribution, arbitrage, rug signals). Includes confidence scores and risk levels.

**get_trade_signals** — Get composite trade signals from cross-signal analysis. Returns signals with token, direction (bullish/bearish), score (0-100), thesis, evidence. Also returns activity anomalies vs 7-day baseline.

**get_conviction_signals** — Get conviction signals from 11-source cross-signal correlation (swap pressure, smart money, exchange flow, token momentum, risk warnings, smart wallet consensus, MEV bot interest, position shift, wallet flow imbalance, DEX microstructure, price-flow divergence). Returns conviction_score (0-100), signal_count, thesis, evidence.

**get_predictions** — ML-based short-term price predictions. LightGBM + LSTM ensemble trained on 33 on-chain and technical features. Returns per-symbol direction, probability, confidence. Horizons: 5m, 10m, 15m. Covers 19 tokens.

**get_smart_wallets** — Top wallets ranked by 7-day trading performance. Returns wallet address, composite score (0-100), win rate, total P&L, profit factor, protocols used, trade count.

**get_mev_leaderboard** — MEV bot leaderboard ranked by 7-day extracted value. Returns bot address, strategy (flash_loan_arb, lending_arb, dex_arb), success rate, P&L, extracted value, gas costs, trade count.

**get_intelligence_feed** — Unified event feed from 6 sources: whale transfers, intent detections, liquidation risks, profitable trades, MEV extractions, and signals. Filter by event_type.

### Token Discovery (2)

**get_emerging_tokens** — Emerging tokens ranked by momentum score. Returns tokens discovered on-chain with swap activity, unique traders, holder growth, and smart money interest.

**get_trending_tokens** — Tokens ranked by swap volume over a time window. Returns symbol, volume, change percentage, swap count, unique wallets, and buy/sell ratio.

### Search & Q&A (3)

**search_rag** — Semantic search over 6.5M+ indexed on-chain intelligence chunks. Returns ranked results with text, topic, chain, and relevance score. Hybrid dense + BM25 retrieval with cross-encoder reranking.

**ask_blockchain** — Ask a natural language question about blockchain activity. Best for: 'What happened on ETH today?', 'Any whale movements?', 'What has Binance been doing?'.

**get_network_summary** — Structured network summary: hourly stats (tx_count, volume, gas), whale activity (count, top movements), latest block, and system health. Direct DB queries, no RAG.

### Price Data (1)

**get_price_history** — Recent price candles (OHLCV) and price change. Returns candles[] with OHLCV data and price_change with current/past price and change_pct. Supports 20 major tokens, 1-minute resolution.

### Risk & Alerts (2)

**get_alarm_feed** — Alarm feed with triggered on-chain events. Returns alarm_type, severity, chain, timestamp, title, detail, value_usd.

**get_alarm_categories** — All available alarm categories with severity levels, supported chains, and default thresholds.

### Forensic / Compliance (8)

**screen_address** — OFAC sanctions screening for a single address. Returns `sanctions_status` (MATCH/CLEAR), all matching entries with program-level entity attribution (TORNADO CASH, LAZARUS GROUP, GARANTEX), confidence score, and a regulatory disclaimer string. Sub-2ms response. No PII.

**detect_mixer_interactions** — Find transactions where an address interacted with known mixing protocols (Tornado Cash, Railgun). Returns `is_mixer_contract` (set when the queried address is itself a mixer pool/router), `interaction_count`, and per-tx details with mixer_name, pool_label, and side. Lookback: up to 365 days.

**trace_flows** — Bridge-aware multi-hop graph traversal from a starting address. Returns nodes + edges with `sanctions_status` and `mixer_flag` propagated per node. Direction: forward (downstream), backward (upstream), or both. Limits: max 8 hops, value threshold (default $1K), lookback up to 1 year.

**assess_risk** — Composite risk scoring (0-100) for an address. Returns `risk_score`, `risk_band` (LOW/MEDIUM/HIGH/CRITICAL), and `recommendation` (PROCEED / STANDARD_DUE_DILIGENCE / ENHANCED_DUE_DILIGENCE / BLOCK_AND_ESCALATE). Combines sanctions, mixer exposure, behavioral patterns, and counterparty risk.

**check_abuse_status** — Community-source abuse list lookup (phishing, drainers, scam tokens, malicious contracts). Strictly distinct from sanctions: returns `abuse_status` (MATCH/CLEAR), `category` (drainer / malicious_contract / hacker / poisoning / scam_token / rug_pull / phishing / exploit_victim), source attribution, and severity weighting.

**generate_compliance_report** — HMAC-SHA256-signed compliance report for an address. Combines sanctions screening, mixer interactions, wallet profile, risk score, counterparty exposure, tx findings, and an executive summary into one signed JSON payload. Each report has a `content_hash` verifiable at `GET /v1/verify/{hash}`. Embeds reproducibility chain (git_commit, alembic_head, eval_baseline) + data_provenance counts.

**export_compliance_pdf** — WeasyPrint-rendered PDF export of a previously-generated signed compliance report. Returns base64-encoded PDF + the original signed JSON for diffability.

**get_risk_briefing** — Security-focused risk briefing. Returns risk_events (anomalies), intents (behavioral patterns with confidence/risk_level), and transactions (with risk_score and flags).

### Compliance Monitoring (3)

**monitor_address** — Register an address (per-customer, scoped via API key) for retroactive sanctions exposure. When new addresses are added to OFAC/UK/IL/JP lists, the scanner walks the address's historical interactions and emits HMAC-signed retroactive alerts.

**list_retroactive_alerts** — Pull retroactive alerts for the calling API key. Severity HIGH/CRITICAL based on total interaction USD. Optional filter by status (active, dismissed).

**dismiss_retroactive_alert** — Acknowledge / dismiss a retroactive alert by id. Removes from active list; full audit trail preserved.

### KYA Agent Identity (4)

**register_agent_identity** — Register a unique agent identity (name + ed25519 public key) so downstream consumers can verify which agent acted. Public verify at `GET /v1/agent-identity/{name}`.

**validate_agent_action** — Verify a signed action payload against a registered agent identity. Returns valid/invalid + signer name + identity status.

**revoke_agent_identity** — Revoke an existing agent identity. Subsequent verify attempts return revoked status.

**list_my_agent_identities** — List all agent identities registered by the calling API key (per-customer scoped).

### Cross-Chain (2)

**get_cross_chain_signals** — ETH on-chain to Hyperliquid perpetual correlation signals. Detects when ETH whale activity (accumulation, exchange withdrawal) correlates with HL positioning changes. Returns signal type, entities, values, confidence, direction, and time lag.

**get_btc_flows** — Bitcoin whale flows with entity enrichment from 2.3M labeled addresses. Returns flow type, BTC/USD amount, from/to entity names, intent classification, and market signal. Uses CIOH clustering for entity resolution.

### Hyperliquid (5)

**get_hl_market** — Hyperliquid market state: smart money positioning (long/short %), aggressive flow direction, and funding rates with open interest for all coins.

**get_hl_traders** — Top Hyperliquid perpetual traders ranked by smart money score. Returns win rate, PnL, Sharpe ratio, profit factor, edge score, and best coin.

**get_hl_funding_arbs** — Active HL funding arbitrage opportunities with annualized rates and notional liquidity.

**get_hl_liquidation_heatmap** — HL liquidation heatmap by coin and price level. Identifies cluster zones where forced liquidations are likely.

**get_hl_copy_trade_alerts** — Real-time copy-trade alerts when tracked HL traders open or close positions.

### System (9)

**get_system_status** — Consolidated system status. Sections: health, pipeline, chain, alerts, stats. One call replaces the deprecated wrappers below.

**get_pipeline_status** — *Deprecated, use `get_system_status(sections=['pipeline'])`.* Current state of the 7-stage pipeline (INGEST, NORMALIZE, ENRICH, CHUNK, EMBED, INDEX, STORE).

**get_chain_status** — *Deprecated, use `get_system_status(sections=['chain'])`.* Per-chain processing status with block watermarks and lag.

**get_health** — *Deprecated, use `get_system_status(sections=['health'])`.* Overall system health score (0-100).

**get_stats** — *Deprecated, use `get_system_status(sections=['stats'])`.* Aggregate statistics: total blocks, transactions, RAG chunks, whale txs.

**get_alerts** — *Deprecated, use `get_system_status(sections=['alerts'])`.* Alert history with rule, severity, and resolution status.

**get_logs** — Recent system log entries, optionally filtered by level and service. Sanitized (no paths, DSNs, passwords, IPs).

**get_signal_accuracy** — Historical accuracy metrics for trade signals across horizons (5m, 10m, 15m, 1h, 4h, 24h) at the token level.

**get_signal_history** — Historical signal entries with realized outcomes for backtesting and model evaluation.

### Direct Ethereum RPC (7)

**rpc_get_balance** — ETH balance of an Ethereum address. Returns balance in ETH and wei, with entity label if known.

**rpc_get_block** — Ethereum block details: timestamp, gas usage, transaction count, base fee. Set `include_transactions=true` for transaction list with from/to labels.

**rpc_get_transaction** — Full transaction details by hash: from/to with entity labels, value in ETH, gas cost, status (success/reverted), log count. Combines tx data and receipt.

**rpc_get_logs** — Event logs emitted by a contract. Useful for tracking Transfer events, approvals, swaps. Max 2000-block range.

**rpc_get_contract_info** — Check if an address is a smart contract, get ETH balance, code size, transaction count, entity label and classification.

**rpc_read_contract** — Read smart contract state via view functions. Supports ERC-20: name(), symbol(), decimals(), totalSupply(), balanceOf(address), owner(). No ABI needed.

**rpc_trace_transaction** — Internal call trace of a transaction: all internal calls, ETH transfers, contract interactions with entity labels. Full execution tree for complex DeFi transactions.

---

## REST API

- Base URL: `https://api.bitpoort.com/v1/`
- Auth lanes: (a) API key via `X-API-Key` or `Authorization: Bearer bp_...`, (b) OAuth 2.1 via `Authorization: Bearer <opaque>` (use the same MCP + REST surface). Discovery at `https://api.bitpoort.com/.well-known/oauth-authorization-server` (RFC 8414) and `https://api.bitpoort.com/.well-known/openid-configuration`. OAuth scopes: `mcp:read`, `api:read`, `profile:read`, `openid`, `email`. Refresh tokens rotate; reuse revokes the chain.
- Format: JSON

### Public Endpoints (no auth)

- `GET /v1/whales/recent` — Recent whale transactions across ETH ($50K+), BTC, and stablecoins ($250K+)
- `GET /v1/entity/{name}` — Entity profile with stats, counterparties, recent transactions
- `GET /v1/entity/list` — Top entities ranked by whale volume
- `GET /v1/health` — System health check
- `GET /v1/feed/hl/*` — Hyperliquid public data (positions, funding, liquidations)
- `POST /v1/keys` — Instant API key for agents (no email, free, 1 req/sec, 10,000/day cap)
- `POST /v1/register` — Email-verified registration (permanent key, no expiry)
- `GET /v1/verify/{hash}` — Verify a signed compliance report content_hash

### Authenticated Endpoints

- `POST /v1/chat` — Natural language blockchain queries with tool use (Claude Sonnet, up to 5 rounds, Pro tier)
- `POST /v1/chat/stream` — Streaming chat (SSE)
- `GET /v1/feed/eth` — Real-time Ethereum event feed
- `GET /v1/feed/btc` — Real-time Bitcoin event feed
- `GET /v1/intelligence/*` — Trade signals, predictions, conviction scores
- `GET /v1/wallets/*` — Smart wallet rankings, MEV leaderboard
- `GET /v1/graph/*` — Entity relationship graph
- `GET /v1/explorer` — RPC agent for direct blockchain queries
- `GET /v1/alarm/*` — Alarm feeds and categories

---

## Data Coverage

### Ethereum
- Full 7-stage indexing pipeline
- Erigon archive node (full history)
- 500M+ transactions indexed
- Whale threshold: $50K+
- Real-time: ~12s block time

### Bitcoin
- Bitcoin Core with txindex
- 359K+ entity flows tracked
- 2.3M labeled addresses (CIOH clustering)
- Exchange, mining pool, and custodian labels

### Hyperliquid
- Non-validator node
- Positions, funding rates, liquidations, open interest
- Smart money positioning and top trader rankings

### Forensic data
- Sanctions: 1,386 designated addresses across OFAC_SDN + UK_HMT + IL_NBCTF + JP_METI, refreshed daily
- Mixers: 43 known contracts across Tornado Cash, Railgun, and other privacy protocols
- Reproducibility: every signed report embeds git_commit + alembic_head + eval_baseline (97.5% tool selection accuracy across 47 evaluated tools)
- Public verify: GET https://api.bitpoort.com/v1/verify/{report_hash} (no auth required)

### Tracked Tokens (ML Predictions)
ETH, BTC, SOL, LINK, ARB, OP, UNI, AAVE, LDO, ENS, CRV, PENDLE, AVAX, BNB, DOT, XRP, ADA, MKR, SHIB

---

## Pricing

| Tier | Price | Auth | Rate | Daily | LLM Chat | MCP / REST |
|------|-------|------|------|-------|----------|-----------|
| Free | $0 | API key (no signup) | 1/sec | 10,000 | BYOK | All 61 tools |
| Pro | $99/mo | API key + OAuth | 10/sec | 1,000,000 | Managed + BYOK overflow | All 61 tools |
| Enterprise | Custom | API key + OAuth + SSO/SAML | Unlimited | Unlimited | Custom managed | All 61 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.

---

## Links

- Website: https://bitpoort.com
- Documentation: https://bitpoort.com/docs
- MCP Server: https://mcp.bitpoort.com/
- REST API: https://api.bitpoort.com/v1/
- Register: https://bitpoort.com/register
- Whale Tracker: https://bitpoort.com/whales