Skip to main content

​
Prerequisites

  • Node.js >= 20.0.0
  • Package manager: npm, pnpm, or yarn

​
SDK

Install the SDK in your TypeScript or JavaScript project: 
npm install @boltzpay/sdk
The SDK works in explore mode with zero configuration: you can quote prices, check endpoints, and discover APIs without any credentials. To enable payments, install the Coinbase CDP SDK peer dependency: 
npm install @coinbase/cdp-sdk
@coinbase/cdp-sdk is an optional peer dependency. The SDK loads it lazily on the first fetch() call, so your bundle stays lean if you only use explore mode.

​
MCP Server (Claude Desktop)

No install needed. Run directly with npx: 
npx -y @boltzpay/mcp
Add it to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json): 
{
  "mcpServers": {
    "boltzpay": {
      "command": "npx",
      "args": ["-y", "@boltzpay/mcp"]
    }
  }
}
This gives Claude 7 tools: fetch, quote, check, budget, history, discover, and wallet.

​
CLI

No install needed. Run directly with npx: 
npx @boltzpay/cli check https://invy.bot/api
Or install globally: 
npm install -g @boltzpay/cli
Then use the boltzpay command directly: 
boltzpay check https://invy.bot/api
boltzpay discover
boltzpay fetch https://invy.bot/api --json

​
Credentials Setup

​
Coinbase CDP (required for payments)

BoltzPay uses Coinbase CDP to sign on-chain transactions (USDC on Base). You need three values:
1

Create an account

Go to portal.cdp.coinbase.com and create an account.
2

Create an API key

You will get an API Key ID and an API Key Secret.
3

Create a wallet

Note the Wallet Secret.
4

Set environment variables

export COINBASE_API_KEY_ID="your-api-key-id"
export COINBASE_API_KEY_SECRET="your-api-key-secret"
export COINBASE_WALLET_SECRET="your-wallet-secret"
Keep your secrets out of source code. Use a .env file or your platform’s secret management.
For the MCP server, pass credentials via the env block in your Claude Desktop config: 
{
  "mcpServers": {
    "boltzpay": {
      "command": "npx",
      "args": ["-y", "@boltzpay/mcp"],
      "env": {
        "COINBASE_API_KEY_ID": "your-api-key-id",
        "COINBASE_API_KEY_SECRET": "your-api-key-secret",
        "COINBASE_WALLET_SECRET": "your-wallet-secret",
        "BOLTZPAY_DAILY_BUDGET": "5.00"
      }
    }
  }
}

​
NWC (optional, for L402 protocol)

If you want to pay L402-compatible endpoints (Bitcoin Lightning payments), you need a Nostr Wallet Connect (NWC) connection string from a Lightning wallet.

​
How to get your NWC connection string

  1. Coinos (recommended) — Free web wallet. Sign up with a username and password, then go to ☰ Menu > ⚙️ Preferences > Nostr > Copy NWC. Your nostr+walletconnect://... string is ready.
  2. Primal — Free mobile app with built-in Lightning wallet and NWC support.
  3. Alby Hub — Your own Lightning node. Available as a cloud service ($12.90/mo) or free self-hosted (Docker). Go to Connections > Add Connection to generate the NWC URI.
  4. Any NWC wallet — Umbrel, Start9, or any wallet listed on nwc.dev.

​
Set the connection string

export NWC_CONNECTION_STRING="nostr+walletconnect://relay.getalby.com/v1?secret=...&relay=wss://relay.getalby.com"
Or in the SDK constructor: 
const agent = new BoltzPay({
  coinbaseApiKeyId: process.env.COINBASE_API_KEY_ID,
  coinbaseApiKeySecret: process.env.COINBASE_API_KEY_SECRET,
  coinbaseWalletSecret: process.env.COINBASE_WALLET_SECRET,
  nwcConnectionString: process.env.NWC_CONNECTION_STRING,
});
Most endpoints today use the x402 protocol (USDC). L402 is a Lightning-native protocol from Lightning Labs. You can enable both simultaneously — the SDK auto-detects which protocol each endpoint uses.