---
title: "Search the web with X402 payment"
method: POST
path: "/x402/web/search"
---

# Search the web with X402 payment

`POST /x402/web/search`

X402 payment endpoint. First request returns 402 with payment requirements. Retry with PAYMENT-SIGNATURE header containing cryptographic proof to get search results. See https://x402.gitbook.io/x402 for protocol details.

## Headers

- `PAYMENT-SIGNATURE` string

## Request body

- WebSearchParams
  - `query` string, required
  - `page` integer
  - `maxAgeSeconds` integer
  - `location` WebSearchLocation
    - `country` string, required
    - `state` string
    - `city` string
  - `filters` WebSearchFilters
    - `exactPhrase` boolean
    - `semanticPhrase` boolean
    - `excludeTerms` string[]
    - `boostTerms` string[]
    - `filetype` 'pdf' | 'doc' | 'docx' | 'xls' | 'xlsx' | 'ppt' | 'pptx' | 'html'
    - `site` string
    - `excludeSite` string
    - `intitle` string
    - `inurl` string

## Response `200`

Search completed successfully (after valid payment)

- WebSearchResponse
  - `jobId` string, required
  - `status` 'completed' | 'failed' | 'pending' | 'running' | 'stopped', required
  - `error` string, nullable
  - `data` WebSearchResponseData
    - `query` string, required
    - `results` WebSearchResultItem[], required
      - `title` string, required
      - `url` string, required
      - `description` string, required

## Other responses

- `400` — Invalid search parameters
- `402` — Payment Required - returned on first request without PAYMENT-SIGNATURE header
- `500` — Server error

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) · [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperbrowser/hyperbrowser-api/revisions/9d8b355ebbf2/schema)