# search.prim.sh Search for agents. No ads, no SEO spam. Just facts and clean markdown. Base URL: https://search.prim.sh Auth: x402 (USDC on Base Sepolia). GET /, GET /pricing, GET /v1/metrics are free. Chain: Base Sepolia (eip155:84532) during beta. Install: curl -fsSL https://search.prim.sh/install.sh | sh Limits: Max results per search: 20 Rate limit applies per wallet — check Retry-After header on 429 --- ## Quick Start 1. POST /v1/search with {"query": "...", "max_results": 5} → web search results 2. POST /v1/search/news with {"query": "..."} → recent news articles 3. POST /v1/extract with {"urls": ["https://..."]} → clean markdown content ## Tips - Set include_answer: true to get an AI-generated summary alongside search results. - Use exclude_domains to remove noise sources (e.g. reddit.com, quora.com). - POST /v1/extract accepts a single URL string or an array of URLs. - Failed extractions (paywalls, 404s) are reported in the failed array — the request still succeeds. - Check Retry-After header on 429 responses before retrying. --- ## x402 Payment 1. Make request. Server returns 402 with Payment-Required header. 2. Sign EIP-3009 transferWithAuthorization. 3. Retry with Payment-Signature header (base64-encoded signed authorization). Error envelope: {"error": {"code": "", "message": ""}} Error codes: invalid_request rate_limited provider_error --- ## Endpoints ### GET / Health check. Free. Response (200): service string "search.sh" status string "ok" --- ### GET /pricing Machine-readable pricing for all endpoints. Free. Response (200): service string "search.prim.sh" currency string "USDC" network string "eip155:8453" routes array Route pricing list .method string HTTP method .path string URL path .price_usdc string Price in USDC (decimal string) .description string Human-readable description --- ### GET /v1/metrics Operational metrics. Uptime, request counts, latency percentiles, error rates. Free. Response (200): service string "search.prim.sh" uptime_s number Seconds since last restart requests object Request counts and latencies by endpoint payments object Payment counts by endpoint errors object Error counts by status code --- ### POST /v1/search Search the web and return ranked results with optional AI-generated answer Price: $0.01 Request: query string required Search query string. max_results number optional Maximum number of results to return. 1-20, default 10. search_depth "basic" | "advanced" optional Search depth. "basic" | "advanced", default "basic". country string optional Two-letter ISO 3166-1 country code to bias results (e.g. "US"). time_range "day" | "week" | "month" | "year" optional Restrict results by recency. "day" | "week" | "month" | "year". include_answer boolean optional Include AI-generated answer summarizing top results. Default false. include_domains string[] optional Restrict results to these domains only (e.g. ["docs.base.org"]). exclude_domains string[] optional Exclude results from these domains (e.g. ["reddit.com"]). Response (200): query string Search query echoed back. answer string AI-generated answer summarizing top results. Only present if include_answer was true. results SearchResult[] Ranked search results. response_time number Time taken to complete the search in milliseconds. Errors: 400 invalid_request Missing or invalid query 402 payment_required x402 payment needed 429 rate_limited Too many requests. Check Retry-After header. 502 provider_error Upstream search provider unavailable --- ### POST /v1/search/news Search for recent news articles, ordered by recency Price: $0.01 Request: query string required Search query string. max_results number optional Maximum number of results to return. 1-20, default 10. search_depth "basic" | "advanced" optional Search depth. "basic" | "advanced", default "basic". country string optional Two-letter ISO 3166-1 country code to bias results (e.g. "US"). time_range "day" | "week" | "month" | "year" optional Restrict results by recency. "day" | "week" | "month" | "year". include_answer boolean optional Include AI-generated answer summarizing top results. Default false. include_domains string[] optional Restrict results to these domains only (e.g. ["docs.base.org"]). exclude_domains string[] optional Exclude results from these domains (e.g. ["reddit.com"]). Response (200): query string Search query echoed back. answer string AI-generated answer summarizing top results. Only present if include_answer was true. results SearchResult[] Ranked search results. response_time number Time taken to complete the search in milliseconds. Errors: 400 invalid_request Missing or invalid query 402 payment_required x402 payment needed 429 rate_limited Too many requests 502 provider_error Upstream search provider unavailable --- ### POST /v1/extract Extract readable content from one or more URLs as markdown or plain text Failed extractions are in the failed array. Request succeeds if at least one URL was attempted. Price: $0.005 Request: urls string | string[] required URL string or array of URLs to extract content from. format "markdown" | "text" optional Output format. "markdown" | "text", default "markdown". Response (200): results ExtractResult[] Successfully extracted pages. failed FailedExtraction[] Pages that could not be extracted. response_time number Time taken to complete the extraction in milliseconds. Errors: 400 invalid_request Missing urls field or invalid URL format 402 payment_required x402 payment needed 429 rate_limited Too many requests 502 provider_error Upstream extraction provider unavailable --- ## Ownership Stateless. No resources stored per wallet. Each request is independent.