x402 protocol family

x402 turns an HTTP 402 Payment Required into a real
payment handshake: a server answers 402 with the price, the caller pays in USDC
on Base, then retries the request with proof of payment in an X-PAYMENT header.
The Blockchain0x x402 packages implement both sides for Node, Python, Go, and
Ruby.

The handshake

1. The caller requests a protected resource and gets 402 with a body listing
   accepted payment requirements (scheme exact-usdc, network, amount, recipient).
2. The caller pays the requirement on-chain (USDC transfer on Base).
3. The caller retries with an X-PAYMENT header carrying the attested transfer
   (paymentRequestId, txHash, payerAddress, amountUsdc, network).
4. The server verifies the proof and settles the invoice via
   paymentRequests.settle, then serves the resource.

Wire primitives (Node)

The default export (@blockchain0x/x402) gives you the raw building blocks -
parse402Response and parsePaymentHeader to read the wire, buildPaymentHeader
to write it, and the X402WireError type. A minimal pay-side flow built straight
from those primitives:

const res = await fetch(url);
if (res.status !== 402) {
  return res;
}

const challenge = await parse402Response(res); // the server's payment requirements
console.log('payment required:', challenge);

// ...pay the requirement on-chain, then attest the transfer:
const payment: ExactUsdcPayment = { scheme: 'exact-usdc', version: 1, ...attest };
return fetch(url, { headers: { 'X-PAYMENT': buildPaymentHeader(payment) } });

Pay-side client

For the full automatic flow, @blockchain0x/x402/client wraps fetch:
createX402Client({ sdk, agentId?, confirmTimeoutSeconds?, confirmPollMs? })
returns a drop-in fetch that, on a 402, pays the requirement through your
Blockchain0x SDK, waits for the transfer to confirm, and retries the request with
the X-PAYMENT header - all transparently. Pass the Blockchain0x client as sdk.

Server adapters

To charge for your own endpoints, mount an adapter that emits the 402, verifies
the returned X-PAYMENT, and settles the invoice:

• Express - import { createX402Middleware } from '@blockchain0x/x402/server/express'
• Fastify - import { createX402Plugin } from '@blockchain0x/x402/server/fastify'

Both take the same adapter options and delegate settlement to
sdk.paymentRequests.settle - the adapter is a thin verification shim; the
canonical settlement happens server-side against the transactions table.

Next

• SDKs overview - the core SDK surface.
• Send payments and idempotency - autonomous spend.