API Documentation

One endpoint, 38 tools, one predictable JSON contract. Pay per request with USDC on Base via x402 — or top up a balance and use an API key.

Quickstart

Send a request without payment first. You will receive HTTP 402 with the price and payment details. Sign the payment, repeat the request with the X-PAYMENT header, and get your data.

curl -X POST https://api.serp-base.com/v1/query \
  -H "Content-Type: application/json" \
  -d '{"tool":"google_web","query":"best crm software","depth":10}'

Typical flow with x402:

POST /v1/query            ->  402 Payment Required
                               { price, network, payTo, asset }
POST /v1/query + X-PAYMENT ->  200 OK  { ok: true, tool, data }

If you prefer an API key, create a dashboard account, top up with USDC and send the key in the X-API-KEY header instead.

Authentication

Two ways to pay — pick either one:

Requests without any payment receive 402 with the exact requirements.

Services — what each group does

Every service has a page with use cases, the full tool list for that group and a link to each tool's API reference. Start from the service if you know the job, or from the tool if you know the endpoint.

Not sure which one you need? See the price table on the main page — every tool with its price per 1,000 requests, all in one place.

All tools — detailed reference

Every tool has its own page with full parameters, flexible options, code samples and the response format. Pick one:

Payment (x402)

Payments use the x402 protocol over USDC on Base. Gas is paid by the facilitator, so you only need USDC.

• Network: Base mainnet (eip155:8453)
• Asset: USDC
• Test network: Base Sepolia (eip155:84532) — free test USDC from the Circle faucet

To exercise the test network, send the header X-PAYMENT-NETWORK: base-sepolia to receive testnet requirements.

Response format

Every tool answers with the same envelope:

{
  "ok": true,
  "tool": "google_web",
  "paid_via": "x402",
  "network": "base",
  "data": { ... }
}

Search tools return a normalized structure:

{
  "found": 100,
  "count": 10,
  "related": ["related query", "..."],
  "results": [
    {
      "position": 1,
      "url": "https://example.com",
      "title": "Page title",
      "snippet": "Text excerpt from the page…",
      "breadcrumbs": "example.com › section",
      "content_type": "organic"
    }
  ]
}

Search results

11 tools covering Google, Yandex and their verticals. All share one normalized JSON shape.

Common parameters:

Scraping & extraction

extract_schema example — you describe the fields, we return structure:

{
  "tool": "extract_schema",
  "url": "https://news.ycombinator.com",
  "schema": [
    {"name": "titles", "type": "list", "desc": "first 3 story titles"}
  ]
}

Captcha solving

17 captcha types, one contract. Image captchas take image; widget captchas take sitekey + url.

Example — solve an image captcha:

{
  "tool": "captcha_image",
  "image": "<base64 PNG or JPEG>"
}
// -> {"solution": "x4p9"}

OCR & documents

Multilingual by design — no language parameter needed. Cyrillic, Latin, CJK and Arabic are handled in the same call. PDF pages are returned with page markers.

{
  "tool": "ocr_document",
  "image": "<base64>",
  "prompt": "Extract all text"
}

Large PDFs: documents over 10 pages are handled asynchronously — submit the document, receive a job id, then poll for the result. Ask us to enable it for your account.

Browser fingerprints

Consistent fingerprints collected from real browser profiles — not synthetic templates. 24 coherent fields per fingerprint.

{ "tool": "fingerprint" }
// -> {"fingerprint": {"os": "...", "gpu_renderer": "...", ...}}

The 24 fields: OS and version · CPU cores · RAM · GPU vendor and renderer · screen resolution · viewport · colour depth · timezone · language · user agent · browser version · platform · device type · hardware concurrency · max touch points · connection (downlink, rtt, effective type) · media devices (audio in/out, video in) · fonts · canvas hash · WebGL hash · audio hash · do-not-track · storage quota.

Pass a profile id to collect a fresh fingerprint from a live browser instead:

{ "tool": "fingerprint", "profile": "<profile-id>" }

Screenshots

Optional fields: full (boolean), width, wait (ms before capture). Returns base64 PNG.

Pricing

Per 1,000 requests, in USD. No monthly fee, no minimum, no subscription.

How charging works: one request = one unit. Tools that need several upstream calls (for example positions with a deep keyword set) return a requests field showing how many units were consumed.

Errors

Error responses are always JSON: {"error": "human readable message"}.

Code examples

Python — requests + x402 client:

import requests

URL = "https://api.serp-base.com/v1/query"
payload = {"tool": "google_web", "query": "best crm", "depth": 10}

r = requests.post(URL, json=payload)
if r.status_code == 402:
    reqs = r.json()["accepts"][0]      # price, network, payTo
    # sign with your wallet, then:
    r = requests.post(URL, json=payload,
                      headers={"X-PAYMENT": signed_payment})

print(r.json()["data"])

JavaScript:

const r = await fetch("https://api.serp-base.com/v1/query", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ tool: "ocr_document", image: base64 })
});
const data = await r.json();

With an API key (dashboard account):

curl -X POST https://api.serp-base.com/v1/query \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_key_here" \
  -d '{"tool":"parse_page","url":"https://example.com"}'

MCP & agents

Agent access over MCP is on the way. Your agent will connect to a single MCP server and discover every tool automatically — no wrapper code, payment settled in-band through x402.

Works with any MCP-capable client: Claude Code, Cursor, CrewAI, LangChain and others. Contact us if you want early access.

FAQ