x402serps logox402serps

Docs

All endpoints are POST JSON at https://x402serps.com. Unpaid calls get HTTP 402 with x402 requirements (USDC on Base or Solana; both listed in accepts[]); retry with the X-PAYMENT header. Failed calls are not charged.

Prepaid credits (API key)

curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "Authorization: Bearer xs_YOUR_KEY" -d '{"q":"x402"}'
curl https://x402serps.com/api/v1/balance -H "Authorization: Bearer xs_YOUR_KEY"

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.

Free trial

curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "X-Trial: 1" -d '{"q":"x402"}'

25 free calls per network (IPv4 /24) (10/min) on single-query endpoints. Response header X-Trial-Remaining; when used up you get the normal 402 with X-Trial-Status. Works over MCP too (send X-Trial: 1 on the HTTP request).

Endpoints

POST /api/v1/search          $0.01   {"q":"query","num":10}
  -> {"query","provider","results":[{position,title,url,snippet}]}
POST /api/v1/news            $0.01   {"q":"query","num":10}
  -> {"query","provider","results":[{position,title,url,snippet,source,date}]}
POST /api/v1/extract         $0.003  {"url":"https://example.com","maxChars":50000}
  -> {"url","finalUrl","title","contentType","markdown","length","truncated"}
POST /api/v1/search-extract  $0.02   {"q":"query","n":3}
  -> search results (top n, max 5) each with extracted markdown in "content"
POST /api/v1/batch           $0.15   {"queries":["q1","q2", "... up to 25"],"num":10}
  -> {"count","results":[{query,provider,results}]}
POST /api/v1/images           $0.01   {"q":"query","num":10,"gl":"us"}
  -> Google Images: image URL, thumbnail, size
POST /api/v1/places           $0.01   {"q":"query","num":10,"gl":"us"}
  -> Google Maps: address, rating, phone, website, lat/lng
POST /api/v1/shopping         $0.01   {"q":"query","num":10,"gl":"us"}
  -> Google Shopping: product, price, store, rating
POST /api/v1/scholar          $0.01   {"q":"query","num":10,"gl":"us"}
  -> Google Scholar: papers, year, citations, PDF
POST /api/v1/videos           $0.01   {"q":"query","num":10,"gl":"us"}
POST /api/v1/research         $0.08   {"q":"question","n":5,"maxChars":20000}   cited brief from top 3-8 pages (extractive)
POST /api/v1/visibility       $0.10   {"brand":"example.com","keywords":["k1","k2"],"gl":"us"}   1-10 keywords, flat price
  -> Google Videos: title, channel, duration, date

Extract only fetches public http/https pages (private/internal addresses blocked), max 2MB, 10s timeout.

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.

// 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());

MCP

Endpoint: /api/mcp  (JSON-RPC over HTTP)
Tools: web_search {query,num}, news_search {query,num}, extract {url,maxChars}, search_extract {query,n,maxChars}, batch_search {queries,num}, image_search {query,num,gl}, places_search {query,num,gl,location}, shopping_search {query,num,gl}, scholar_search {query,num,gl}, video_search {query,num,gl}, deep_research {query,n,maxChars}, ai_visibility_check {brand,keywords,gl} — send X-PAYMENT (x402 v1) header with the call

Install the MCP server

How payment works over MCP

initialize and tools/list are free. Each tools/call is paid with x402: the client sends a signed USDC payment (Base or Solana) in the X-PAYMENT header of the MCP HTTP request. If it is missing, the tool result contains the x402 payment requirements (price, network, payTo) so an x402-aware agent can pay and retry. Use x402 / x402-fetch 1.2.x to sign payments.

Free trial over MCP

Add the header X-Trial: 1 to the MCP connection (the configs below already do). You get 25 free calls per network (IPv4 /24), at most 10 a minute, on single-query tools. After that, calls return the normal payment requirements. Remove the header once you pay with x402.

Claude Code

claude mcp add --transport http x402serps https://x402serps.com/api/mcp --header "X-Trial: 1"

Claude Desktop

claude_desktop_config.json (uses the mcp-remote bridge; or add https://x402serps.com/api/mcp under Settings → Connectors)

{
  "mcpServers": {
    "x402serps": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://x402serps.com/api/mcp",
        "--header",
        "X-Trial:1"
      ]
    }
  }
}

Cursor

~/.cursor/mcp.json or .cursor/mcp.json — or one-click install in Cursor

{
  "mcpServers": {
    "x402serps": {
      "url": "https://x402serps.com/api/mcp",
      "headers": {
        "X-Trial": "1"
      }
    }
  }
}

VS Code

.vscode/mcp.json (or run the command below)

{
  "servers": {
    "x402serps": {
      "type": "http",
      "url": "https://x402serps.com/api/mcp",
      "headers": {
        "X-Trial": "1"
      }
    }
  }
}
code --add-mcp '{"name":"x402serps","type":"http","url":"https://x402serps.com/api/mcp","headers":{"X-Trial":"1"}}'

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "x402serps": {
      "serverUrl": "https://x402serps.com/api/mcp",
      "headers": {
        "X-Trial": "1"
      }
    }
  }
}

Generic streamable-HTTP client

URL:       https://x402serps.com/api/mcp
Transport: streamable HTTP (POST JSON-RPC, JSON responses)
Headers:   X-Trial: 1      (free trial)  or  X-PAYMENT: <x402 payload>  (paid)

curl -s -X POST https://x402serps.com/api/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s -X POST https://x402serps.com/api/mcp -H 'content-type: application/json' -H 'X-Trial: 1' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"web_search","arguments":{"query":"x402"}}}'

Registry metadata: /server.json (MCP Registry name com.x402serps/search) · /.well-known/mcp.json

Data source

Web and news results are Google results via Serper.dev.

Discovery

/openapi.json   /.well-known/x402   /.well-known/agent.json   /llms.txt   /agents.md   /status   /api/status   /server.json

Contact: tj5773104@gmail.com