x402 quickstart

This page shows the shape of calling an x402-paid read from code. It is illustrative: endpoint paths, prices, and network details are configuration, and the paid read API is still in development. Use it to understand the integration pattern, not as a published contract.

The client side

On the client, an x402-aware fetch wrapper handles the payment step for you. You make a normal request, and when the server answers with a 402 and a quote, the wrapper signs the authorization locally, lets the facilitator settle, and returns the final response. From your code it looks like one call.

import { wrapFetchWithPayment } from "x402-fetch";

// A wallet client that can sign the payment authorization locally.
// The signer stays on your side; no key is sent to the server.
const fetchWithPay = wrapFetchWithPayment(fetch, walletClient);

// Looks like a normal request. The 402 quote, the local signature,
// and the onchain settlement are handled inside the wrapper.
const res = await fetchWithPay("https://<read-host>/v1/read?sym=BTCUSDT");
const read = await res.json();

console.log(read);

What happens under the hood

The single call above expands into the flow from the x402 overview:

1. The wrapper sends GET /v1/read?sym=BTCUSDT.
2. The server replies 402 with a quote in USDC.
3. The wrapper signs a payment authorization with your wallet, locally.
4. A facilitator settles the payment onchain.
5. The server returns 200 and the read, which the wrapper passes back to you.

Your code sees a normal response. The payment is the only addition, and it is automatic.

The server side, in brief

On the server, a payment middleware sits in front of the read endpoints. It quotes a price per route, verifies that an incoming request carries a valid settled payment, and only then forwards the request to the underlying read. Endpoints without a valid payment receive the 402 and quote instead of the data. The price per route, the asset, and the facilitator are configuration.

Designing prices

Because pricing is per request and can go down to a fraction of a cent, you can price cheap, high-frequency reads differently from heavier ones. A lightweight market read might cost a fraction of a cent, while a richer composed read costs a few cents. These are examples, the point is that the unit of billing is one call, not one month.

Status and caveats

The paid read API is in active development, so treat every path and price here as a placeholder. When you integrate, settle on a public network the standard supports, start against a test network before mainnet, and keep your signer on your side at all times. See Security and disclaimers.