{ "openapi": "3.1.0", "info": { "title": "AgentSearch x402 API", "version": "0.2.0", "description": "Pay-per-call web search, page extract, headless render and search-and-read for AI agents. x402 v2 on Base mainnet (USDC); no API key or account. Failed calls are not charged.", "contact": { "url": "https://agentsearchhq.com" }, "x-logo": { "url": "https://agentsearchhq.com/icon-512.png" }, "x-guidance": "Four POST JSON endpoints, each paid per call with x402 v2 (exact scheme, USDC on Base). An unpaid request returns 402 with the PAYMENT-REQUIRED header; an x402 client (x402-fetch, x402-axios, x402 Python httpx/requests) signs an EIP-3009 authorization and retries with PAYMENT-SIGNATURE. search {query, max_results 1-10} returns ranked results; extract {url} returns page markdown; render {url} runs a headless browser for JavaScript pages and returns markdown; search_and_read {query, num_results 1-5, max_chars?, render_fallback?} searches and returns the top pages' markdown in one call (charged only when at least one page has text). Invalid input (400), upstream failures (502) and empty results are never charged. Typical flow: search_and_read for search plus page text in one call; or search, then extract the best URLs, and render only when extract comes back empty." }, "externalDocs": { "url": "https://agentsearchhq.com/docs/x402" }, "servers": [ { "url": "https://api.agentsearchhq.com" } ], "security": [], "paths": { "/x402/v1/search": { "post": { "operationId": "search", "summary": "Live web search for AI agents and RAG pipelines", "description": "Live web search for AI agents and RAG pipelines. Returns ranked results (title, URL, snippet, score, domain) for a natural-language or keyword query, for grounding answers in current web information. $0.008 USDC per call on Base; calls that return no results are not charged.", "tags": [ "search" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Search query in natural language or keywords." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "Maximum number of results (1-10)." } }, "required": [ "query" ], "additionalProperties": false }, "example": { "query": "latest x402 protocol news", "max_results": 5 } } } }, "responses": { "400": { "description": "Invalid JSON or input (never charged)" }, "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 v2 PaymentRequired" } } }, "409": { "description": "Payment authorization already used" }, "413": { "description": "Body too large" }, "429": { "description": "Rate limited" }, "502": { "description": "Upstream or facilitator failure (never charged)" }, "503": { "description": "Service disabled or busy" }, "200": { "description": "Result (payment settled; PAYMENT-RESPONSE header carries the receipt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "result_count": { "type": "integer" }, "retrieved_at": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "content": { "type": "string" }, "score": { "type": "number" }, "domain": { "type": "string" }, "published_date": { "type": [ "string", "null" ] } } } } }, "required": [ "results" ] }, "example": { "query": "latest x402 protocol news", "result_count": 1, "retrieved_at": "2026-11-09T12:00:00Z", "results": [ { "title": "x402 - payments protocol for the internet", "url": "https://www.x402.org/", "content": "x402 is an open payment standard built on HTTP 402 ...", "score": 0.91, "domain": "x402.org", "published_date": null } ] } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.008" }, "protocols": [ { "x402": { "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337" } } ] } } }, "/x402/v1/extract": { "post": { "operationId": "extract", "summary": "Fetches a public web page and returns clean, LLM-ready markdown (plus title, links and fetch metadata)", "description": "Fetches a public web page and returns clean, LLM-ready markdown (plus title, links and fetch metadata). Suited to reading articles, docs and other static pages after a search. $0.007 USDC per call on Base; failed or empty extractions are not charged.", "tags": [ "extract" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute public http(s) URL of the page." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "400": { "description": "Invalid JSON or input (never charged)" }, "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 v2 PaymentRequired" } } }, "409": { "description": "Payment authorization already used" }, "413": { "description": "Body too large" }, "429": { "description": "Rate limited" }, "502": { "description": "Upstream or facilitator failure (never charged)" }, "503": { "description": "Service disabled or busy" }, "200": { "description": "Result (payment settled; PAYMENT-RESPONSE header carries the receipt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "markdown": { "type": "string" }, "text": { "type": "string" }, "links": { "type": "array" }, "meta": { "type": "object" } }, "required": [ "url" ] }, "example": { "url": "https://example.com/", "title": "Example Domain", "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples ...", "text": "", "links": [ { "href": "https://www.iana.org/domains/example", "text": "More information..." } ], "meta": { "status_code": 200, "content_type": "text/html", "chars": 167, "truncated": false } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.007" }, "protocols": [ { "x402": { "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337" } } ] } } }, "/x402/v1/render": { "post": { "operationId": "render", "summary": "Renders a JavaScript-heavy public web page in a headless browser and returns the final content as markdown with title and links", "description": "Renders a JavaScript-heavy public web page in a headless browser and returns the final content as markdown with title and links. Suited to single-page apps and pages that plain fetching leaves empty. $0.01 USDC per call on Base; failed or empty renders are not charged.", "tags": [ "render" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Absolute public http(s) URL of the page." } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com" } } } }, "responses": { "400": { "description": "Invalid JSON or input (never charged)" }, "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 v2 PaymentRequired" } } }, "409": { "description": "Payment authorization already used" }, "413": { "description": "Body too large" }, "429": { "description": "Rate limited" }, "502": { "description": "Upstream or facilitator failure (never charged)" }, "503": { "description": "Service disabled or busy" }, "200": { "description": "Result (payment settled; PAYMENT-RESPONSE header carries the receipt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "status_code": { "type": [ "integer", "null" ] }, "title": { "type": [ "string", "null" ] }, "markdown": { "type": "string" }, "links": { "type": "array" }, "meta": { "type": "object" } }, "required": [ "url" ] }, "example": { "url": "https://example.com/", "status_code": 200, "title": "Example Domain", "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples ...", "links": [ { "href": "https://www.iana.org/domains/example", "text": "More information..." } ], "meta": { "render_ms": 820, "js": true, "chars": 167, "truncated": false } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" }, "protocols": [ { "x402": { "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337" } } ] } } }, "/x402/v1/search_and_read": { "post": { "operationId": "search_and_read", "summary": "Search and read in one paid call: runs a live web search and returns the top 1-5 results with clean, LLM-ready markdown of each page (title, URL, snippet, score, page text), for grounding answers and RAG without separate search and extract calls", "description": "Search and read in one paid call: runs a live web search and returns the top 1-5 results with clean, LLM-ready markdown of each page (title, URL, snippet, score, page text), for grounding answers and RAG without separate search and extract calls. $0.015 USDC per call on Base; charged only when at least one page has text.", "tags": [ "search_and_read" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Search query in natural language or keywords." }, "num_results": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3, "description": "How many top results to read (1-5)." }, "max_results": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Alias of num_results (used only when num_results is absent)." }, "max_chars": { "type": "integer", "minimum": 1, "maximum": 20000, "default": 8000, "description": "Maximum markdown characters per page (1-20000)." }, "render_fallback": { "type": "boolean", "default": false, "description": "Retry at most one empty or thin page in a headless browser." } }, "required": [ "query" ], "additionalProperties": false }, "example": { "query": "latest x402 protocol news", "num_results": 3 } } } }, "responses": { "400": { "description": "Invalid JSON or input (never charged)" }, "402": { "description": "Payment required: x402 challenge in the PAYMENT-REQUIRED header", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 v2 PaymentRequired" } } }, "409": { "description": "Payment authorization already used" }, "413": { "description": "Body too large" }, "429": { "description": "Rate limited" }, "502": { "description": "Upstream or facilitator failure (never charged)" }, "503": { "description": "Service disabled or busy" }, "200": { "description": "Result (payment settled; PAYMENT-RESPONSE header carries the receipt)", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "result_count": { "type": "integer" }, "extracted_count": { "type": "integer" }, "retrieved_at": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "domain": { "type": "string" }, "published_date": { "type": [ "string", "null" ] }, "markdown": { "type": "string" }, "chars": { "type": "integer" }, "truncated": { "type": "boolean" }, "extract_status": { "type": "string", "enum": [ "ok", "empty", "failed", "timeout", "blocked", "rendered" ] }, "source": { "type": [ "string", "null" ] }, "error": { "type": "string" } } } } }, "required": [ "results" ] }, "example": { "query": "latest x402 protocol news", "result_count": 1, "extracted_count": 1, "retrieved_at": "2026-11-10T12:00:00Z", "results": [ { "title": "x402 - payments protocol for the internet", "url": "https://www.x402.org/", "snippet": "x402 is an open payment standard built on HTTP 402 ...", "score": 0.91, "domain": "x402.org", "published_date": null, "markdown": "# x402\n\nx402 is an open payment standard ...", "chars": 4120, "truncated": false, "extract_status": "ok", "source": "extract" } ] } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.015" }, "protocols": [ { "x402": { "version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0xC49B157887e51c21CB655f39CF65D6a4c2a4C337" } } ] } } } }, "x-discovery": { "wellKnown": "https://api.agentsearchhq.com/.well-known/x402" } }