Skip to main content

​
General

BoltzPay is an open-source TypeScript SDK that lets AI agents pay for API data automatically. You call agent.fetch(url) and the SDK handles protocol detection, payment signing, and settlement. Your agent gets the data, the server gets paid.
Two protocols today:
  • x402 (Coinbase) — USDC on-chain payments via HTTP 402 status codes. Live on Base and Base Sepolia.
  • L402 (Lightning Labs) — Bitcoin Lightning payments via HTTP 402 + L402 header. Uses an NWC (Nostr Wallet Connect) connection string.
The SDK auto-detects which protocol each endpoint uses.
Yes. The SDK, CLI, and MCP server are all MIT-licensed and free to use. You only pay for the API data you consume — those payments go directly to the API providers, not to us.
No. Your Coinbase CDP keys and NWC connection string stay on your machine. BoltzPay never touches, stores, or proxies your credentials. You sign your own transactions.

​
Payments & Wallets

x402 is a payment protocol built by Coinbase that uses the HTTP 402 status code (“Payment Required”). When you hit a paid endpoint, the server responds with a 402 and payment details in the headers. The client signs a USDC transaction, sends the payment proof, and gets the data. All on-chain, all automatic.
USDC (USD Coin) for x402 payments, on the Base blockchain. Prices are denominated in USD. For L402, payments use Bitcoin via the Lightning Network.
For x402 endpoints: yes, you need USDC on Base. You get USDC through Coinbase CDP — no manual wallet setup or seed phrases. For L402 endpoints: you need a Lightning wallet with an NWC connection string (e.g. Coinos, free).For explore mode (checking prices, discovering APIs): no crypto, no keys, nothing.
Yes. Set network: "base-sepolia" to use the Base Sepolia testnet with free test USDC. The Nickel Joke endpoint is a testnet demo. You can also run the local test server for fully offline testing.
Set daily, monthly, and perTransaction limits in the SDK config. Before every payment, the SDK checks all limits. If any would be exceeded, the payment is blocked and a BudgetExceededError is thrown. Lightning payments (sats) are converted to USD via satToUsdRate (default: 0.001, ~$100K/BTC) and count toward the same budget limits. See Configuration for details.
Yes. Set only nwcConnectionString in the config — no Coinbase credentials needed. The SDK will pay L402 endpoints via Lightning and pass through free endpoints normally. x402 endpoints will be detected but payment will fail gracefully (the SDK reports the price without paying). This is useful if you only want Bitcoin Lightning payments.
NWC is an open protocol that lets apps connect to your Lightning wallet without touching your private keys. Think of it as “OAuth for Bitcoin wallets”. You generate a connection string (nostr+walletconnect://...) from your wallet and paste it into BoltzPay. Free wallets with NWC support include Coinos and Primal. For advanced users, Alby Hub (self-hosted or cloud) and Umbrel also work. See the full list on nwc.dev.

​
Setup & Troubleshooting

Not for explore mode. You can discover APIs, check prices, get quotes, and browse the directory without any credentials. Coinbase keys are only required when you want to actually pay for data via fetch().
Some corporate or coworking WiFi networks use proxies that intercept HTTP 402 responses or strip payment headers. This prevents x402 detection. Try on a direct connection, or use --debug in the CLI to inspect raw headers.
Yes. The CLI has a --json mode designed for cross-language use. Call it from Python via subprocess and parse the JSON output. See the Python bridge guide for examples with LangChain and CrewAI.
ChatGPT doesn’t support MCP, but a hosted REST API is on our roadmap (2026 Q2). Once live, you’ll be able to create a Custom GPT with BoltzPay Actions using our OpenAPI spec. In the meantime, use the SDK or CLI directly.
Three options:
  1. Explore mode — Use BoltzPay({}) with no credentials. You can discover APIs, check prices, and get quotes for free.
  2. Testnet — Set network: "base-sepolia" and get free testnet USDC from the Circle faucet. The Nickel Joke endpoint works on testnet.
  3. Local test server — Run examples/test-server/ for fully offline testing with a mock facilitator. See examples/test-server/README.md.