https://github.com/botwallet-co/agent-cli
Dedicated CLI for AI agents to earn, pay, and participate in the AI economy. Access x402 paid APIs, create invoices to receive funds, request funds from human owners, and send or receive payments in USDC — all with built-in owner approvals, spending guardrails, and FROST threshold signing on Solana.
https://github.com/botwallet-co/agent-cli
agents agentskills ai ai-agents cli developer-tools open-source payments solana usdc wallet x402
Last synced: 2 months ago
JSON representation
Dedicated CLI for AI agents to earn, pay, and participate in the AI economy. Access x402 paid APIs, create invoices to receive funds, request funds from human owners, and send or receive payments in USDC — all with built-in owner approvals, spending guardrails, and FROST threshold signing on Solana.
- Host: GitHub
- URL: https://github.com/botwallet-co/agent-cli
- Owner: botwallet-co
- License: apache-2.0
- Created: 2026-03-02T15:24:14.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-22T08:44:59.000Z (3 months ago)
- Last Synced: 2026-03-22T23:12:41.231Z (3 months ago)
- Topics: agents, agentskills, ai, ai-agents, cli, developer-tools, open-source, payments, solana, usdc, wallet, x402
- Language: Go
- Homepage: https://botwallet.co
- Size: 264 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# BotWallet CLI
**Your AI has a brain. Give it a wallet.**
[](https://www.npmjs.com/package/@botwallet/agent-cli)
[](LICENSE)
[](https://github.com/botwallet-co/agent-cli)
The CLI that lets AI agents hold, spend, and earn real money (USDC on Solana).
[Website](https://botwallet.co) · [Dashboard](https://app.botwallet.co) · [Docs](https://docs.botwallet.co) · [npm](https://www.npmjs.com/package/@botwallet/agent-cli)
---
Three commands. Your agent has a wallet with spending limits, human oversight, and FROST threshold signing.
```bash
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 `
- **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
```bash
# 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
```bash
# 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 --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 # 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 ` | Switch default wallet |
| `wallet deposit` | Solana USDC deposit address |
| `wallet owner ` | Update pledged owner (unclaimed only) |
| `wallet rename ` | 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 ` | **Step 1:** Create payment intent |
| `pay confirm ` | **Step 2:** FROST sign & submit |
| `pay preview @to ` | Pre-check if payment will succeed |
| `pay list` | List payments |
| `pay cancel ` | Cancel a pending payment |
| `pay --paylink ` | 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 --to ` | Send paylink to email or bot's inbox |
| `paylink get ` | Check if paid |
| `paylink get --reference ` | Look up by your reference ID |
| `paylink list` | List paylinks |
| `paylink cancel ` | 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 --reason "..."` | Request funds from owner |
| `fund ask --reason "..."` | Same as above (explicit subcommand) |
| `fund list` | List fund requests |
### Withdrawals (`botwallet withdraw ...`) — Two-Step
| Command | Description |
|---------|-------------|
| `withdraw --reason "..."` | **Step 1:** Create request (owner must approve) |
| `withdraw confirm ` | **Step 2:** FROST sign & submit |
| `withdraw get ` | Check withdrawal status |
### Approval Status (`botwallet approval ...`)
| Command | Description |
|---------|-------------|
| `approval status ` | 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 ` | 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 ` | **Step 1:** Probe API, see price |
| `x402 fetch confirm ` | **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 ` | 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:
1. `--api-key` flag
2. `BOTWALLET_API_KEY` / `BW_API_KEY` env var
3. `--wallet` flag (selects from config)
4. Default wallet from `~/.botwallet/config.json`
## Output Modes
**JSON (default)** — for bots:
```bash
$ botwallet wallet balance
{"balance": 42.50, "daily_limit": 500.00, "spent_today": 10.00, "remaining_today": 490.00}
```
**Human** (`--human` flag) — formatted with colors:
```bash
$ botwallet wallet balance --human
── Balance ────────────────────
Available: $42.50
── Daily Spending ─────────────
Spent Today: $10.00 / $500.00
```
## Examples
```bash
# Pay someone
botwallet pay preview @openai 25.00
botwallet pay @openai 25.00 --note "API credits"
botwallet pay confirm
# 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 --to client@example.com --message "Here's your invoice"
botwallet paylink send --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
# Wait for human approval (using approval status polling)
botwallet pay @merchant 500.00 # Returns awaiting_approval + approval_id
botwallet approval status # Poll: pending → approved
botwallet pay confirm # After approved
# Discover and use paid APIs
botwallet x402 discover # List verified Solana APIs
botwallet x402 discover "speech" # Search by keyword
botwallet x402 fetch # Probe, see price
botwallet x402 fetch confirm # 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/.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
```bash
make build # Current platform
make build-all # All platforms
make test # Run tests
```
## Links
- **Website**: [botwallet.co](https://botwallet.co)
- **Human Dashboard**: [app.botwallet.co](https://app.botwallet.co)
- **Documentation**: [docs.botwallet.co](https://docs.botwallet.co)
- **npm**: [@botwallet/agent-cli](https://www.npmjs.com/package/@botwallet/agent-cli)
## License
Apache 2.0 — See [LICENSE](LICENSE) for details.