Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.boltzpay.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Step 1: Explore Mode (no keys)

Create a BoltzPay instance with an empty config. No credentials needed: you can discover APIs, check prices, and get quotes for free. 
import { BoltzPay } from "@boltzpay/sdk";

const agent = new BoltzPay({});

// Check what this instance can do
const caps = agent.getCapabilities();
console.log("Can pay:", caps.canPay);     // false (no keys)
console.log("Protocols:", caps.protocols); // ["x402"]

​
Get a price quote

const quote = await agent.quote("https://invy.bot/api");

console.log("Protocol:", quote.protocol);             // "x402"
console.log("Price:", quote.amount.toDisplayString()); // "$0.05"
console.log("Network:", quote.network);                // "base"

​
Multi-chain pricing

Some endpoints accept payment on multiple chains. The quote includes all options: 
if (quote.allAccepts && quote.allAccepts.length > 1) {
  console.log("Available chains:");
  for (const accept of quote.allAccepts) {
    console.log(` - ${accept.network}: ${accept.amount} cents`);
  }
}

​
Discover APIs from the registry

Browse scored and indexed endpoints from the BoltzPay registry: 
const entries = await agent.discover();

for (const entry of entries) {
  console.log(`${entry.name} (score: ${entry.score})`);
  console.log(`  ${entry.url} — ${entry.protocol ?? "unknown"}`);
}
Filter by protocol, minimum score, or keyword: 
const mppApis = await agent.discover({
  protocol: "mpp",
  minScore: 70,
  query: "weather",
});

​
Step 2: Payment Mode (x402 — USDC)

Add Coinbase CDP credentials to pay x402 endpoints (USDC on Base). The SDK detects whether an endpoint requires payment, negotiates the protocol, pays, and returns the data. 
import { BoltzPay } from "@boltzpay/sdk";

const agent = new BoltzPay({
  coinbaseApiKeyId: process.env.COINBASE_API_KEY_ID!,
  coinbaseApiKeySecret: process.env.COINBASE_API_KEY_SECRET!,
  coinbaseWalletSecret: process.env.COINBASE_WALLET_SECRET!,
});

const response = await agent.fetch("https://invy.bot/api");
console.log("Status:", response.status); // 200
Don’t have Coinbase keys yet? See Installation for setup instructions.

​
Step 2b: Lightning Mode (L402 — Bitcoin, optional)

Add an NWC connection string to also pay L402 endpoints (Bitcoin via Lightning Network). Both protocols can be enabled simultaneously — the SDK auto-detects which one each endpoint uses. 
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!, // Lightning wallet
});

// Same fetch() call — protocol is transparent
const response = await agent.fetch("https://satsapi.dev/v1/price"); // L402, pays in sats
const data = await response.json();
console.log("Paid:", response.payment?.amount.toDisplayString()); // "$0.003"
Get your NWC connection string for free from Coinos, Primal, or any NWC-compatible wallet. See Installation for details.
For MPP wallets (Tempo, Stripe), see Configuration.

​
Step 3: Read the Response

agent.fetch() returns a BoltzPayResponse with familiar methods (json(), text()) plus payment metadata. 
const response = await agent.fetch("https://invy.bot/api");

// Read the response body
const data = await response.json();
console.log("Data:", data);

// Check payment details (null if endpoint was free)
if (response.payment) {
  console.log("Amount:", response.payment.amount.toDisplayString()); // "$0.05"
  console.log("Protocol:", response.payment.protocol);               // "x402"
  console.log("Tx hash:", response.payment.txHash);                  // "0xabc..."
}

​
Free endpoints pass through

If the endpoint does not require payment, fetch() works like a normal HTTP call. No payment is made, and response.payment is null. 
const free = await agent.fetch("https://api.example.com/public");
console.log(free.payment); // null

​
Full Example

import { BoltzPay } from "@boltzpay/sdk";

const agent = new BoltzPay({
  coinbaseApiKeyId: process.env.COINBASE_API_KEY_ID!,
  coinbaseApiKeySecret: process.env.COINBASE_API_KEY_SECRET!,
  coinbaseWalletSecret: process.env.COINBASE_WALLET_SECRET!,
  budget: {
    daily: "5.00",        // $5/day spending limit
    perTransaction: "1.00", // $1 max per request
  },
});

// Quote before paying
const quote = await agent.quote("https://invy.bot/api");
console.log(`This will cost ${quote.amount.toDisplayString()}`);

// Pay and fetch
const response = await agent.fetch("https://invy.bot/api");
const data = await response.json();
console.log(data);

// Check remaining budget
const budget = agent.getBudget();
console.log("Daily remaining:", budget.dailyRemaining?.toDisplayString());

// Review payment history
const history = agent.getHistory();
console.log("Payments:", history.length);

​
Quick CLI Quote

Verify an endpoint from your terminal without writing any code: 
npx @boltzpay/cli quote https://invy.bot/api
# Protocol: x402 | Price: $0.05 | Chain: Base

​
Next Steps

  • Configuration - all constructor options, budget settings, environment variables
  • Registry - how the registry scores and indexes paid APIs
  • Sessions - persistent payment sessions and channels
  • Claude Desktop - give Claude the ability to pay for APIs
  • CLI Reference - terminal commands and Python bridge