Installation - BoltzPay

Prerequisites

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

SDK

Install the SDK in your TypeScript or JavaScript project:

npm
pnpm
yarn

npm install @boltzpay/sdk

pnpm add @boltzpay/sdk

yarn add @boltzpay/sdk

The SDK works in explore mode with zero configuration: you can quote prices, diagnose endpoints, and discover APIs without any credentials. To enable payments, install the Coinbase CDP SDK peer dependency:

npm
pnpm
yarn

npm install @coinbase/cdp-sdk

pnpm add @coinbase/cdp-sdk

yarn add @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, diagnose, budget, history, discover, and wallet. The discover tool now supports protocol, score, and query filters to narrow results.

CLI

No install needed. Run directly with npx:

npx @boltzpay/cli quote https://invy.bot/api

Or install globally:

npm
pnpm

npm install -g @boltzpay/cli

pnpm add -g @boltzpay/cli

Then use the boltzpay command directly:

boltzpay quote https://invy.bot/api
boltzpay discover --protocol mpp --min-score 70
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:

Create an account

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

Create an API key

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

Create a wallet

Note the Wallet Secret.

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.

Tempo (MPP protocol)

For MPP endpoints using the Tempo payment channel network. You need a private key (hex-encoded).

export TEMPO_PRIVATE_KEY="0x..."

Or in the SDK constructor via the wallets array:

const agent = new BoltzPay({
  wallets: [
    {
      type: "tempo",
      name: "main",
      tempoPrivateKey: process.env.TEMPO_PRIVATE_KEY!,
    },
  ],
});

Tempo wallets enable both one-shot MPP payments and streaming sessions via payment channels. See Sessions for the streaming API.

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

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.
Primal — Free mobile app with built-in Lightning wallet and NWC support.
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.
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.

​Prerequisites

​SDK

​MCP Server (Claude Desktop)

​CLI

​Credentials Setup

​Coinbase CDP (required for payments)

​Tempo (MPP protocol)

​NWC (optional, for L402 protocol)

​How to get your NWC connection string

​Set the connection string

Prerequisites

SDK

MCP Server (Claude Desktop)

CLI

Credentials Setup

Coinbase CDP (required for payments)

Tempo (MPP protocol)

NWC (optional, for L402 protocol)

How to get your NWC connection string

Set the connection string