Knowledge Base · Payments & x402
Charging per message: x402 on top of a chat endpoint
The symptom
There was no billing concept at all: one endpoint, one model call, no notion of who had paid or how much.
What was actually wrong
The service needed a price, a per-request invoice, a settlement check on the incoming request, and a durable per-wallet balance for the browser flow — without a payment processor, since the payments settle on a public chain.
The fix
The API returns a payment challenge with a nonce, the recipient and the exact amount in atomic units when the caller asks for an invoice; the same endpoint accepts the settled payment receipt in a request header and verifies it against the invoice before serving the answer, spending the nonce. For browser users, a wallet top-up path credits messages and the counter is decremented per answer.
What we took away
Design the invoice to be single-use and bind it to the answer it pays for. Machine-to-machine usage and human usage pull in different directions — support both, but keep one verification path so the rules stay consistent.