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#

RoleDomainAPI Providerhttps://www.cpbox.ioFacilitatorhttps://www.cppay.finance

Endpoint (Agent Interface)#

http

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#

bash

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

With Parameters#

bash

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)#

bash

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)#

ts

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#

FeatureWeb Search (this)LLM Context ( llm-context)Answers ( answers)OutputStructured results (links, snippets, metadata)Pre-extracted page content for LLMsEnd-to-end AI answers with citationsResult typesWeb, news, videos, discussions, FAQ, infobox, locations, richExtracted text chunks, tables, codeSynthesized answer + source listUnique featuresGoggles, structured data ( schemas), rich callbacksToken budget control, threshold modesMulti-iteration search, streaming, OpenAI SDK compatibleSpeedFast (~0.5-1s)Fast (<1s)Slower (~30-180s)Best forSearch UIs, data extraction, custom rankingRAG pipelines, AI agents, groundingChat interfaces, thorough research

Parameters#

ParameterTypeRequiredDefaultDescriptionqstringYes-Search query (1-400 chars, max 50 words)countrystringNoUSSearch country (2-letter country code or ALL)search_langstringNoenLanguage preference (2+ char language code)ui_langstringNoen-USUI language (e.g., "en-US")countintNo20Max results per page (1-20)offsetintNo0Page offset for pagination (0-9)safesearchstringNomoderateAdult content filter ( off/ moderate/ strict)freshnessstringNo-Time filter ( pd/ pw/ pm/ py or date range)text_decorationsboolNotrueInclude highlight markersspellcheckboolNotrueAuto-correct queryresult_filterstringNo-Filter result types (comma-separated)gogglesstringNo-Custom ranking filter (URL or inline)extra_snippetsboolNo-Get up to 5 extra snippets per resultoperatorsboolNotrueApply search operatorsunitsstringNo-Measurement units ( metric/ imperial)enable_rich_callbackboolNofalseEnable rich 3rd party data callbackinclude_fetch_metadataboolNofalseInclude fetched_content_timestamp on results

Freshness Values#

ValueDescriptionpdPast day (24 hours)pwPast week (7 days)pmPast month (31 days)pyPast year (365 days)YYYY-MM-DDtoYYYY-MM-DDCustom date range

Result Filter Values#

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

bash

# 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.

HeaderTypeDescriptionX-Loc-LatfloatUser latitude (-90.0 to 90.0)X-Loc-LongfloatUser longitude (-180.0 to 180.0)X-Loc-TimezonestringIANA timezone (e.g., "America/San_Francisco")X-Loc-CitystringCity nameX-Loc-StatestringState/region code (ISO 3166-2)X-Loc-State-NamestringState/region full name (e.g., "California")X-Loc-Countrystring2-letter country codeX-Loc-Postal-CodestringPostal code (e.g., "94105")

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#

FieldTypeDescriptiontypestringAlways "search"``query.originalstringThe original search queryquery.alteredstring?Spellcheck-corrected query (if changed)query.cleanedstring?Cleaned/normalized queryquery.spellcheck_offbool?Whether spellcheck was disabledquery.more_results_availableboolWhether more pages existquery.show_strict_warningbool?True if strict safesearch blocked adult resultsquery.search_operatorsobject?Applied search operators ( applied, cleaned_query, sites)web.typestringAlways "search"``web.results[].titlestringPage titleweb.results[].urlstringPage URLweb.results[].descriptionstring?Snippet/description textweb.results[].agestring?Human-readable age (e.g., "2 days ago")web.results[].languagestring?Content language codeweb.results[].meta_urlobjectURL components ( scheme, netloc, hostname, path)web.results[].thumbnailobject?Thumbnail ( src, original)web.results[].thumbnail.originalstring?Original full-size image URLweb.results[].thumbnail.logobool?Whether the thumbnail is a logoweb.results[].profileobject?Publisher identity ( name, url, long_name, img)web.results[].page_agestring?ISO datetime of publication (e.g., "2025-04-12T14:22:41")web.results[].extra_snippetslist[str]?Up to 5 additional excerptsweb.results[].deep_resultsobject?Additional links ( buttons, links) from the pageweb.results[].schemaslist?Raw schema.org structured dataweb.results[].productobject?Product info and reviewsweb.results[].recipeobject?Recipe details (ingredients, time, ratings)web.results[].articleobject?Article metadata (author, publisher, date)web.results[].bookobject?Book info (author, ISBN, rating)web.results[].softwareobject?Software product infoweb.results[].ratingobject?Aggregate ratingsweb.results[].faqobject?FAQ found on the pageweb.results[].movieobject?Movie info (directors, actors, genre)web.results[].videoobject?Video metadata (duration, views, creator)web.results[].locationobject?Location/restaurant detailsweb.results[].qaobject?Question/answer infoweb.results[].creative_workobject?Creative work dataweb.results[].music_recordingobject?Music/song dataweb.results[].organizationobject?Organization infoweb.results[].reviewobject?Review dataweb.results[].content_typestring?Content type classificationweb.results[].fetched_content_timestampint?Fetch timestamp (with include_fetch_metadata=true)web.mutated_by_gogglesboolWhether results were re-ranked by Gogglesweb.family_friendlyboolWhether results are family-friendlymixedobject?Preferred display order (see Mixed Response below)discussions.results[]array?Forum discussion clustersdiscussions.results[].data.forum_namestring?Forum/community namediscussions.results[].data.num_answersint?Number of answers/repliesdiscussions.results[].data.questionstring?Discussion questiondiscussions.results[].data.top_commentstring?Top-voted comment excerptfaq.results[]array?FAQ entriesnews.results[]array?News articlesvideos.results[]array?Video resultsinfobox.results[]array?Knowledge graph entrieslocations.results[]array?Local POI resultsrich.hint.verticalstring?Rich result typerich.hint.callback_keystring?Callback key for rich data

JSON Example#

json

{
  "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": "<callback_key_hex>"
    }
  }
}

Mixed Response#

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

ArrayPurposemainPrimary result list (ordered sequence of results to display)topResults to display above main resultssideResults to display alongside main results (e.g., infobox)

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#

OperatorSyntaxDescriptionSitesite:example.comLimit results to a specific domainFile extensionext:pdfResults with a specific file extensionFile typefiletype:pdfResults created in a specific file typeIn titleintitle:pythonPages with term in the titleIn bodyinbody:tutorialPages with term in the bodyIn pageinpage:guidePages with term in title or bodyLanguagelang:esPages in a specific language (ISO 639-1)Locationloc:usPages from a specific country (ISO 3166-1 alpha-2)Include+termForce inclusion of a termExclude-termExclude pages containing the termExact match"exact phrase"Match the exact phrase in orderANDterm1 AND term2Both terms required (uppercase)OR / NOTterm1 OR term2, NOT termLogical operators (uppercase)

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.

MethodExampleHosted--data-urlencode "goggles=https://<hosted-goggle-url>"Inline--data-urlencode 'goggles=$discard\n$site=example.com'

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 \n ( %0A).

Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Block list: $discard,site=pinterest.com\n$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:

bash

# 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#

http

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

ParameterTypeRequiredDescriptioncallback_keystringYesCallback key from the web search rich.hint.callback_key field

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