Axo CLI
Use axo for wallet setup, send/receive operations, withdraw flows, paid fetch, and managed MPP sessions.
@axobot/cli ships the axo CLI and is the fastest way to operationalize agent payments from scripts, local development, and autonomous runtimes.
Repository
Source code, release history, and examples.
NPM Package
Install globally or execute with npx.
Install
npm install -g @axobot/cliOr run directly:
npx @axobot/cli 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 provider API host |
ZBD_AI_BASE_URL | https://axo.bot | 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 |
ZBD_WALLET_SESSIONS | ~/.zbd-wallet/sessions.json | Local MPP session state path |
Command Reference
axo init [--key <apiKey>]
axo info
axo balance
axo receive <amount_sats>
axo receive --static
axo send <destination> <amount_sats>
axo payments
axo payment <id>
axo paylink create <amount_sats>
axo paylink get <id>
axo paylink list
axo paylink cancel <id>
axo withdraw create <amount_sats>
axo withdraw status <withdraw_id>
axo fetch <url> [--method <method>] [--data <json>] [--max-sats <amount>]
axo session create <url> [--return-invoice <bolt11>] [--return-lightning-address <address>]
axo session status [session_id]
axo session close <session_id>Destination Types (send)
| Destination | Example | Route |
|---|---|---|
| BOLT11 invoice | lnbc... | /v0/payments |
| Lightning Address | name@domain.com | /v0/ln-address/send-payment |
| 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":"name@axo.bot","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://axo.bot/paylinks/pl_001","status":"active","lifecycle":"active","amount_sats":250}Info
Paylink lifecycle values: created | active | paid | expired | dead. Terminal states (paid, expired, dead) are permanent.
axo 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
sessions.json # MPP session lifecycle for the CLIInfo
axo fetch uses @axobot/fetch under the hood, including token caching and max payment guardrails.
Companion Runnable Examples
axobot-cli does not currently ship its own examples/ directory. For a full runnable flow, pair it with:
- the protected route example in
axobot-pay - the paid fetch example in
axobot-fetch