x402 quickstart

Create pay-per-use browser sessions with crypto payments

Quick start

1. Install dependencies

   npm install viem x402
   
2. Create a session

   Run the following with your wallet’s private key (requires USDC on Base):

   PRIVATE_KEY=0x... npx tsx scripts/test-with-wallet.ts
   

API reference

Create session

Creates a new browser session with prepaid time.

POST /browser/session/create

Request Body:

{
  "estimatedMinutes": 30
}

First Response (402)

When you first make a request, you’ll receive a 402 Payment Required response with payment details:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "500000",
      "payTo": "0x...",
      "resource": "https://x402.browserbase.com/browser/session/create"
    }
  ]
}

With Payment (200)

After sending the payment header, you’ll receive your session details:

{
  "sessionId": "abc-123",
  "connectUrl": "wss://connect.browserbase.com/...",
  "paidMinutes": 30,
  "expiresAt": "2025-12-03T18:00:00Z",
  "pricing": {
    "ratePerHour": 0.12,
    "amountPaid": 0.06,
    "currency": "USDC"
  }
}

Get session status

Check the status of an active session.

GET /browser/session/:id/status

Response:

{
  "sessionId": "abc-123",
  "status": "active",
  "usage": {
    "minutesPaid": 30,
    "minutesUsed": 5,
    "minutesRemaining": 25
  },
  "expiresAt": "2025-12-03T18:00:00Z"
}

Extend session

Add more time to an active session.

POST /browser/session/:id/extend

Request Body:

{
  "additionalMinutes": 15
}

Extending a session requires another x402 payment for the additional time.

Terminate session

End a session early. Unused time may be eligible for refund.

POST /browser/session/:id/terminate

Response:

{
  "sessionId": "abc-123",
  "finalStatus": "terminated",
  "usage": {
    "minutesPaid": 30,
    "minutesUsed": 10
  },
  "refund": {
    "eligible": true,
    "amount": 0.33,
    "currency": "USDC"
  }
}

Making x402 payments

x402 Package (Recommended)

Use the x402 package for full control over the payment flow:

Node.js

import { privateKeyToAccount } from "viem/accounts";
import { getAddress } from "viem";
import { exact } from "x402/schemes";

const account = privateKeyToAccount("0x...");

// 1. Get payment requirements
const res = await fetch("https://x402.browserbase.com/browser/session/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ estimatedMinutes: 30 }),
});

const { accepts } = await res.json();
const req = accepts[0];

// 2. Create payment header
const paymentHeader = await exact.evm.createPaymentHeader(account, 1, {
  scheme: req.scheme,
  network: req.network,
  maxAmountRequired: req.maxAmountRequired,
  resource: req.resource,
  description: req.description,
  mimeType: req.mimeType,
  payTo: getAddress(req.payTo),
  maxTimeoutSeconds: req.maxTimeoutSeconds,
  asset: getAddress(req.asset),
  extra: req.extra,
});

// 3. Send with payment
const session = await fetch(
  "https://x402.browserbase.com/browser/session/create",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-PAYMENT": paymentHeader,
    },
    body: JSON.stringify({ estimatedMinutes: 30 }),
  },
).then((r) => r.json());

console.log(session.connectUrl); // wss://connect.browserbase.com/...

x402-fetch (Automatic)

Use x402-fetch for automatic payment handling:

Node.js

import { wrapFetch } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");
const x402Fetch = wrapFetch(fetch, account);

// Payments are handled automatically
const session = await x402Fetch(
  "https://x402.browserbase.com/browser/session/create",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ estimatedMinutes: 30 }),
  },
).then((r) => r.json());

console.log(session.connectUrl); // wss://connect.browserbase.com/...

The x402-fetch wrapper automatically handles the 402 response, signs the payment, and retries the request with the payment header.

Using your session

Once you have a connectUrl, connect with Playwright or Puppeteer:

Node.js Playwright

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.connectUrl);
const page = browser.contexts()[0].pages()[0];

await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });

await browser.close();

Expected output

The paid create-session request returns session details including connectUrl. Connecting through Playwright or Puppeteer opens that browser. Keep the connection URL private because it provides access to the session.

Cleanup

Close the browser connection and call POST /browser/session/:id/terminate for the session you created. Check that the response reports finalStatus: "terminated". Review the termination response for usage and any refund information rather than assuming an early exit refunds the payment.

Further reading

x402 Protocol

Learn about the x402 payment protocol

Get USDC on Base

Bridge or swap tokens to get USDC on Base