Skip to main content
This quickstart gets you from zero to a working paid request flow.
Use Node.js 22+ for all packages in this toolkit.

​
1) Install Wallet CLI

npm install -g @zbdpay/agent-wallet

​
2) Initialize Wallet Identity

zbdw init --key <your_api_key>
# {"lightningAddress":"your-name@zbd.ai","status":"ok"}
Then verify balance and metadata: 
zbdw info
zbdw balance

​
3) Try Core Wallet Actions

zbdw receive 1000
zbdw receive --static

​
4) Fetch a Paid Endpoint (L402)

zbdw fetch https://your-paid-api.com/premium --max-sats 100
Run the same command again to reuse the token cache when valid. 
zbdw fetch https://your-paid-api.com/premium --max-sats 100
If cache is reused, payment_id is typically null on the second call.

​
4b) Zero-to-Demo with Included Examples

If you want to see the full paid-route flow with minimal setup, run the maintained examples directly from the monorepo workspace: 
npm --prefix agent-pay run build
ZBD_API_KEY=<your_api_key> npm --prefix agent-pay run example:http-server
Then in another terminal: 
npm --prefix agent-fetch run build
PROTECTED_URL="https://api.example.com/protected" ZBD_API_KEY=<your_api_key> npm --prefix agent-fetch run example:zbd

​
5) Add a Paid Route with agent-pay

import express from "express";
import { createExpressPaymentMiddleware } from "@zbdpay/agent-pay";

const app = express();

app.get(
  "/premium",
  createExpressPaymentMiddleware({ amount: 21, apiKey: process.env.ZBD_API_KEY }),
  (_req, res) => res.json({ premium: true }),
);

app.listen(3000);

​
6) Use agent-fetch in App Code

import { agentFetch, FileTokenCache } from "@zbdpay/agent-fetch";

const tokenCache = new FileTokenCache(`${process.env.HOME}/.zbd-wallet/token-cache.json`);

const response = await agentFetch("https://api.example.com/premium", {
  tokenCache,
  maxPaymentSats: 100,
  pay: async (challenge) => {
    // Implement invoice payment with your wallet API call.
    return {
      preimage: "<payment-preimage>",
      paymentId: "<payment-id>",
      amountPaidSats: challenge.amountSats,
    };
  },
});

console.log(response.status, await response.json());

​
Next Guides

Agent Wallet

CLI command reference, env vars, and JSON output contract.

Agent Pay

Add L402 to Express, Hono, and Next.js.

Agent Fetch

Full client options, async settlement, and caching.

Repo Map

Canonical repositories and package boundaries.