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.

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 is https://api.mrscraper.com, and each operation path already starts with /circle, for example /circle/api/mrscraper/scraperAPI.

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. Gateway settles the payment, then MrScraper 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 default are forwarded only when supplied; otherwise, the upstream service chooses its default.

Response

The response body is the renderer result itself, without an ok/service/data wrapper. Illustrative successful response:

{
  "html": "<html><body><h1>Example Domain</h1></body></html>",
  "markdown": "# Example Domain",
  "screenshot": null,
  "runtime": 4.2,
  "retry_count": 0,
  "error": null
}

Disabled outputs can remain present with empty or null values. 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

The response has success, message, and data at the top level, without an ok/service wrapper. Illustrative parsed response, with arrays shortened:

{
  "success": true,
  "message": "Successfully scraped",
  "data": {
    "general": {
      "query": "web scraping",
      "language": "en",
      "location": "us",
      "page_title": "web scraping - Google Search"
    },
    "organic": [
      {
        "title": "Example search result",
        "link": "https://example.com",
        "description": "An example result snippet.",
        "rank": 1
      }
    ],
    "people_also_ask": [
      { "question": "What is web scraping used for?", "rank": 1 }
    ],
    "pagination": {
      "current_page": 1,
      "next_page": 2
    }
  }
}

format: "html" still returns an HTTP JSON response; read the HTML string at data.html. Upstream tokenUsage is omitted. Pagination metadata is forwarded unchanged and may differ from the requested page. Set page explicitly when requesting another results page.

Errors

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. Other error codes include UPSTREAM_TIMEOUT, UPSTREAM_HTTP_ERROR, UPSTREAM_TOO_LARGE, UPSTREAM_UNAVAILABLE, and INTERNAL_ERROR. 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.