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 between your API consumers and your origin server, handling payment challenges, invoice creation, and access verification so your API code stays unchanged.
The problem
Traditional API monetization requires accounts, API keys, OAuth flows, credit card processing, and billing infrastructure. This creates friction for developers and is impossible for autonomous AI agents that need to pay for API access programmatically.
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), and 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 weekly cycle: a small usage-based fee for infrastructure and gateway services
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 open-source (MIT) 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, LNbits, NWC, and Phoenixd (for agent-side payments). Zero runtime dependencies. - Python:
bolthub- L402 client with LND and LNbits support. 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