---
title: "Create a session with X402 payment"
method: POST
path: "/x402/session"
---

# Create a session with X402 payment

`POST /x402/session`

## Request

- Base URL: `https://api.hyperbrowser.ai`
- URL: `https://api.hyperbrowser.ai/x402/session`
- Auth: none required
- TypeScript: <https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/docs/x402/session/post.ts> (a function with typed inputs; its response is checked against the schema)

Purchase one browser session at 0.10 USDC per hour, paid upfront for timeoutMinutes (5–60, default 30). No Hyperbrowser account or API key is required. A valid unpaid request returns 402 with payment requirements. Retry with a signed PAYMENT-SIGNATURE authorization. Payment is settled before connection credentials and a managementToken are returned. One authorization can create only one session. Invalid options are rejected before payment verification. See /integrations/x402/sessions for connection examples and lifetime behavior.

## Headers

- `PAYMENT-SIGNATURE` string

## Request body

- X402SessionParams: Optional preferences for a browser session priced at 0.10 USDC per hour, paid upfront for timeoutMinutes. Unknown fields are rejected before payment verification. Web recording is disabled. Other regular session creation options are not supported.
  - `screen` object: Browser screen dimensions. An omitted dimension uses its default.
    - `width` number
    - `height` number
  - `viewOnlyLiveView` boolean: Make the live-view link read-only. CDP, WebDriver, and the computer action endpoint still allow browser control.
  - `timeoutMinutes` integer: Maximum session lifetime in minutes, from 5 through 60. Defaults to 30. Determines the session duration and upfront price at 0.10 USDC per hour. Connection token lifetimes and expiresAt follow this value.

## Response `200`

Browser created and payment settled. Use the returned connection details to control it without further X402 payments.

- X402SessionResponse: Connection credentials and a management token for the purchased browser. Save this response; get does not reissue connection credentials. These tokens cannot authenticate regular account APIs.
  - `id` string, uuid, required: Purchased session ID.
  - `wsEndpoint` string, uri, required: CDP WebSocket URL for Playwright, Puppeteer, or another CDP client. Includes its authentication token.
  - `webdriverEndpoint` string, uri, required: Selenium/WebDriver endpoint. Send token in the x-hyperbrowser-token header.
  - `liveUrl` string, uri, required: Authenticated live-view URL. Interaction is disabled when viewOnlyLiveView is true.
  - `computerActionEndpoint` string, uri, required: Endpoint for mouse, keyboard, and screenshot actions. Includes its authentication token.
  - `token` string, required: Credential scoped to this browser session. Use it for WebDriver authentication, not the regular get/list/stop/update/extend session APIs.
  - `expiresAt` string, date-time, required: Returned session expiry timestamp based on timeoutMinutes. The browser can stop earlier if closed or disconnected.
  - `managementToken` string, required: Bearer token for GET /x402/session/{id} and PUT /x402/session/{id}/stop only. Valid for 24 hours from purchase, including after browser expiry. Does not authenticate browser connections or regular account APIs.

## Other responses

- `400`: Invalid or unsupported request parameters or malformed payment proof. Invalid options are rejected before payment verification or reservation of the proof.
- `402`: Payment is missing or invalid, or settlement failed. Connection credentials are not returned. On settlement failure, the server attempts to stop the browser.
- `409`: This payment authorization is already reserved or used, including by a request still in progress. No additional session is launched.
- `429`: Session capacity is currently unavailable. A request rejected before settlement can be retried with the same unexpired authorization.
- `500`: Session creation or payment processing failed.
- `503`: The service or payment facilitator is temporarily unavailable. If settlement was attempted, the authorization stays reserved; an error response alone does not establish that payment was not settled.

## Changes

- **2026-10-07** `71c0e245abdf`: 1 breaking, 6 warning, 2 info
  - the `timeoutMinutes` request property's min was increased to `5.00`
  - removed the request property `acceptCookies`
  - removed the request property `adblock`
  - removed the request property `annoyances`
  - …5 more
- **2026-10-06** `fc3f89e0805a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/x402/session/post.md)

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)