x402 (Circle Gateway)

Use MrScraper's HTTP APIs from an AI agent or application and pay per request in USDC through Circle Gateway. Buyers do not need a MrScraper API key or session cookie.

The integration exposes two services:

• scraperAPI retrieves a public page as rendered HTML, Markdown, a screenshot, or a combination of these outputs.
• webSearch searches Google with region, language, and pagination controls for web discovery, research, and SEO analysis.

Endpoints and pricing

Base URL: https://api.mrscraper.com/circle

Both endpoints accept and return application/json. Each search-results page is a separate request. Upstream fields such as token_usage and tokenUsage describe MrScraper plan usage; they are separate from the x402 USDC price.

The live PAYMENT-REQUIRED challenge supplies the payable amount, accepted network, asset, and recipient. Check these requirements before authorizing a payment.

OpenAPI specification

Open the OpenAPI 3.1 JSON specification

The document covers only these two paid endpoints, including required and optional request fields, response schemas, output examples, error responses, and the x402 payment headers. Each operation includes these custom OpenAPI extensions:

The specification's servers URL already includes /circle. Append the operation path once when constructing a request URL.

Payment setup and flow

Use a buyer client that supports Circle Gateway batched x402 payments and an EOA wallet with an available USDC balance in Gateway. Follow Circle's buyer quickstart to set up the wallet and initial deposit. Existing x402 clients can follow Circle's buyer integration guide.

For each API call:

1. Send a JSON POST request to either endpoint.
2. A valid unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header.
3. Your buyer client reads the challenge, selects a supported payment option, and signs the payment authorization.
4. The client repeats the same method, URL, and JSON body with PAYMENT-SIGNATURE attached.
5. After payment is accepted, the gateway runs the service and returns its result.

Invalid service inputs are rejected with HTTP 400 before payment is requested. Unknown request fields are ignored. Use the field names documented here, including camelCase options such as proxyCountry and renderJs.

scraperAPI

Retrieve public webpage content, including pages rendered with JavaScript. Use the returned content for research, public product and price monitoring, article collection, or retrieval workflows. Availability depends on the target website.

curl -i 'https://api.mrscraper.com/circle/api/mrscraper/scraperAPI' \
  -H 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "html": true,
    "markdown": true,
    "screenshot": false
  }'

Request fields

Fields without a documented gateway default are forwarded only when supplied; otherwise, the upstream service chooses its default. Set html, markdown, and screenshot explicitly when choosing an output combination.

Response

Illustrative successful response, with optional payment metadata omitted:

{
  "ok": true,
  "service": "fetchHtml",
  "data": {
    "html": "<html><body><h1>Example Domain</h1></body></html>",
    "markdown": "# Example Domain",
    "screenshot": null,
    "runtime": 4.2,
    "token_usage": 2,
    "retry_count": 0,
    "error": null
  }
}

Disabled outputs can remain present with empty or null values. Additional upstream metadata may also appear; the OpenAPI document describes those fields. Allow enough time in your client for rendering and response transfer. The request's timeout field is separate from your client's HTTP deadline.

webSearch

Search Google to discover relevant pages, inspect organic titles and snippets, and compare results across regions and languages. Search modules such as People Also Ask depend on what Google returns for the query.

curl -i 'https://api.mrscraper.com/circle/api/mrscraper/webSearch' \
  -H 'Content-Type: application/json' \
  --data '{
    "query": "web scraping",
    "region": "us",
    "language": "en",
    "page": 1,
    "format": "json"
  }'

Request fields

Response

Illustrative parsed response, with optional payment metadata omitted:

{
  "ok": true,
  "service": "googleSearch",
  "data": {
    "success": true,
    "message": "Successfully scraped",
    "tokenUsage": 1,
    "data": {
      "organic": [
        {
          "title": "Example search result",
          "link": "https://example.com",
          "description": "An example result snippet.",
          "rank": 1
        }
      ]
    }
  }
}

format: "html" still returns an HTTP JSON response; read the HTML string at data.data.html. For parsed results, organic links are at data.data.organic. Pagination metadata is forwarded unchanged and may differ from the requested page. Set page explicitly when requesting another results page.

Payment metadata and errors

A paid response can include a top-level payment object with payer, amountAtomic, and network; transaction is included when supplied by Gateway. USDC uses six decimal places, so amountAtomic: "10000" represents 0.01 USDC.

Gateway validation and upstream errors use an ok: false envelope:

{
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed",
    "issues": [
      {
        "path": ["url"],
        "message": "URL must target a public host"
      }
    ]
  }
}

This is an illustrative validation error; issue messages vary. Payment middleware errors use a different shape: a string error with optional reason or message. The initial unpaid 402 body is {}; its requirements are in PAYMENT-REQUIRED.