SDK API

npm install @boltzpay/sdk

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

const sdk = new BoltzPay(config: BoltzPayConfig);

async fetch(url: string, options?: FetchOptions): Promise<BoltzPayResponse>

const response = await sdk.fetch('https://invy.bot/api');
const data = await response.json();
console.log(data);
console.log(response.payment); // { protocol: 'x402', amount: Money, ... }

async quote(url: string): Promise<QuoteResult>

const quote = await sdk.quote('https://invy.bot/api');
console.log(quote.amount.toDisplayString()); // "$0.05"
console.log(quote.protocol);                 // "x402"

getBudget(): BudgetState

const budget = sdk.getBudget();
console.log(budget.dailySpent.toDisplayString());     // "$1.25"
console.log(budget.dailyRemaining?.toDisplayString()); // "$8.75"

resetDailyBudget(): void

getHistory(): readonly PaymentRecord[]

getMetrics(): PaymentMetrics

const metrics = sdk.getMetrics();
console.log(metrics.totalSpent.toDisplayString()); // "$4.25"
console.log(metrics.successCount);                  // 12
console.log(metrics.errorRate);                      // 0.08
console.log(metrics.avgLatencyMs);                   // 342

exportHistory(format: "csv" | "json"): string

const csv = sdk.exportHistory("csv");
const json = sdk.exportHistory("json");

getCapabilities(): {
  network: string;
  protocols: string[];
  canPay: boolean;
  canPayLightning: boolean;
  chains: ChainNamespace[];
  addresses: { evm?: string; svm?: string };
}

async getBalances(): Promise<{
  evm?: { address: string; balance: Money | undefined };
  svm?: { address: string; balance: Money | undefined };
}>

async getWalletStatus(): Promise<WalletStatus>

const status = await sdk.getWalletStatus();
console.log(status.connection.status); // "connected"
console.log(status.canPay);           // true
if (status.lightning?.balance) {
  console.log(status.lightning.balance.display); // "4800 sats"
}

async discover(options?: DiscoverOptions): Promise<readonly DiscoveredEntry[]>

async openSession(url: string, options?: BoltzPaySessionOptions): Promise<BoltzPaySession>

const session = await sdk.openSession("https://api.example.com/stream", {
  maxDeposit: "2.00",
});

for await (const event of session.stream("https://api.example.com/stream")) {
  if (event.type === "data") console.log(event.payload);
}

const receipt = await session.close();

wrapMcpClient(client: McpClientLike): WrappedMcpClient

const wrapped = sdk.wrapMcpClient(mcpClient);
const result = await wrapped.callTool({ name: "tool", arguments: { q: "data" } });
if (result.receipt) {
  console.log(`Paid via ${result.receipt.method}`);
}

async diagnose(url: string): Promise<DiagnoseResult>

const result = await sdk.diagnose('https://invy.bot/api');
console.log(result.health);   // "paid"
console.log(result.protocol); // "x402"
console.log(result.price);    // "$0.05"
console.log(result.totalMs);  // 257

close(): void

on<E extends EventName>(event: E, listener: EventListener<E>): this

off<E extends EventName>(event: E, listener: EventListener<E>): this

sdk
  .on('payment', (record) => {
    console.log(`Paid ${record.amount.toDisplayString()} via ${record.protocol}`);
  })
  .on('budget:warning', (event) => {
    console.log(`${(event.usage * 100).toFixed(0)}% of ${event.period} budget used`);
  })
  .on('error', (err) => {
    console.error('SDK error:', err.message);
  });

interface BoltzPayConfig {
  coinbaseApiKeyId?: string;
  coinbaseApiKeySecret?: string;
  coinbaseWalletSecret?: string;
  nwcConnectionString?: string;      // Must start with "nostr+walletconnect://"
  network?: "base" | "base-sepolia"; // Default: "base"
  preferredChains?: ChainNamespace[];
  budget?: BudgetConfig;
  persistence?: {
    enabled?: boolean;                // Default: false
    directory?: string;               // Default: "~/.boltzpay/"
    historyMaxRecords?: number;       // Default: 500
  };
  logLevel?: "debug" | "info" | "warn" | "error" | "silent"; // Default: "warn"
  wallets?: WalletConfig[];
  mppPreferredMethods?: string[];
  registryUrl?: string;                // Default: "https://status.boltzpay.ai"
  sessionMaxDeposit?: string | number;
  storage?: "file" | "memory" | StorageAdapter;
  logFormat?: "text" | "json";         // Default: "text"
  maxAmountPerRequest?: string | number;
  allowlist?: string[];
  blocklist?: string[];
  retry?: RetryConfig;
  rateLimit?: RateLimitConfig;
  timeouts?: TimeoutConfig;
}

interface BudgetConfig {
  daily?: string | number;            // e.g. "10.00" or 10
  monthly?: string | number;
  perTransaction?: string | number;
  warningThreshold?: number;          // 0..1, default: 0.8
  satToUsdRate?: number;              // Default: 0.001 (~$100K/BTC)
}

type WalletConfig =
  | { type: "coinbase"; name: string; coinbaseApiKeyId: string; coinbaseApiKeySecret: string; coinbaseWalletSecret: string; networks?: string[] }
  | { type: "nwc"; name: string; nwcConnectionString: string; networks?: string[] }
  | { type: "tempo"; name: string; tempoPrivateKey: string; networks?: string[] }
  | { type: "stripe-mpp"; name: string; stripeSecretKey: string; networks?: string[] }
  | { type: "visa-mpp"; name: string; visaJwe: string; networks?: string[] };

interface FetchOptions {
  maxAmount?: number | string;
  headers?: Record<string, string>;
  method?: string;                    // Default: "GET"
  body?: Uint8Array;
  chain?: ChainNamespace;
  dryRun?: boolean;                   // Default: false
}

class BoltzPayResponse {
  readonly ok: boolean;
  readonly status: number;
  readonly headers: Record<string, string>;
  readonly payment: PaymentDetails | undefined;
  readonly protocol: string | undefined;

  async json<T = unknown>(): Promise<T>;
  async text(): Promise<string>;
  get body(): ReadableStream<Uint8Array> | null;
}

interface QuoteResult {
  amount: Money;
  protocol: string;
  network: string | undefined;
  allAccepts?: readonly AcceptOption[];
  inputHints?: EndpointInputHints;
}

interface PaymentDetails {
  readonly protocol: string;
  readonly amount: Money;
  readonly url: string;
  readonly timestamp: Date;
  readonly txHash: string | undefined;
}

interface PaymentRecord {
  readonly id: string;                // UUID
  readonly url: string;
  readonly protocol: string;
  readonly amount: Money;
  readonly timestamp: Date;
  readonly txHash: string | undefined;
  readonly network: string | undefined;
  readonly durationMs?: number;       // Payment round-trip time
  readonly sessionId?: string;        // Session ID for session payments
  readonly sessionStatus?: string;    // "open" | "closed"
  readonly transport?: string;        // "mcp" for MCP transport payments
}

interface PaymentMetrics {
  readonly totalSpent: Money;
  readonly callCount: number;
  readonly successCount: number;
  readonly errorCount: number;
  readonly errorRate: number;         // 0..1 ratio
  readonly avgLatencyMs: number;
  readonly lastPaymentAt: Date | undefined;
}

interface DryRunResult {
  readonly wouldPay: boolean;
  readonly reason?: DryRunFailureReason;
  readonly quote?: {
    readonly amount: Money;
    readonly protocol: string;
    readonly network: string | undefined;
    readonly scheme: string;
  };
  readonly budgetCheck?: {
    readonly allowed: boolean;
    readonly dailyRemaining: Money | undefined;
    readonly monthlyRemaining: Money | undefined;
    readonly wouldExceed: "daily" | "monthly" | "per_transaction" | null;
  };
  readonly wallet?: {
    readonly name: string;
    readonly type: string;  // "coinbase", "nwc", "tempo", "stripe-mpp", "visa-mpp"
  };
  readonly endpoint?: {
    readonly health: EndpointHealth;
    readonly formatVersion: string;
  };
}

const result = await sdk.fetch("https://invy.bot/api", { dryRun: true });
if (result.wouldPay) {
  console.log(result.quote?.amount.toDisplayString()); // "$0.05"
  console.log(result.wallet?.type);                     // "coinbase"
} else {
  console.log(result.reason);                           // "budget_exceeded"
}

interface BudgetState {
  readonly dailySpent: Money;
  readonly monthlySpent: Money;
  readonly dailyLimit: Money | undefined;
  readonly monthlyLimit: Money | undefined;
  readonly perTransactionLimit: Money | undefined;
  readonly dailyRemaining: Money | undefined;
  readonly monthlyRemaining: Money | undefined;
}

interface DiscoverOptions {
  readonly protocol?: string;    // "x402", "l402", "mpp"
  readonly minScore?: number;    // 0-100
  readonly category?: string;
  readonly query?: string;       // Free-text search
  readonly limit?: number;       // Default: 200
  readonly offset?: number;      // Pagination offset
  readonly signal?: AbortSignal;
}

interface DiscoveredEntry {
  readonly slug: string;
  readonly name: string;
  readonly url: string;
  readonly protocol: string | undefined;
  readonly score: number;       // 0-100
  readonly health: string;      // "healthy", "degraded", "dead"
  readonly category: string;
  readonly isPaid: boolean;
  readonly badge: "new" | "established" | null;
}

class BoltzPaySession {
  readonly channelId: string;
  readonly spent: bigint;

  async fetch(url: string, init?: RequestInit): Promise<Response>;
  async *stream(url: string, init?: Record<string, unknown>): AsyncIterable<SessionEvent>;
  async close(): Promise<SessionReceipt>;
}

type SessionEvent =
  | { type: "data"; payload: string }
  | { type: "payment"; voucher: VoucherInfo };

interface VoucherInfo {
  channelId: string;
  cumulativeAmount: bigint;
  index: number;
}

interface SessionReceipt {
  channelId: string;
  totalSpent: bigint;
  refunded: bigint;
  voucherCount: number;
}

interface BoltzPaySessionOptions {
  maxDeposit?: number | string;  // Max deposit in USD
  signal?: AbortSignal;
}

interface WrappedMcpClient {
  callTool(
    params: { name: string; arguments?: Record<string, unknown> },
    options?: unknown,
  ): Promise<WrappedCallToolResult>;
}

interface WrappedCallToolResult {
  content: unknown;
  isError?: boolean;
  _meta?: Record<string, unknown>;
  receipt?: McpPaymentReceipt;
}

interface McpPaymentReceipt {
  method: string;
  status: string;
  reference: string;
  timestamp: string;
}

interface WalletStatus {
  readonly network: string;
  readonly isTestnet: boolean;
  readonly protocols: readonly string[];
  readonly canPay: boolean;
  readonly credentials: {
    readonly coinbase: CredentialStatus;
  };
  readonly connection: ConnectionStatus;
  readonly accounts: {
    readonly evm: AccountStatus | undefined;
    readonly svm: AccountStatus | undefined;
  };
  readonly budget: BudgetState;
  readonly lightning?: LightningStatus;
}

type ConnectionStatus =
  | { status: "connected"; latencyMs: number }
  | { status: "error"; error: string; latencyMs?: number }
  | { status: "skipped"; reason: string };

interface LightningStatus {
  readonly configured: boolean;
  readonly connection: {
    readonly status: "connected" | "error" | "skipped";
    readonly latencyMs?: number;
    readonly error?: string;
  };
  readonly balance?: { readonly sats: bigint; readonly display: string };
}

interface BoltzPayEvents {
  payment: [PaymentRecord];
  "budget:warning": [BudgetWarningEvent];
  "budget:exceeded": [BudgetExceededEvent];
  error: [Error];
  "retry:attempt": [RetryAttemptEvent];
  "retry:exhausted": [RetryExhaustedEvent];
  "payment:uncertain": [PaymentUncertainEvent];
  "protocol:unsupported-scheme": [UnsupportedSchemeEvent];
  "protocol:unsupported-network": [UnsupportedNetworkEvent];
  "wallet:selected": [WalletSelectedEvent];
  "session:open": [SessionOpenEvent];
  "session:voucher": [SessionVoucherEvent];
  "session:close": [SessionCloseEvent];
  "session:error": [SessionErrorEvent];
  "mcp:payment": [McpPaymentEvent];
}

interface BudgetWarningEvent {
  readonly spent: Money;
  readonly limit: Money;
  readonly period: "daily" | "monthly";
  readonly usage: number; // 0..1 ratio
}

interface BudgetExceededEvent {
  readonly requested: Money;
  readonly limit: Money;
  readonly period: "daily" | "monthly" | "per_transaction";
}

import { Money } from '@boltzpay/sdk';

type ChainNamespace = "evm" | "svm";

interface AcceptOption {
  readonly namespace: ChainNamespace;
  readonly network: string;
  readonly amount: bigint;     // USD cents
  readonly payTo: string;
  readonly asset: string;
  readonly scheme: string;
}

export type { ProtocolType, WalletInfo } from '@boltzpay/core';

import {
  BoltzPayError,
  BudgetExceededError,
  ConfigurationError,
  InsufficientFundsError,
  NetworkError,
  ProtocolError,
} from '@boltzpay/sdk';

BoltzPayError (abstract)
├── BudgetExceededError      429   + requested: Money, limit: Money
├── ConfigurationError       400
├── InsufficientFundsError   402
├── NetworkError             503
└── ProtocolError            502

abstract class BoltzPayError extends Error {
  abstract readonly code: string;
  abstract readonly statusCode: number;
}

try {
  const response = await sdk.fetch('https://invy.bot/api');
} catch (error) {
  if (error instanceof BudgetExceededError) {
    console.log(`Budget: ${error.requested.toDisplayString()} exceeds ${error.limit.toDisplayString()}`);
  } else if (error instanceof InsufficientFundsError) {
    console.log('Wallet needs more USDC');
  } else if (error instanceof ConfigurationError) {
    console.log('Check your API keys');
  } else if (error instanceof ProtocolError) {
    console.log(`Protocol error: ${error.code}`);
  } else if (error instanceof NetworkError) {
    console.log('Network issue, retrying...');
  } else if (error instanceof BoltzPayError) {
    console.log(`SDK error [${error.code}]: ${error.message}`);
  } else {
    throw error;
  }
}

try {
  await sdk.fetch(url);
} catch (error) {
  if (error instanceof BoltzPayError) {
    switch (error.code) {
      case 'daily_budget_exceeded':
      case 'monthly_budget_exceeded':
        console.log('Budget exhausted — wait for reset');
        break;
      case 'per_transaction_exceeded':
        console.log('This endpoint is too expensive');
        break;
      case 'missing_coinbase_credentials':
        console.log('Configure Coinbase keys to enable payments');
        break;
      case 'insufficient_usdc':
        console.log('Fund your wallet with USDC');
        break;
      default:
        console.log(`${error.code}: ${error.message}`);
    }
  }
}

export const VERSION = "0.3.0";