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[]

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[]>

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"
}

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)
}

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

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;
}

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 category?: string;
  readonly signal?: AbortSignal;
  readonly enableLiveDiscovery?: boolean; // Default: true
}

interface DiscoveredEntry extends ApiDirectoryEntry {
  readonly live: DiscoverEntryStatus;
}

type DiscoverEntryStatus =
  | { status: "live"; livePrice: string; protocol: string; network: string | undefined }
  | { status: "free" }
  | { status: "offline"; reason: string }
  | { status: "error"; reason: 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];
}

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 {
  API_DIRECTORY,
  getDirectoryCategories,
  filterDirectory,
  toDiscoverJson,
} from '@boltzpay/sdk';

interface ApiDirectoryEntry {
  readonly name: string;
  readonly url: string;
  readonly protocol: string;
  readonly category: string;
  readonly description: string;
  readonly pricing: string;
  readonly chain?: string;
  readonly status?: "live" | "testnet";
}

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.1.1";