BotPay CLI

BotPay is a developer CLI for free x402 service discovery and direct Agent wallet payments. It does not route discovery through a paid API aggregator or pay marketplace search fees.

The payment path is direct:

developer or agent -> BotPay CLI -> seller x402 endpoint -> seller/facilitator

Principles

• Free discovery first: official facilitator Bazaar APIs, /openapi.json, and /.well-known/x402.
• No hidden payments: commands transfer USDC only when --yes is present.
• Direct settlement: BotPay signs the seller's x402 challenge with the local Agent wallet.
• Constrained signing: network, asset, maximum/exact amount, payTo, and cross-origin resource changes are checked before signing.
• Escrow vouchers remain supported.
• Stable JSON output is available with --json.

Install

npm install -g botpay
botpay --help
botpay wallet init

Running --help, services, bazaar, discover, check, or a payment plan does not create a wallet automatically.

BotPay Scan Account

The CLI is an authorized device for a BotPay Scan user. Email, Google, EVM, and Solana remain web login identities; none of them becomes the CLI account key.

botpay login
botpay whoami
botpay workspace list
botpay workspace use <workspace-id>
botpay project list
botpay project use <project-id>

botpay login opens BotPay Scan and shows a short device code and QR code. After approval, the CLI receives a 15-minute access token and a rotating 30-day refresh token. Account login does not grant invoke:write and does not create or fund a payment wallet.

The previous wallet-first entry remains available as a web login shortcut:

botpay login --wallet

It opens the same device authorization page with the wallet sign-in pane selected. The approved CLI still belongs to the resulting stable BotPay user.

Manage local account profiles and remotely revocable devices:

botpay profile list
botpay profile use personal
botpay profile use company
botpay device list
botpay device revoke <device-id>
botpay logout
botpay logout --all

Wallet roles are separate from login identities:

botpay wallet list
botpay wallet link --purpose payment
botpay wallet use <wallet-id> --purpose payout

For CI/CD, create a project-scoped service token and provide it through the environment. The default service-token scopes are catalog read and API publish; they do not include payment invocation.

botpay token create --name ci-publisher --scope catalog:read,api:publish

Free Discovery

The default Bazaar source is Coinbase's public x402 discovery endpoint. Bazaar reads do not require a wallet or payment.

botpay bazaar list --page 1 --page-size 20 --network eip155:8453 --max-usdc 0.10
botpay bazaar list --limit 50
botpay bazaar stats
botpay bazaar search "video generation" --pages 20 --max-usdc 3
botpay bazaar origin https://mvp.botpay.network
botpay discover https://video.botpay.network
botpay check https://video.botpay.network/api/x402/video/watch --method POST

bazaar list always displays one bounded page and never prints the complete catalog; the maximum display limit is 100. bazaar stats walks the complete free catalog only to aggregate statistics, stopping when Bazaar reports that pagination has ended (or returns an empty page). In an interactive terminal it writes one updating progress line to stderr, while final text or JSON remains on stdout; --quiet and --json disable progress. It never emits individual resources or estimates totals from a configured page count. bazaar search performs local keyword ranking over free Bazaar pages. Increase --pages for broader search coverage. bazaar origin scans those same free pages for one exact seller origin. None of these commands calls a paid directory endpoint.

Direct API Calls

Build a no-payment plan:

botpay call https://provider.example/api --method POST \
  --body '{"query":"example"}' --max-usdc 0.05

Execute only after review:

botpay call https://provider.example/api --method POST \
  --body @request.json --max-usdc 0.05 --yes

Use --body - to read JSON from stdin and repeat --header 'Name: value' for headers. check --probe sends an unpaid runtime request and may invoke an unprotected route, so use it deliberately for non-GET methods.

BotPay Services

botpay services
botpay plan nft --to 0xRecipient
botpay execute nft --to 0xRecipient --yes
botpay plan video
botpay execute video --yes

Service origins are configurable. The CLI reads free origin discovery first and uses its built-in manifest only when the origin does not publish compatible discovery.

Escrow Voucher

botpay voucher create --yes
botpay voucher redeem --voucher 'BOTPAY-VOUCHER:...' --yes

Voucher creation pays 1 USDC to the voucher treasury. Redemption pays the advertised 0.01 USDC fee. The full voucher secret is returned once and is not written to receipts; only its SHA-256 hash is stored.

Full Refund

botpay refund \
  --to 0xOriginalPayer \
  --original-payer 0xOriginalPayer \
  --yes

Refund ignores BotPay Credits and sends the complete Base USDC balance from the local Agent wallet through an x402 payment signed by that local Agent wallet. The recipient must equal the original payer. The Agent Voucher Treasury (0x008D030704CFAfaeE1dA041Fdec6de071Bd546d9) and its private key are never used by this refund path. Native ETH is not refunded.

Credits

botpay credits balance
botpay credits topup --amount 10 --open

Human-readable balance output is intentionally one line: BotPay Credits: N.

Configuration

State is stored under ~/.botpay by default:

• agent-wallets.json: private keys, mode 0600
• config.json: non-secret overrides, mode 0600
• profiles.json: account profile, Scan origin, Workspace, and Project selection, mode 0600
• Account credentials: macOS Keychain when available; otherwise AES-256-GCM encrypted credentials.json with a restricted local key file
• discovery-cache.json: free origin discovery cache
• receipts.ndjson: payment receipts and voucher hashes, never voucher secrets

Useful environment variables:

| Variable | Purpose | | --- | --- | | BOTPAY_HOME | Override the state directory | | BOTPAY_TOKEN | Use a BotPay project/service token for CI/CD | | BOTPAY_CREDENTIALS_KEY | Supply the 32-byte hex key for encrypted credential fallback storage | | BOTPAY_AGENT_PRIVATE_KEY | Use an external EVM key without writing it to disk | | BOTPAY_BAZAAR_URLS | Comma-separated free Bazaar endpoints | | BOTPAY_VOUCHER_API_BASE | Override the escrow voucher origin | | BOTPAY_NFT_ORIGIN | Override the NFT origin | | BOTPAY_VIDEO_ORIGIN | Override the video origin | | BASE_RPC_URL | Override the Base RPC URL |

Non-secret values can also be managed with botpay config show and botpay config set.

Automation

botpay --json bazaar search "market data" --pages 10
botpay --json wallet balance
botpay --json plan voucher-create

Successful commands emit { "ok": true, "data": ..., "meta": ... }. Failures emit { "ok": false, "error": { "code", "message", "details" }, "meta": ... } to stderr and set a non-zero exit code.

Diagnostics And Legacy Demo

botpay doctor
botpay demo

botpay demo preserves the previous interactive WalletConnect experience. The production command surface is non-interactive unless an explicit browser or legacy demo command is requested.