Agent Wallet

Use zbdw for wallet setup, send/receive operations, withdraw flows, and paid fetch.

@zbdpay/agent-wallet ships the zbdw CLI and is the fastest way to operationalize agent payments.

Repository

Source code, release history, and examples.

NPM Package

Install globally or execute with npx.

Install

npm install -g @zbdpay/agent-wallet

Or run directly:

npx @zbdpay/agent-wallet init --key <your_api_key>

Environment Variables

Variable	Default	Purpose
ZBD_API_KEY	none	API key for wallet and payments requests
ZBD_API_BASE_URL	https://api.zbdpay.com	Override ZBD API host
ZBD_AI_BASE_URL	https://zbd.ai	Registration service host
ZBD_WALLET_CONFIG	~/.zbd-wallet/config.json	Wallet config path
ZBD_WALLET_PAYMENTS	~/.zbd-wallet/payments.json	Local payments log path
ZBD_WALLET_TOKEN_CACHE	~/.zbd-wallet/token-cache.json	L402 token cache path

Command Reference

zbdw init [--key <apiKey>]
zbdw info
zbdw balance

zbdw receive <amount_sats>
zbdw receive --static

zbdw send <destination> <amount_sats>
zbdw payments
zbdw payment <id>

zbdw paylink create <amount_sats>
zbdw paylink get <id>
zbdw paylink list
zbdw paylink cancel <id>

zbdw withdraw create <amount_sats>
zbdw withdraw status <withdraw_id>

zbdw fetch <url> [--method <method>] [--data <json>] [--max-sats <amount>]

Destination Types (send)

Destination	Example	Route
BOLT11 invoice	lnbc...	/v0/payments
Lightning Address	[e-mail]	/v0/ln-address/send-payment
ZBD Gamertag	@player	/v0/gamertag/send-payment
LNURL	lnurl...	/v0/ln-address/send-payment

JSON Output Contract

Success and failure responses are always JSON on stdout.

{
  "error": "error_code",
  "message": "Human-readable message",
  "details": {}
}

Common success examples:

{"lightningAddress":"[e-mail]","status":"ok"}
{"balance_sats":50000}
{"payment_id":"pay_123","fee_sats":1,"status":"completed"}
{"status":200,"body":{},"payment_id":"pay_123","amount_paid_sats":21}
{"id":"pl_001","url":"https://zbd.ai/paylinks/pl_001","status":"active","lifecycle":"active","amount_sats":250}

Paylink lifecycle values: created | active | paid | expired | dead. Terminal states (paid, expired, dead) are permanent. zbdw paylink get also syncs the latest payment attempt to local payments.json.

Storage Layout

~/.zbd-wallet/
  config.json
  payments.json       # includes paylink settlement records with paylink_id, paylink_lifecycle
  paylinks.json       # local paylink index (ZBD_WALLET_PAYLINKS to override)
  token-cache.json

zbdw fetch uses @zbdpay/agent-fetch under the hood, including token caching and max payment guardrails.

Companion Runnable Examples

agent-wallet does not currently ship its own examples/ directory. For a full runnable flow, pair it with:

• agent-pay/examples/http-server.mjs
• agent-fetch/examples/zbd-agent-fetch.mjs

Troubleshooting

Command not found: zbdw

Build and alias the local binary, or install globally with npm install -g @zbdpay/agent-wallet.

register_failed during init

Confirm ZBD_AI_BASE_URL points to a reachable zbd-ai service and your API key is valid.

wallet_response_invalid

Verify your configured API base URL returns wallet balance fields in expected shape.