Skip to main content

What is x402?

x402 is an open payment standard built on the HTTP 402 Payment Required status code. It lets clients pay for API access per-request using USDC stablecoins on Base or Solana, with no accounts, API keys, or subscriptions needed. Exa supports x402 on two endpoints: /search and /contents. When you send a request without an API key or payment header, Exa responds with 402 and a PAYMENT-REQUIRED header containing pricing details and the supported payment networks. Your client signs a USDC payment, retries the request with a PAYMENT-SIGNATURE header, and receives the results once settlement confirms on-chain. This is ideal for AI agents that need to autonomously pay for web search without pre-provisioned credentials.
x402 and API key access are independent. If your request includes an x-api-key or Authorization: Bearer header, the normal API key billing flow is used and x402 is bypassed entirely.

Supported endpoints

All other endpoints are not available via x402.

How it works

x402 payment flow sequence diagram: Client sends request to server, gets 402 with PAYMENT-REQUIRED header, creates payment payload, retries with PAYMENT-SIGNATURE, server verifies via facilitator, does work, settles on-chain, returns 200 with results and PAYMENT-RESPONSE

Step 1: Discovery

Send a request to a supported endpoint without an API key or payment header:
You’ll receive a 402 response with a base64-encoded PAYMENT-REQUIRED header. Decoded, it looks like:
The amount is in USDC atomic units (6 decimals), so "7000" = $0.007. The client can pay with any advertised accepts entry it supports. Solana entries include facilitator-provided fields such as extra.feePayer; use the exact entry from the PAYMENT-REQUIRED header when constructing the payment.

Step 2: Pay and retry

Sign the payment with your wallet and re-send the request with a PAYMENT-SIGNATURE header containing your base64-encoded payment payload. The x402 client SDKs handle this automatically.

Step 3: Settlement

Exa verifies your payment signature with the facilitator, then starts on-chain settlement in parallel with processing your request. The response is held until settlement confirms. On success, you receive:
  • HTTP 200 with your results
  • A PAYMENT-RESPONSE header containing the settlement receipt (base64-encoded), including the on-chain transaction hash
If settlement fails, you get 402 with both PAYMENT-RESPONSE (error details) and PAYMENT-REQUIRED (so you can retry).

Pricing

x402 uses the same bundled pricing as API key billing. Prices are calculated upfront based on your request parameters (not actual results returned).

Search (/search)

Adding contents.summary costs an additional $0.001 per result.
x402 requests are capped at 10 results maximum. If you request more than 10, numResults is silently clamped to 10 and pricing is based on 10 results.

Contents (/contents)

Each content type is charged per page/URL: If you request no content types (no text, highlights, or summary), text is enabled by default.

Examples

Quickstart

Install dependencies

No install is needed for cURL, but you’ll need to handle the 402 challenge and payment signing manually. The SDK approach is recommended for production use.
Don’t want to manage private keys? Coinbase Agentic Wallets provide TEE-isolated key management for AI agents. Your agent never sees the private key. The wallet is viem-compatible, so it works directly with @x402/fetch.

Make a paid search request

cURL requires manual payment signing. For production, use the JavaScript or Python SDK which handles the full 402 > sign > retry flow automatically.

Discovery mode (no wallet needed)

Probe pricing without a wallet by sending unauthenticated requests:

Payment networks

Exa advertises every currently supported network in the accepts array. Choose the entry that matches your wallet and registered x402 client scheme. Both use 6-decimal USDC (1000000 = $1.00) and settle on-chain via an x402 facilitator.

Rate limits

x402 has its own rate limiting separate from API key limits: After 5 unauthenticated 402 discovery requests from the same IP within 60 seconds, further requests return 429 Too Many Requests. Making a successful paid request decrements the counter. Per-wallet QPS is enforced across all paid requests from the same wallet address.

Headers reference

Request headers

Response headers

Error codes

FAQ

If your request includes an x-api-key header or Authorization: Bearer token, the API key flow takes priority and x402 is bypassed. They don’t stack. It’s one or the other per request.
Your response is blocked. You receive a 402 with both PAYMENT-RESPONSE (containing the error) and PAYMENT-REQUIRED (so your client can retry). No results are returned until settlement succeeds.
x402 requests enforce a maximum of 10 results per search. If you need more, use the API key flow with a paid plan.
Any EVM-compatible wallet that can sign EIP-712 typed data on Base, or a Solana wallet supported by the x402 SVM client for solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp. The x402 SDK supports viem, ethers, Coinbase Wallet signers, and Solana SVM signers. For EVM-based AI agents, Coinbase Agentic Wallets offer TEE-isolated key management so your agent never handles raw private keys directly.

Resources

Last modified on June 26, 2026