BotPay CLI

BotPay is a production CLI for x402 service discovery, direct Agent wallet payments, and paid access to the guarded BotPay /go exchange MCP. Bazaar commands are unlocked locally by one successful 0.01 USDC /pay purchase; the /go connector is unlocked separately by one successful 0.10 USDC /go purchase.

The payment path is direct:

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

Principles

• Explicit access: Bazaar commands require a successful local /pay receipt; /openapi.json and /.well-known/x402 origin inspection remain free.
• Separate authorities: a paid /go receipt unlocks the trading connector, but never approves an exchange order. Live orders require a separate operator approval in the trading gateway.
• 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.

Fund the local Agent wallet with Base USDC (beta limit: 5 USDC):

# Scan a WalletConnect QR code and approve a direct Base USDC transfer
npx botpay wallet topup --method walletconnect --amount 1 --yes

# Redeem Scan Credits at 200 Credits per USDC through gasless x402/PayAI
npx botpay login
npx botpay wallet topup --method scan --amount 1 --yes

Without --yes, either command prints a plan and changes nothing. Reuse --idempotency-key when retrying the same Scan redemption.

Codex, Cursor, Claude Code, OpenClaw, Hermes, and Manus

BotPay includes a standard stdio MCP server, so compatible Agent clients can discover typed BotPay tools for services, Bazaar search/list/stats, origin discovery, endpoint inspection, wallet balance, payment planning, and guarded service execution.

Codex:

codex mcp add botpay -- npx -y botpay@latest mcp

Claude Code:

claude mcp add --transport stdio --scope user botpay -- npx -y botpay@latest mcp

Cursor project configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "botpay": {
      "command": "npx",
      "args": ["-y", "botpay@latest", "mcp"]
    }
  }
}

Other stdio MCP clients can use the same command: npx -y botpay@latest mcp. The separate botpay-mcp executable is also included for globally installed packages.

After purchasing /go access, add the guarded trading MCP as a second server:

botpay plan go
botpay execute go --yes
botpay go status
codex mcp add botpay-go -- npx -y botpay@latest go mcp

Claude Code uses claude mcp add --transport stdio --scope user botpay-go -- npx -y botpay@latest go mcp. Cursor and other stdio clients use command npx with arguments -y, botpay@latest, go, mcp. The connector runs read_only by default. Configure exchange secrets only in the trusted gateway environment, never in Agent prompts or skill files.

BotPay also ships one portable Agent Skills skill. Install every supported local integration and create a Manus upload bundle:

botpay agent install --target all

Use --project . for repository-scoped installation, or select one client with --target codex, --target cursor, --target claude, --target openclaw, --target hermes, or --target manus. Reload the local client after installation. The skill prefers MCP and falls back to stable --json CLI commands when an Agent has shell access but no MCP configuration.

OpenClaw installs the Skill in its native location and configures the BotPay stdio MCP server when the openclaw executable is available:

npx -y botpay@latest agent install --target openclaw

The installer also runs openclaw mcp doctor botpay --probe. If OpenClaw is not on PATH, it still installs the Skill and prints the exact MCP setup command instead of reporting a false success.

Hermes installs the Skill in $HERMES_HOME/skills/botpay (or ~/.hermes/skills/botpay by default), safely merges the BotPay server into the matching config.yaml, preserves existing configuration and comments, and runs hermes mcp test botpay when the Hermes executable is available:

npx -y botpay@latest agent install --target hermes

For a project-scoped Hermes install, BotPay also adds that project's .agents/skills directory to Hermes skills.external_dirs.

Manus runs in the cloud and cannot launch a local stdio process from the user's machine. BotPay therefore creates a Skill ZIP with SKILL.md at its root, ready for Skills > + Add > Upload a skill:

npx -y botpay@latest agent install --target manus --output ./botpay-manus-skill.zip

The imported Manus Skill uses BotPay's stable JSON CLI fallback when shell execution is available. Typed BotPay tools in Manus require a separately deployed HTTPS MCP endpoint; this installer does not pretend that the local stdio MCP is reachable from Manus. Use --no-mcp to install only Skill files, or --no-probe to skip local MCP health checks.

MCP starts read-only: botpay_execute_service rejects all payments unless the user deliberately sets BOTPAY_MCP_ALLOW_PAYMENTS=1 in that MCP server's environment. Even then, the tool also requires confirmed: true after explicit human approval of the exact plan. Discovery, listing, search, statistics, inspection, balances, and planning never pay.

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

Bazaar Access and Discovery

The default Bazaar source is Coinbase's official x402 discovery endpoint. Before the first Bazaar read on a local installation, explicitly plan and purchase access:

botpay plan pay
botpay execute pay --yes
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 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 Bazaar pages. Increase --pages for broader search coverage. bazaar origin scans those same pages for one exact seller origin. These commands verify the local /pay receipt but never initiate another payment themselves.

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 pay
botpay execute pay --yes
botpay plan go
botpay go status
botpay plan safe
botpay plan nft --to 0xRecipient
botpay plan token --amount 0.5
botpay execute nft --to 0xRecipient --yes
botpay plan video
botpay execute video --yes

The production catalog includes the five canonical api.botpay.network resources: GET /pay, GET /go, POST /safe, POST /nft, and POST /token. The token resource requires --amount from 0.1 through 10 USDC. These are non-interactive production commands; the unpublished local nine-menu demo is not part of this package.

GET /go is a distinct paid capability. A successful 0.10 USDC x402 call stores a local /go access receipt and returns the endpoint's six-digit verificationCode once; only its SHA-256 hash is stored. The access receipt allows botpay go mcp to launch the pinned [email protected] connector for Binance, OKX, Coinbase, Hyperliquid spot, and Polymarket. The access payment is not a trade approval and does not move funds into any exchange.

The exchange connector intentionally exposes no withdrawals, transfers, margin, futures, or leverage. It defaults to TRADING_MODE=read_only; paper and live execution require explicit configuration. Agents may inspect markets and prepare proposals, while a human-controlled operator credential must separately approve each proposal or batch before execution. Cross-venue batches are non-atomic and can partially execute.

Bazaar commands require a successful one-time local access purchase through /pay:

botpay plan pay
botpay execute pay --yes
botpay bazaar search "market data"

The access receipt is stored locally under ~/.botpay/receipts.ndjson. Bazaar commands never initiate a payment themselves; without a valid /pay receipt they return BAZAAR_ACCESS_REQUIRED and show the explicit unlock command.

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: /pay and /go access receipts plus voucher hashes, never voucher secrets or exchange credentials

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_API_ORIGIN | Override the canonical BotPay API origin | | BOTPAY_VOUCHER_API_BASE | Override the escrow voucher origin | | BOTPAY_NFT_ORIGIN | Override the NFT origin | | BOTPAY_VIDEO_ORIGIN | Override the video origin | | BOTPAY_MCP_ALLOW_PAYMENTS | Set to 1 only in an explicitly approved MCP server to unlock guarded service execution | | 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

botpay doctor