DEV Community

AgentSearch
AgentSearch

Posted on Originally published at agentsearchhq.com

Search + Read in One Paid Call

#ai #api #webdev #x402

AgentSearch has a new x402 route that searches the web and returns extracted page text in a single paid call.

Endpoint: POST https://api.agentsearchhq.com/x402/v1/search_and_read

The call returns the top 3 results (up to 5) with extracted page text. It costs $0.015 USDC per call on Base, via x402. There is no account and no API key. You are charged only when at least one page returns text.

It's in the packages too: the tool is agentsearch_search_and_read in @agentsearchhq/agentsearch-mcp 1.7.0, langchain-agentsearch 0.6.0, crewai-agentsearch 0.4.0, llama-index-tools-agentsearch 0.4.0, openai-agents-agentsearch 0.4.0 and @agentsearchhq/langchain 0.4.0; n8n-nodes-agentsearch 0.6.0 adds the searchAndRead operation.

One payment, not four

Used separately, a search plus three extracts is four payments: $0.008 + 3 × $0.007 = $0.029. The combined call is $0.015 USDC — about 48% less — and only one settlement.

Standalone search ($0.008) and extract ($0.007) stay available when you only need one of those steps.

Request

POST https://api.agentsearchhq.com/x402/v1/search_and_read with a JSON body:

  • query (required)
  • num_results (default 3, max 5)
  • max_chars (default 8000, max 20000)
  • render_fallback (default false)

A successful call returns results with extracted page text. Documented result fields include title, URL, snippet, score, domain, markdown, chars, truncated, extract_status and source, plus a top-level extracted_count.

How payment works

This uses the same x402 flow as the rest of the AgentSearch API:

  1. POST the request without payment. The API responds with HTTP 402 Payment Required. Terms are in the PAYMENT-REQUIRED header (base64 JSON). For this route the amount is 15000 atomic USDC, which is $0.015. Nothing is charged at this step.
  2. Retry the same request with a signed x402 payment (PAYMENT-SIGNATURE). Any x402 client works — curl, @x402/fetch, Python, or another wallet-capable client.
  3. A successful paid call returns results with extracted page text (receipt in PAYMENT-RESPONSE). You are charged only when at least one page returns text. Empty or failed calls are not billed.

curl example

The unpaid request below is the official example from the docs. It should return HTTP 402 and is not charged:

curl -si https://api.agentsearchhq.com/x402/v1/search_and_read \
  -H 'content-type: application/json' \
  -d '{"query":"x402 payment protocol","num_results":3}'
# HTTP 402, amount 15000 = $0.015, payTo 0xC49B…C337, nothing charged
Enter fullscreen mode Exit fullscreen mode

Then retry the same body with any x402 client so it can sign the 402 and send PAYMENT-SIGNATURE. A @x402/fetch sketch, using the same wrapper as the other AgentSearch x402 routes:

// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await fetchWithPayment(
  "https://api.agentsearchhq.com/x402/v1/search_and_read",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      query: "x402 payment protocol",
      num_results: 3,
      max_chars: 8000,
      render_fallback: false,
    }),
  },
);
console.log(res.status, await res.json()); // 200 + extracted page text; receipt in PAYMENT-RESPONSE
Enter fullscreen mode Exit fullscreen mode

When to use it

Use this when an agent needs page text, not just search snippets, and you want search-plus-read in one payment. If you only need URLs and snippets, standalone search is enough. If you already have URLs, standalone extract is enough.

No signup. Pay per successful call in USDC on Base.

Top comments (0)