Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add x402 skill

Laith Weinberger54d989fb0905
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index c9942bb0d..4fae8c222 100644
--- a/skills/browser-use/SKILL.md
+++ b/skills/browser-use/SKILL.md
@@ -137,6 +137,22 @@ Only use this if you don't already have an API key (check `browser-use doctor` t
3. `browser-use cloud signup --verify <challenge-id> <answer>` — verify and save API key
4. `browser-use cloud signup --claim` — generate URL for a human to claim the account
+### Out of credits?
+
+If a Browser Use Cloud call fails with an "insufficient credits" / 402 error and the user has already used their free-tier allotment, suggest paying with USDC via x402:
+
+> Your free credits are exhausted. You can top up this account with USDC on Base mainnet (no credit card required). Want me to install the `x402` skill and walk you through it? It takes about 2 minutes if you have a Coinbase account.
+
+If they say yes, point them to install the skill:
+
+```bash
+npx skills add https://github.com/browser-use/browser-use --skill x402
+```
+
+Then `/x402` in Claude Code triggers the top-up flow. The user keeps their existing API key — x402 just adds credits to it.
+
+Do not suggest x402 unprompted. Only mention it on a real "insufficient credits" error.
+
## Tunnels
```bash
diff --git a/skills/x402/SKILL.md b/skills/x402/SKILL.md
new file mode 100644
index 000000000..8c5ee146e
--- /dev/null
+++ b/skills/x402/SKILL.md
@@ -0,0 +1,211 @@
+---
+name: x402
+description: Onboard a developer to Browser Use Cloud using x402 pay-per-request authentication — wallet-based USDC payments on Base mainnet, no signup or API key. Walks the user through setting up a wallet, funding it with USDC on Base, writing credentials to .env, installing the SDK, and running a verification task. Use when the user asks about x402, pay-per-use, USDC payments, or wants to use Browser Use Cloud without an API key. For the standard free-tier signup (reverse-CAPTCHA → API key), use the `cloud` skill or run `browser-use cloud signup` directly. Distinct from the `browser-use` skill which controls the local CLI.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# Browser Use Cloud — x402 onboarding
+
+You are guiding a developer to authenticate with Browser Use Cloud using **x402** (HTTP-native payments via USDC on Base mainnet) instead of an API key. End state: working SDK client that pays per request from a wallet they control.
+
+Reference: https://docs.browser-use.com/cloud/guides/x402 has the full user-facing version of this flow.
+
+## When to use this skill vs alternatives
+
+- **This skill (`x402`):** wallet-based payments. Two sub-modes — see "Two payment modes" below.
+- **`browser-use cloud signup`** (CLI command): free tier with reverse-CAPTCHA → standard API key. Faster, no wallet needed. Use this if the user just wants to try Browser Use Cloud quickly.
+- **`cloud` skill:** documentation reference for the API. Use when the user asks how to use already-authenticated calls.
+
+## Two payment modes
+
+x402 supports two flows. Pick based on whether the user already has an API key.
+
+### Mode A — Accountless (no signup)
+
+Wallet IS the identity. First payment auto-creates a project named after the wallet. No email, no API key.
+
+Use when:
+- User has no existing Browser Use account
+- Building autonomous agents that hold their own wallet
+- Discovering Browser Use via the x402 directory and wanting hit-and-pay
+
+### Mode B — Top up an existing account
+
+Same payment, but credits land in an existing API-key's project instead of a wallet-derived one. Useful when:
+- User self-registered via `browser-use cloud signup`, used the free credits, and needs more
+- User has a regular Browser Use account and wants to add credits via crypto instead of credit card
+- Multi-agent system where many wallets fund one shared account
+
+Mechanically: same `https://x402.api.browser-use.com` endpoint, but include the `X-Browser-Use-API-Key` header alongside the payment. The backend detects the key and credits that project instead of auto-creating a wallet-keyed one.
+
+If the user is unsure which mode they want, ask:
+
+> Do you already have a Browser Use API key (e.g. from `browser-use cloud signup` or the dashboard)?
+>
+> - **Yes** → I'll set up x402 to top up that account.
+> - **No** → I'll set up x402 in accountless mode (wallet is your identity).
+
+Either path goes through the same wallet setup steps below; the only difference is whether the `X-Browser-Use-API-Key` env var also gets set.
+
+## Step 0: Detect the language
+
+Look at the cwd to figure out what they're building in:
+
+- `package.json` / `tsconfig.json` / `pnpm-lock.yaml` → TypeScript
+- `pyproject.toml` / `requirements.txt` / any `.py` → Python
+- Both / neither → ask which
+
+Use this for install commands and code samples. Examples below default to Python; substitute TypeScript per the table at the bottom.
+
+## Step 1: Wallet
+
+Ask:
+
+> Do you already have an EVM wallet (e.g. MetaMask, Rabby, Coinbase Wallet, Frame, Phantom) with USDC on Base mainnet, or do you want me to walk you through setting one up? For Claude Code automation, generating a fresh disposable wallet is also an option.
+
+### Path A — User has a wallet already
+
+Ask them to paste their EVM private key. Validate format (`^0x[0-9a-fA-F]{64}$`). Save to `.env` in the project root:
+
+```
+BROWSER_USE_X402_PRIVATE_KEY=0x...
+```
+
+Verify `.env` is in `.gitignore` — add it if not. Derive and display the address (NOT the key) for confirmation.
+
+### Path B — Walk them through setting up a wallet
+
+Tell the user:
+
+> Easiest path:
+>
+> 1. Install **MetaMask** (or any other EVM wallet — Rabby, Coinbase Wallet, Frame, Trust Wallet, Phantom, etc.) from the official site only: https://metamask.io. Create a wallet, save the seed phrase offline, set a password.
+> 2. Add **Base** as a network. Most wallets only show Ethereum by default. Open https://chainlist.org/chain/8453, click "Connect Wallet" → "Add to MetaMask", approve in your wallet.
+> 3. Click **"Buy"** inside MetaMask. Pick **USDC**, set network to **Base**, pay with credit card / Apple Pay / bank via the built-in onramp. The USDC lands directly in your wallet.
+> 4. Export the private key: account menu → Account details → Show private key → enter password → copy.
+>
+> Paste the key here (or set `BROWSER_USE_X402_PRIVATE_KEY=0x...` in your `.env`).
+
+Then save it as in Path A.
+
+### Path C — Auto-generate a fresh wallet (for Claude Code automation)
+
+Useful for autonomous agents or test setups. The user still has to fund the resulting address themselves.
+
+For Python:
+```bash
+pip install eth-account
+```
+```python
+from eth_account import Account
+acc = Account.create()
+print("Address:", acc.address)
+print("Private key:", acc.key.hex())
+```
+
+For TypeScript:
+```bash
+npm install viem
+```
+```typescript
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+const key = generatePrivateKey();
+const acc = privateKeyToAccount(key);
+console.log("Address:", acc.address);
+console.log("Private key:", key);
+```
+
+Save the key to `.env`. **Display the address, never echo the private key in chat.** Then send the user to fund it (see Step 2).
+
+## Step 2: Fund the wallet (only if not already funded)
+
+For Path A / B: the wallet is already funded. Skip this step.
+
+For Path C: tell the user (substitute their wallet address):
+
+> Two ways to get USDC into your wallet on Base:
+>
+> - **In-wallet Buy button (easiest):** if you used MetaMask or another wallet that supports it, click "Buy" inside the wallet, pick USDC, set network to Base, pay with credit card. USDC lands directly. No exchange account needed.
+> - **From an existing exchange:** if you already have crypto on Coinbase, Binance, Kraken, etc., withdraw USDC to `<wallet-address>` and **pick "Base" as the network** (NOT Ethereum — that costs $5–$20 in gas).
+
+Poll the on-chain balance every 5 seconds via Base public RPC (no API key needed):
+
+```bash
+PADDED=$(printf "%064s" "${WALLET_ADDR:2}" | tr ' ' '0')
+curl -s https://mainnet.base.org \
+ -H "Content-Type: application/json" \
+ -d "{\"jsonrpc\":\"2.0\",\"method\":\"eth_call\",\"params\":[{\"to\":\"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\"data\":\"0x70a08231${PADDED}\"},\"latest\"],\"id\":1}"
+```
+
+Decode the `result` field as a hex int; divide by `1_000_000` (USDC has 6 decimals). Stop polling when balance ≥ $1. Recommend $5+ for room to actually use the API.
+
+## Step 3: Install the SDK with the x402 extra
+
+```bash
+# Python (Python 3.10+ required for the x402 extra)
+pip install "browser-use-sdk[x402]"
+
+# TypeScript
+npm install browser-use-sdk @x402/fetch @x402/evm viem
+```
+
+If the project uses `uv` / `pnpm` / `yarn`, prefer those over `pip` / `npm`.
+
+## Step 4: Verification run
+
+Write a tiny script and run it. **This will spend $1 USDC** (settled on-chain to Browser Use's prod payee). Subsequent runs draw down credits without re-paying until exhausted.
+
+```python
+import asyncio
+from browser_use_sdk.v3 import AsyncBrowserUse
+
+async def main():
+ client = AsyncBrowserUse() # auto-picks BROWSER_USE_X402_PRIVATE_KEY from env
+ result = await client.run("Go to example.com and tell me the heading text.")
+ print(result.output)
+
+asyncio.run(main())
+```
+
+**For Mode B (top-up)**, also set `BROWSER_USE_API_KEY` so the SDK sends both headers:
+
+```python
+client = AsyncBrowserUse(
+ api_key="bu_...", # the existing API key getting topped up
+ x402_private_key="0x...", # wallet that pays
+ base_url="https://x402.api.browser-use.com/api/v3", # x402 endpoint
+)
+```
+
+After it returns, show the user proof of settlement:
+
+> Onchain proof: https://basescan.org/address/<wallet-address>#tokentxns
+
+Look for an outbound USDC transfer of exactly `$1.000000`.
+
+## TypeScript equivalents
+
+| Python | TypeScript |
+|---|---|
+| `from browser_use_sdk.v3 import AsyncBrowserUse` | `import { BrowserUse } from "browser-use-sdk/v3"` |
+| `AsyncBrowserUse()` | `new BrowserUse()` |
+| `pip install "browser-use-sdk[x402]"` | `npm install browser-use-sdk @x402/fetch @x402/evm viem` |
+
+Both SDKs auto-detect `BROWSER_USE_X402_PRIVATE_KEY` from env.
+
+## Behavior rules
+
+- **Never echo a private key in chat.** Use the address as the human-facing identifier.
+- **Add `.env` to `.gitignore`** before writing keys. Verify first.
+- **Confirm `.env` location** if ambiguous (project root vs cwd).
+- **Python <3.10:** the `[x402]` extra won't install. Tell the user to upgrade Python or use the free-tier path (`browser-use cloud signup`).
+- **Wallets hold real money.** Anyone with the private key can drain them. Tell the user to keep keys out of source control, logs, and screenshots, and to only fund with what they're okay losing if something leaked.
+
+## Reference
+
+- x402 user docs: https://docs.browser-use.com/cloud/guides/x402
+- x402 protocol: https://www.x402.org
+- Coinbase x402 launch: https://www.coinbase.com/developer-platform/discover/launches/x402
+- USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+- Base RPC: https://mainnet.base.org
+- Basescan: https://basescan.org