BotWallet CLI

Your AI has a brain. Give it a wallet.

The CLI that lets AI agents hold, spend, and earn real money (USDC on Solana).

Three commands. Your agent has a wallet with spending limits, human oversight, and FROST threshold signing.

npm install -g @botwallet/agent-cli
botwallet register --name "My Agent Wallet" --owner you@email.com
botwallet paylink create 25.00 --desc "Research report"  # Your agent just created an invoice

What agents can do with BotWallet:

Pay other agents and merchants — botwallet pay @recipient 10.00
Earn money via invoices and paylinks — botwallet paylink create
Access paid APIs through x402 — botwallet x402 fetch <url>
Request funds from their human owner — botwallet fund 50.00
Withdraw USDC to any Solana address — botwallet withdraw

Every transaction is FROST 2-of-2 threshold signed (agent + server). The full private key never exists anywhere. Human owners set guard rails — per-transaction limits, daily caps, merchant allowlists — and approve anything outside the rules.

Installation

# npm (recommended)
npm install -g @botwallet/agent-cli

# Linux/macOS
curl -fsSL https://botwallet.co/install.sh | bash

# Windows (PowerShell)
iwr https://botwallet.co/install.ps1 | iex

# From source
go install github.com/botwallet-co/agent-cli@latest

Quick Start

# Create a wallet (FROST threshold key generation, saves credentials locally)
botwallet register --name "Orion's Wallet" --owner "your@email.com"

# Create an invoice and send it
botwallet paylink create 25.00 --desc "Research report"
botwallet paylink send <request_id> --to client@example.com --message "Here's your invoice"

# Two-step payment flow
botwallet pay @merchant 10.00                # Step 1: Create intent
botwallet pay confirm <transaction_id>       # Step 2: FROST sign & submit

register is the recommended way to create a wallet. wallet create does the same thing.

Command Groups

Wallet (`botwallet wallet ...`)

Command	Description
`wallet create --name "..." --owner email`	Create wallet (FROST key generation)
`wallet info`	Wallet info and claim status
`wallet balance`	Balance and spending limits
`wallet list`	List locally stored wallets
`wallet use <name>`	Switch default wallet
`wallet deposit`	Solana USDC deposit address
`wallet owner <email>`	Update pledged owner (unclaimed only)
`wallet rename <name>`	Rename display name (username unchanged)
`wallet backup`	Back up Key 1 (two-step safety process)
`wallet export -o file.bwlt`	Export wallet to encrypted .bwlt file
`wallet import file.bwlt`	Import wallet from .bwlt file

Payments (`botwallet pay ...`) — Two-Step

Command	Description
`pay @recipient <amount>`	Step 1: Create payment intent
`pay confirm <tx_id>`	Step 2: FROST sign & submit
`pay preview @to <amount>`	Pre-check if payment will succeed
`pay list`	List payments
`pay cancel <tx_id>`	Cancel a pending payment
`pay --paylink <id>`	Pay a payment link directly

Flags: --note, --reference, --paylink, --idempotency-key

Payment Links — Earning (`botwallet paylink ...`)

Command	Description
`paylink create [amount] --desc "..."`	Create payment link to get paid
`paylink send <id> --to <email\|@bot>`	Send paylink to email or bot's inbox
`paylink get <id>`	Check if paid
`paylink get --reference <ref>`	Look up by your reference ID
`paylink list`	List paylinks
`paylink cancel <id>`	Cancel paylink

Create flags: --desc (required), --item (repeatable), --expires, --reference, --revealOwner Send flags: --to (required, email or @bot-username), --message (optional note)

--item format — repeat for each line item, total auto-calculated:

--item "API Calls, 5.00, 2" --item "Setup Fee, 10.00"

Fund Requests (`botwallet fund ...`)

Command	Description
`fund <amount> --reason "..."`	Request funds from owner
`fund ask <amount> --reason "..."`	Same as above (explicit subcommand)
`fund list`	List fund requests

Withdrawals (`botwallet withdraw ...`) — Two-Step

Command	Description
`withdraw <amount> <addr> --reason "..."`	Step 1: Create request (owner must approve)
`withdraw confirm <id>`	Step 2: FROST sign & submit
`withdraw get <id>`	Check withdrawal status

Approval Status (`botwallet approval ...`)

Command	Description
`approval status <approval_id>`	Check status of a specific approval (pending/approved/rejected/expired)

Use this to poll after any action returns awaiting_approval. When status is approved, run the corresponding confirm command.

Events & Notifications (`botwallet events`)

Command	Description
`events`	Check unread notifications
`events --type approval_resolved`	Filter by event type
`events --all`	Include already-read events
`events --limit 25`	Max events to return (default: 10)
`events --since <ISO-timestamp>`	Only events after this time
`events --mark-read`	Mark all 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

notifications is an alias for events.

x402 Paid APIs (`botwallet x402 ...`) — Two-Step

Command	Description
`x402 discover`	List verified Solana APIs (curated catalog)
`x402 discover "query"`	Search catalog by keyword
`x402 discover --bazaar`	Search the full x402 Bazaar (Coinbase CDP)
`x402 discover --bazaar --all`	Bazaar: include all networks (default: Solana only)
`x402 fetch <url>`	Step 1: Probe API, see price
`x402 fetch confirm <fetch_id>`	Step 2: Pay and retrieve data

Discover flags: --bazaar, --limit (bazaar), --offset (bazaar), --all (bazaar), --facilitator Fetch flags: --method, --body, --header (repeatable)

Utilities

Command	Description
`history`	Transaction history (`--type in/out/payment/deposit/withdrawal`)
`limits`	Spending limits and guard rails
`approvals`	List all pending owner approvals
`approval status <id>`	Check a specific approval's status
`lookup @username`	Check if recipient exists
`ping`	Test API connectivity
`version`	Print version information
`docs`	Full embedded documentation

transactions is an alias for history.

Authentication

Credentials auto-saved on wallet create. Priority order:

--api-key flag
BOTWALLET_API_KEY / BW_API_KEY env var
--wallet flag (selects from config)
Default wallet from ~/.botwallet/config.json

Output Modes

JSON (default) — for bots:

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

Human (--human flag) — formatted with colors:

$ botwallet wallet balance --human
── Balance ────────────────────
  Available: $42.50
── Daily Spending ─────────────
  Spent Today: $10.00 / $500.00

Examples

# Pay someone
botwallet pay preview @openai 25.00
botwallet pay @openai 25.00 --note "API credits"
botwallet pay confirm <transaction_id>

# Earn money (simple)
botwallet paylink create 50.00 --desc "Research report"

# Earn money (itemized invoice — total auto-calculated)
botwallet paylink create --desc "Dev services" --item "API Calls, 5.00, 2" --item "Setup Fee, 10.00"
botwallet paylink send <id> --to client@example.com --message "Here's your invoice"
botwallet paylink send <id> --to @data-bot --message "Payment for data analysis"

# Request funds
botwallet fund 50.00 --reason "API costs"

# Withdraw
botwallet withdraw 100.00 YourSolanaAddr... --reason "Monthly earnings"
# Owner approves, then:
botwallet withdraw confirm <withdrawal_id>

# Wait for human approval (using approval status polling)
botwallet pay @merchant 500.00                  # Returns awaiting_approval + approval_id
botwallet approval status <approval_id>         # Poll: pending → approved
botwallet pay confirm <transaction_id>          # After approved

# Discover and use paid APIs
botwallet x402 discover                             # List verified Solana APIs
botwallet x402 discover "speech"                    # Search by keyword
botwallet x402 fetch <url_from_results>             # Probe, see price
botwallet x402 fetch confirm <fetch_id>             # Pay and get data

# Multiple wallets
botwallet wallet list
botwallet wallet use my-other-wallet

How It Works

BotWallet uses FROST (Flexible Round-Optimized Schnorr Threshold) 2-of-2 signatures. During wallet creation, a Distributed Key Generation ceremony produces two key shares:

S1 (agent's share): stored locally at ~/.botwallet/seeds/<wallet>.seed
S2 (server's share): held by BotWallet, never sent to the agent

The full private key never exists anywhere. Every transaction requires both parties to produce partial signatures that combine into a valid Ed25519 signature. Neither the agent nor BotWallet can move funds alone.

All payments settle in USDC on Solana — a dollar-pegged stablecoin. 10.00 = $10.00.

Building from Source

make build          # Current platform
make build-all      # All platforms
make test           # Run tests

License

Apache 2.0 — See LICENSE for details.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BotWallet CLI

Installation

Quick Start

Command Groups

Wallet (`botwallet wallet ...`)

Payments (`botwallet pay ...`) — Two-Step

Payment Links — Earning (`botwallet paylink ...`)

Fund Requests (`botwallet fund ...`)

Withdrawals (`botwallet withdraw ...`) — Two-Step

Approval Status (`botwallet approval ...`)

Events & Notifications (`botwallet events`)

x402 Paid APIs (`botwallet x402 ...`) — Two-Step

Utilities

Authentication

Output Modes

Examples

How It Works

Building from Source

Links

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

BotWallet CLI

Installation

Quick Start

Command Groups

Wallet (botwallet wallet ...)

Payments (botwallet pay ...) — Two-Step

Payment Links — Earning (botwallet paylink ...)

Fund Requests (botwallet fund ...)

Withdrawals (botwallet withdraw ...) — Two-Step

Approval Status (botwallet approval ...)

Events & Notifications (botwallet events)

x402 Paid APIs (botwallet x402 ...) — Two-Step

Utilities

Authentication

Output Modes

Examples

How It Works

Building from Source

Links

License

Wallet (`botwallet wallet ...`)

Payments (`botwallet pay ...`) — Two-Step

Payment Links — Earning (`botwallet paylink ...`)

Fund Requests (`botwallet fund ...`)

Withdrawals (`botwallet withdraw ...`) — Two-Step

Approval Status (`botwallet approval ...`)

Events & Notifications (`botwallet events`)

x402 Paid APIs (`botwallet x402 ...`) — Two-Step