Configuration

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

const agent = new BoltzPay({
  // ...options
});

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 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!,
});

const agent = new BoltzPay({
  wallets: [
    {
      type: "coinbase",
      name: "main",
      coinbaseApiKeyId: process.env.COINBASE_API_KEY_ID!,
      coinbaseApiKeySecret: process.env.COINBASE_API_KEY_SECRET!,
      coinbaseWalletSecret: process.env.COINBASE_WALLET_SECRET!,
    },
    {
      type: "nwc",
      name: "lightning",
      nwcConnectionString: process.env.NWC_CONNECTION_STRING!,
    },
    {
      type: "tempo",
      name: "tempo-main",
      tempoPrivateKey: process.env.TEMPO_PRIVATE_KEY!,
    },
    {
      type: "stripe-mpp",
      name: "stripe",
      stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
    },
    {
      type: "visa-mpp",
      name: "visa",
      visaJwe: process.env.VISA_JWE!,
    },
  ],
});

const agent = new BoltzPay({
  registryUrl: "https://my-registry.example.com", // default: https://status.boltzpay.ai
});

const agent = new BoltzPay({
  sessionMaxDeposit: "5.00", // Cap session deposits at $5
});

const agent = new BoltzPay({
  // ...credentials
  budget: {
    daily: "5.00",
    monthly: "100.00",
    perTransaction: "1.00",
    warningThreshold: 0.8,
  },
});

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

try {
  const response = await agent.fetch("https://emc2ai.io/x402/bitquery/whale-intel/raw");
} catch (error) {
  if (error instanceof BudgetExceededError) {
    console.log(error.code);       // "daily_budget_exceeded" | "monthly_budget_exceeded" | "per_transaction_exceeded"
    console.log(error.requested);  // Money — the amount requested
    console.log(error.limit);      // Money — the limit exceeded
  }
}

const budget = agent.getBudget();
console.log("Daily spent:", budget.dailySpent.toDisplayString());          // "$0.10"
console.log("Daily remaining:", budget.dailyRemaining?.toDisplayString()); // "$4.90"

interface BudgetState {
  dailySpent: Money;           monthlySpent: Money;
  dailyLimit?: Money;          monthlyLimit?: Money;
  perTransactionLimit?: Money;
  dailyRemaining?: Money;      monthlyRemaining?: Money;
}

agent.resetDailyBudget();

agent.on("payment", (record) => {
  console.log(record.url);                           // "https://invy.bot/api"
  console.log(record.protocol);                      // "x402"
  console.log(record.amount.toDisplayString());      // "$0.05"
  console.log(record.txHash);                        // "0xabc..." or undefined
});

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

// BudgetWarningEvent { spent: Money, limit: Money, period: "daily"|"monthly", usage: number }
agent.on("budget:warning", (event) => {
  console.log(`${(event.usage * 100).toFixed(0)}% of ${event.period} budget used`);
});

// BudgetExceededEvent { requested: Money, limit: Money, period: "daily"|"monthly"|"per_transaction" }
agent.on("budget:exceeded", (event) => {
  console.log(`Blocked: ${event.period} limit of ${event.limit.toDisplayString()} reached`);
});

agent.on("error", (error) => {
  console.log(error.name, error.message);
});

agent.on("session:open", (event) => {
  console.log(`Session opened: channel ${event.channelId}, deposit ${event.depositAmount.toDisplayString()}`);
});

agent.on("session:voucher", (event) => {
  console.log(`Voucher #${event.index}: ${event.cumulativeAmount} (channel ${event.channelId})`);
});

agent.on("session:close", (event) => {
  console.log(`Session closed: spent ${event.totalSpent}, refunded ${event.refunded}`);
});

agent.on("session:error", (event) => {
  console.error(`Session error: ${event.error.message}`);
});

agent.on("mcp:payment", (event) => {
  console.log(`MCP payment: tool ${event.toolName}, amount ${event.amount.toDisplayString()}`);
});

const history = agent.getHistory();

for (const record of history) {
  console.log(`${record.url} — ${record.amount.toDisplayString()} via ${record.protocol}`);
}

Server offers: [evm $0.05, svm $0.05]  →  evm $0.05  (EVM wins tie)
Server offers: [evm $0.05, svm $0.03], pref: ["evm"]  →  evm $0.05
Server offers: [evm $0.05, svm $0.03], pref: none  →  svm $0.03

const agent = new BoltzPay({
  // ...credentials
  preferredChains: ["evm"],  // Always prefer EVM when available
});

const response = await agent.fetch("https://invy.bot/api", {
  chain: "svm",  // Force Solana for this request
});

boltzpay fetch https://invy.bot/api --chain svm

const agent = new BoltzPay({
  network: "base-sepolia",
});

export BOLTZPAY_NETWORK=base-sepolia

const agent = new BoltzPay({
  logLevel: "debug",
});

const agent = new BoltzPay({
  timeouts: {
    detect: 10_000,  // Protocol detection (ms)
    quote: 15_000,   // Price quote (ms)
    payment: 30_000, // Payment execution (ms)
  },
});

# Required for payments
COINBASE_API_KEY_ID=your-key-id
COINBASE_API_KEY_SECRET=your-key-secret
COINBASE_WALLET_SECRET=your-wallet-secret

# Optional — enables L402 (Lightning) protocol
NWC_CONNECTION_STRING=nostr+walletconnect://...

# Optional — enables MPP protocols
TEMPO_PRIVATE_KEY=your-tempo-private-key
STRIPE_SECRET_KEY=sk_live_...

BOLTZPAY_NETWORK=base
BOLTZPAY_LOG_LEVEL=warn
BOLTZPAY_DAILY_BUDGET=5.00
BOLTZPAY_MONTHLY_BUDGET=100.00
BOLTZPAY_PER_TRANSACTION=1.00