Revert "docs(x402): deprecate x402 integration"

README.md

@@ -117,23 +117,24 @@ The agent is a Durable Object, so it needs a binding and a SQLite migration in `
 | **Browser Agents**      | Run agents in the browser tab with `agents/browser`                             |
 | **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls            |
 | **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem          |
+| **x402 Payments**       | Pay-per-call APIs and tools via the x402 protocol                               |
 | **Observability**       | Built-in tracing, metrics, and structured logs                                  |
 | **SQL**                 | Direct SQLite queries via Durable Objects                                       |
 | **React Hooks**         | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration            |
 | **Vanilla JS Client**   | `AgentClient` and `VoiceClient` for non-React environments                      |
 
 ## Packages
 
-| Package                                                 | Description                                                                                  |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| [`agents`](packages/agents)                             | Core SDK — `Agent` class, routing, state, scheduling, MCP, email, workflows, browser agents  |
-| [`@cloudflare/ai-chat`](packages/ai-chat)               | Higher-level AI chat — persistent messages, resumable streaming, tool execution              |
-| [`@cloudflare/think`](packages/think)                   | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools |
-| [`@cloudflare/codemode`](packages/codemode)             | LLMs write executable code that calls your tools, instead of one tool call at a time         |
-| [`@cloudflare/shell`](packages/shell)                   | Sandboxed JS execution + virtual filesystem (`Workspace`) for agents                         |
-| [`@cloudflare/voice`](packages/voice)                   | Voice pipeline — STT, TTS, VAD, streaming, SFU utilities                                     |
-| [`@cloudflare/worker-bundler`](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding                  |
-| [`hono-agents`](packages/hono-agents)                   | Hono middleware for adding agents to Hono apps                                               |
+| Package                                                 | Description                                                                                       |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| [`agents`](packages/agents)                             | Core SDK — `Agent` class, routing, state, scheduling, MCP, email, workflows, x402, browser agents |
+| [`@cloudflare/ai-chat`](packages/ai-chat)               | Higher-level AI chat — persistent messages, resumable streaming, tool execution                   |
+| [`@cloudflare/think`](packages/think)                   | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools      |
+| [`@cloudflare/codemode`](packages/codemode)             | LLMs write executable code that calls your tools, instead of one tool call at a time              |
+| [`@cloudflare/shell`](packages/shell)                   | Sandboxed JS execution + virtual filesystem (`Workspace`) for agents                              |
+| [`@cloudflare/voice`](packages/voice)                   | Voice pipeline — STT, TTS, VAD, streaming, SFU utilities                                          |
+| [`@cloudflare/worker-bundler`](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding                       |
+| [`hono-agents`](packages/hono-agents)                   | Hono middleware for adding agents to Hono apps                                                    |
 
 > AI-chat modules used to live in `agents/ai-chat-agent`, `agents/chat`, `agents/ai-react`, and `agents/ai-types`. Those entry points still re-export, but they're deprecated — import from `@cloudflare/ai-chat` directly. New chat-from-scratch projects should look at `@cloudflare/think`.
 
@@ -147,7 +148,7 @@ The [`examples/`](examples) directory has 30+ self-contained demos. A non-exhaus
 - **Code Mode & sandboxes** — [`codemode/`](examples/codemode), [`codemode-mcp/`](examples/codemode-mcp), [`codemode-mcp-openapi/`](examples/codemode-mcp-openapi), [`dynamic-workers/`](examples/dynamic-workers), [`dynamic-workers-playground/`](examples/dynamic-workers-playground), [`worker-bundler-playground/`](examples/worker-bundler-playground)
 - **Voice** — [`voice-agent/`](examples/voice-agent) is the unified voice pipeline example with Workers AI, AssemblyAI, Telnyx, and ElevenLabs STT; [`voice-input/`](examples/voice-input) covers dictation; [`telnyx-voice-agent/`](examples/telnyx-voice-agent) covers phone transport; [`elevenlabs-starter/`](examples/elevenlabs-starter) covers broader ElevenLabs media APIs
 - **Workflows & approvals** — [`workflows/`](examples/workflows), [`a2a/`](examples/a2a)
-- **Auth & comms** — [`auth-agent/`](examples/auth-agent), [`cross-domain/`](examples/cross-domain), [`email-agent/`](examples/email-agent), [`github-webhook/`](examples/github-webhook), [`push-notifications/`](examples/push-notifications)
+- **Auth, payments, comms** — [`auth-agent/`](examples/auth-agent), [`cross-domain/`](examples/cross-domain), [`x402/`](examples/x402), [`x402-mcp/`](examples/x402-mcp), [`email-agent/`](examples/email-agent), [`github-webhook/`](examples/github-webhook), [`push-notifications/`](examples/push-notifications)
 - **Game & misc** — [`tictactoe/`](examples/tictactoe), [`ai-chat/`](examples/ai-chat)
 
 Examples using the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) live in [`openai-sdk/`](openai-sdk). Work-in-progress experiments live in [`experimental/`](experimental) (no stability guarantees).

examples/TODO.md

@@ -5,6 +5,7 @@ Tracked issues from the examples audit. See `AGENTS.md` in this folder for the c
 ## Missing README.md
 
 - [x] `resumable-stream-chat/` — add README
+- [x] `x402/` — add README
 
 ## Add frontend + Vite plugin
 
@@ -16,11 +17,18 @@ Most examples should be full-stack (frontend + backend). Focused server-only MCP
 - [x] `mcp-server/` — restored raw transport server-only example
 - [x] `mcp-worker/` — added MCP tool tester frontend
 - [x] `mcp-worker-authenticated/` — added info page with endpoint docs
+- [x] `x402/` — added React+Kumo frontend with "Fetch & Pay" UI
+- [x] `x402-mcp/` — added React+Kumo frontend with tool forms and payment modal
 
 ## Vite plugin fix
 
 - [ ] `cross-domain/` — add `@cloudflare/vite-plugin` to existing `vite.config.ts` (currently uses `@vitejs/plugin-react` only)
 
+## Type declarations
+
+- [x] `x402/` — renamed `worker-configuration.d.ts` to `env.d.ts`, regenerated
+- [x] `x402-mcp/` — renamed `worker-configuration.d.ts` to `env.d.ts`, regenerated
+
 ## Missing env.d.ts
 
 - [ ] `a2a/` — generate `env.d.ts` with `npx wrangler types`
@@ -55,3 +63,5 @@ Migrate examples to use Kumo components and Tailwind.
 - [x] `mcp-worker/` — added Kumo frontend
 - [x] `mcp-worker-authenticated/` — added Kumo frontend
 - [x] `mcp-elicitation/` and `mcp-elicitation-mrtr/` — intentionally server-only; elicitation requires an MCP client
+- [x] `x402/` — migrated from worker-only to Kumo frontend
+- [x] `x402-mcp/` — migrated from inline HTML to React+Kumo, replaced raw WebSocket with useAgent

examples/playground/README.md

@@ -64,7 +64,7 @@ The playground is organized into feature categories, each with interactive demos
 | **Server**       | Creating MCP servers with tools, resources, and prompts |
 | **Client**       | Connecting to external MCP servers                      |
 | **OAuth**        | OAuth authentication for MCP connections                |
-| **Advanced MCP** | Transports, elicitation, and codemode patterns          |
+| **Advanced MCP** | Transports, elicitation, codemode, and x402 patterns    |
 
 ### Workflows
 
@@ -84,9 +84,9 @@ The playground is organized into feature categories, each with interactive demos
 
 ### Product Integrations
 
-| Demo                    | Description                                          |
-| ----------------------- | ---------------------------------------------------- |
-| **Integration Stories** | Email, webhooks, push, A2A, and browser-tool stories |
+| Demo                    | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| **Integration Stories** | Email, webhooks, push, A2A, x402, and browser-tool stories |
 
 ## Project Structure
 

examples/playground/TODO.md

@@ -18,7 +18,7 @@
 - [ ] **Queue Patterns** - Rate limiting, batching, deduplication using the queue
 - [x] **Agent Tools** - Show `agentTool()`, `runAgentTool()`, `useAgentToolEvents()`, and sub-agent drill-in
 - [x] **Think + Shell** - Explain the assistant runtime, durable workspace, state tools, and sandboxed execution
-- [x] **Expanded MCP** - Explain transports, elicitation, OAuth server, codemode MCP, and WebMCP patterns
+- [x] **Expanded MCP** - Explain transports, elicitation, OAuth server, codemode MCP, WebMCP, and x402 patterns
 - [x] **Product Integrations** - Explain email, webhooks, push, A2A, payments, and browser-tool product stories
 - [x] **Multi-Agent** - One agent calling another agent (agent-to-agent communication)
 - [x] **Routing Strategies** - Different agent naming patterns (per-user, per-session, shared)

examples/playground/src/demos/integrations/ProductIntegrationsDemo.tsx

@@ -4,7 +4,7 @@ import { DemoWrapper } from "../../layout";
 import { CodeExplanation, LogPanel, type CodeSection } from "../../components";
 import { useLogs } from "../../hooks";
 
-type StoryId = "email" | "webhook" | "push" | "a2a" | "browser";
+type StoryId = "email" | "webhook" | "push" | "a2a" | "x402" | "browser";
 
 const stories: Array<{
   id: StoryId;
@@ -73,6 +73,20 @@ const stories: Array<{
     ],
     examplePath: "examples/a2a"
   },
+  {
+    id: "x402",
+    title: "Paid Tool Call",
+    product: "Payments before expensive actions",
+    description:
+      "A paid endpoint or MCP tool returns payment requirements. The client confirms, pays with x402, and retries the protected call.",
+    events: [
+      ["payment_required", { price: "0.01 USDC" }],
+      ["user_confirmed", { maxPaymentValue: "0.10 USDC" }],
+      ["payment_attached", { network: "base-sepolia" }],
+      ["tool_completed", { result: "premium result" }]
+    ],
+    examplePath: "examples/x402"
+  },
   {
     id: "browser",
     title: "Browser Worker",

examples/playground/src/demos/mcp/AdvancedDemo.tsx

@@ -110,6 +110,25 @@ return createLegacyMcpHandler(server, { route: "/codemode" })(
   request,
   env,
   ctx
+);`
+  },
+  {
+    title: "Paid Tools with x402",
+    description:
+      "Add payment requirements to expensive MCP tools. The client can confirm or reject the payment before the call proceeds.",
+    snippet: `import { withX402 } from "agents/x402";
+
+const server = withX402(new McpServer({ name: "PayMCP" }), config);
+
+server.paidTool(
+  "search_pro",
+  "Deep search",
+  0.01,
+  schema,
+  {},
+  async (args) => {
+    return search(args);
+  });
 );`
   }
 ];
@@ -152,7 +171,7 @@ if (result.state === "authenticating") {
   {
     title: "Expose advanced cases as links when setup is heavy",
     description:
-      "Some MCP stories need real OAuth providers or browser support. The Playground should explain them clearly and link to focused examples for full setup.",
+      "Some MCP stories need real OAuth providers, wallets, or browser support. The Playground should explain them clearly and link to focused examples for full setup.",
     code: `// Good Playground shape
 // 1. Show the decision and code path
 // 2. Simulate the state transitions
@@ -171,8 +190,8 @@ export function AdvancedMcpDemo() {
         <>
           MCP in the Agents SDK is more than connecting to one server. Agents
           can host MCP, consume external servers, use OAuth, run in-process RPC,
-          prompt users mid-tool-call with elicitation, and wrap APIs with
-          codemode.
+          prompt users mid-tool-call with elicitation, wrap APIs with codemode,
+          and protect expensive tools with x402 payments.
         </>
       }
     >
@@ -287,6 +306,7 @@ export function AdvancedMcpDemo() {
                 ["OAuth server", "examples/mcp-worker-authenticated"],
                 ["Codemode MCP", "examples/codemode-mcp"],
                 ["OpenAPI MCP", "examples/codemode-mcp-openapi"],
+                ["x402 MCP", "examples/x402-mcp"],
                 ["WebMCP", "examples/webmcp"]
               ].map(([label, path]) => (
                 <div

examples/playground/src/pages/Home.tsx

@@ -109,7 +109,7 @@ const features = [
       {
         name: "Advanced MCP",
         path: "/mcp/advanced",
-        description: "Transports, elicitation, and codemode"
+        description: "Transports, elicitation, codemode, and x402"
       }
     ]
   },
@@ -184,7 +184,7 @@ const features = [
       {
         name: "Integration Stories",
         path: "/integrations/products",
-        description: "Email, webhooks, push, A2A, and browser tools"
+        description: "Email, webhooks, push, A2A, x402, and browser tools"
       }
     ]
   }

examples/x402-mcp/.env.example

@@ -0,0 +1,5 @@
+# Ethereum address to receive payments (server side)
+MCP_ADDRESS=0xYourWalletAddressHere
+
+# Private key for signing payments (client side — test only, never use a real key)
+CLIENT_TEST_PK=0xYourPrivateKeyHere

examples/x402-mcp/.gitignore

@@ -0,0 +1,148 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+.output
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Sveltekit cache directory
+.svelte-kit/
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Firebase cache directory
+.firebase/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# pnpm
+.pnpm-store
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Vite files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+.vite/
+
+
+.wrangler
+.DS_Store