Circle Gateway
Let AI agents retrieve web pages and search the web with pay-per-request USDC payments through Circle Gateway x402.
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: Search the web to retrieve real-time search results, including relevant website URLs, titles, and descriptions.
Endpoints and pricing
Base URL: https://api.mrscraper.com/circle
| Service | Method and path | Price per request |
|---|---|---|
| scraperAPI | POST /api/mrscraper/scraperAPI | 0.01 USDC |
| webSearch | POST /api/mrscraper/webSearch | 0.01 USDC |
Both endpoints accept and return application/json.
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:
| Extension | Value | Meaning |
|---|---|---|
x-price-usdc | "0.01" | USDC price per request. |
x-payment-protocol | "x402" | Payment protocol. |
x-x402-version | 2 | x402 protocol version. |
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:
- Send a JSON
POSTrequest to either endpoint. - A valid unpaid request returns HTTP
402with aPAYMENT-REQUIREDheader. - Your buyer client reads the challenge, selects a supported payment option, and signs the payment authorization.
- The client repeats the same method, URL, and JSON body with
PAYMENT-SIGNATUREattached. - Gateway settles the payment, then MrScraper runs the service and returns its result.
| Header | Direction | Purpose |
|---|---|---|
PAYMENT-REQUIRED | Response | Base64-encoded x402 v2 requirements on the initial unpaid challenge. |
PAYMENT-SIGNATURE | Request | Base64-encoded payment payload generated by the buyer client. |
PAYMENT-RESPONSE | Response | Base64-encoded settlement result. Can also appear on a later upstream error, because settlement happens first. |
The cURL examples start the payment flow
The requests below show the JSON inputs and return HTTP 402 when sent without payment. Use your Circle Gateway-compatible buyer client to sign and complete the paid request.
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 numResults.
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
| Field | Type | Required | Default / accepted values |
|---|---|---|---|
url | string | Yes | Public HTTP(S) URL without embedded credentials. Private/local hosts and IPv6 literals are rejected. |
html | boolean | No | true. The renderer currently returns html even when set to false. |
markdown | boolean | No | Include Markdown in the markdown field. |
screenshot | boolean | No | Include a base64 JPEG in the screenshot field. Can substantially increase response size. |
proxyCountry | string | No | "us". Two-letter proxy country code. Also used as geoCode when geoCode is omitted. |
geoCode | string | No | Two-letter upstream geo code. Defaults to proxyCountry. |
browserRendering | boolean | No | true. Set to false to fetch the page without JavaScript rendering. |
timeout | integer | No | 1–300 seconds for upstream page retrieval. |
maxRetries | integer | No | 1–10 upstream retries. 0 is not accepted. |
tokenCap | integer | No | 1–10000 upstream plan tokens for retries. Separate from the USDC price. |
waitUntil | string | No | "domcontentloaded", "load", or "networkidle". |
waitForSelector | string | No | CSS selector, up to 1,000 characters. |
blockResources | boolean | No | Forward the renderer's resource-blocking option. |
warmStart | boolean | No | Visit the site's root before retrieving the target page. |
returnCookie | boolean | No | Request upstream cookie information when supported. |
super | boolean | No | Forward the real-device routing option. |
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
}| Field | Type | Meaning |
|---|---|---|
html | string | Rendered HTML; can be empty when disabled. |
markdown | string | Markdown; can be empty when disabled. |
screenshot | string or null | Base64 JPEG image bytes, without a data: prefix; can be null when disabled. |
runtime | number | Upstream renderer runtime in seconds. |
retry_count | integer | Retries reported by the renderer. |
error | string or null | Upstream page-rendering error, if any. |
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 the web to retrieve real-time search results, including relevant website URLs, titles, and descriptions. Use region to compare results across countries.
curl -i 'https://api.mrscraper.com/circle/api/mrscraper/webSearch' \
-H 'Content-Type: application/json' \
--data '{
"query": "web scraping",
"region": "us",
"numResults": 10
}'Request fields
| Field | Type | Required | Default / accepted values |
|---|---|---|---|
query | string | Yes | Search text, 1–1,000 characters after trimming whitespace. |
region | string | No | "us". Two-letter country code for the results. |
numResults | integer | No | 10. Accepts 10–100. The search can return fewer results. |
Response
The response has success, message, and data at the top level, without an ok/service wrapper. data is the list of ranked results. Illustrative response, with the list shortened:
{
"success": true,
"message": "Search completed",
"data": [
{
"rank": 1,
"title": "Web scraping",
"url": "https://en.wikipedia.org/wiki/Web_scraping",
"description": "Web scraping, web harvesting, or web data extraction is data scraping used for extracting data from websites.",
"source": "Wikipedia"
},
{
"rank": 2,
"title": "What is Web Scraping? The Complete Guide",
"url": "https://www.scraperapi.com/web-scraping/",
"description": "Web scraping, or web data extraction, is the process of extracting publicly available web data using automated tools.",
"source": "ScraperAPI"
}
]
}| Field | Type | Meaning |
|---|---|---|
success | boolean | Whether the upstream search service succeeded. |
message | string | Upstream status message. |
data | array | Ranked results, at most numResults. Can be empty. |
data[].rank | integer | One-based position in the results. |
data[].title | string | Result title. |
data[].url | string | Destination page URL. |
data[].description | string | Result snippet, when available. |
data[].source | string | Site or publisher name shown with the result, when available. |
Upstream tokenUsage is omitted. When success is false, the shape of data varies by failure and can be null.
Errors
| HTTP status | Meaning |
|---|---|
200 | Upstream request completed. Inspect error for scraperAPI or success for webSearch. |
400 | Invalid service inputs, or malformed/unsupported payment requirements. |
402 | Payment required or rejected. Read the payment headers and any error details. |
500 | Unexpected gateway or payment-processing error. |
502 | Upstream connection, HTTP status, or response-size error. |
503 | No payment networks available from the payment middleware. |
504 | Upstream HTTP request timed out. |
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.
Paid failures and retries
Circle Gateway settles the payment before the upstream service runs. An upstream failure does not trigger an automatic retry or refund, and PAYMENT-RESPONSE can appear on a 500, 502, or 504 response after payment was settled. A new paid request can incur another charge; account for that before retrying.
x402
Let AI agents retrieve web pages and search the web with pay-per-request USDC payments over x402, through Circle Gateway, Agentic Market, or Inflowpay.
Agentic Market
Let AI agents retrieve web pages and search the web with pay-per-request USDC payments on Base through x402, listed on Agentic.market.