# Satoshi API — Full Reference

> Bitcoin fee intelligence that saves money on every transaction.

## Overview

Satoshi API is a REST API for Bitcoin blockchain data, built for AI agents and developers. It wraps a Bitcoin Core full node with analyzed, structured data — fee recommendations, mempool analysis, block statistics, mining data, and real-time streams. Native MCP integration lets Claude, GPT, and other LLM agents call Bitcoin endpoints as tools.

**Who it's for:** AI agents that need Bitcoin data, developers building Bitcoin apps, wallets optimizing fee spend, bots monitoring the mempool.

## Authentication

1. Register: POST https://bitcoinsapi.com/api/v1/register with `{"email": "you@example.com", "agreed_to_terms": true}`
2. Include your key in every request: `X-API-Key: <your_key>`
3. Anonymous access (no key) works for lightweight GET endpoints with reduced limits.

Tiers: anonymous (no key), free (registered), pro ($19/mo), enterprise (custom).

## Rate Limits

| Tier       | Req/min | Daily    | Block cap | Notes              |
|------------|---------|----------|-----------|--------------------|
| Anonymous  | 30      | 1,000   | 144       | GET only           |
| Free       | 100     | 10,000  | 144       | All endpoints      |
| Pro        | 500     | 100,000 | 1,008     | $19/mo via Stripe  |
| Enterprise | 2,000   | Custom  | 2,016     | Contact us         |

Response headers for self-throttling:
- `X-RateLimit-Limit` — max requests per window
- `X-RateLimit-Remaining` — requests left in window
- `X-RateLimit-Reset` — seconds until window resets
- `X-RateLimit-Daily-Limit` / `X-RateLimit-Daily-Remaining`
- `Retry-After` — seconds to wait (on 429 responses)

## Endpoints

All paths prefixed with `/api/v1`. Base URL: `https://bitcoinsapi.com`

### Fees (save money on every transaction)
| Method | Path | Description |
|--------|------|-------------|
| GET | /fees | All fee estimates (multiple confirmation targets) |
| GET | /fees/recommended | Smart recommendation: send now or wait? |
| GET | /fees/landscape | Full fee landscape with percentiles |
| GET | /fees/mempool-blocks | Projected mempool blocks with fee ranges |
| GET | /fees/estimate-tx | Estimate fee for a specific transaction size |
| GET | /fees/history | Historical fee data |
| GET | /fees/plan | Fee planning: optimal send timing |
| GET | /fees/savings | How much you save by waiting |
| GET | /fees/{target} | Fee estimate for specific confirmation target |

### Mempool
| Method | Path | Description |
|--------|------|-------------|
| GET | /mempool | Full mempool analysis: fee buckets, congestion |
| GET | /mempool/info | Raw mempool info from Bitcoin Core |
| GET | /mempool/tx/{txid} | Specific unconfirmed transaction details |
| GET | /mempool/txids | List of all mempool transaction IDs |
| GET | /mempool/recent | Recently added mempool transactions |

### Blocks
| Method | Path | Description |
|--------|------|-------------|
| GET | /blocks/latest | Latest block with full analysis |
| GET | /blocks/tip/height | Current chain tip height |
| GET | /blocks/tip/hash | Current chain tip hash |
| GET | /blocks/{height_or_hash} | Block by height or hash |
| GET | /blocks/{height}/stats | Block statistics |
| GET | /blocks/{hash}/header | Raw block header |
| GET | /blocks/{hash}/txids | Transaction IDs in a block |
| GET | /blocks/{hash}/txs | Transactions in a block (paginated) |
| GET | /blocks/{hash}/raw | Raw block hex |

### Transactions
| Method | Path | Description |
|--------|------|-------------|
| GET | /tx/{txid} | Full transaction analysis |
| GET | /tx/{txid}/raw | Raw transaction data |
| GET | /tx/{txid}/status | Confirmation status |
| GET | /tx/{txid}/hex | Transaction hex |
| GET | /tx/{txid}/outspends | Which outputs are spent |
| GET | /tx/{txid}/merkle-proof | Merkle proof for a transaction |
| GET | /utxo/{txid}/{vout} | UTXO lookup |
| POST | /transactions/decode | Decode a raw transaction hex |
| POST | /transactions/broadcast | Broadcast a signed transaction |

### Mining
| Method | Path | Description |
|--------|------|-------------|
| GET | /mining | Mining summary: hashrate, difficulty, pools |
| GET | /mining/nextblock | Next block prediction |
| GET | /mining/hashrate/history | Historical hashrate data |
| GET | /mining/revenue | Current mining revenue |
| GET | /mining/pools | Mining pool distribution |
| GET | /mining/difficulty/history | Historical difficulty adjustments |
| GET | /mining/revenue/history | Historical mining revenue |

### Network
| Method | Path | Description |
|--------|------|-------------|
| GET | /network | Network info: version, connections, relay fee |
| GET | /network/forks | Chain tips and forks |
| GET | /network/difficulty | Difficulty adjustment progress and estimate |
| GET | /network/validate-address/{address} | Validate a Bitcoin address |

### Supply & Statistics
| Method | Path | Description |
|--------|------|-------------|
| GET | /supply | Circulating supply, halving info, inflation rate |
| GET | /stats/utxo-set | UTXO set statistics |
| GET | /stats/segwit-adoption | SegWit adoption metrics |
| GET | /stats/op-returns | OP_RETURN usage statistics |

### Prices & Tools
| Method | Path | Description |
|--------|------|-------------|
| GET | /prices | BTC/USD price (multi-provider fallback) |
| GET | /tools/exchange-compare | Compare exchange prices and fees |

### Address (requires indexer)
| Method | Path | Description |
|--------|------|-------------|
| GET | /address/{address} | Address balance and transaction history |
| GET | /address/{address}/utxos | UTXOs for an address |

### Real-Time Streams (SSE)
| Method | Path | Description |
|--------|------|-------------|
| GET | /stream/blocks | New block notifications |
| GET | /stream/fees | Fee rate changes |
| GET | /stream/whale-txs | Large transaction alerts |

### WebSocket
| WS | /ws | Real-time subscriptions (blocks, fees, mempool) |

### Registration & Billing
| Method | Path | Description |
|--------|------|-------------|
| POST | /register | Self-serve API key registration |
| POST | /unsubscribe | Unsubscribe from emails |
| POST | /billing/checkout | Create Stripe checkout session |
| GET | /billing/status | Subscription status |

### History Explorer
| Method | Path | Description |
|--------|------|-------------|
| GET | /history/events | All curated Bitcoin history events |
| GET | /history/events/{id} | Single event detail |
| GET | /history/eras | All Bitcoin eras (Genesis → Ordinals) |
| GET | /history/eras/{id} | Single era detail |
| GET | /history/concepts | Protocol concepts (UTXO, SegWit, etc.) |
| GET | /history/concepts/{id} | Single concept detail |
| GET | /history/search?q={query} | Search events, eras, concepts |

### Guide
| Method | Path | Description |
|--------|------|-------------|
| GET | /guide | API guide with categories and use cases |
| GET | /guide/categories | All endpoint categories |

### Fee Observatory (x402 paid - $0.005)
| Method | Path | Description |
|--------|------|-------------|
| GET | /fees/observatory/scoreboard | Per-source accuracy ranking |
| GET | /fees/observatory/block-stats | Per-block fee statistics |
| GET | /fees/observatory/estimates | Multi-source fee estimate time series |

### Status
| Method | Path | Description |
|--------|------|-------------|
| GET | /health | API health check |
| GET | /health/deep | Deep health check (node + DB) |
| GET | /status | Service status and version |
| GET | /x402-info | x402 payment information and pricing |
| GET | /x402-demo | x402 demo (returns sample 402 format) |

### JSON-RPC Proxy
| Method | Path | Description |
|--------|------|-------------|
| POST | /rpc | Proxy JSON-RPC calls to the Bitcoin Core node |

The `/api/v1/rpc` endpoint proxies standard JSON-RPC 2.0 requests directly to the underlying Bitcoin Core node. This is used by [bitcoin-mcp](https://github.com/Bortlesboat/bitcoin-mcp) for zero-config mode — when no local node is available, bitcoin-mcp routes all tool calls through this endpoint automatically.

**Request format:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getblockchaininfo",
  "params": []
}
```

**Response format:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}
```

Only read-only methods are whitelisted (plus `sendrawtransaction` for broadcasting). Wallet and admin methods are blocked. Allowed methods include: `getblockchaininfo`, `getblockcount`, `getbestblockhash`, `getblockhash`, `getblock`, `getblockheader`, `getblockstats`, `getchaintips`, `getchaintxstats`, `getdifficulty`, `getmempoolinfo`, `getrawmempool`, `getmempoolentry`, `getrawtransaction`, `decoderawtransaction`, `decodescript`, `gettxout`, `estimatesmartfee`, `getmininginfo`, `getnetworkhashps`, `getnetworkinfo`, `getpeerinfo`, `gettxoutsetinfo`, `validateaddress`, `sendrawtransaction`, and others.

Standard rate limits apply per your API tier (anonymous: 30 req/min, free: 100 req/min, pro: 500 req/min, enterprise: 2,000 req/min). An API key is not required but recommended for higher limits.

## Response Format

**Success:**
```json
{
  "data": { ... },
  "meta": { "block_height": 900000, "timestamp": "2026-03-09T..." }
}
```

**Error:**
```json
{
  "error": "Description of what went wrong",
  "request_id": "uuid-for-tracing"
}
```

## Example Requests & Responses

### GET /api/v1/fees/recommended
```json
{
  "data": {
    "fast": { "sat_per_vbyte": 25, "target_blocks": 1 },
    "medium": { "sat_per_vbyte": 12, "target_blocks": 3 },
    "slow": { "sat_per_vbyte": 5, "target_blocks": 6 },
    "recommendation": "medium",
    "congestion": "moderate",
    "timestamp": "2026-03-09T12:00:00Z"
  },
  "meta": { "block_height": 900000 }
}
```

### GET /api/v1/blocks/latest
```json
{
  "data": {
    "height": 900000,
    "hash": "00000000000000000002a7c...",
    "tx_count": 3421,
    "size": 1678234,
    "weight": 3992816,
    "timestamp": 1741500000,
    "fee_stats": { "min": 1.0, "max": 450.0, "median": 12.5, "mean": 18.3 }
  },
  "meta": { "block_height": 900000 }
}
```

### GET /api/v1/mempool
```json
{
  "data": {
    "tx_count": 45230,
    "vsize_mb": 32.5,
    "congestion": "moderate",
    "next_block_min_fee": 8.5,
    "fee_buckets": [
      { "range": "1-5", "count": 12000, "vsize_mb": 8.2 },
      { "range": "5-10", "count": 8500, "vsize_mb": 6.1 }
    ]
  },
  "meta": { "block_height": 900000 }
}
```

### POST /api/v1/register
Request:
```json
{ "email": "agent@example.com", "agreed_to_terms": true }
```
Response:
```json
{
  "data": {
    "api_key": "sat_...",
    "tier": "free",
    "rate_limit": { "per_minute": 100, "daily": 10000 }
  }
}
```

## Error Codes

| Code | Meaning |
|------|---------|
| 400 | Bad request — invalid parameters or malformed body |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — endpoint requires higher tier or POST requires auth |
| 404 | Not found — resource doesn't exist (block, tx, address) |
| 429 | Rate limited — check Retry-After header |
| 500 | Server error — check request_id for support |

## Common Agent Workflows

### 1. Fee optimization: Should I send now or wait?
1. `GET /fees/recommended` — get current fee tiers and congestion level
2. `GET /fees/savings` — see how much waiting would save
3. `GET /fees/plan` — get optimal timing recommendation
4. Decision: if congestion is "low", send now at the slow rate. If "high", wait.

### 2. Transaction monitoring
1. `POST /transactions/broadcast` — broadcast a signed transaction
2. `GET /tx/{txid}/status` — poll for confirmation status
3. `GET /blocks/latest` — check if tx is in the latest block
4. Report: confirmed in block X after Y minutes.

### 3. Mempool congestion alerting
1. `GET /mempool` — baseline congestion level
2. `GET /stream/fees` (SSE) — subscribe to fee rate changes
3. When congestion drops from "high" to "moderate", alert the user
4. `GET /fees/recommended` — provide updated fee recommendation

## Paid Endpoints (x402 micropayments)

Most endpoints are free. A few premium endpoints use the x402 protocol
for per-request micropayments in USDC on Base:

| Endpoint | Price | Why paid |
|----------|-------|----------|
| /api/v1/ai/* | $0.01 | LLM inference costs |
| /api/v1/broadcast | $0.01 | Transaction relay resources |
| /api/v1/mining/nextblock | $0.01 | Heavy computation |
| /api/v1/fees/observatory/* | $0.005 | Multi-source analytics DB |
| /api/v1/fees/landscape | $0.005 | Rich mempool computation |

### How x402 works
1. Request a paid endpoint without payment -> get HTTP 402 with `paymentRequirements`
2. Sign a USDC payment on Base using the details in the 402 response
3. Resend the request with the `X-PAYMENT` header containing the signed payment
4. Payment is verified by the x402 facilitator and you get the response

**Payment info endpoint:** GET /api/v1/x402-info
**Demo/sandbox:** GET /api/v1/x402-demo (free — returns a sample 402 so you can test your client)
**Protocol spec:** https://x402.org
**SDK:** https://github.com/coinbase/x402

## Pricing (subscription tiers)

- **Free:** 0/mo — 100 req/min, 10K/day, all endpoints
- **Pro:** $19/mo — 500 req/min, 100K/day, extended block history
- **Enterprise:** Custom — 2K req/min, dedicated support

## MCP Setup (for AI agents)

Install: pip install bitcoin-mcp

Config for Claude Desktop/Cursor/Windsurf:
```json
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp"
    }
  }
}
```

Claude Code: claude mcp add bitcoin -- bitcoin-mcp

Zero-config: auto-falls back to hosted Satoshi API when no local node.
MCP server card: https://bitcoinsapi.com/.well-known/mcp/server-card.json

## Links

- API docs (branded): https://bitcoinsapi.com/api-docs
- API docs (OpenAPI/Swagger): https://bitcoinsapi.com/docs
- MCP setup guide: https://bitcoinsapi.com/mcp-setup
- Protocol guide: https://bitcoinsapi.com/guide
- History explorer: https://bitcoinsapi.com/history
- Pricing: https://bitcoinsapi.com/pricing
- GitHub: https://github.com/Bortlesboat/bitcoin-api
- PyPI: https://pypi.org/project/satoshi-api/
- MCP server: https://github.com/Bortlesboat/bitcoin-mcp
- Discord: https://discord.gg/EB6Jd66EsF
- Status: https://stats.uptimerobot.com/satoshi-api
- Contact: api@bitcoinsapi.com