New to crypto? Here’s the gist:
- USDC is a stablecoin designed to track the US dollar.
- Base is the blockchain network used for these payments.
- Wallet = a public address (your “username”) and a private key (your “password”). The private key signs payments.
- You’ll need USDC on Base in a wallet you control. Check the current payment options before funding it.
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
Use a reference x402 client library without the Browser Use SDK.
SDK quickstart
The Browser Use SDK has built-in x402 support. Pass a wallet private key, and you’re done.BROWSER_USE_X402_PRIVATE_KEY in your env, and skip the constructor arg entirely:
Python x402 is async-only: use
AsyncBrowserUse, not BrowserUse.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. Hithttps://x402.api.browser-use.com directly with any x402 client library:
X402_MAX_ATOMIC_USDC only after reviewing the payment options
returned by the x402 challenge. The value uses atomic USDC units.
Set BROWSER_USE_TASK_MAX_COST_USD separately to the maximum USD the task may
spend.
https://x402.api.browser-use.com exposes the same routes as https://api.browser-use.com. It supports every /api/v2/* and /api/v3/* route, 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
No wallet yet? Jump to Wallet setup below.
Pricing and credits
The SDK first authenticates requests with a single-use wallet signature. If the wallet project does not exist yet or has insufficient credits, the backend marks the response as requiring a top-up, and the SDK makes an x402 payment. Review the current payment options and rates on the pricing page. 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:- Agents that ran out of 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
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. From then on it behaves exactly like a normal account. The only difference is how you prove it’s yours: instead of an API key, you sign with your wallet. 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: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
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. If your Browser Use credit balance needs a top-up, the SDK’s x402 client handles the server’s payment challenge; otherwise it proceeds without moving wallet funds. The private-key convenience path does not add a payment cap. A cap applies only when you pass a pre-built x402 client with an explicit payment policy, as shown above. A bit more detail:- Your code makes a request (e.g. “run this task”).
- The SDK signs a request-bound wallet authentication message without moving wallet funds.
- If the server explicitly requests a top-up, the x402 client checks any caller-supplied payment policy, signs an allowed payment, and retries. With the private-key convenience path, no client-side cap is registered.
- Coinbase moves the authorized USDC on-chain, and the server updates your project’s credit balance. See the pricing page for current crediting terms.
- Status polls use wallet authentication without moving funds while the task runs.
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.Advanced: bring your own x402 client
For custom signers or multi-network setups that support Base/EVM, build the x402 client yourself, and pass it asx402 instead of x402_private_key:
X402_MAX_ATOMIC_USDC only after reviewing the current x402
payment options. The value uses atomic USDC units.
Troubleshooting
HTTP 402 keeps coming back, never settles
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/fetchjust 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'
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"
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
Insufficient credits despite paying
Check the balance again after the payment request completes. If a settled
payment is not reflected, contact support with your wallet address and
transaction details. See the pricing page
for current crediting and failed-request terms.
Wallet on the wrong network
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 — authenticate through a Browser Use project instead of a wallet