HTTP 402 has been reserved for decades. Most of the web ignored it because cards need a form. Agents don’t have a form. They have a status code, a challenge, and a retry. That’s why 402 is suddenly a product, not trivia.
The loop
- Client calls the route.
- Server returns 402 with how to pay (amount, rail, who).
- Client settles.
- Client retries with proof.
- Server runs the handler and returns the payload.
If step two is “redirect to a hosted page,” you don’t have 402. You have checkout with extra headers. If step four is a cookie from a human login, you don’t have an agent rail.
Payment Required is the handshake. The form is the fallback for humans who still want one.
402 vs what you already have
- API keys — identity and quota, not per-call settlement
- Stripe Checkout — human UI, swipe economics
- Prepaid credits — accounting after the fact
- 402 — this request, this price, then the work
Snippet-shaped mental model
Middleware on the route you already run. Unpaid → 402. Paid → JSON. That’s express-vybe-402. The buyer is a Vybe balance with policy—not a PAN in a prompt.
Read this, then wrap one route. The playground is your local logs: unpaid, paid, once. Collect can list the same SKU for humans. Same ledger.
