Architecture

How wallet, fetch, pay, and registry components fit together for agent-native payments.

The ZBD Agents architecture is built around a simple split: agent-pay issues payment challenges, and agent-fetch or zbdw fetch solves them automatically.

Components

@zbdpay/agent-wallet

CLI interface (zbdw) for wallet operations, payment history, withdraw flows, and paid fetch.

@zbdpay/agent-fetch

Client-side L402 flow manager with cache reuse and max payment guardrails.

@zbdpay/agent-pay

Server middleware that returns 402 challenges and verifies payment proof.

zbd.ai Registry

Identity layer for stable Lightning addresses and LNURL resolution.

Request Lifecycle

1. Client requests protected resource

   A request hits an endpoint wrapped by agent-pay.

2. Server returns 402 challenge

   agent-pay creates an invoice and returns WWW-Authenticate: L402 ... plus challenge JSON.

3. Client pays challenge

   agent-fetch (or zbdw fetch) pays the invoice and retrieves the preimage.

4. Client retries with proof

   The request is retried with Authorization: L402 <macaroon>:<preimage>.

5. Server verifies and allows

   agent-pay validates signature, hash, amount, expiry, and settlement state before returning 200.

Shared Local State

Path	Primary Writer	Primary Reader
~/.zbd-wallet/config.json	zbdw init	zbdw, dashboard
~/.zbd-wallet/payments.json	zbdw send/receive	zbdw, dashboard
~/.zbd-wallet/token-cache.json	zbdw fetch	zbdw fetch
~/.zbd-wallet/server-tokens.json	agent-pay	agent-pay

The toolkit is optimized for Node.js 22+ across all core packages.