API Reference

Base URL: https://api.botwallet.co/v1

The CLI and MCP server are the supported clients. Actions that sign transactions (payment and withdrawal confirmation, x402 purchases, registration) involve a FROST signing round trip that those clients implement for you; use them unless you are porting the protocol to a new language. Everything else can be called directly.

Endpoints

Endpoint	Method	Auth	Purpose
`/bot`	POST	`Bearer bw_bot_...`	Everything an agent does
`/merchant`	POST	`Bearer bw_merchant_...`	Merchant reconciliation, see Merchant integration
`/public`	GET / POST	none	The pages the dashboard uses for paying, funding and claiming

Request format

Every call is a POST with a JSON body containing an action and its parameters at the top level.

POST /v1/bot
Authorization: Bearer bw_bot_...
Content-Type: application/json
X-Idempotency-Key: 6f1c0d2e-...        (optional, for pay and withdraw)

{ "action": "pay", "to": "merchant", "amount": 10.00, "note": "API usage" }

Bot API keys are created at registration, shown once and stored hashed. A key identifies the wallet; it cannot move funds on its own because signing also needs the agent’s key share.

Response format

{ "success": true, "data": { "...": "..." } }

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "how_to_fix": "Include header: Authorization: Bearer <api_key>"
  }
}

Common codes: VALIDATION_ERROR, UNAUTHORIZED, WALLET_NOT_CLAIMED, NOT_FOUND, INSUFFICIENT_FUNDS, INVALID_RECIPIENT, INVALID_STATUS, AWAITING_APPROVAL, ALREADY_COMPLETED, TRANSACTION_EXPIRED, INTERNAL_ERROR.

Bot actions

No authentication

Action	Description
`ping`	API status and version
`dkg_init`, `dkg_complete`	FROST distributed key generation, used by `register`
`register`	Create a wallet: `name`, `owner_email?`, `agent_model?`, `description?`, `metadata?`. Returns the API key, username, claim URL and claim code
`wallet_import_key`	Retrieve the decryption key for a `.bwlt` import

Wallet

Only info, update_owner and update_name work before the wallet is claimed; everything else returns WALLET_NOT_CLAIMED.

Action	Description
`info`	Wallet metadata, status and claim info
`update_owner`	Change the pledged owner email (`owner_email`). Unclaimed wallets only
`update_name`	Change the display name (`name`)
`balance`	On-chain balance, budget and remaining allowance
`reconcile`	Re-check the on-chain balance

Spending

Action	Description
`lookup`	`username`: does the recipient exist
`can_i_afford`	`to`, `amount`: balance and guard-rail pre-check
`pay`	`to` + `amount`, or `payment_request_id`; `note?`, `reference?`. Creates the intent and returns `transaction_id` and `status` (`pre_approved`, `awaiting_approval` or `rejected`)
`confirm_payment`	`transaction_id`: returns the message to sign
`frost_sign_init`, `frost_sign_complete`, `submit_signed_tx`	FROST signing rounds and submission to Solana
`list_payments`	`status?`, `limit?`, `offset?`
`cancel_payment`	`transaction_id`

Earning

Action	Description
`create_payment_request`	`description`, `amount?`, `items?`, `reference?`, `expires_in?`, `reveal_owner?`. Returns the paylink
`get_payment_request`	`request_id` or `reference`
`list_payment_requests`	`status?`, `limit?`, `offset?`
`cancel_payment_request`	`request_id`
`send_paylink_invitation`	`request_id`, `to_email` or `to_wallet`, `message?`

Funding and withdrawals

Action	Description
`get_deposit_address`	The wallet’s Solana USDC address
`request_funds`	`amount`, `reason`
`list_fund_requests`	`status?`, `limit?`, `offset?`
`withdraw`	`amount`, `to_address`, `reason`. Always needs owner approval
`confirm_withdrawal`	`transaction_id`, after approval
`get_withdrawal`	`withdrawal_id`

x402

Action	Description
`x402_prepare`	Probe a URL and create a payment intent for its 402 requirements
`x402_confirm`, `x402_sign_complete`, `x402_settle`	Pay, sign and settle the purchase

The curated API catalog is public: GET /public?action=x402_catalog.

History, guard rails and events

Action	Description
`transactions`	`type?`, `limit?`, `offset?`
`my_limits`	The owner’s guard rails as they apply to this wallet
`pending_approvals`	Everything waiting for the owner
`approval_status`	`approval_id`
`events`	`types?`, `limit?`, `unread_only?`, `since?`
`mark_read`	Mark events as read
`wallet_export`	Server-side half of a `.bwlt` export

Transaction statuses

Status	Confirmable	Meaning
`pre_approved`	yes	Guard rails passed; confirm to sign and submit
`awaiting_approval`	no	Waiting for the owner
`approved`	yes	Owner approved; confirm to sign and submit
`rejected`	no	Blocked by guard rails or the owner
`pending`	no	Being submitted to Solana
`completed`	—	Settled on-chain
`failed`	no	Solana submission failed
`expired`	no	Not confirmed within 48 hours

Idempotency

Send an X-Idempotency-Key header (the CLI’s --idempotency-key, the MCP idempotency_key parameter) with pay and withdraw. Retrying with the same key returns the original result instead of creating a second transaction.

Public endpoint

GET /public?action=<name> serves the pages that humans use. Useful read-only actions: pay&short_code=... (paylink details), pay_status&short_code=... (has it been paid), claim_info&wallet_id=..., x402_catalog and stats.