Title: x402 web search API
Source: https://nodely.io/docs/x402/search/

# x402 web search API

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](https://nodely.io/docs/x402/payment).

-   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`](https://x402.api.nodely.io/v1/search/pricing) lists the current names (`engines`, `news_engines`).
-   A search where no engine returns anything isn’t charged.

<a id="request"></a>

## 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](https://nodely.io/docs/x402/search/#streaming) |

```json
{ "query": "algorand x402", "max_results": 5, "time_range": "month" }
```

<a id="response"></a>

## Response

```json
{
  "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.

<a id="streaming"></a>

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

<a id="examples"></a>

## Examples

Show the 402 offer without paying:

```bash
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](https://nodely.io/docs/x402/payment#client-example-nodejs):

```js
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](https://x402.api.nodely.io/docs/).