Install

npm install @bolthub/agent

Zero runtime dependencies. Uses only Node.js built-ins (fetch, crypto, fs). No third-party packages in your supply chain.

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

Phoenixd

Use PhoenixdWallet when your agent pays via an existing Phoenixd HTTP API. Prefer LndWallet with the bolthub Node Launcher or your own LND when you are choosing a new setup.

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

const wallet = new PhoenixdWallet({
  baseUrl: "http://localhost:9740",
  password: "your-phoenixd-password",
});

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

TypeScript SDK