x402 (pay-per-request)

Pay for Browser Use Cloud with crypto (USDC on Base). ~30 seconds from wallet to first request.

x402 is a payment protocol created by Coinbase that lets APIs, or AI agents, charge for requests directly with crypto.

x402 lets your code, or an autonomous AI agent, pay Browser Use Cloud directly with cryptocurrency. No account signup, no credit card, and no API key is needed. Your wallet is your identity.

x402 currently supports the V2 and V3 APIs. It does not support API V4 yet. Use a standard Browser Use API key for V4 runs.

New to crypto? Here’s the gist:

• USDC is a stablecoin pegged 1:1 to the US dollar. 1 USDC = $1.
• Base is a low-fee blockchain network operated by Coinbase. Sending a payment costs fractions of a cent.
• Wallet = a public address (your “username”) and a private key (your “password”). The private key signs payments.
• You’ll need at least $1 of USDC on Base in a wallet you control. The Claude Code quickstart below walks you through everything from scratch.

Four ways to start, ranked by laziness:

Claude Code

One command. Claude does the wallet setup, funding walkthrough, and verification for you.

Agent wallets

AgentCash or Coinbase’s Agentic Wallet. Your coding agent gets a wallet directly and pays as it goes.

SDK

One line in your Python or TypeScript app. Bring your own wallet.

Raw HTTP

Skip the SDK. Sign EIP-3009, send X-PAYMENT header.

Claude Code quickstart

The fastest path. Install the x402 skill, and Claude walks you through everything:

npx skills add https://github.com/browser-use/browser-use --skill x402

Then in Claude Code:

> /x402

Claude walks you through creating or importing a wallet outside the chat, loading BROWSER_USE_X402_PRIVATE_KEY before Claude starts, installing the SDK, and running a verification task.

Already have a Browser Use Cloud account? The skill detects this and switches to top-up mode, adding credits to that existing account instead of creating a new, wallet-keyed one.

SDK quickstart

The Browser Use SDK has built-in x402 support. Pass a wallet private key, and you’re done.

Python

pip install "browser-use-sdk[x402]"

Python

import asyncio
from browser_use_sdk.v3 import AsyncBrowserUse

async def main():
    client = AsyncBrowserUse(x402_max_payment_usd=1.0)
    result = await client.run(
        "Go to example.com and tell me the heading.",
        max_cost_usd=0.75,
    )
    print(result.output)

asyncio.run(main())

Or set BROWSER_USE_X402_PRIVATE_KEY in your env, and skip the constructor arg entirely:

Python

client = AsyncBrowserUse()   # auto-detects from env

Python x402 is async-only: use AsyncBrowserUse, not BrowserUse.

x402_max_payment_usd / x402MaxPaymentUsd is a hard ceiling, not a spend trigger. The SDK rejects every payment option above it. A new paid request to the x402 host still receives a payment challenge even when the wallet project has unused Browser Use credit.

Raw HTTP quickstart

Use this if you’re in a language we don’t ship an SDK for (Go, Rust, Ruby, etc.), or if you want to use other x402 APIs from the same client library. Hit https://x402.api.browser-use.com directly with any x402 client library:

import asyncio
import os

from x402 import max_amount, x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from eth_account import Account

async def main():
    client = x402Client()
    register_exact_evm_client(
        client,
        EthAccountSigner(Account.from_key(os.environ["BROWSER_USE_X402_PRIVATE_KEY"])),
        policies=[max_amount(1_000_000)],
    )

    async with x402HttpxClient(client, timeout=120.0) as http:
        response = await http.post(
            "https://x402.api.browser-use.com/api/v3/sessions",
            json={"task": "..."},
        )
        print(response.status_code, response.text[:500])

asyncio.run(main())

https://x402.api.browser-use.com supports every /api/v2/* and /api/v3/* route. It does not expose /api/v4/*. Paid requests are gated by an x402 challenge instead of API key auth.

What you need

• EVM wallet (MetaMask, Rabby, Coinbase Wallet, etc.) with its private key available to your app
• USD Coin (USDC) on Base mainnet
• SDK top-up: $1.00 USDC by default, with a configurable hard per-payment cap

You do not need ETH for gas. We use EIP-3009, so you sign offchain, and the facilitator pays gas.

No wallet yet? Jump to Wallet setup below.

Pricing and credits

The x402 host challenges every new paid request. The SDK filters out payment options above x402_max_payment_usd / x402MaxPaymentUsd, signs one remaining option, and retries the request. The default SDK cap is $1.00 USDC per payment. That payment becomes prepaid credit on the wallet’s Browser Use project, then the request spends from the project’s balance.

Creating another session is another paid request, so it triggers another x402 payment even when the project still has credit. Polling, reading messages, stopping, deleting, and sending a follow-up to a session created by that wallet are free when the request includes the exact session ID. The balance helper is also free because it uses a single-use wallet signature.

Mid-task drain still terminates the task. Browser Use sessions run on a worker that doesn’t see x402, so once a long-running task starts and burns through its credits, it stops with INSUFFICIENT_CREDITS — it does not pause and wait for the next x402 payment.

See the pricing page for model and browser costs.

Topping up an existing account

If you already have a Browser Use API key (for example, one created via the dashboard or the agent signup REST flow), you can use x402 to add credits to that account instead of creating a new project based on your crypto wallet. Send your existing API key alongside the payment:

Python

import asyncio
import os

from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse(
    api_key=os.environ["BROWSER_USE_API_KEY"],
    x402_max_payment_usd=1.0,              # hard cap for each top-up
    base_url="https://x402.api.browser-use.com/api/v3",
)
async def main():
    result = await client.run("...", max_cost_usd=0.75)
    print(result.output)

asyncio.run(main())

When the backend sees both a payment and a valid API key, the credit goes to the key’s project rather than auto-creating a new wallet-keyed one. Useful for:

• Agents that ran out of free-tier credits and need to keep going
• Adding credits via crypto when you already have a regular Browser Use account
• Multi-wallet setups funding one shared account

Each paid request sent through the x402 host makes a new payment. After a top-up, use a normal BrowserUse client with the API key and the default https://api.browser-use.com host to spend the existing balance without making another x402 payment.

Checking your credit balance

When you sign up the normal way, Browser Use creates an account for you (we call it a “project”) that holds your credits and runs your tasks, and you log into it with an API key. When you pay with only a wallet (no API key), there’s no signup step — so the very first time you pay, Browser Use automatically creates one of these same accounts for you and ties it to your wallet. The free wallet signature currently reads that project’s balance. It does not replace API-key authentication for ordinary API requests.

This balance is your Browser Use credit balance — the prepaid USD you’ve added to that account through x402 payments, minus what your tasks have spent.

To check how much credit that account has left, use the method below:

Python

import asyncio
import os

from browser_use_sdk.v3 import get_wallet_balance

async def main():
    balance = await get_wallet_balance(os.environ["BROWSER_USE_X402_PRIVATE_KEY"])
    print(balance["total_credits_usd"])

asyncio.run(main())

The response contains:

Field	Description
wallet	The wallet address (lowercased)
project_id	The account (project) tied to your wallet that the credits live in
total_credits_usd	Your remaining Browser Use credit balance, in USD
additional_credits_usd	Of that total, the portion added via x402 top-ups (excludes any plan allowance)

This is for accounts created from a wallet (the default x402 mode). If you’re topping up an existing account, check that account’s balance the normal way with your API key via client.billing.account(). A wallet that has never paid yet has no account, so the call returns 404 until the first payment.

How the balance check works

The SDK signs a fixed, server-defined message (EIP-191, the same “Sign-In with Ethereum” mechanism) with your wallet’s private key. The signature proves you control the address without moving any funds. The server recovers the signer, matches it to the wallet’s project, and returns the balance.

How it works

Your code asks for something on the x402 host:

1. The server returns an x402 challenge for a paid V2 or V3 route.
2. The SDK removes every option above your configured payment cap.
3. The SDK signs one remaining payment and retries the request.
4. Coinbase moves the USDC on-chain, and Browser Use adds the same amount to your project’s credit balance.
5. The request runs against that project. Exact management requests for the resulting session ID are free.

Wallet setup

If you don’t have a wallet ready, here’s an easy way to set one up using MetaMask. It’s a popular crypto wallet. Any other EVM-compatible wallet works equally well: Rabby, Coinbase Wallet, Frame, Trust Wallet, Phantom, etc. Pick whichever you prefer.

1. Install MetaMask (or your wallet of choice)

   Get the MetaMask browser extension via the official site only. Create a new wallet, save the seed phrase somewhere offline, set a password.

2. Add the Base network

   By default, most wallets only show Ethereum. You need to add Base (the network we accept payments on) so your wallet can hold USDC there.

3. Get USDC into your wallet on Base

   Click “Buy” inside MetaMask. Pick USDC, set network to Base, and pay with credit card, bank, etc. The USDC lands directly in your wallet.

4. Export the private key

   In MetaMask: click the account menu → Account details → Private keys → enter your password → copy. That string (starts with 0x) is your BROWSER_USE_X402_PRIVATE_KEY. Other wallets have similar export options in their account settings.

Wallets hold real money, and anyone with the private key can drain it. Be careful with your keys.

Advanced: bring your own x402 client

For custom signers, multi-network setups, or non-EVM wallets, build the x402 client yourself, and pass it as x402 instead of x402_private_key:

Python

import os

from x402 import max_amount, x402Client
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from eth_account import Account
from browser_use_sdk.v3 import AsyncBrowserUse

key = os.environ["BROWSER_USE_X402_PRIVATE_KEY"]
x402 = x402Client()
register_exact_evm_client(
    x402,
    EthAccountSigner(Account.from_key(key)),
    policies=[max_amount(1_000_000)],
)
client = AsyncBrowserUse(x402=x402)

Troubleshooting

Why did a second task make another payment?

Every new paid request to the x402 host gets a fresh payment challenge. A wallet-keyed project’s existing credit does not currently bypass that challenge. Reuse the same session for free follow-ups, or use a normal API key client after topping up an existing account.

HTTP 402 keeps coming back, never settles

Two likely causes:

• Wallet has no USDC on Base. Check your balance. If empty, top it up.
• Your HTTP client isn’t x402-aware. Plain requests / fetch just sees a 402 and stops; it doesn’t know how to read the payment instructions and sign a payment. Use the SDK (which handles this automatically), or wrap your HTTP client with one of the x402 client libraries.

ImportError / Cannot find module '@x402/fetch'

You haven’t installed the optional x402 deps. Run pip install "browser-use-sdk[x402]" (Python) or npm install @x402/fetch @x402/evm viem (TypeScript).

HTTP 503 with "payment was not settled... you were not charged"

We verified your payment request but couldn’t credit your project, so we deliberately did not settle on-chain. No USDC was moved, so just retry. This is rare.

Insufficient credits despite paying

Wait a few seconds. Settlement and credit grant happen in the same request, but the response may be sent before the credit grant fully commits. If credits still show $0 after a few minutes, contact support with your wallet address. (Conversely, if a payment settles but the request itself then fails, we automatically reclaim the credits so you aren’t charged for nothing.)

Wallet on the wrong network

eip155:8453 is Base mainnet; eip155:84532 is Base Sepolia testnet. Browser Use Cloud only accepts mainnet. Withdrawing USDC to Sepolia from Coinbase is not the same as Base mainnet, even though both use the same wallet address.

Related

• x402 protocol spec
• Agent wallets quickstart — pay from AgentCash or a Coinbase Agentic Wallet
• Standard API key auth — alternative if you don’t want pay-per-use
• x402 Claude Code skill source