A payment Worker should be boring before it is monetized.

Cloudflare's Agents docs now describe x402 and MPP as agentic-payment paths for HTTP resources and MCP tools. That makes the edge gate important: the Worker should return a readable 402, keep paid responses out of shared caches, and refuse to serve protected content until verification is real.

open starter checklist cors guide run checker Cloudflare docs attack map

runtime: Worker
gate: HTTP 402
cache: no-store/private

worker.gate

$ npm test
402 challenge: no-store, private
preflight: allows x-payment
vary: origin + payment headers
paid path: refuses placeholder payment
result: safe until verifier is wired

worker checklist

The launch contract for an edge payment gate.

402

Challenge before content

Unauthenticated paid routes should return a structured 402 with amount, resource, network, and payee data before any protected response body is generated.

cors

Readable to browser agents

OPTIONS must allow content-type,x-payment, and the actual 402 response must include Access-Control-Allow-Origin plus exposed payment headers.

cache

No shared cache reuse

Use Cache-Control: no-store, private on payment challenges and protected responses, then vary on origin and payment-relevant headers.

verify

No grant before verification

The starter deliberately returns 501 after a placeholder payment header. That is safer than accidentally shipping paid content before settlement validation exists.

resource

Bind the exact route

Top-level resource metadata and accept-level resource echo should point to the same canonical HTTPS URL the agent is buying.

logs

Keep receipts without prompts

Log request ids, challenge ids, route, rail, and verification result. Do not place prompts, PII, API keys, or wallet secrets in payment metadata.

starter map

The public repo is intentionally small.

The starter is not a fake payment processor. It is a safe edge shape to copy before adding a real x402 or MPP verifier. The important part is that every risky default is explicit.

src/worker.mjs
  OPTIONS /paid/report        -> 204 CORS preflight
  GET/POST /paid/report       -> 402 payment challenge
  GET/POST with X-PAYMENT     -> 501 until verifier is wired
  GET /health                 -> public cacheable health check

test/smoke.mjs
  verifies no-store/private, Vary, CORS,
  resource echo, and no grant before verification

Start from the repo, wire your actual verifier, then run the no-payment checker against the deployed Worker before you announce the paid route.

Open the Worker starter or run the broader x402 Surface Check.

commands

Smoke-test the gate before promotion.

npm checker

local proof

git clone https://github.com/TateLyman/x402-cache-safe-worker
cd x402-cache-safe-worker
npm test

npx --yes x402-surface-check@latest \
  --endpoint --method POST https://worker.example.com/paid/report \
  --origin https://app.example.com \
  --body '{"report":"demo"}'

why now

The platform layer is normalizing paid agent calls.

Cloudflare

Workers and MCP tools

Cloudflare documents x402 and MPP for agentic payments, including HTTP content, MCP tools, and Agents SDK client flows.

official docs

AWS

Managed spend governance

AgentCore Payments preview points the market toward session spending limits, wallet authentication, observability, and x402 negotiation as managed infrastructure.

official announcement

research

Attack surface is real

May 2026 x402 attack research highlights finality, replay, caller binding, header/cache handling, and discovery steering as launch controls, not theoretical footnotes.

open paper

paid pass

Need a Worker, MCP tool, or x402 route checked before public launch?

Send the deployed route, manifest, repo, intended origin, and what a paid call is supposed to unlock.

send scope