Decide what you are pricing
Not every call. Reading a page must stay free — a viewer never authenticates, and a paid read would break every share. The natural thing to price is issuing a key, or a one-time unlock such as making a link permanent. Pick the smallest surface that recovers your cost; everything you leave free is a request you never have to settle.
Emit the challenge
On the priced endpoint, answer the first unpaid call with 402 and a body the
client can act on: amount, asset, recipient, nonce.
HTTP/2 402 Payment Required
Content-Type: application/json
{ "amount": "…", "asset": "…", "pay_to": "…", "nonce": "…" }The nonce is what stops a settled proof being replayed against a second request.
Verify settlement with a facilitator
You do not want your Worker watching a chain. A facilitator takes the signed authorization, settles it, and hands back a proof you can check cheaply. The trust you are taking on is that the facilitator settled what it claims — which is why production x402 lives or dies on the facilitator, not the Worker.
Record what was provisioned
A payment buys a specific thing: this key, this unlock, this window. Store that, keyed by
the nonce, so the retry can be checked against it and a refund has something to reverse. In
this deployment that is one more D1 table next to rate_limits and
oauth_revocations.
Wire the retry
The client retries the original request with the proof attached in a header; you verify the proof against the recorded provision and answer normally.
curl -i https://read.botook.ai/api-keys -X POST \
-H "X-Payment: <proof of settlement>"
HTTP/2 201The endpoint's happy path is unchanged — it just gained a gate in front.
What you already have
link_walletand the account model, so the payer has a durable identity.- A rate limiter and a revocation list, so the new table has neighbours to copy.
- OAuth 2.1, so a client that pays can also be one that registered itself.
What you do not have, and would be buying: a facilitator relationship, a settlement asset, and a dispute process. Those are a business, not a patch.
Could I price reads instead of key issuance?
You could, but every shared link would then demand payment from its reader, which defeats the point of a share. Price the author's side, not the viewer's.
Do I have to use a facilitator?
No — the recipient can verify settlement directly. A facilitator exists so your edge Worker does not have to hold chain state or wait on confirmation latency inside a request.