Introduction
What bolthub is and how it works.
What is bolthub?
bolthub is a payment gateway that monetizes HTTP APIs with Bitcoin Lightning micropayments using the L402 protocol. It sits in front of your origin. We handle the 402 challenges, invoices, and access checks. Your code stays the same.
The problem
The old way needs accounts, API keys, OAuth flows, credit card processing, and a billing stack. That slows down human developers. For autonomous AI agents, it's a non-starter.
The solution
With bolthub, any HTTP request can be monetized with a simple flow:
- Client sends a request to your gateway URL
- Gateway returns HTTP 402 Payment Required with a Lightning invoice
- Client pays the invoice (settles in 1-3 seconds)
- Client retries with proof of payment
- Gateway verifies and proxies to your origin API
No accounts, no API keys, no signup required. Works for humans with Lightning wallets and AI agents with programmatic wallet access.
Non-custodial architecture
bolthub never holds, receives, or controls user funds. When a client pays for API access:
- Consumer payments go directly to the API provider's Lightning wallet. The gateway creates a standard bolt11 invoice via the provider's configured wallet (LND via the bolthub Node Launcher, NWC, or LNbits). The consumer can pay it with any Lightning wallet: LND, Phoenix, Alby, a mobile wallet, WebLN, or any other bolt11-compatible client.
- Platform fees are billed separately on a monthly cycle: a small usage-based fee for infrastructure and gateway services, with 7 days to pay each invoice
Supported pricing models
| Model | Behavior |
|---|---|
per_request | Fixed price per API call |
per_kb | Price scales with response size |
token_bucket | Buy a bucket of requests upfront |
time_pass | Unlimited access for a time window |
metered | Prepaid balance, deducted per use |
SDKs and tools
All packages are MIT-licensed and designed with minimal dependencies to reduce supply-chain risk.
- MCP Registry:
@bolthub/mcp-registry- one config, every API on the marketplace. The recommended way to connect AI agents. - MCP Bridge:
@bolthub/mcp-bridge- connects MCP-compatible AI agents (Cursor, Claude Desktop) to a specific paywalled API - CLI:
@bolthub/cli- search, explore, and call APIs from the terminal. Zero third-party dependencies. - TypeScript:
@bolthub/agent- L402 client with wallet adapters for LND, NWC, LNbits, and Phoenixd (for agent-side payments). Zero runtime dependencies. - Python:
bolthub- L402 client with wallet adapters for LND, NWC, LNbits, and Phoenixd. One dependency (httpx). - Origin verification:
@bolthub/verify(TypeScript, zero-dep) andbolthub-verify(Python, zero-dep) - verify gateway signatures on your origin server.
Next steps
- Wallet Setup: configure a Lightning wallet
- Using Paywalled APIs: consume L402-gated endpoints
- MCP Registry: connect your AI agent to the marketplace