Setup
If you haven't connected yet, follow the setup guide: INLINECODE0
Once connected, you need these credentials for all API calls:
- -
BOB_API_KEY — your agent API key - INLINECODE2 — your agent ID
- INLINECODE3 — INLINECODE4
You can use the bob CLI (optional) or call the REST API directly. All commands output structured JSON with an ok field and next_actions that suggest follow-up commands.
Non-custodial v0 mode note: use BTC rails (lightning, onchain) and proof flows. Direct custodial ingress endpoints (wallet fund, wallet receive, receive confirm, operator fund) return 409 Conflict.
Core concepts
- - Agent: An AI agent with its own identity, wallets, and spending policies
- Wallet: Holds a balance in a specific currency (USD, BTC, USDC). Each agent can have multiple wallets.
- Policy: Spend limits, rate limits, and kill switches that constrain agent behavior
- Transaction: A record of money moving in or out of a wallet
- Payment: An outbound payment to an external bank account (ACH, wire) or internal account (book)
- Counterparty: A saved bank account destination for ACH/wire payouts
- Service Gate: A priced action that callers unlock by presenting a completed payment intent
Commands
Check your identity
CODEBLOCK0
Returns your role (agent or operator), identity details, and role-aware next_actions.
Agent details and wallet balances
CODEBLOCK1
Response includes a wallets array with each wallet's balance, currency, rail, and status.
Wallet management
CODEBLOCK2
INLINECODE17 now includes a bob_address field on each wallet when a default agent address is available.
In non-custodial v0 mode, bob wallet fund and bob wallet receive are intentionally disabled (409 Conflict).
| Flag | Description |
|---|
| INLINECODE22 | Required: lightning or onchain (auto-selects wallet by rail) |
| INLINECODE23 |
Specific wallet ID (overrides --rail lookup) |
|
--amount | Sats to request (required for lightning) |
|
--currency | BTC hint when multiple wallets share a rail |
|
--memo | Optional payment description |
|
--expiry-seconds | Invoice TTL for lightning (default 900) |
Returns data.instructions with the payable invoice, address, or account details.
One-shot send (auto-quote + execute)
CODEBLOCK3
Destination is auto-detected:
- -
<agent-uuid> → same-operator internal transfer - INLINECODE30 → routes as
bob_address (BTC by default) - INLINECODE32 → Lightning invoice (BTC)
- INLINECODE33 → on-chain BTC address
| Flag | Description |
|---|
| INLINECODE34 | Required. Smallest currency unit |
| INLINECODE35 |
Override auto-detected currency |
|
--priority | cheapest, fastest, or balanced (default: balanced) |
|
--description | Optional payment note |
|
--max-fee | Maximum acceptable fee |
|
--rail | Pin to a specific rail |
|
--destination-type | Override auto-detection: raw, bank
counterparty, unitaccount, bob_address |
Quotes then executes in one step. Returns intent_id, payment_id, and quote_summary. On failure, next_actions includes exact recovery commands.
CLI config introspection
CODEBLOCK4
Record a transaction (spend from your wallet)
CODEBLOCK5
| Flag | Description |
|---|
| INLINECODE45 | Required. Amount in smallest currency unit (cents for USD, sats for BTC) |
| INLINECODE46 |
USD, BTC, or USDC (default: BTC) |
|
--rail | auto, lightning, onchain, card, ach, wire, book (default: auto) |
|
--endpoint | Target endpoint or merchant identifier |
|
--wallet-id | Specific wallet to debit (auto-selected if omitted) |
Transfer money to another agent
CODEBLOCK6
| Flag | Description |
|---|
| INLINECODE50 | Required. Destination agent ID |
| INLINECODE51 |
Required. Amount in smallest currency unit |
|
--currency | USD, BTC, or USDC (default: BTC) |
|
--description | Optional note |
Create an outbound payment (legacy USD rails: ACH, wire, or book)
CODEBLOCK7
| Flag | Description |
|---|
| INLINECODE54 | Required. Amount in smallest currency unit |
| INLINECODE55 |
ach, wire, or book (default: auto) |
|
--counterparty-id | Required for ACH/wire. Saved bank account ID |
|
--to-account-id | Required for book. Destination account ID |
|
--description | Optional note |
Check payment status
CODEBLOCK8
If status is pending or clearing, next_actions will suggest re-checking.
Manage counterparties (saved bank accounts)
CODEBLOCK9
Quote and execute payments (intent workflow)
The intent workflow quotes routes before executing, giving you visibility into fees, ETAs, and available rails.
CODEBLOCK10
| Flag | Description |
|---|
| INLINECODE60 | Required. Amount in smallest currency unit |
| INLINECODE61 |
raw,
bank_counterparty,
unit_account, or
bob_address |
|
--destination-ref | Raw invoice/address, counterparty ID, Unit account ID, or
alias@bankofbots.ai |
|
--priority |
cheapest,
fastest, or
balanced (default: balanced) |
|
--execution-mode |
auto or
pinned (default: auto) |
|
--rail | Pin to a specific rail (lightning, onchain, ach, wire, book) |
|
--wallet-id | Pin to a specific wallet |
|
--max-fee | Maximum acceptable fee in cents |
Non-custodial proof submission
For raw BTC payment intents, submit proof of payment to verify settlement:
CODEBLOCK11
INLINECODE78 requires a valid challenge id/signature pair.
BTC proof ownership currently uses a Lightning node identity anchor for both lightning and onchain proof types.
| Proof Type | Description |
|---|
| INLINECODE79 | On-chain transaction ID |
| INLINECODE80 |
Lightning payment hash |
|
btc_lightning_preimage | Lightning preimage (SHA256 verified against payment hash, strongest proof) |
Query history
CODEBLOCK12
Marketplace discovery
CODEBLOCK13
View policies
CODEBLOCK14
Agent credit score and history
CODEBLOCK15
The credit system scores agents from 0-100 across four tiers: trusted (80+, 1.5x limits), growing (65-79, 1.2x limits), building (45-64, 1.0x limits), and watch (0-44, 0.6x limits). When credit tier enforcement is enabled, the tier multiplier adjusts spend and rate limits up or down from the base policy values.
Agent routing profile (autonomous rail preference)
CODEBLOCK16
Routing profile influences quote ranking for priority=balanced and is applied during intent quote + execute.
Agent webhooks and event stream
CODEBLOCK17
Agent-scoped webhooks/events include payment intent lifecycle events (quoted, executing, submitted, complete, failed) so agents can react asynchronously without polling every endpoint.
Operator funding
CODEBLOCK18
In non-custodial v0 mode these commands are intentionally disabled (409 Conflict). Fund from external/self-custody and submit/import BTC payment proofs for credit.
Operator credit controls
CODEBLOCK19
Operator payment addresses
CODEBLOCK20
Sub-agent management (create agents under your operator)
You have an operator identity (BOB_OPERATOR_API_KEY) that lets you create and manage sub-agents. Use --api-key to authenticate as your operator when running agent management commands.
CODEBLOCK21
| Flag | Description |
|---|
| INLINECODE91 | Required. Use $BOB_OPERATOR_API_KEY to authenticate as operator |
| INLINECODE93 |
Required. Human-readable name for the sub-agent |
|
--operator-id | Required. Your operator ID (
$BOB_OPERATOR_ID) |
|
--budget | Initial spend budget in smallest currency unit |
|
--currency | USD, BTC, or USDC (default: BTC) |
|
--currencies | Comma-separated list of currencies for wallet creation |
|
--auto-approve | Auto-approve the agent (default: true) |
The created sub-agent gets its own API key, wallets, and policies. You can fund it, transfer money to it, and set its policies — all using your operator key. The sub-agent's API key is returned in the response.
Operator BTC settlement and reconciliation
CODEBLOCK22
BTC rails are regtest/LND-backed in this environment. Synthetic BTC stub mode is disabled.
Service gates (pay-to-access)
CODEBLOCK23
| Flag | Description |
|---|
| INLINECODE100 | Required. Human-readable gate name |
| INLINECODE101 |
Required. Minimum payment amount (smallest currency unit) |
|
--currency | USD, BTC, or USDC (default: BTC) |
|
--intent-id | Required for unlock. Completed payment intent ID |
|
--status | For update: active or disabled |
Output format
Every command returns JSON with this structure:
CODEBLOCK24
Always check ok before using data. When ok is false, data.error contains the error message and next_actions provides recovery suggestions. Use next_actions to discover what to do next.
Error recovery
When ok is false, next_actions provides context-aware recovery suggestions. Key patterns:
- 1. Kill switch active: STOP all transactions immediately. Run
bob policy list <agent-id> to confirm. - Spend/rate limit exceeded: Check
bob spend list <agent-id> to see current usage vs limits. - Insufficient balance: Check
bob wallet list <agent-id> to see available funds. - 403 Forbidden: Check
bob auth me to verify your identity and role.
Important rules
- 1. Amounts are always in the smallest currency unit: cents for USD, satoshis for BTC.
- Policies set by your operator constrain your spending. If a transaction is denied,
data.error explains why. Do not retry denied transactions without changing the parameters. - Kill switch: If you receive a kill switch denial, stop all transaction attempts immediately. The operator has frozen your spending.
- Settlement times: Book payments are instant. ACH takes 1-3 business days. Wire settles same day.
- next_actions: Every response includes suggested follow-up commands. Use them to discover what to do next.
