Skip to content
Nodely

x402 web search API

View Markdown · Agent resources

This API sends one query to several search engines, merges the results and ranks them. It costs 0.0085 USDC per query on Algorand and 0.009 USDC on Base or Arc, paid with x402.

  • Endpoint: POST https://x402.api.nodely.io/v1/search. GET with query parameters also works; separate list values with commas.
  • Engines: several independent web search engines, named by Greek letters (alpha, gamma, …); topic: news uses separate news engines. /v1/search/pricing lists the current names (engines, news_engines).
  • A search where no engine returns anything isn’t charged.

Request

Section titled “Request”

Field names follow Tavily. The API also accepts the field names used by Exa, You.com, Perplexity, Brave, Serper and Linkup, so an existing client usually works unchanged.

Field Type Notes
query string, 1–400 chars Required. Alias: q
max_results integer 1–50, default 10 Aliases: count, num_results, numResults, maxResults, limit, num
page integer 1–10, default 1
time_range day / week / month / year Aliases: freshness, search_recency_filter
start_date, end_date date (YYYY-MM-DD)
include_domains, exclude_domains string array
language string e.g. en, en-US
country string ISO 3166-1 alpha-2
safesearch off / moderate / strict (or 0 / 1 / 2)
topic general / news, default general
engines array of engine names from /v1/search/pricing Limits the search to these engines. Unknown names are ignored with a warning; 400 if none is left
include_answer boolean, default false
stream boolean, default false See Streaming 
{ "query": "algorand x402", "max_results": 5, "time_range": "month" }

Response

Section titled “Response”
{
  "query": "algorand x402",
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "content": "…",
      "score": 0.92,
      "published_date": "2026-10-01",
      "engines": ["alpha", "gamma"],
      "position": 1
    }
  ],
  "answer": null,
  "suggestions": [],
  "engines": [{ "name": "gamma", "results": 10, "elapsed_s": 0.8 }],
  "response_time": 1.4,
  "request_id": "…",
  "warnings": []
}
  • score is between 0 and 1.
  • engines on each result lists the engines that returned it.
  • The top-level engines reports each engine’s result count, error (timeout, blocked, suspended or unavailable) and timing.
  • thumbnail, when present, is an image hosted by the result’s own site.

The PAYMENT-RESPONSE header confirms the payment; on Algorand it holds the payment’s transaction id.

Streaming

Section titled “Streaming”

Send Accept: application/x-ndjson for newline-delimited JSON, or Accept: text/event-stream for server-sent events. Each engine’s results arrive as soon as that engine answers.

The stream sends events in this order:

  • meta
  • results: one per engine, with only results not already sent
  • engine_error: when an engine fails
  • done or error

The done event carries the full response shown above, and the request is charged. A stream that ends with error isn’t charged.

Examples

Section titled “Examples”

Show the 402 offer without paying:

Terminal window
curl -si -X POST https://x402.api.nodely.io/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"x402"}'

Paid request with the Node.js client from Pricing & payment:

const res = await paidFetch("https://x402.api.nodely.io/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({ query: "algorand news", topic: "news", time_range: "week" }),
});

The full schema is in the live API reference.