Botwallet

Prevent duplicate payments and accidental financial operations in code

When retrying any `botwallet_pay` or `botwallet_x402_pay_and_fetch` call that failed or timed out, always pass an `idempotency_key`. Generate a deterministic key from the operation context (e.g., recipient + amount + purpose). Without this, a retry can send money twice.

When writing code that involves Botwallet operations, never hardcode wallet addresses or payment amounts in source files. Use environment variables or configuration files. Hardcoded values risk accidental payments when code runs in CI, tests, or production.

MCP server: botwallet

{
  "command": "npx",
  "args": [
    "-y",
    "@botwallet/mcp"
  ]
}

>-

# x402 Paid APIs

The x402 protocol lets APIs charge per-request using HTTP 402 responses. When you hit a paid endpoint, it returns pricing info instead of data. You pay with your Botwallet and get the response.

Three tools handle the full flow:

---

## How x402 Works

1. You make a normal HTTP request to an API
2. If it's free, you get the response immediately
3. If it's paid, the server returns HTTP 402 with a price and payment address
4. You sign a payment, attach it as a header, and retry the request
5. The server verifies the payment and returns the data

The Botwallet MCP tools handle steps 3-5 for you. You just discover, probe, and pay.

---

## Workflow

### 1. Discover APIs

Call `botwallet_x402_discover` to search for paid APIs. You can search a curated catalog or the Coinbase Bazaar directory.

Parameters:
- `query` — what you're looking for (e.g., "weather", "translation", "image generation")
- `source` — `"catalog"` (curated, default) or `"bazaar"` (Coinbase directory)
- `limit` / `offset` — pagination

### 2. Probe Before Paying

Call `botwallet_x402_fetch` to check a URL without spending anything. This is window shopping.

- If the URL is free (HTTP 200), you get the content back immediately. Done.
- If the URL is paid (HTTP 402), you get back a `fetch_id`, `price_usdc`, `fee_usdc`, `total_usdc`, and payment details.

Parameters:
- `url` — the API endpoint (must be HTTPS)
- `method` — GET, POST, PUT, or DELETE (default: GET)
- `headers` — additional HTTP headers
- `body` — request body for POST/PUT

Probe multiple APIs to compare prices before committing.

### 3. Pay and Fetch

Call `botwallet_x402_pay_and_fetch` with the `fetch_id` from the probe. This performs FROST threshold signing, builds the payment header, calls the API, and settles the transaction.

Parameters:
- `fetch_id` — from the previous `botwallet_x402_fetch` call
- `headers` — additional headers for the API request
- `body` — request body for POST/PUT

Returns the API response content and payment details (`amount_usdc`, `fee_usdc`, `total_usdc`, `transaction_id`).

---

## Example Flow

User asks: "Find me a cheap speech-to-text API and transcribe this audio."

1. `botwallet_x402_discover` with `query: "speech-to-text"` — browse available options
2. `botwallet_x402_fetch` on the cheapest option — check the exact price
3. If the price is acceptable, `botwallet_x402_pay_and_fetch` with the `fetch_id` — pay and get the transcription

If the price exceeds the wallet's per-transaction limit, the payment will go through the normal approval flow. The `check-pending` rule handles polling for approval resolution.

---

## Tips

- Always probe first. Never pay without checking the price.
- Compare prices across providers when multiple options exist for the same task.
- Free endpoints (HTTP 200 from probe) cost nothing — `botwallet_x402_fetch` returns the data directly.
- x402 payments go through the same guard rails as regular payments. Per-transaction limits, daily caps, and approval gates all apply.
- If a payment needs approval, the flow pauses the same way as `botwallet_pay`. The `check-pending` rule will catch the resolution.

---

## Tool Reference

| Use Case | Tool |
|----------|------|
| Search for paid APIs | `botwallet_x402_discover` |
| Probe URL for pricing (free check) | `botwallet_x402_fetch` |
| Pay and get API response | `botwallet_x402_pay_and_fetch` |

>-

# Botwallet

You have access to the Botwallet MCP tools that let you hold, spend, and earn real USDC on Solana.

This skill covers when and why to use each tool, the workflows that connect them, and the best practices that keep transactions safe.

---

## Core Concepts

### Human Owner

Every wallet is tied to a human owner. They claim the wallet, fund it, set spending limits, and approve high-value transactions through the Botwallet Dashboard (`app.botwallet.co`). You operate autonomously within the boundaries they set. When something exceeds those boundaries, it goes to them for approval.

### FROST 2-of-2 Threshold Signing

Your wallet uses FROST threshold signatures. Two key shares are created during registration:

- **S1** (yours): stored locally at `~/.botwallet/seeds/<wallet>.seed`
- **S2** (server): held by Botwallet, never sent to you

The full private key never exists anywhere. Every transaction requires both parties to co-sign. This is why some operations have a two-step pattern — the second step is the FROST signing ceremony.

### Two-Step Pattern

Operations that move money follow: **create intent → confirm**.

1. Call the primary tool (e.g., `botwallet_pay`). The server checks guard rails.
2. If pre-approved, signing happens automatically and you get the result.
3. If it needs approval, you get `needs_approval: true`. Wait for the human, then call the confirm tool (e.g., `botwallet_confirm_payment`).

### Guard Rails

The human owner sets:

- **Per-transaction limit** — max amount per single payment
- **Daily limit** — max total spending per day
- **Merchant allowlist** — restrict payments to approved recipients only

Check current limits with `botwallet_my_limits`.

### All Money Is USDC

Amounts are always in USDC on Solana. `10.00` means $10.00.

---

## Getting Started

### 1. Register a Wallet

Call `botwallet_register` with a descriptive name and the human's email if known (`owner_email`).

Pick a name yourself — something recognizable like "Cursor Dev Wallet" or "Research Budget." The name is visible to the human when they claim the wallet. Optionally pass `description` and `metadata` (e.g., `{"platform": "cursor", "project": "my-app"}`) to help the human identify wallets later.

### 2. Share the Claim URL

Registration returns a `claim_url` and `claim_code`. Share both with the human. Explain what Botwallet lets you do together — invoices, payments, paid APIs, fund requests.

### 3. Welcome Invoice

After the human claims the wallet, create a sample invoice to demo the paylink feature:

1. `botwallet_create_paylink` — create an itemized invoice with fun line items
2. `botwallet_send_paylink` — send it to the human's email

This shows real capabilities and gets them engaged.

---

## Workflow Patterns

### Paying Someone

1. `botwallet_lookup` — verify the recipient exists
2. `botwallet_can_i_afford` — pre-flight check (balance, limits, guard rails)
3. `botwallet_pay` — create the payment intent (pass `to` + `amount`, or `payment_request_id` to pay a paylink)
4. If auto-approved: done, funds sent
5. If `needs_approval: true`: share the `approval_url` with the human, save the `transaction_id`, then call `botwallet_confirm_payment` after they approve

### Earning Money (Paylinks)

1. `botwallet_create_paylink` — create a payment link. Pass `amount` for a flat request, or `items` for an itemized invoice (items use cents: `unit_price_cents: 500` = $5.00)
2. `botwallet_send_paylink` — deliver it via email (`to_email`) or bot inbox (`to_wallet`)
3. `botwallet_get_paylink` — check if it's been paid

Paylinks expire (default 24h, configurable with `expires_in`). Monitor them.

### Requesting Funds

Call `botwallet_request_funds` with a clear reason. The human sees this in their dashboard and decides whether to approve.

### Withdrawals

1. `botwallet_withdraw` — create the withdrawal (always requires owner approval)
2. Wait for approval via `botwallet_events`
3. `botwallet_confirm_withdrawal` — complete it after approval

### Handling Approvals

When any operation returns `needs_approval: true`:

1. Share the `approval_url` with the human
2. Save the `transaction_id` (or `withdrawal_id`) and `approval_id` to persistent memory
3. Check `botwallet_events` or `botwallet_pending_approvals` for the resolution
4. If approved → call the corresponding confirm tool (`botwallet_confirm_payment` or `botwallet_confirm_withdrawal`)
5. If rejected → note the reason from the event and move on

Note: the `check-pending` rule handles polling for you automatically at session start and during long tasks. You don't need to manually schedule checks.

---

## Best Practices

- **Always pre-flight large payments.** Call `botwallet_can_i_afford` before `botwallet_pay` to avoid failed attempts.
- **Save IDs to persistent memory.** Transaction IDs, approval IDs, and paylink IDs are needed later for confirms and status checks.
- **Use idempotency keys when retrying.** Pass `idempotency_key` to `botwallet_pay` to prevent duplicate payments on retry.
- **Provide clear reasons.** Fund requests and withdrawals go to the human — a good reason gets faster approval.
- **Check limits proactively.** Use `botwallet_my_limits` before operations near your spending cap.
- **Use paylinks for earning, direct pay for spending.** Paylinks create a payment URL; direct pay sends USDC immediately.

---

## Tool Reference

### Wallet

| Use Case | Tool |
|----------|------|
| Check connectivity | `botwallet_ping` |
| Create a new wallet | `botwallet_register` |
| Wallet metadata and status | `botwallet_info` |
| On-chain balance and budget | `botwallet_balance` |
| Set owner email | `botwallet_update_owner` |
| Change display name | `botwallet_rename` |
| List local wallets | `botwallet_wallet_list` |
| Switch active wallet | `botwallet_wallet_use` |

### Spending

| Use Case | Tool |
|----------|------|
| Verify recipient exists | `botwallet_lookup` |
| Pre-flight check | `botwallet_can_i_afford` |
| Send payment | `botwallet_pay` |
| Complete approved payment | `botwallet_confirm_payment` |
| List outgoing payments | `botwallet_list_payments` |
| Cancel pending payment | `botwallet_cancel_payment` |

### Earning

| Use Case | Tool |
|----------|------|
| Create invoice / payment link | `botwallet_create_paylink` |
| Send paylink to someone | `botwallet_send_paylink` |
| Check paylink status | `botwallet_get_paylink` |
| List your paylinks | `botwallet_list_paylinks` |
| Cancel pending paylink | `botwallet_cancel_paylink` |

### Funding & Withdrawals

| Use Case | Tool |
|----------|------|
| Get deposit address | `botwallet_get_deposit_address` |
| Request funds from owner | `botwallet_request_funds` |
| List fund requests | `botwallet_list_fund_requests` |
| Withdraw USDC | `botwallet_withdraw` |
| Complete approved withdrawal | `botwallet_confirm_withdrawal` |
| Check withdrawal status | `botwallet_get_withdrawal` |

### History & Guard Rails

| Use Case | Tool |
|----------|------|
| Full transaction ledger | `botwallet_transactions` |
| View spending limits | `botwallet_my_limits` |
| Pending approvals | `botwallet_pending_approvals` |
| Check specific approval | `botwallet_approval_status` |
| Wallet notifications | `botwallet_events` |

### Transfer

| Use Case | Tool |
|----------|------|
| Export wallet to file | `botwallet_wallet_export` |
| Import wallet from file | `botwallet_wallet_import` |
| Reveal backup mnemonic | `botwallet_wallet_backup` |

Remind the human to back up both wallet key shares before they have funds at risk

After creating a wallet, or when you notice the wallet has a non-zero balance or active paylinks, nudge the human once to back up their key shares. Both shares are needed to recover the wallet — neither alone is enough.

Two shares to back up:

1. **S1 (agent's share):** Call `botwallet_wallet_backup` to reveal the 12-word mnemonic. Tell the human to write it down and store it somewhere safe — a password manager, a physical note, or an encrypted file. This share lives locally on the machine at `~/.botwallet/seeds/`.

2. **S2 (server's share):** The human exports this from the Botwallet Dashboard at app.botwallet.co. Go to the wallet, open backup settings, and export the second 12-word mnemonic. You cannot do this step for them — it requires their login.

Explain it simply: "Your wallet has two key halves. You just saved one. The other is in your dashboard — export it too. If you ever lose this machine, both halves together can recover everything. One alone can't."

Mention this once. If the human acknowledges or dismisses it, don't bring it up again.

Poll for pending approvals, funded requests, and other wallet events

At the start of each session, call `botwallet_events` (unread events only) and `botwallet_pending_approvals` to catch anything that happened while you were idle.

Act on what you find:

- `approval_resolved` — if the human approved, call the corresponding confirm tool (`botwallet_confirm_payment` or `botwallet_confirm_withdrawal`). If rejected, note the reason and move on.
- `fund_request_funded` — the human funded your request. Check `botwallet_balance` and resume the task that was blocked on funding.
- `deposit_received`, `payment_completed`, `paylink_received`, `guardrails_updated` — informational. No action needed, but worth noting if relevant to the current task.

After processing all actionable events, call `botwallet_events` with `mark_read: true` to clear the queue. Only mark read after you've acted on everything — once marked, events won't reappear.

During long sessions, re-check `botwallet_pending_approvals` periodically if you're waiting on a human decision.