CLI Reference

The Agent CLI (botwallet) is the reference client for the Botwallet API. Source: botwallet-co/agent-cli. Run botwallet docs for the same reference offline, or botwallet docs --json for a machine-readable command schema.

Installation

npm install -g @botwallet/agent-cli                  # npm, all platforms
brew install botwallet-co/tap/botwallet              # Homebrew, macOS/Linux
curl -fsSL https://botwallet.co/install.sh | sh      # shell installer, Linux/macOS
iwr https://botwallet.co/install.ps1 | iex           # PowerShell, Windows
go install github.com/botwallet-co/agent-cli@latest  # from source

Windows users can also scoop bucket add botwallet https://github.com/botwallet-co/scoop-bucket and then scoop install botwallet.

Output

JSON by default, for agents and scripts. Add --human for formatted output.

$ botwallet wallet balance
{"balance": 42.50, "daily_limit": 500.00, "spent_today": 10.00, "remaining_today": 490.00}

Errors are JSON too: { "error": "CODE", "message": "...", "how_to_fix": "..." }.

Global flags

Flag	Description
--api-key <key>	API key (or set BOTWALLET_API_KEY / BW_API_KEY)
--wallet <name>	Use a specific local wallet (see wallet list)
--api-url <url>	API base URL, for development
--human	Human-readable output with colors

Credential precedence: --api-key, then the environment variable, then --wallet, then the default wallet in ~/.botwallet/config.json.

register

botwallet register --name "My Agent Wallet" --owner you@email.com

Creates a wallet with FROST key generation and saves the API key and key share locally. register is the recommended entry point; wallet create is identical.

Flag	Description
--name, -n	Wallet name (required)
--owner	Owner’s email; the wallet appears in their dashboard
--model, -m	Agent model, for example claude-3
--desc	What this wallet is for
--meta key=value	Metadata, repeatable (--meta platform=cursor --meta project=my-app)

The output includes claim_url and claim_code. The wallet is blocked until the owner claims it; only wallet info, wallet owner and wallet rename work before then.

wallet

Command	Description
wallet create --name "..." --owner <email>	Create a wallet (same as register)
wallet info	Wallet info and claim status
wallet balance	Balance and spending limits
wallet list	List locally stored wallets
wallet use <name>	Switch the default wallet
wallet deposit	Solana USDC deposit address
wallet owner <email>	Update the pledged owner (unclaimed wallets only)
wallet rename <name>	Rename the display name (username unchanged)
wallet backup	Back up the agent’s key share (two-step safety process)
wallet export -o <file.bwlt>	Export the wallet to an encrypted .bwlt file
wallet import <file.bwlt> [--name <name>]	Import a wallet from a .bwlt file

pay

Payments are two steps: create an intent, then sign and submit.

Command	Description
pay @recipient <amount>	Step 1: create a payment intent (guard rails checked)
pay confirm <transaction_id>	Step 2: FROST-sign and submit
pay --paylink <id>	Pay a payment link directly (then pay confirm)
pay preview @recipient <amount>	Check whether a payment would succeed
pay list	List payments (--status actionable|all|completed|failed|expired, --id, --limit, --offset)
pay cancel <transaction_id>	Cancel a pending payment

Flags for pay: --note (alias --memo), --reference, --paylink, --idempotency-key.

Step 1 returns a status: pre_approved means you can confirm right away; awaiting_approval means the owner must approve first (poll approval status <approval_id>); rejected means a guard rail blocked it.

paylink

Create payment links and invoices to get paid.

Command	Description
paylink create [amount] --desc "..."	Create a payment link
paylink send <id> --to <email|@bot>	Send it by email or to another bot’s inbox
paylink get <id>	Check whether it has been paid
paylink get --reference <ref>	Look it up by your reference
paylink list	List paylinks (--status pending|completed|expired|cancelled, --limit, --offset)
paylink cancel <id>	Cancel a pending paylink

Create flags: --desc (required), --item (repeatable), --expires (1h, 24h, 7d; default 24h), --reference, --revealOwner (default true). Send flags: --to (required), --message.

Itemized invoice, total calculated for you:

botwallet paylink create --desc "Dev services" --item "API Calls, 5.00, 2" --item "Setup Fee, 10.00"

fund

Command	Description
fund <amount> --reason "..."	Ask the owner for funds
fund ask <amount> --reason "..."	Same, explicit subcommand
fund list	List fund requests (--status pending|approved|denied, --limit, --offset)

withdraw

Two steps: the owner must approve before you can sign.

Command	Description
withdraw <amount> <solana-address> --reason "..."	Step 1: create the request
withdraw confirm <withdrawal_id>	Step 2: FROST-sign and submit after approval
withdraw get <withdrawal_id>	Check status

Flags: --reason (required), --idempotency-key.

x402

Buy access to paid APIs. Probing is free; you only pay at the confirm step.

Command	Description
x402 discover	Curated catalog of verified Solana x402 APIs
x402 discover "query"	Search the catalog
x402 discover --bazaar [--all]	Search the full x402 Bazaar (Coinbase CDP); --all includes non-Solana networks
x402 fetch <url>	Step 1: probe the API and see its price
x402 fetch confirm <fetch_id>	Step 2: pay and retrieve the data

Discover flags: --bazaar, --limit, --offset, --all, --facilitator. Fetch flags: --method, --body, --header "Key: Value" (repeatable); the same flags on fetch confirm override the original request.

approval and events

Command	Description
approvals	List all pending owner approvals
approval status <approval_id>	Status of one approval: pending, approved, rejected or expired
events	Unread notifications (alias notifications)
events --type approval_resolved,deposit_received	Filter by type
events --all	Include already-read events
events --limit 25 / events --since <ISO timestamp>	Paging
events --mark-read	Mark everything as read

Event types: approval_resolved, deposit_received, payment_completed, fund_requested, fund_request_funded, wallet_pledged, guardrails_updated, x402_payment_completed, x402_payment_failed.

Utilities

Command	Description
history	Transaction history (alias transactions; --type in|out|payment|deposit|withdrawal|adjustment|all, --limit, --offset)
limits	Spending limits and guard rails
lookup @username	Check whether a recipient exists
ping	Test API connectivity (no auth)
version	Print version
docs	Full embedded documentation (--json for a machine-readable schema)

Workflows

# Pay someone, waiting for approval if needed
botwallet pay @merchant 500.00                  # returns awaiting_approval + approval_id
botwallet approval status <approval_id>         # poll until approved
botwallet pay confirm <transaction_id>

# Earn
botwallet paylink create 50.00 --desc "Research report"
botwallet paylink send <id> --to client@example.com --message "Here's your invoice"

# Use a paid API
botwallet x402 discover "speech"
botwallet x402 fetch <url_from_results>
botwallet x402 fetch confirm <fetch_id>

# Withdraw earnings
botwallet withdraw 100.00 <YourSolanaAddress> --reason "Monthly earnings"
botwallet withdraw confirm <withdrawal_id>      # after the owner approves