Satoshi API MCP server
Commit Nov 4, 2026Provides real-time Bitcoin fee intelligence, mempool state, and transaction analysis for AI agents and self-hosted infrastructure.
Also known as Bortlesboat/bitcoin-api
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- Apache-2.0
What is Satoshi API MCP?
Satoshi API provides real-time Bitcoin fee intelligence, mempool state, and transaction analysis for AI agents and self-hosted infrastructure.
Summary generated from the project's README
About Satoshi API MCP server
Satoshi API provides real-time Bitcoin intelligence for developers and AI agents. It focuses on fee optimization by combining mempool state with multiple fee estimates to provide actionable recommendations. Instead of raw data, it offers guidance on whether to send a transaction now or wait for lower costs. This tool is designed for self-hosting via a simple pip installation, requiring connection to a Bitcoin Core or Knots node using RPC credentials.
For those building with AI, the bitcoin-mcp implementation offers 50 standard tools, 6 prompts, and 8 resources. Users can connect their agents to a local node or a remote Satoshi API instance. The system supports advanced features like x402 paid endpoints for monetized access and real-time data streaming via SSE for blocks and fees. It also includes research capabilities to export fee forecasting data into JSONL format for offline analysis.
What you can do with it
- 1Optimize transaction timingAsk an AI agent to determine if current network conditions are suitable for sending a Bitcoin transaction.
- 2Analyze transaction detailsRequest a decoded analysis and status check for a specific transaction ID.
- 3Monitor network congestionHave an agent check the current congestion score and fee buckets in the mempool.
- 4Perform fee forecasting researchGenerate a JSONL export of fee observations to conduct offline forecasting work.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
BITCOIN_RPC_USERSATOSHI_API_URL
| Name | Description | |
|---|---|---|
| BITCOIN_RPC_USER | — | |
| SATOSHI_API_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablebortlesboat/bitcoin-api is public and reachablegithub.com/bortlesboat/bitcoin-api ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/bortlesboat/bitcoin-api ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub
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 former hosted Satoshi API demo and x402 facilitator are paused.
bitcoinsapi.comnow runs a separate edge project, so this repo's endpoints are self-host only.
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 2.x API (mcp>=2.3,<3); the development extra also installs it so the MCP tests run in a fresh environment.
With the bitcoin-api-x402 extension installed, a self-hosted instance lists its paid endpoints at /.well-known/x402. The paid flow is: discover them, 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 ideas under consideration (not scheduled while the hosted service is paused): 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.
Satoshi API MCP questions
What does Satoshi API do?
It provides Bitcoin fee recommendations, mempool congestion scores, transaction analysis, and block data to help users know when to send transactions.
Is the hosted version available?
No, the former hosted Satoshi API demo and x402 facilitator are currently paused; the endpoints are for self-hosting only.