@bolthub/agent

L402 client for AI agents. Automatically handles 402 Payment Required challenges, pays Lightning invoices, and retries requests with proof of payment.

Install

npm install @bolthub/agent

Quick Start

import { L402Client, LndWallet } from "@bolthub/agent";

const wallet = new LndWallet({
  host: "https://your-lnd-node:8080",
  macaroon: "0201036c6e...",
});

const client = new L402Client({
  wallet,
  maxPerRequestSats: 100,
  budgetSats: 10_000,
});

const resp = await client.get(
  "https://acme.gw.bolthub.ai/v1/weather",
  { params: { city: "berlin" } }
);
const data = await resp.json();

Wallet Adapters

LND

import { LndWallet } from "@bolthub/agent";

const wallet = new LndWallet({
  host: "https://your-lnd-node:8080",
  macaroon: "admin-macaroon-hex",
  timeoutSeconds: 30,
});

LNbits

import { LnbitsWallet } from "@bolthub/agent";

const wallet = new LnbitsWallet({
  url: "https://lnbits.example.com",
  adminKey: "your-admin-key",
});

NWC (Nostr Wallet Connect)

import { NwcWallet } from "@bolthub/agent";

const wallet = new NwcWallet(nwcConnection);

Custom Wallet

Implement the WalletAdapter interface:

import type { WalletAdapter } from "@bolthub/agent";

const myWallet: WalletAdapter = {
  async payInvoice(bolt11: string) {
    const preimage = await myPaymentLogic(bolt11);
    return { preimage };
  },
};

Budget Guards

const client = new L402Client({
  wallet,
  maxPerRequestSats: 100,   // reject invoices over 100 sats
  budgetSats: 10_000,        // total spending cap
});

console.log(client.totalSpent);      // sats spent so far
console.log(client.remainingBudget); // sats remaining

Session Persistence

By default sessions are kept in memory. Use FileSessionStore to persist tokens across process restarts (stored in ~/.bolthub/sessions.json):

import { L402Client, LndWallet, FileSessionStore } from "@bolthub/agent";

const client = new L402Client({
  wallet: new LndWallet({ host, macaroon }),
  sessionStore: new FileSessionStore(),
});

API Reference

| Export | Description | |--------|-------------| | L402Client | HTTP client with automatic L402 challenge handling | | LndWallet | Wallet adapter for LND REST API | | LnbitsWallet | Wallet adapter for LNbits | | PhoenixdWallet | Wallet adapter for Phoenixd | | NwcWallet | Wallet adapter for Nostr Wallet Connect | | WebLnWallet | Browser-only wallet via the WebLN provider | | isWebLnAvailable() | Check if a WebLN provider exists | | FileSessionStore | Disk-backed session token persistence | | createL402Client() | Shorthand factory for L402Client | | WalletAdapter | Interface to implement for custom wallets | | L402Error | Base error class for L402 failures | | L402BudgetError | Thrown when budget limits are exceeded | | L402PaymentError | Thrown when the wallet fails to pay | | L402TimeoutError | Thrown when a request times out |

License

MIT