{ "slug": "http-402-paywall-implementation", "title": "Implementing an HTTP 402 Paywall an Agent Can Actually Pay", "description": "A working implementation guide for machine-payable content: the 402 response body, Link headers, key issuance and validation, caching rules, and the mistakes that make a 402 gate unpayable.", "kind": "sub", "order": 7, "target_query": "how to implement an HTTP 402 paywall", "secondary_queries": [ "http 402 payment required example response", "machine readable paywall for AI agents", "api key issuance after stripe checkout worker" ], "tags": [ "402", "paywall", "monetization", "agents", "implementation" ], "published": "2026-07-26", "updated": "2026-07-26", "words": 1262, "premium": false, "license": "https://changegamer.ai/license.xml", "canonical": "https://changegamer.ai/articles/http-402-paywall-implementation", "markdown": "https://changegamer.ai/articles/http-402-paywall-implementation.md", "takeaways": [ "A payable 402 has five things in the body: what was blocked, the price, where to pay, exactly how to retry, and links to terms and licence.", "Never gate the terms. If your 402 points at a pricing or licence page, that page must stay free, or the loop cannot close.", "Put the commercial metadata in `Link` headers too, so a `HEAD` request is enough to learn the price.", "Paid responses must be `Cache-Control: no-store`. A CDN that caches a paid body publicly leaks the product.", "Key validation belongs at the edge, in front of the asset — not inside the page. Return the same 402 shape for \"no key\" and \"key of insufficient tier\", differing only in the instruction." ], "outline": [ { "depth": 2, "text": "The loop, in five steps", "anchor": "the-loop-in-five-steps", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#the-loop-in-five-steps" }, { "depth": 2, "text": "Step 1 — The 402 response", "anchor": "step-1-the-402-response", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#step-1-the-402-response" }, { "depth": 2, "text": "Step 2 — Advertise terms in headers as well", "anchor": "step-2-advertise-terms-in-headers-as-well", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#step-2-advertise-terms-in-headers-as-well" }, { "depth": 2, "text": "Step 3 — Issue keys without a human in the loop", "anchor": "step-3-issue-keys-without-a-human-in-the-loop", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#step-3-issue-keys-without-a-human-in-the-loop" }, { "depth": 2, "text": "Step 4 — Validate at the edge, in front of the content", "anchor": "step-4-validate-at-the-edge-in-front-of-the-content", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#step-4-validate-at-the-edge-in-front-of-the-content" }, { "depth": 2, "text": "Step 5 — Caching, or how to leak the product", "anchor": "step-5-caching-or-how-to-leak-the-product", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#step-5-caching-or-how-to-leak-the-product" }, { "depth": 2, "text": "Testing it like an agent would", "anchor": "testing-it-like-an-agent-would", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#testing-it-like-an-agent-would" }, { "depth": 2, "text": "What this does not solve", "anchor": "what-this-does-not-solve", "url": "https://changegamer.ai/articles/http-402-paywall-implementation#what-this-does-not-solve" } ], "faq": [ { "question": "Is HTTP 402 a real status code?", "answer": "Yes — 402 Payment Required is reserved in the HTTP specification and has been \"experimental\" for its whole life, with no standard payment semantics attached. That is precisely why implementations must carry their own machine-readable body: the status code says \"pay\", and your JSON says how." }, { "question": "Should the 402 body include a preview of the content?", "answer": "Include enough for a machine to decide: title, description, section outline, length, last-updated date. Do not include the sellable substance. A buyer that cannot evaluate the purchase defaults to not buying, so an outline usually increases conversion rather than cannibalising it." }, { "question": "Do I need crypto to accept machine payments?", "answer": "No. Ordinary card checkout that issues an API key works: the 402 points at a checkout URL, the buyer completes it, your webhook mints a key, and the agent retries with an `Authorization: Bearer` header. On-chain rails such as x402 add a no-account path for wallet-holding agents and can run alongside." }, { "question": "What status code should an insufficient-tier key return?", "answer": "A 402 with an explicit upgrade instruction is the pragmatic choice — the request is still \"payment required\", just of a different amount. 403 is defensible but tells an agent to give up rather than to buy. Whichever you pick, keep the body shape identical so one parser handles both cases." } ], "body": "Most paywalls are unpayable by machines: they redirect to a marketing page, return 200 with a teaser, or require an email confirmation loop. This is how to build one that a competent agent can complete end to end, which is the money half of [the agent-ready website](/articles/agent-ready-website).\n\nThe wire contract this page implements is documented in [paying for access: the HTTP 402 flow](/resources/paying-for-access-402); the rail comparison is [agentic payment protocols](/resources/agentic-payment-protocols).\n\n## The loop, in five steps\n\n```\n1. GET /resources/premium-thing → 402 + JSON body + Link headers\n2. (agent parses price, terms, payment_url)\n3. buyer/agent completes checkout → your webhook mints a key\n4. GET /resources/premium-thing → with: Authorization: Bearer cg_live_…\n5. 200 OK + Cache-Control: no-store → content\n```\n\nEverything below is detail on making each step machine-completable.\n\n## Step 1 — The 402 response\n\nThis body is your entire sales page for a machine buyer. Five things are mandatory:\n\n```json\n{\n \"error\": \"payment_required\",\n \"resource\": \"premium-thing\",\n \"title\": \"The Premium Thing\",\n \"description\": \"What this resource contains, in one sentence.\",\n \"outline\": [\"Section one\", \"Section two\", \"Section three\"],\n \"words\": 2400,\n \"updated\": \"2026-07-20\",\n \"price\": 5,\n \"currency\": \"EUR\",\n \"payment_url\": \"https://buy.example.com/premium-key\",\n \"how_to_pay\": \"Buy an access key at payment_url, then retry this request with header 'Authorization: Bearer '.\",\n \"pricing\": \"https://example.com/api/pricing.json\",\n \"terms\": \"https://example.com/terms.md\",\n \"license\": \"https://example.com/license.xml\",\n \"free_alternatives\": [\"https://example.com/llms.txt\", \"https://example.com/resources/overview.md\"]\n}\n```\n\nDesign notes that matter more than they look:\n\n- **`how_to_pay` is prose for a machine.** Spell out the header name and the retry. An agent that has to infer your auth scheme will guess wrong.\n- **`outline` and `words` are the preview.** Structure without substance: enough to evaluate, not enough to substitute.\n- **`free_alternatives` reduces hostility.** An agent that hits a wall and is told what it *can* have stays on your site.\n- **Content type is JSON.** Never HTML. An error page is not a payment interface.\n\n## Step 2 — Advertise terms in headers as well\n\nHeaders let a `HEAD` request learn the commercial terms with no body transfer:\n\n```http\nHTTP/1.1 402 Payment Required\nContent-Type: application/json; charset=utf-8\nCache-Control: no-store\nLink: ; rel=\"payment\",\n ; rel=\"payment-manifest\",\n ; rel=\"pricing\",\n ; rel=\"license\"\n```\n\nPair this with a machine-readable payment manifest at a stable URL describing your accepted methods and the retry loop, plus a pricing catalogue listing every tier. Those two documents are what let an agent decide *without* triggering a 402 first — see [JSON API for agents](/resources/json-api) for the shape.\n\n## Step 3 — Issue keys without a human in the loop\n\nThe payment provider's webhook is what turns a completed checkout into an entitlement:\n\n```ts\n// Webhook handler (Cloudflare Worker + KV shown; any KV/DB works)\nexport async function onPaymentCompleted(event: CheckoutEvent, env: Env) {\n // 1. Verify the webhook signature. Never mint on an unverified event.\n if (!(await verifySignature(event.raw, env.WEBHOOK_SECRET))) {\n return new Response(\"bad signature\", { status: 400 });\n }\n // 2. Idempotency: the same event may arrive more than once.\n const existing = await env.KEYS.get(`session:${event.sessionId}`);\n if (existing) return json({ status: \"duplicate\", key: existing });\n\n // 3. Mint a prefixed, high-entropy key. Prefix = greppable in logs and\n // in leaked-secret scanners.\n const key = `cg_live_${crypto.randomUUID().replace(/-/g, \"\")}`;\n const record = { tier: event.tier, created: new Date().toISOString() };\n await env.KEYS.put(`key:${key}`, JSON.stringify(record));\n await env.KEYS.put(`session:${event.sessionId}`, key);\n\n // 4. Deliver: return it in the response AND make it retrievable once\n // at a URL bound to the session id, so an agent that lost the\n // response body can still fetch it.\n return json({ status: \"ok\", key, tier: event.tier });\n}\n```\n\nThree rules learned the hard way:\n\n1. **Idempotency is not optional.** Payment webhooks retry. Without a session-keyed guard you will mint several keys for one purchase and lose the ability to reason about entitlements.\n2. **Log the tier, never the key.** Telemetry that records minted keys turns your log store into a credential store.\n3. **Provide a retrieval path.** An agent may complete checkout in a context where it cannot keep the response. A `GET /key?session=…` that returns the key for a completed session — and a clear \"pending\" state if the webhook has not landed yet — closes that gap.\n\n## Step 4 — Validate at the edge, in front of the content\n\nValidation must happen before the asset is served, not inside a rendered page. In a Workers-style architecture:\n\n```ts\nexport default {\n async fetch(req: Request, env: Env) {\n const url = new URL(req.url);\n const slug = premiumSlugFor(url.pathname); // null for free paths\n if (!slug) return env.ASSETS.fetch(req); // free content, untouched\n\n const key = bearer(req) ?? req.headers.get(\"x-api-key\");\n const tier = key ? await tierOf(key, env) : null;\n\n if (tier && tierAllows(tier, minTierFor(slug))) {\n const res = await env.ASSETS.fetch(req);\n return noStore(res); // never shared-cache paid bodies\n }\n return build402(slug, env, { upgrade: tier !== null });\n },\n};\n```\n\nDetails that decide whether this is robust:\n\n- **Accept two header spellings.** `Authorization: Bearer ` and `X-API-Key: `. Agents differ; accepting both costs one line.\n- **One 402 builder, used everywhere.** The HTTP gate, the tier-upgrade path and any tool-call interface (MCP, for instance) must return the same shape from the same function, or your documented contract and your behaviour will drift.\n- **Same shape for \"no key\" and \"wrong tier\".** Only `how_to_pay` changes: buy, versus upgrade. One parser handles both.\n- **Never paywall index or policy files.** Keep `robots.txt`, `llms.txt`, sitemaps, your licence and your terms outside the gate by construction — ideally by routing, so no future code change can accidentally include them. A payment loop whose terms are behind the paywall is a dead end.\n\n## Step 5 — Caching, or how to leak the product\n\nThe single most expensive mistake in this design is a cacheable paid response. Rules:\n\n| Response | Cache-Control | Why |\n|---|---|---|\n| Free content | `public, max-age=…` | Normal caching; cheap for everyone |\n| 402 | `no-store` | Prices and instructions change; never serve a stale wall |\n| Paid 200 | `no-store` | A shared cache would serve the paid body to unauthenticated clients |\n\nIf your CDN applies blanket caching headers by path pattern, verify that paid paths are excluded — with an actual request, using a key, checking the response headers. Assume nothing about inherited config.\n\n## Testing it like an agent would\n\n```bash\n# 1. Wall present and machine-readable\ncurl -s -i https://example.com/resources/premium-thing.md | head -20\n\n# 2. The advertised terms are reachable WITHOUT paying\ncurl -so /dev/null -w \"%{http_code}\\n\" https://example.com/terms.md\ncurl -so /dev/null -w \"%{http_code}\\n\" https://example.com/license.xml\n\n# 3. A valid key unlocks it, and the response is not cacheable\ncurl -s -i -H \"Authorization: Bearer $KEY\" \\\n https://example.com/resources/premium-thing.md | grep -i cache-control\n\n# 4. An invalid key returns the SAME 402 shape, not a 500\ncurl -s -H \"Authorization: Bearer nope\" \\\n https://example.com/resources/premium-thing.md | head -5\n\n# 5. Free surfaces are untouched by the gate\nfor p in /robots.txt /llms.txt /sitemap.xml; do\n printf \"%s \" \"$p\"; curl -so /dev/null -w \"%{http_code}\\n\" \"https://example.com$p\"\ndone\n```\n\nMake tests 2 and 5 permanent CI assertions. They encode the promise that discovery and terms are free, which is the one invariant that must survive every future refactor.\n\n## What this does not solve\n\nA 402 gate prices access; it does not prevent redistribution, and it does not express a licence. Those are separate layers: RSL states terms, provenance standards make origin verifiable, and neither collects money — see [licensing content for AI training](/articles/licensing-content-for-ai-training). And a gate is only as good as its demand: if you have not measured which content agents want, you are guessing at both the wall and the price, which is the argument of [what to charge AI crawlers](/articles/what-to-charge-ai-crawlers) and [measuring AI agent traffic](/articles/measuring-ai-agent-traffic).", "cluster": { "id": "agent-ready-web", "title": "The agent-ready web", "description": "How to make a website readable, citable, controllable and payable for AI agents and AI crawlers — the operator side of the machine-first web.", "status": "complete", "pillar": { "slug": "agent-ready-website", "title": "The Agent-Ready Website: A Complete Guide to AI Visibility, Access Control and Monetization", "description": "The full operator playbook for making a website work for AI agents and AI crawlers: be fetchable, be readable, be controllable, be payable — with a 30-day implementation plan.", "kind": "pillar", "order": 0, "html": "https://changegamer.ai/articles/agent-ready-website", "markdown": "https://changegamer.ai/articles/agent-ready-website.md", "json": "https://changegamer.ai/api/articles/agent-ready-website.json" }, "articles": [ { "slug": "llms-txt-vs-robots-txt-vs-sitemap", "title": "llms.txt vs robots.txt vs sitemap.xml: Which File Does What", "description": "The three root-level files every agent-ready site publishes, what each one is actually for, and why publishing one does not substitute for the others.", "kind": "sub", "order": 1, "html": "https://changegamer.ai/articles/llms-txt-vs-robots-txt-vs-sitemap", "markdown": "https://changegamer.ai/articles/llms-txt-vs-robots-txt-vs-sitemap.md", "json": "https://changegamer.ai/api/articles/llms-txt-vs-robots-txt-vs-sitemap.json" }, { "slug": "how-to-write-an-llms-txt-file", "title": "How to Write an llms.txt File (Format, Template, and Maintenance)", "description": "A step-by-step guide to writing a useful llms.txt: the exact format, a copy-paste template, what to put under ## Optional, how to validate it, and how to keep it from rotting.", "kind": "sub", "order": 2, "html": "https://changegamer.ai/articles/how-to-write-an-llms-txt-file", "markdown": "https://changegamer.ai/articles/how-to-write-an-llms-txt-file.md", "json": "https://changegamer.ai/api/articles/how-to-write-an-llms-txt-file.json" }, { "slug": "serving-markdown-variants-to-ai-agents", "title": "Serving Markdown Variants to AI Agents: The Cheapest Win in AI Visibility", "description": "How to publish a .md twin of every page — URL patterns, content negotiation, discovery headers, generation pitfalls — and why it cuts what an agent pays to read you.", "kind": "sub", "order": 3, "html": "https://changegamer.ai/articles/serving-markdown-variants-to-ai-agents", "markdown": "https://changegamer.ai/articles/serving-markdown-variants-to-ai-agents.md", "json": "https://changegamer.ai/api/articles/serving-markdown-variants-to-ai-agents.json" }, { "slug": "how-ai-search-engines-choose-sources", "title": "How AI Search Engines Choose Sources (And What You Can Actually Influence)", "description": "What is known, what is claimed and what is speculation about how ChatGPT, Perplexity and AI Overviews pick the pages they cite — and the short list of things a site owner can actually control.", "kind": "sub", "order": 4, "html": "https://changegamer.ai/articles/how-ai-search-engines-choose-sources", "markdown": "https://changegamer.ai/articles/how-ai-search-engines-choose-sources.md", "json": "https://changegamer.ai/api/articles/how-ai-search-engines-choose-sources.json" }, { "slug": "should-you-block-ai-crawlers", "title": "Should You Block AI Crawlers? A Decision Framework by Business Model", "description": "Blocking AI crawlers is four separate decisions, not one. A framework that maps each crawler class to what it costs and earns you, by business model, with the exact robots.txt for each answer.", "kind": "sub", "order": 5, "html": "https://changegamer.ai/articles/should-you-block-ai-crawlers", "markdown": "https://changegamer.ai/articles/should-you-block-ai-crawlers.md", "json": "https://changegamer.ai/api/articles/should-you-block-ai-crawlers.json" }, { "slug": "what-to-charge-ai-crawlers", "title": "What to Charge AI Crawlers: Pricing Models for Machine Buyers", "description": "Per-crawl, per-resource, corpus licence or subscription key — the four ways to price AI access, the arithmetic behind each, and why pricing before you have demand data is the standard mistake.", "kind": "sub", "order": 6, "html": "https://changegamer.ai/articles/what-to-charge-ai-crawlers", "markdown": "https://changegamer.ai/articles/what-to-charge-ai-crawlers.md", "json": "https://changegamer.ai/api/articles/what-to-charge-ai-crawlers.json" }, { "slug": "http-402-paywall-implementation", "title": "Implementing an HTTP 402 Paywall an Agent Can Actually Pay", "description": "A working implementation guide for machine-payable content: the 402 response body, Link headers, key issuance and validation, caching rules, and the mistakes that make a 402 gate unpayable.", "kind": "sub", "order": 7, "html": "https://changegamer.ai/articles/http-402-paywall-implementation", "markdown": "https://changegamer.ai/articles/http-402-paywall-implementation.md", "json": "https://changegamer.ai/api/articles/http-402-paywall-implementation.json" }, { "slug": "structured-data-for-ai-agents", "title": "Structured Data for AI Agents: Which Schema.org Types Earn Their Keep", "description": "Most schema.org markup is invisible to machine readers. The types that are worth the effort for AI agents, how to emit them without drift, and what to build instead of more markup.", "kind": "sub", "order": 8, "html": "https://changegamer.ai/articles/structured-data-for-ai-agents", "markdown": "https://changegamer.ai/articles/structured-data-for-ai-agents.md", "json": "https://changegamer.ai/api/articles/structured-data-for-ai-agents.json" }, { "slug": "json-api-design-for-agents", "title": "JSON API Design for AI Agents: Endpoints They Prefer Over Scraping", "description": "How to publish read-only JSON endpoints that agents choose over scraping your HTML: discovery index, stable shapes, freshness signals, bulk exports, and errors a machine can act on.", "kind": "sub", "order": 9, "html": "https://changegamer.ai/articles/json-api-design-for-agents", "markdown": "https://changegamer.ai/articles/json-api-design-for-agents.md", "json": "https://changegamer.ai/api/articles/json-api-design-for-agents.json" }, { "slug": "measuring-ai-agent-traffic", "title": "Measuring AI Agent Traffic: Server-Side Telemetry That Answers Real Questions", "description": "Why client-side analytics miss AI agents entirely, the minimum row schema to log, the five queries worth running, and how to tell a real crawler from a spoofed user agent.", "kind": "sub", "order": 10, "html": "https://changegamer.ai/articles/measuring-ai-agent-traffic", "markdown": "https://changegamer.ai/articles/measuring-ai-agent-traffic.md", "json": "https://changegamer.ai/api/articles/measuring-ai-agent-traffic.json" }, { "slug": "licensing-content-for-ai-training", "title": "Licensing Content for AI Training: RSL, Terms, and Provenance", "description": "How to publish machine-readable licence terms for AI use — what RSL is, what it does and does not do, how it differs from robots.txt and Content Signals, and where provenance standards fit.", "kind": "sub", "order": 11, "html": "https://changegamer.ai/articles/licensing-content-for-ai-training", "markdown": "https://changegamer.ai/articles/licensing-content-for-ai-training.md", "json": "https://changegamer.ai/api/articles/licensing-content-for-ai-training.json" }, { "slug": "mcp-server-as-distribution-channel", "title": "Running an MCP Server as a Distribution Channel for Your Content", "description": "Why a content site should expose an MCP server, which tools to ship, how discovery and authentication work, how to gate paid tools, and the honest limits of the channel.", "kind": "sub", "order": 12, "html": "https://changegamer.ai/articles/mcp-server-as-distribution-channel", "markdown": "https://changegamer.ai/articles/mcp-server-as-distribution-channel.md", "json": "https://changegamer.ai/api/articles/mcp-server-as-distribution-channel.json" }, { "slug": "why-ai-agents-cant-read-your-site", "title": "Why AI Agents Can't Read Your Site: Twelve Failure Modes and How to Find Them", "description": "A diagnostic catalogue of the twelve reasons AI agents and crawlers fail on real sites — from silent WAF blocks to JS-only rendering — each with the command that detects it and the fix.", "kind": "sub", "order": 13, "html": "https://changegamer.ai/articles/why-ai-agents-cant-read-your-site", "markdown": "https://changegamer.ai/articles/why-ai-agents-cant-read-your-site.md", "json": "https://changegamer.ai/api/articles/why-ai-agents-cant-read-your-site.json" } ] }, "navigation": { "pillar": { "slug": "agent-ready-website", "title": "The Agent-Ready Website: A Complete Guide to AI Visibility, Access Control and Monetization", "description": "The full operator playbook for making a website work for AI agents and AI crawlers: be fetchable, be readable, be controllable, be payable — with a 30-day implementation plan.", "kind": "pillar", "order": 0, "html": "https://changegamer.ai/articles/agent-ready-website", "markdown": "https://changegamer.ai/articles/agent-ready-website.md", "json": "https://changegamer.ai/api/articles/agent-ready-website.json" }, "previous": { "slug": "what-to-charge-ai-crawlers", "title": "What to Charge AI Crawlers: Pricing Models for Machine Buyers", "description": "Per-crawl, per-resource, corpus licence or subscription key — the four ways to price AI access, the arithmetic behind each, and why pricing before you have demand data is the standard mistake.", "kind": "sub", "order": 6, "html": "https://changegamer.ai/articles/what-to-charge-ai-crawlers", "markdown": "https://changegamer.ai/articles/what-to-charge-ai-crawlers.md", "json": "https://changegamer.ai/api/articles/what-to-charge-ai-crawlers.json" }, "next": { "slug": "structured-data-for-ai-agents", "title": "Structured Data for AI Agents: Which Schema.org Types Earn Their Keep", "description": "Most schema.org markup is invisible to machine readers. The types that are worth the effort for AI agents, how to emit them without drift, and what to build instead of more markup.", "kind": "sub", "order": 8, "html": "https://changegamer.ai/articles/structured-data-for-ai-agents", "markdown": "https://changegamer.ai/articles/structured-data-for-ai-agents.md", "json": "https://changegamer.ai/api/articles/structured-data-for-ai-agents.json" } }, "resources": [ { "slug": "paying-for-access-402", "html": "https://changegamer.ai/resources/paying-for-access-402", "markdown": "https://changegamer.ai/resources/paying-for-access-402.md", "json": "https://changegamer.ai/api/resources/paying-for-access-402.json" }, { "slug": "agentic-payment-protocols", "html": "https://changegamer.ai/resources/agentic-payment-protocols", "markdown": "https://changegamer.ai/resources/agentic-payment-protocols.md", "json": "https://changegamer.ai/api/resources/agentic-payment-protocols.json" }, { "slug": "access-and-pricing", "html": "https://changegamer.ai/resources/access-and-pricing", "markdown": "https://changegamer.ai/resources/access-and-pricing.md", "json": "https://changegamer.ai/api/resources/access-and-pricing.json" }, { "slug": "json-api", "html": "https://changegamer.ai/resources/json-api", "markdown": "https://changegamer.ai/resources/json-api.md", "json": "https://changegamer.ai/api/resources/json-api.json" } ] }