Introduction

What is bolthub?

bolthub is a payment layer for tool calls. It lets you charge AI agents (and humans) per call for your MCP tools and HTTP endpoints, settling over Lightning. bolthub is non-custodial and never in the funds path.

There are two ways in:

In code: the @bolthub/pay SDK adds a price to any MCP tool or HTTP endpoint. MIT-licensed and self-hostable; no bolthub account needed.
No code (hosted): the hosted gateway sits in front of your existing HTTP API. It handles the 402 challenges, invoices, and access checks. Your code stays the same. The rest of this page describes this path.

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 the hosted gateway, any HTTP request can be a paid request 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

Buyers need no accounts, API keys, or signup: the payment is the credential. 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, capped at 5% of what your endpoints earned that cycle, with 7 days to pay each invoice. Months with zero traffic are free: a dormant workspace never generates an 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

Four packages, one job each. All MIT-licensed with minimal dependencies to reduce supply-chain risk.

Payments: @bolthub/pay (npm) / bolthub (PyPI) - the payments SDK, both sides of the sale. Sellers: createPaywall prices any MCP tool or HTTP endpoint. Buyers: ToolClient pays for MCP tools, L402Client for HTTP APIs, with wallet adapters (LND, NWC, LNbits, Phoenixd) and hard budgets. Zero runtime dependencies (npm) / one (httpx, PyPI).
MCP: @bolthub/mcp - the bolthub MCP server. One config entry gives an agent the whole marketplace, specific gateways, and your other MCP servers, with one shared Lightning budget.
CLI: @bolthub/cli - search, explore, and call APIs from the terminal.
Origin verification: @bolthub/verify (npm) and bolthub-verify (PyPI) - verify gateway signatures on your origin server. Zero-dep.

Migrating? @bolthub/agent merged into @bolthub/pay (0.4.0); @bolthub/mcp-registry and @bolthub/mcp-bridge merged into @bolthub/mcp. The old names are deprecated on npm and keep working, but point here.

Which package do I need?

Selling (get paid for your tools):

You have	Do this	Package
An HTTP API	List it behind the hosted gateway (no code — Quickstart). Agents get it as MCP tools automatically; you never touch MCP.	none
Your own MCP tools (your server, your code)	Wrap them with `createPaywall` and register them as tools settled via the hosted facilitator.	`@bolthub/pay` / `bolthub`
An origin that must only accept gateway traffic	Verify the gateway signature on your origin.	`@bolthub/verify` / `bolthub-verify`

Buying (pay for tools and APIs):

You are	Do this	Package
Configuring an MCP client (Cursor, Claude Desktop, …)	One config entry: `npx -y @bolthub/mcp`.	`@bolthub/mcp`
Writing code	`ToolClient` (MCP tools) or `L402Client` (HTTP), budgets included.	`@bolthub/pay` / `bolthub`
In a terminal	`bolthub search` / `bolthub call`.	`@bolthub/cli`

Next steps

@bolthub/pay: charge for your tools in code
Wallet Setup: configure a Lightning wallet
Using Paywalled APIs: consume L402-gated endpoints
@bolthub/mcp: connect your AI agent to the marketplace

Introduction

On this page