Lightning payments
for AI agents.
Bitcoin intelligence API with 21 endpoints, atomic escrow, and native MCP integration. Your agents pay sats, get data — no accounts, no API keys, no subscriptions.
Built for the agent economy
MCP Native
Drop-in MCP server for Claude, GPT, and Gemini. pip install satoshiapi-mcp — your agent discovers Bitcoin data as a native tool.
Atomic Escrow
Hash-locked delivery for agent-to-agent commerce. Payment settles atomically on delivery. Neither party can cheat. Non-custodial — pure cryptography.
Pay-per-call
10-200 sats per request via L402 Lightning. No subscriptions, no billing dashboards. Payment IS authentication.
No accounts ever
No signup, no API keys, no OAuth, no KYC. Any agent starts calling endpoints immediately. Completely permissionless.
OpenAPI 3.1
Full spec for all 16 data endpoints. Auto-generate client SDKs in any language. Import into Postman or your agent framework.
Open source
Full source on GitHub. Run your own instance with your own LND node. MIT licensed. Non-custodial by design.
Endpoints
Core data — 10 sats| Endpoint | Price | Returns |
|---|---|---|
| GET /price | 10 sats | BTC/USD price + 24h change |
| GET /mempool | 10 sats | Fee estimates — fastest, 30min, 1hr, economy (sat/vB) |
| GET /blockheight | 10 sats | Block height + network hashrate (EH/s) |
| GET /halving | 10 sats | Halving countdown, block subsidy, stock-to-flow, supply stats |
| GET /tx/{txid} | 10 sats | Transaction details — confirmations, fee, inputs/outputs |
| Endpoint | Price | Returns |
|---|---|---|
| GET /sentiment | 25 sats | Fear & Greed index (0–100) + classification |
| GET /fees/forecast | 25 sats | Fee forecast, mempool congestion, optimal send timing |
| GET /lightning/stats | 25 sats | Network capacity, channel count, top nodes, avg fees |
| GET /address/{addr} | 25 sats | Balance, tx count, UTXO data for any Bitcoin address |
| GET /signal | 50 sats | DCA signal — STRONG_BUY / BUY / HOLD / REDUCE + reasoning |
| GET /market/summary | 50 sats | Complete market snapshot — price, volume, dominance, sentiment, fees |
| GET /whale | 100 sats | Whale activity — large transactions, exchange flows, accumulation |
| Endpoint | Price | Returns |
|---|---|---|
| GET /market/regime | 150 sats | Bull/bear/crab classification with confidence score + signals |
| GET /risk/score | 200 sats | Composite risk score (0-100) — sentiment, fees, momentum, congestion |
| GET /dca/plan | 200 sats | Personalized DCA recommendation — multiplier, timing, fee strategy |
| Endpoint | Method | Description |
|---|---|---|
| /escrow/create | POST | Seller commits delivery hash → hold invoice created |
| /escrow/fund | POST | Buyer pays hold invoice → funds lock in Lightning HTLC |
| /escrow/deliver | POST | Seller reveals preimage → payment settles atomically |
| /escrow/cancel | POST | Cancel escrow → funds return to buyer automatically |
| /escrow/status | POST | Check contract status or list all active contracts |
| Endpoint | Price | Returns |
|---|---|---|
| GET /health | Free | Service status, all endpoints, pricing, node info |
Quick start
For AI agents — pip install
# Install the MCP server pip install satoshiapi-mcp # Add to Claude Desktop (~/.config/claude/claude_desktop_config.json) { "mcpServers": { "satoshiapi": { "command": "python3", "args": ["-m", "satoshiapi_mcp"], "env": { "SATOSHIAPI_LND_REST": "https://your-lnd:8079", "SATOSHIAPI_LND_MACAROON": "/path/to/invoice.macaroon", "SATOSHIAPI_LND_CERT": "/path/to/tls.cert" } } } } # Your agent can now call: get_btc_price, get_risk_score, get_dca_plan, # get_whale_activity, get_market_regime, and 12 more tools # Payments happen automatically via your LND node
For developers — curl
# 1. Free health check curl https://api.satoshiapi.io/health # 2. Request paid endpoint → get L402 challenge curl -i https://api.satoshiapi.io/risk/score # → 402 + WWW-Authenticate: L402 macaroon="...", invoice="lnbc..." # 3. Pay the Lightning invoice, save the preimage # 4. Request with L402 token curl -H "Authorization: L402 <macaroon>:<preimage_hex>" \ https://api.satoshiapi.io/risk/score # → {"risk_score": 42, "risk_level": "MODERATE", "action": "..."}
Atomic escrow — agent-to-agent trade
# 1. Seller registers service + commits delivery hash curl -X POST https://api.satoshiapi.io/escrow/create \ -H "Content-Type: application/json" \ -d '{"seller_id":"agent-B", "service_name":"Image Gen", "price_sats":1000, "delivery_hash":"sha256_of_preimage"}' # → {"escrow_id":"...", "payment_request":"lnbc..."} # 2. Buyer pays the hold invoice → funds lock in HTLC # (nobody can touch them — not buyer, not seller, not SatoshiAPI) # 3. Seller delivers + reveals preimage → payment settles atomically curl -X POST https://api.satoshiapi.io/escrow/deliver \ -d '{"escrow_id":"...", "preimage":"the_actual_preimage"}' # → {"state":"delivered"} — buyer got data, seller got sats. Atomic. ₿
How L402 payment works
Request any paid endpoint
Server returns HTTP 402 with a WWW-Authenticate header containing a macaroon and Lightning invoice.
Pay the Lightning invoice
Use any wallet — Strike, Phoenix, Alby, or any L402 client. Settles in seconds. Save the preimage.
Get your data
Re-request with Authorization: L402 <macaroon>:<preimage>. Server verifies and returns data instantly.