satoshi-api 0.1.0

Satoshi API — developer-friendly Bitcoin REST API powered by your own node

Satoshi API

The thinnest REST layer over your Bitcoin node. One pip install, instant API.

Powered by bitcoinlib-rpc for analyzed data (fees, mempool congestion, block stats) rather than raw RPC dumps. Part of the AI agent pipeline: bitcoinlib-rpc -> satoshi-api -> bitcoin-mcp.

Prerequisites

• Bitcoin Core running with server=1 in bitcoin.conf (RPC enabled)
• Python 3.10+

Node configuration notes:

• Transaction lookups (/tx/{txid}, /tx/{txid}/raw) for confirmed transactions require txindex=1
• Block template (/mining/nextblock) requires at least one connected peer on mainnet
• Block stats (/blocks/{height}/stats) is unavailable for pruned blocks below the prune height

Quick Start

pip install bitcoin-api  # or: pip install -e . for local dev

# Point at your node
export BITCOIN_RPC_USER=your_user
export BITCOIN_RPC_PASSWORD=your_password
# For testnet: export BITCOIN_RPC_PORT=18332
# For signet:  export BITCOIN_RPC_PORT=38332

# Run
bitcoin-api  # or: satoshi-api
# -> http://localhost:9332/docs

Docker

# Create .env with your node credentials
echo "BITCOIN_RPC_USER=your_user" > .env
echo "BITCOIN_RPC_PASSWORD=your_password" >> .env

docker compose up -d

Endpoints

All endpoints are under /api/v1/. Interactive docs at /docs.

Endpoint	Description
GET /health	Node ping (no auth required)
GET /status	Sync progress, peers, disk usage
GET /network	Version, connections, relay fee
GET /network/forks	Chain tips / fork detection
GET /network/difficulty	Difficulty epoch progress, retarget estimate
GET /blocks/latest	Latest block analysis
GET /blocks/tip/height	Chain tip height
GET /blocks/tip/hash	Chain tip block hash
GET /blocks/{height_or_hash}	Block by height or hash
GET /blocks/{height}/stats	Raw block statistics
GET /blocks/{hash}/txids	Transaction IDs in a block
GET /blocks/{hash}/txs	Full transactions in a block (paginated)
GET /blocks/{hash}/header	Block header hex string
GET /tx/{txid}	Transaction analysis (fees, SegWit, Taproot, inscriptions)
GET /tx/{txid}/raw	Raw decoded transaction
GET /tx/{txid}/status	Confirmation status
GET /tx/{txid}/hex	Raw transaction hex string
GET /tx/{txid}/outspends	Spending status of each output
GET /utxo/{txid}/{vout}	UTXO lookup
GET /mempool	Mempool analysis (fee buckets, congestion)
GET /mempool/info	Raw mempool stats
GET /mempool/tx/{txid}	Mempool entry for a transaction
GET /mempool/txids	All transaction IDs in the mempool
GET /mempool/recent	Most recent mempool entries
GET /fees	Fee estimates (1, 3, 6, 25, 144 blocks)
GET /fees/recommended	Human-readable fee recommendation
GET /fees/{target}	Fee estimate for specific block target
GET /fees/mempool-blocks	Projected next blocks from mempool by fee rate
GET /mining	Hashrate, difficulty, retarget estimate
GET /mining/nextblock	Block template analysis
GET /network/validate-address/{addr}	Validate a Bitcoin address
GET /prices	BTC price in USD, EUR, GBP, JPY, CAD, AUD
POST /decode	Decode raw transaction hex
POST /broadcast	Broadcast signed transaction

Examples

# Health check
curl http://localhost:9332/api/v1/health

# Fee recommendation
curl http://localhost:9332/api/v1/fees/recommended

# Analyze a transaction
curl http://localhost:9332/api/v1/tx/a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d

# Latest block
curl http://localhost:9332/api/v1/blocks/latest

# With API key (higher rate limits)
curl -H "X-API-Key: your_key_here" http://localhost:9332/api/v1/mempool

API Keys

Anonymous access works out of the box. For higher rate limits, create a key:

python scripts/create_api_key.py --tier free --label "my-app"
python scripts/create_api_key.py --tier pro --label "production"

Pass the key via X-API-Key header. Query parameter ?api_key= is deprecated (sunset: 2026-09-01).

Rate Limits

Tier	Req/min	Req/day
Anonymous	30	1,000
Free (API key)	100	10,000
Pro	500	100,000
Enterprise	2,000	Unlimited

Rate limit info in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining.

Every response includes X-Request-ID (UUID) and X-Auth-Tier headers.

Response Format

Standard envelope on all endpoints:

{
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-05T12:00:00+00:00",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "node_height": 880000,
    "chain": "main"
  }
}

Errors:

{
  "error": {
    "status": 404,
    "title": "Not Found",
    "detail": "Transaction not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Input Validation

• Transaction IDs and block hashes must be exactly 64 hex characters
• Invalid formats return 422 immediately (no wasted RPC calls)
• Invalid API keys return 401 (not silent downgrade to anonymous)

Development

pip install -e ".[dev]"
pytest

License

MIT