Skip to main content
AI agents can pay for Ceramic Search per request, with no account and no API key. The Search API accepts payment through the Cloudflare Monetization Gateway using x402, an open protocol for paying over HTTP. Payments are made in USDC on Base.

​
Prerequisites

To try the example, you need:
  • Node.js 20 or later
  • A wallet with USDC on Base mainnet. USDC on another chain or a testnet won’t work.

x402 Search Agent

A complete example with a research agent, spending caps, and a step-by-step curl demo.

​
How it works

  1. You send a search request without an API key.
  2. The Gateway responds with 402 Payment Required and a PAYMENT-REQUIRED header describing the price, network, and recipient.
  3. Your client signs a USDC authorization for exactly that amount and retries the request with a PAYMENT-SIGNATURE header.
  4. The Gateway verifies the payment, forwards the request to Ceramic, and returns the search results with a PAYMENT-RESPONSE receipt.
A few things to know:
  • Failed searches cost nothing. The Gateway only settles payment after a successful response.
  • You don’t need ETH for gas. The Gateway submits and pays for the on-chain transfer.
  • Your private key never leaves your client. It signs a one-time authorization for the quoted amount, valid for a limited window.
  • The price comes from the 402 response. Check the PAYMENT-REQUIRED header for the current price per search.