[Agents] Expand x402 documentation into dedicated section

[CameronWhiteside]

Summary

Expands the x402 documentation from a single overview page into a dedicated section with focused how-to guides for each integration pattern.

x402 is an open payment standard built on HTTP 402 that enables programmatic payments without accounts or API keys. This restructure helps developers find the right guide faster:

• Charge for HTTP content — Gate APIs and web pages using a Worker proxy template
• Charge for MCP tools — Add per-call pricing to MCP servers with paidTool
• Pay from Agents SDK — Wrap MCP clients with withX402Client for automatic or human-approved payments
• Pay from coding tools — Add x402 support to OpenCode and Claude Code

The previous single-page format mixed charging and paying use cases with marketing-style framing. The new structure uses direct technical language and links to GitHub templates for configuration details rather than duplicating content.

Documentation checklist

• The change adheres to the documentation style guide.
• Files which have changed name or location have been allocated redirects. (The old /agents/x402/ path now serves the index page, so existing links continue to work.)

[threepointone]

/bonk review this PR. lean on the diataxis framework

[ask-bonk]

Good restructure overall — splitting the single page into focused how-to guides with clear charge/pay separation is a solid improvement. The content is well organized and follows the style guide conventions.

I found a few code example issues and one documentation clarity point. See inline comments.

[ask-bonk]

Minor: the text says "Define protected routes in wrangler.jsonc" but the code block language is ```json. Since JSONC supports comments and the file extension is .jsonc, consider using ```jsonc for accuracy — though note jsonc may not be in the supported languages list for syntax highlighting (check if it falls back to txt). Alternatively, the <WranglerConfig> component could be used here for consistency with other docs, but since this is a template-specific vars fragment rather than a full Wrangler config, the raw block is fine.

[CameronWhiteside]

goign json here on the body type - but actually simplified this significantly

[ask-bonk]

The review has been submitted. Here's a summary of what I found:

Review Summary

Overall: Good restructure. The split from a single page into focused how-to guides with clear "charge" vs "pay" separation is well-organized and follows the docs style guide.

Issues found (7 inline comments):

1. pay-from-agents-sdk.mdx:19-20 — onStart() is missing async (uses await inside), and env.WORKER_URL should be this.env.WORKER_URL (Agent class uses this.env for bindings)

2. charge-for-mcp-tools.mdx:23 — env.MCP_ADDRESS is used at module scope, but env is not available there in Workers. Suggested using a placeholder string like "0xYourWalletAddress" for consistency

3. charge-for-http-content.mdx:84 — process.env.SERVER_ADDRESS is not available in Workers without Node.js compat. Suggested a placeholder string instead

4. pay-with-tool-plugins.mdx:116 — Path mismatch: settings.json references .claude/dist/handle-x402.mjs but the source is created at .claude/scripts/handle-x402.mjs. The relationship is not explained

5. pay-with-tool-plugins.mdx:179 — The cd .claude && npm run build step assumes a package.json that is never shown. Readers would not know how to set this up

6. charge-for-http-content.mdx:23 — Minor: code block uses ```json for what's described as a wrangler.jsonc file

github run

[threepointone]

Hmm I don't know why it isn't running the workflows, probably because this is happening off a fork. We need those workflows to run to see how it looks

[Oxyjun]

What are we deploying here? Can we add in a sentence to explicitly describe?

[threepointone]

please don't land this just yet until we chat!