Documentation

Everything you need to call x402search from an agent. All examples assume Base mainnet with real USDC; swap to Base Sepolia + testnet USDC for development.

The endpoint

POST https://x402search.app/v1/search
Content-Type: application/json
X-Payment: <base64 of signed EIP-3009 authorization>    (second call)

{"query": "transformer inference optimization", "count": 10}

The handshake

Call without X-Payment. You get 402 Payment Required with a PaymentRequirements describing the amount, asset, recipient, chain.
Your wallet signs an EIP-3009 TransferWithAuthorization for that exact amount to that recipient. Any x402 client library will do this for you.
Resubmit the same request with X-Payment: base64(json(payload)). We call the facilitator's /verify, run the search, then /settle.
On success you get 200 OK with the search results and a X-Payment-Response header containing the on-chain tx hash.

Pricing

Scenario	micro-USDC	USD
Fresh query (hits upstream)	2500	$0.0025
Cache hit (served from memory)	1000	$0.001

You still pay for cache hits, but at 40% of the upstream price. Empty results and upstream errors cost nothing — settlement happens only after a billable result lands.

Example — Python with x402 helpers

from x402.clients.httpx import x402_payment_required_hook
from eth_account import Account
import httpx

account = Account.from_key("0x...")
client = httpx.Client(event_hooks={"response": [x402_payment_required_hook(account)]})

resp = client.post(
    "https://x402search.app/v1/search",
    json={"query": "transformer inference optimization", "count": 10},
)
print(resp.json()["results"])
print("tx:", resp.headers["X-Payment-Response"])

Example — raw HTTP

# 1) First call: no X-Payment
curl -X POST https://x402search.app/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"news","count":5}'
# → 402 with PaymentRequirements. Sign payload with EIP-3009.

# 2) Retry with signed payload
curl -X POST https://x402search.app/v1/search \
  -H "Content-Type: application/json" \
  -H "X-Payment: eyJzY2hlbWUiOi4uLn0=" \
  -d '{"query":"news","count":5}'
# → 200 with results + X-Payment-Response: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=

Query parameters

Field	Type	Description
`query`	string	Up to 128 chars after filter operators are appended.
`count`	int	1–50 (default 10).
`include_sites`	string[]	Added to query as `site:x.com site:y.com`.
`exclude_sites`	string[]	Added as `-site:x.com`.
`time_range`	enum	one_day · one_week · one_month · one_year
`start_date` / `end_date`	YYYY-MM-DD	Explicit range; overrides `time_range`.
`need_content`	bool	Fetch full-page content (counts against upstream budget).

Response schema

{
  "query_echo": "transformer inference optimization",
  "results": [{
    "result_kind": "web",
    "url": "https://arxiv.org/abs/...",
    "title": "...",
    "abstracts": {
      "short": {"text": "...", "trust": "display_only"},
      "query_related": {"text": "...", "trust": "llm_safe"},
      "body_full": {"text": null, "trust": "llm_safe"}
    },
    "relevance": {"score_0_1": 0.9, "raw": {...}},
    "authority": {"tier": "very_high", "raw": {...}}
  }],
  "amount_micro_usdc": 2500,
  "cached": false
}

Why the three-tier abstracts

Upstream vendors label summary fields inconsistently — one vendor's content is the full body, another's is a short summary. We don't match by field name; we explicitly map each vendor to short / query_related / body_full with per-tier trust so you know which text is safe to feed an LLM.

Receipts

GET https://x402search.app/v1/receipts?wallet=0xC0ffee...&limit=50

{
  "wallet": "0xc0ffee...",
  "receipts": [{
    "query": "...",
    "result_count": 10,
    "amount_micro_usdc": 2500,
    "tx_hash": "0x...",
    "cached": false,
    "created_at": "2026-10-27T..."
  }]
}

Public, read-only. Agents can self-reconcile without trusting us — every receipt points to a tx on Base that you can verify independently.

Error semantics

HTTP	Meaning
402	X-Payment missing, malformed, or facilitator says invalid.
400	Query too long, count out of range, bad time filter. Checked before verify.
409	Payment payload replayed. Use a fresh nonce.
502	Upstream error or empty billable result, or settlement failed. No charge.
503	All upstream keys circuit-broken. No charge.

Configuration

Env var	Default	Notes
`SH_X402_PAY_TO_ADDRESS`	—	Required. Where USDC lands.
`SH_X402_NETWORK`	base	base \| base-sepolia
`SH_X402_FACILITATOR_URL`	https://x402.org/facilitator	Default facilitator. Minimum amount: $0.001.
`SH_PRICE_PER_SEARCH_MICRO_USDC`	2500	$0.0025 default.
`SH_CACHE_HIT_PRICE_MICRO_USDC`	1000	$0.001 default (facilitator floor).