Satoshi API

Stop overpaying Bitcoin fees. Know when to send.

Self-Hosting · PyPI · MCP Server · Discord Bot

---

Self-hostable · MCP-ready · x402-capable · Apache 2.0

---

Bad fee timing burns sats on every Bitcoin transaction. Satoshi API tells you when to send, what to pay, and whether to wait — combining multiple estimatesmartfee targets with real-time mempool state. Instead of just "4 sat/vB", you get "Fees are low. Good time to send." One pip install, self-hostable, open source.

Important

The project-operated bitcoinsapi.com demo and x402 facilitator are intentionally paused during an infrastructure review. The open-source package remains available for self-hosting; do not rely on the hosted URLs until this notice is removed.

Install & Run

pip install satoshi-api
export BITCOIN_RPC_USER=your_user BITCOIN_RPC_PASSWORD=your_password
satoshi-api
# API:  http://localhost:9332
# Docs: http://localhost:9332/docs

Example

curl http://localhost:9332/api/v1/fees/recommended | jq

{
  "data": {
    "recommendation": "Fees are low. Good time to send.",
    "estimates": { "high": 4, "medium": 2, "low": 1 }
  },
  "meta": { "timestamp": "...", "node_height": 939462, "chain": "main" }
}

Core Endpoints

Category	Example paths	Highlights
Fees	/api/v1/fees/recommended, /api/v1/fees/plan	Recommendations, landscape ("send now or wait?"), history, mempool-blocks
Transactions	/api/v1/tx/{txid}, /api/v1/broadcast	Decoded analysis, status, outspends, UTXO lookup, broadcast
Mempool	/api/v1/mempool, /api/v1/mempool/recent	Congestion score, fee buckets, recent entries
Blocks	/api/v1/blocks/latest, /api/v1/blocks/{height_or_hash}	Latest block, by height/hash, stats, txids, header
Mining	/api/v1/mining, /api/v1/mining/nextblock	Hashrate, difficulty, next block template
Network	/api/v1/network, /api/v1/network/difficulty	Peers, forks, difficulty, address validation
Streams	/api/v1/stream/blocks, /api/v1/stream/fees	Real-time blocks & fees via SSE

...and more (prices, address lookups, exchange comparison). A self-hosted instance serves its interactive docs at /docs.

For AI Agents

bitcoin-mcp provides 50 standard Bitcoin tools, 6 prompts, and 8 resources for AI agents. It connects to your Bitcoin Core/Knots node or an explicitly configured compatible API.

# Install and point at your Satoshi API instance
pip install "git+https://github.com/Bortlesboat/bitcoin-mcp.git"
SATOSHI_API_URL=http://127.0.0.1:9332 bitcoin-mcp

Or connect to a local node directly:

{
  "mcpServers": {
    "bitcoin": { "command": "bitcoin-mcp" }
  }
}

For repo-native agent instructions, use docs/AGENT_INTEGRATION.md. It includes copy-paste snippets for AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, Cursor/Windsurf rules, MCP config, and x402 paid calls.

The API's separate, optional HTTP MCP endpoint at /mcp requires pip install -e '.[mcp]' from this checkout. This uses the MCP SDK 1.x API; the development extra also installs it so the MCP tests run in a fresh environment.

When the hosted service resumes, keyless premium calls start at https://bitcoinsapi.com/x402/start. The paid flow is: discover /.well-known/x402, request a paid /api/v1 endpoint, read PAYMENT-REQUIRED, then retry with PAYMENT-SIGNATURE.

Self-Hosting

pip install satoshi-api
satoshi-api  # runs on :9332

# Expose publicly (free HTTPS + DDoS protection)
cloudflared tunnel --url http://localhost:9332

See self-hosting guide for full production setup.

Research Export

For offline fee-forecasting work, the repo now includes a local JSONL export path with documented observation features and 1-6 block clearing-fee outcomes.

$env:PYTHONPATH='src'
python scripts/export_fee_forecast_benchmark.py data/fee-forecast-benchmark.jsonl --hours 168 --interval-minutes 10

The export joins local fee_history observations to the next 1-6 confirmed blocks from the research tables in data/bitcoin_api.db. After migration 012_add_research_tables.sql, the background fee collector seeds the current tip, captures missed heights and reorg replacements in block_confirmations, and logs fee estimates every cycle, so a normal local API run can build this export without extra manual seeding. Very recent observations without six future block outcomes are skipped automatically.

Contributing

Issues and PRs welcome. Run the test suite before submitting:

pip install -e ".[dev]"
python -m pytest tests/ -q --ignore=tests/test_e2e.py --ignore=tests/locustfile.py

Roadmap

See docs/ROADMAP.md for the 12-month development plan — indexer expansion, multi-network support, fee prediction, SDKs, and more.

Support This Project

Satoshi API is free, open-source Bitcoin infrastructure. You can support the maintainer through GitHub Sponsors, report reproducible issues, or contribute tests and documentation.

Related Projects

• bitcoin-mcp — MCP server with 50 standard Bitcoin tools for AI agents
• ChainPulse — AI-powered Bitcoin network intelligence CLI
• BAIP-1 — Bitcoin Agent Identity Protocol

License

Apache 2.0 — see LICENSE.

---

Self-Hosting · PyPI · MCP Server · Roadmap

Maintained by Andrew Barnes / Bortlesboat. Run the unit-test command above for the current result; a passing local suite does not establish hosted-service availability.