# x402serps
> Pay-per-call web search (Google results), news, and clean page extraction for AI agents. USDC on Base or Solana via x402. No account or API key.

## Endpoints (all POST JSON; unpaid requests return HTTP 402 with x402 payment requirements)
- /api/v1/search  $0.01  {"q":"...","num":10}  (also GET ?q=&num=)  -> {query,provider,results:[{position,title,url,snippet}]}
- /api/v1/news  $0.01  {"q":"...","num":10}  -> {query,provider,results:[{position,title,url,snippet,source,date}]}
- /api/v1/extract  $0.003  {"url":"https://...","maxChars":50000}  -> {url,finalUrl,title,contentType,markdown,length,truncated}
- /api/v1/search-extract  $0.02  {"q":"...","n":3}  -> search results (top n, max 5) each with extracted markdown in "content"
- /api/v1/batch  $0.15  {"queries":["...", ...up to 25],"num":10}  -> {count,results:[{query,provider,results}]}
- /api/v1/images  $0.01  {"q":"...","num":10,"gl":"us"}  -> {query,provider,results:[...]}  (Google Images: image URL, thumbnail, size)
- /api/v1/places  $0.01  {"q":"...","num":10,"gl":"us","location":"London"}  -> {query,provider,results:[...]}  (Google Maps: address, rating, phone, website, lat/lng)
- /api/v1/shopping  $0.01  {"q":"...","num":10,"gl":"us"}  -> {query,provider,results:[...]}  (Google Shopping: product, price, store, rating)
- /api/v1/scholar  $0.01  {"q":"...","num":10,"gl":"us"}  -> {query,provider,results:[...]}  (Google Scholar: papers, year, citations, PDF)
- /api/v1/videos  $0.01  {"q":"...","num":10,"gl":"us"}  -> {query,provider,results:[...]}  (Google Videos: title, channel, duration, date)
- /api/v1/research  $0.08  {"q":"...","n":5,"maxChars":20000}  -> {query,method:"extractive",summary,keyPoints:[{text,source}],sources:[{id,title,url,excerpts}],related}  (deep research: search + read top 3-8 pages, cited brief; ~5-20s)
- /api/v1/visibility  $0.10 flat  {"brand":"example.com","keywords":["k1","... up to 10"],"gl":"us"}  -> {score 0-100,keywordsFound,topCompetitors,results:[{keyword,found,rank,url,features:{aiOverview,answerBox,peopleAlsoAsk,knowledgeGraph},competitors,score}]}  (AI/SEO visibility)
Base URL: https://x402serps.com

## Prepaid credits (API key, pay by card)
Prepaid credits (card via Stripe): $5 = 550 calls, $20 = 2,400 calls, $100 = 13,000 calls. Buy at https://x402serps.com/pricing#credits; your API key (xs_...) is shown once after checkout. Send header Authorization: Bearer xs_... on any /api/v1 endpoint instead of paying with x402. 1 credit = one $0.01 call: search/news/images/places/shopping/scholar/videos/extract 1, search-extract 2, research 8, visibility 10, batch 15. Response header X-Credits-Remaining. Balance: GET /api/v1/balance with the same header. Out of credits -> normal 402 (header X-Credits-Status). Unknown key -> 401.
curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "Authorization: Bearer xs_YOUR_KEY" -d '{"q":"x402"}'

## Free trial
Free trial: send header X-Trial: 1 (no X-PAYMENT) to /api/v1/search, news, extract (and images, places, shopping, scholar, videos). research and visibility are paid-only (not in the trial). 25 free calls per network (IPv4 /24), max 10/minute; response header X-Trial-Remaining shows what's left. When used up, you get the normal 402 (header X-Trial-Status explains). Also works over MCP: send X-Trial: 1 on the MCP HTTP request.
curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "X-Trial: 1" -d '{"q":"x402"}'

## MCP
https://x402serps.com/api/mcp (streamable HTTP JSON). Tools: web_search {query,num} $0.01, news_search {query,num} $0.01, extract {url,maxChars} $0.003, search_extract {query,n,maxChars} $0.02, batch_search {queries[],num} $0.15, image_search {query,num,gl} $0.01, places_search {query,num,gl,location} $0.01, shopping_search {query,num,gl} $0.01, scholar_search {query,num,gl} $0.01, video_search {query,num,gl} $0.01, deep_research {query,n,maxChars} $0.08, ai_visibility_check {brand,keywords[],gl} $0.10.
Send x402 payment in the X-PAYMENT header of the MCP HTTP request; without it, tools/call returns the payment requirements. initialize/tools/list are free.
Manifest: https://x402serps.com/.well-known/mcp.json
Setup (Claude Desktop, Cursor, generic): https://x402serps.com/mcp
Cursor: {"mcpServers":{"x402serps":{"url":"https://x402serps.com/api/mcp"}}}
Claude Desktop: {"mcpServers":{"x402serps":{"command":"npx","args":["-y","mcp-remote","https://x402serps.com/api/mcp"]}}}

## Discovery
- OpenAPI: https://x402serps.com/openapi.json
- x402: https://x402serps.com/.well-known/x402

## Payment
Solana: every paid endpoint also accepts USDC on Solana (asset EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, payTo 99V43C6cN5fxidQLNzZf2nCiC1FQ6SDUFaB3Deeq8wtm, fee paid by facilitator). The 402 lists both options in accepts[]; your client picks one.
scheme exact, network base, asset USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), payTo 0x4473c593876D7E4313Ef09Bd6D5f04cF54258B02. Failed requests (4xx/5xx) are not settled.
Client: npm x402-fetch / x402-axios (wrapFetchWithPayment).

## Quick start (JavaScript)
import { wrapFetchWithPayment } from "x402-fetch";
const f = wrapFetchWithPayment(fetch, account); // viem account with USDC on Base
const r = await f("https://x402serps.com/api/v1/search",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({q:"x402"})});

## Quick start (Python)
from x402.clients.requests import x402_requests
s = x402_requests(account); s.post("https://x402serps.com/api/v1/search", json={"q":"x402"})

## Errors
400 bad input (not charged), 402 payment required/invalid, 502 upstream provider error (not charged).

## When to use which
- One question needing links: search. Fresh events: news. Read a known page: extract.
- Need answers with source text in one hop: search-extract. Many queries (research, SEO, monitoring): batch (~$0.006/query).

## Pages
- Pricing: https://x402serps.com/pricing
- Docs: https://x402serps.com/docs
- MCP: https://x402serps.com/mcp
- Terms: https://x402serps.com/terms  Privacy: https://x402serps.com/privacy

## Data source
Web and news results are Google results via Serper.dev. Status: https://x402serps.com/api/status. Contact: tj5773104@gmail.com

## Client compatibility
Payments use x402 protocol v2 (x402Version: 2). Unpaid calls return HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON) and the same JSON in the body: accepts[] lists Base (eip155:8453) and Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) USDC, plus Bazaar discovery metadata. Pay by retrying with a PAYMENT-SIGNATURE header. Recommended client: @x402/fetch 2.x.
Legacy x402 v1 clients (x402-fetch / x402-axios 1.2.x) still work: add the request header "X402-Version: 1" to get a v1 challenge, and the X-PAYMENT header is accepted as before. Older x402 0.x clients and hand-built payloads are rejected with invalid_payload.

```js
// v2, Base. npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client().register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY)));
const pay = wrapFetchWithPayment(fetch, client);

// v2, Solana. npm i @x402/fetch @x402/svm @solana/kit@^8
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit";
const signer = await createKeyPairSignerFromBytes(getBase58Encoder().encode(process.env.SOLANA_PRIVATE_KEY));
const pay = wrapFetchWithPayment(fetch, new x402Client().register("solana:*", new ExactSvmScheme(signer)));

// v1 (legacy), Base. npm i x402-fetch@^1.2
import { wrapFetchWithPayment, createSigner } from "x402-fetch";
const base = await createSigner("base", process.env.EVM_PRIVATE_KEY);
const pay = wrapFetchWithPayment(fetch, base);

// v1 (legacy), Solana only, no EVM key needed
import { wrapFetchWithPayment, createSigner } from "x402-fetch";
const sol = await createSigner("solana", process.env.SOLANA_PRIVATE_KEY);
const pay = wrapFetchWithPayment(fetch, sol);

// Then, with any of the above (v1 clients must send X402-Version: 1):
const r = await pay("https://x402serps.com/api/v1/search", {
  method: "POST",
  headers: { "content-type": "application/json", "X402-Version": "1" /* v1 clients only */ },
  body: JSON.stringify({ q: "hello" }),
});
console.log(await r.json());
```

## Research & visibility notes
research uses an extractive summarizer (key sentences ranked by query overlap and cross-source agreement, cited as [n]); no LLM, so no hallucinated text, but summaries are quotations rather than prose. visibility checks Google top 10 organic per keyword; aiOverview is reported only when Serper returns it (often absent).