{"components":{"securitySchemes":{"creditKey":{"type":"http","scheme":"bearer","description":"Prepaid credit API key (xs_...), bought at /pricing#credits. 1 credit = $0.01. Alternative to x402 payment."}}},"openapi":"3.1.0","info":{"title":"x402serps","version":"1.1.0","description":"Pay-per-call web search, news, and extraction via x402 (HTTP 402, then retry with X-PAYMENT header). USDC on Base or Solana. Or prepaid card credits: Authorization: Bearer xs_... (see /pricing#credits)."},"servers":[{"url":"https://x402serps.com"}],"paths":{"/api/v1/search":{"post":{"summary":"x402serps: real-time Google web search results (title, url, snippet) for AI agents, one query, up to 20 results","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Search query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1},"get":{"summary":"Web search (GET)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"num","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Results"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/news":{"post":{"summary":"x402serps: real-time Google News results (title, url, snippet, source, date) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"News query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"},"source":{"type":"string"},"date":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/extract":{"post":{"summary":"x402serps: fetch a public http(s) URL and return clean readable markdown text (max 2MB page, 10s, output up to 100k chars)","x-price-usd":"0.003","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"http(s) URL to fetch"},"maxChars":{"type":"number","description":"Max output chars, default 50000, max 100000"}},"required":["url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"finalUrl":{"type":"string"},"title":{"type":"string"},"contentType":{"type":"string"},"markdown":{"type":"string"},"length":{"type":"number"},"truncated":{"type":"boolean"}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/search-extract":{"post":{"summary":"x402serps: Google web search plus clean extracted markdown of the top N results (default 3, max 5) in one call","x-price-usd":"0.02","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Search query (alias: query)"},"n":{"type":"number","description":"Results to extract 1-5, default 3"},"maxChars":{"type":"number","description":"Max chars per page, default 15000"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"},"content":{"type":"object","properties":{"url":{"type":"string"},"finalUrl":{"type":"string"},"title":{"type":"string"},"contentType":{"type":"string"},"markdown":{"type":"string"},"length":{"type":"number"},"truncated":{"type":"boolean"}}},"error":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":2}},"/api/v1/batch":{"post":{"summary":"x402serps: up to 25 Google web search queries in one paid call","x-price-usd":"0.15","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"queries":{"type":"array","items":{"type":"string"},"description":"1-25 queries"},"num":{"type":"number","description":"Results per query 1-20, default 10"}},"required":["queries"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"}}}},"error":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":15}},"/api/v1/images":{"post":{"summary":"x402serps: Google Images results (title, page url, imageUrl, thumbnail, size) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"},"gl":{"type":"string","description":"Country code, e.g. us, gb"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"imageUrl":{"type":"string"},"thumbnailUrl":{"type":"string"},"source":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/places":{"post":{"summary":"x402serps: Google Maps/Places results (name, address, rating, phone, website, lat/lng) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"},"gl":{"type":"string","description":"Country code, e.g. us, gb"},"location":{"type":"string","description":"Optional location, e.g. London, United Kingdom"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"address":{"type":"string"},"rating":{"type":"number"},"ratingCount":{"type":"number"},"category":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"cid":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/shopping":{"post":{"summary":"x402serps: Google Shopping product results (title, price, store, rating, url, image) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"},"gl":{"type":"string","description":"Country code, e.g. us, gb"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"source":{"type":"string"},"price":{"type":"string"},"rating":{"type":"number"},"ratingCount":{"type":"number"},"imageUrl":{"type":"string"},"productId":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/scholar":{"post":{"summary":"x402serps: Google Scholar results (title, url, snippet, publication, year, citations, pdf) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"},"gl":{"type":"string","description":"Country code, e.g. us, gb"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"},"publicationInfo":{"type":"string"},"year":{"type":"number"},"citedBy":{"type":"number"},"pdfUrl":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/videos":{"post":{"summary":"x402serps: Google Videos results (title, url, channel, duration, date, thumbnail) for one query, up to 20","x-price-usd":"0.01","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Query (alias: query)"},"num":{"type":"number","description":"Results 1-20, default 10"},"gl":{"type":"string","description":"Country code, e.g. us, gb"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"position":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"snippet":{"type":"string"},"channel":{"type":"string"},"duration":{"type":"string"},"date":{"type":"string"},"imageUrl":{"type":"string"}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":1}},"/api/v1/research":{"post":{"summary":"x402serps: deep research — Google search, extract the top 3-8 pages in parallel, return a concise cited brief (extractive key sentences) plus source excerpts","x-price-usd":"0.08","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","description":"Research question (alias: query)"},"n":{"type":"number","description":"Pages to read 3-8, default 5"},"maxChars":{"type":"number","description":"Max chars read per page, default 20000"}},"required":["q"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"provider":{"type":"string"},"method":{"type":"string"},"summary":{"type":"string"},"keyPoints":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"number"}}}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"url":{"type":"string"},"position":{"type":"number"},"snippet":{"type":"string"},"excerpts":{"type":"array","items":{"type":"string"}},"extracted":{"type":"boolean"},"error":{"type":"string"}}}},"related":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}}}},"elapsedMs":{"type":"number"}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":8}},"/api/v1/visibility":{"post":{"summary":"x402serps: AI/SEO visibility check — for 1-10 keywords, where a brand or domain ranks on Google, plus AI Overview, answer box, People Also Ask and knowledge graph presence, top competitors and a 0-100 score (flat price)","x-price-usd":"0.10","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string","description":"Brand name or domain, e.g. stripe.com"},"keywords":{"type":"array","items":{"type":"string"},"description":"1-10 keywords"},"gl":{"type":"string","description":"Country code, default us"}},"required":["brand","keywords"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"brand":{"type":"string"},"domain":{"type":"string"},"gl":{"type":"string"},"score":{"type":"number"},"keywordsFound":{"type":"number"},"keywordsChecked":{"type":"number"},"topCompetitors":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"keywords":{"type":"number"}}}},"results":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"found":{"type":"boolean"},"rank":{"type":"number"},"url":{"type":"string"},"mentionedInResults":{"type":"boolean"},"score":{"type":"number"},"features":{"type":"object","properties":{"aiOverview":{"type":"object","properties":{"present":{"type":"boolean"},"brand":{"type":"boolean"}}},"answerBox":{"type":"object","properties":{"present":{"type":"boolean"},"brand":{"type":"boolean"}}},"peopleAlsoAsk":{"type":"object","properties":{"present":{"type":"boolean"},"brand":{"type":"boolean"}}},"knowledgeGraph":{"type":"object","properties":{"present":{"type":"boolean"},"brand":{"type":"boolean"}}}}},"competitors":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"rank":{"type":"number"}}}}}}}}}}}},"400":{"description":"bad input"},"401":{"description":"Unknown API key"},"402":{"description":"x402 payment required (USDC on Base or Solana)"},"502":{"description":"upstream failure"}},"security":[{},{"creditKey":[]}],"x-credits":10}},"/api/v1/balance":{"get":{"summary":"Prepaid credit balance for an API key","security":[{"creditKey":[]}],"responses":{"200":{"description":"{credits, usdValue, purchased, pack, created, lastUsed}"},"401":{"description":"Missing or unknown key"}}}},"/api/stripe/checkout":{"post":{"summary":"Create a Stripe Checkout session for a credit pack (starter $5/550, pro $20/2400, scale $100/13000). Returns {url}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"string","enum":["starter","pro","scale"]}},"required":["pack"]}}}},"responses":{"200":{"description":"{url}"}}}}}}