# Satoshi API

> Bitcoin fee intelligence for AI agents. Know when to send and what to pay.

Satoshi API saves agents money and time when interacting with Bitcoin.
Fee intelligence tells you whether to send now or wait. Payment
monitoring tells you when a transaction confirms. No node required.
Register a free API key and start querying in seconds.

## Why agents choose Satoshi API

- Fee intelligence: "send now or wait?" recommendations save money
  on every Bitcoin transaction
- Payment monitoring: know when a txid confirms without polling
- MCP server (pip install bitcoin-mcp) so Claude, GPT, and other
  LLM agents can call Bitcoin endpoints as native tools
- Clean JSON envelopes, consistent error formats, deterministic
  pagination — designed for programmatic consumption
- Free tier with no credit card — agents can self-register via
  POST https://bitcoinsapi.com/api/v1/register

## Quick start for agents

1. Register:
   POST https://bitcoinsapi.com/api/v1/register
   Body: {"email": "agent@example.com", "agreed_to_terms": true}
   Response includes your API key.

2. Query:
   GET https://bitcoinsapi.com/api/v1/fees/recommended
   Header: X-API-Key: <your_key>

3. Every response follows the same envelope:
   {"data": {...}, "meta": {"block_height": 900000, ...}}

## MCP integration (for AI agent frameworks)

Install: pip install bitcoin-mcp

Claude Desktop config (paste into claude_desktop_config.json):
```json
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp"
    }
  }
}
```

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

No API key needed. No Bitcoin node needed. bitcoin-mcp auto-falls
back to the hosted Satoshi API at bitcoinsapi.com. Provides 49 tools,
6 prompts, and 7 resources that any MCP-compatible agent can
discover and invoke.

MCP server card: https://bitcoinsapi.com/.well-known/mcp/server-card.json
Setup guide: https://bitcoinsapi.com/mcp-setup

## Agent efficiency tips

Use the guide endpoint with filters to pull only what you need:
  GET https://bitcoinsapi.com/api/v1/guide?use_case=fees&lang=curl
  (use_case options: fees, blocks, transactions, mempool, mining, network,
   streams, prices, address, tools, status, authentication, supply, billing)

Every response includes X-Auth-Tier header showing your current tier
(anonymous, free, pro, enterprise) — no separate status call needed.

## Agent self-registration

POST https://bitcoinsapi.com/api/v1/register
Body: {"email": "agent@example.com", "agreed_to_terms": true}
Returns API key instantly. No approval wait. Free tier: 100 req/min, 10K/day.

## Base URL

https://bitcoinsapi.com

## Pages

- API docs (branded): https://bitcoinsapi.com/api-docs
- API docs (OpenAPI/Swagger): https://bitcoinsapi.com/docs
- Protocol guide: https://bitcoinsapi.com/guide
- MCP setup: https://bitcoinsapi.com/mcp-setup
- Bitcoin history explorer: https://bitcoinsapi.com/history
- Pricing: https://bitcoinsapi.com/pricing
- Bitcoin transaction fee calculator: https://bitcoinsapi.com/bitcoin-transaction-fee-calculator
- Best time to send Bitcoin: https://bitcoinsapi.com/best-time-to-send-bitcoin
- Bitcoin fee estimator: https://bitcoinsapi.com/bitcoin-fee-estimator
- Bitcoin API for trading bots: https://bitcoinsapi.com/bitcoin-api-for-trading-bots
- x402 payment dashboard: https://bitcoinsapi.com/x402
- How to reduce Bitcoin transaction fees: https://bitcoinsapi.com/how-to-reduce-bitcoin-transaction-fees

## Free Endpoints (no payment needed)

- /api/v1/health - Node health check
- /api/v1/fees - Fee estimates and recommendations
- /api/v1/fees/recommended - Smart fee recommendation
- /api/v1/fees/history - Historical fee data
- /api/v1/fees/plan - Optimal send timing
- /api/v1/fees/savings - Savings from waiting
- /api/v1/blocks/latest - Latest block info
- /api/v1/blocks/{height_or_hash} - Block by height or hash
- /api/v1/tx/{txid} - Transaction details
- /api/v1/mempool - Mempool analysis
- /api/v1/mining - Mining summary
- /api/v1/mining/pools - Mining pool distribution
- /api/v1/network - Network info
- /api/v1/supply - Circulating supply and halving info
- /api/v1/prices - BTC/USD price
- /api/v1/stream/blocks - Real-time block notifications (SSE)
- /api/v1/stream/fees - Real-time fee changes (SSE)
- ... and 100+ more (see /llms-full.txt for complete list)

## Paid Endpoints (x402 - USDC on Base)

- /api/v1/ai/* - AI-powered analysis ($0.01)
- /api/v1/broadcast - Transaction broadcast ($0.01)
- /api/v1/mining/nextblock - Next block prediction ($0.01)
- /api/v1/fees/observatory/* - Fee observatory analytics ($0.005)
- /api/v1/fees/landscape - Full fee landscape ($0.005)

## Payment (x402 protocol)

Uses the x402 protocol (https://x402.org). Flow:
1. Request a paid endpoint without payment
2. Get a 402 response with payment requirements
3. Sign a USDC payment on Base and resend with X-PAYMENT header
4. Payment is verified and you get the response

Payment info: https://bitcoinsapi.com/api/v1/x402-info
Demo endpoint: https://bitcoinsapi.com/api/v1/x402-demo (free, shows 402 format)

Priority: API-key authentication is checked first. If you have a valid
API key, paid endpoints are included in your tier's rate limit (no x402
payment needed for Pro/Enterprise). x402 is for keyless pay-per-call access.

## Rate limits

- Anonymous: 30 req/min, 1,000/day, GET only, 144-block cap
- Free (registered): 100 req/min, 10,000/day, all endpoints, 144-block cap
- Pro ($19/mo): 500 req/min, 100,000/day, 1,008-block cap
- Enterprise: 2,000 req/min, custom daily, 2,016-block cap

All responses include X-RateLimit-Limit, X-RateLimit-Remaining,
X-RateLimit-Reset, X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining
headers for self-throttling.

## JSON-RPC proxy (for direct Bitcoin Core calls)

POST https://bitcoinsapi.com/api/v1/rpc
Body: {"method": "getblockchaininfo", "params": []}
Proxies read-only Bitcoin Core RPC calls. Used by bitcoin-mcp
for zero-config mode. No API key required.

## Full documentation

For complete endpoint reference, example responses, error codes,
and multi-step agent workflows, see:
https://bitcoinsapi.com/llms-full.txt

## Contact

api@bitcoinsapi.com