Web Search

Paid Web Search proxy via x402 pay-per-use (HTTP 402).

Prerequisites: This skill requires x402-payment. Complete the setup steps before first use.

Security: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.

Service URLs

Endpoint (Agent Interface)

GET  /api/x402/web-search
POST /api/x402/web-search/post

Payment Flow (x402 Protocol)

This endpoint uses HTTP 402 Payment Required:

1. First request (no payment header) -> Server returns 402 with payment requirements JSON
2. Client signs the payment requirements (EIP-712) -> Produces a PAYMENT-SIGNATURE
3. Retry with PAYMENT-SIGNATURE header -> Server verifies, settles, returns result JSON

When using @springmint/x402-payment (Node.js) or x402-sdk-go (Go), the flow is handled automatically.

Quick Start (cURL)

Basic Search

curl -s "https://www.cpbox.io/api/x402/web-search?q=python+web+frameworks" \
  -H "Accept: application/json"

With Parameters

curl -s "https://www.cpbox.io/api/x402/web-search" \
  -H "Accept: application/json" \
  -G \
  --data-urlencode "q=rust programming tutorials" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "safesearch=moderate" \
  --data-urlencode "freshness=pm"

Using with x402-payment

CLI (AI Agent)

npx @springmint/x402-payment \
  --url https://www.cpbox.io/api/x402/web-search \
  --method GET

Tip: add query params directly to --url, e.g. ...?q=bitcoin+etf&freshness=pd.

Library (Node.js)

import { createX402FetchClient } from "@springmint/x402-payment";

const client = await createX402FetchClient();
const response = await client.request(
  "https://www.cpbox.io/api/x402/web-search?q=python+web+frameworks&count=10",
  { method: "GET" },
);
const data = await response.json();

When to Use Web Search

Parameters

Freshness Values

Result Filter Values

Filter types: discussions, faq, infobox, news, query, videos, web, locations

# Only web and video results
curl "...&result_filter=web,videos"

Location Headers (Optional)

For location-aware results, add these headers. Lat/Long is sufficient when coordinates are known — the other headers are only needed as a fallback when coordinates are unavailable.

Priority: X-Loc-Lat + X-Loc-Long take precedence. When provided, downstream services resolve the location directly from coordinates and the text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers only when you don't have coordinates. Sending both won't break anything — lat/long simply wins.

Response Format

Response Fields

JSON Example

{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  },
  "videos": { "...": "..." },
  "news": { "...": "..." },
  "rich": {
    "type": "rich",
    "hint": {
      "vertical": "weather",
      "callback_key": "\x3Ccallback_key_hex>"
    }
  }
}

Mixed Response

The mixed object defines the preferred display order of results across types. It contains three arrays:

Each entry is a ResultReference with type (e.g., "web", "videos"), index (into the corresponding result array), and all (true to include all results of that type at this position).

Search Operators

Set operators=false to disable operator parsing.

Goggles (Custom Ranking)

Goggles let you re-rank search results — boost trusted sources, suppress SEO spam, or build focused search scopes.

Hosted goggles should be hosted on a public URL and include ! name:, ! description:, ! author: headers. Inline rules need no registration.

Syntax: $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combine with commas: $site=example.com,boost=3. Separate rules with \ (%0A).

Allow list: $discard\ $site=docs.python.org\ $site=developer.mozilla.org — Block list: $discard,site=pinterest.com\ $discard,site=quora.com

Resources: See your upstream provider's Goggles documentation.

Rich Data Enrichments

For queries about weather, stocks, sports, currency, etc., use the rich callback workflow:

# 1. Search with rich callback enabled
curl -s "https://www.cpbox.io/api/x402/web-search?q=weather+san+francisco&enable_rich_callback=true" \
  -H "Accept: application/json"

# Response includes: "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. Get rich data with the callback key
curl -s "https://www.cpbox.io/api/x402/web-rich?callback_key=abc123..." \
  -H "Accept: application/json"

Supported Rich Types: Calculator, Definitions, Unit Conversion, Unix Timestamp, Package Tracker, Stock, Currency, Cryptocurrency, Weather, American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey, Web3, Translator

Rich Callback Endpoint

GET /api/x402/web-rich?callback_key=...

Use Cases

• General-purpose search integration: Richest result set (web, news, videos, discussions, FAQ, infobox, locations) in one call. For RAG/LLM grounding, prefer llm-context.
• Structured data extraction: Products, recipes, ratings, articles via schemas and typed fields on results.
• Custom search with Goggles: Boost/discard sites with inline rules or hosted Goggles for fully customized ranking.

Notes

• Pagination: Use offset (0-9) with count to page through results
• Count: Max 20 for web search; actual results may be less than requested