Skip to content

Commit dc08240

Browse files
CameronWhitesideask-bonk[bot]threepointoneOxyjundeathbyknowledge
authored
[Agents] Expand x402 documentation into dedicated section (#28398)
* [Agents] Expand x402 documentation into dedicated section - Split single x402.mdx page into dedicated /agents/x402/ section - Add pages for charging (HTTP content, MCP tools) and paying (Agents SDK, coding tools) - Remove marketing language and question-based framing - Tighten content, remove redundant examples and ASCII diagrams - Link to GitHub templates for detailed configuration * [Agents] Add custom Worker endpoints section to x402 HTTP content page * [Agents] Remove redundant prerequisites from MCP tools page * [Agents] Add facilitator documentation link to x402 config * [Agents] Simplify pay-from-agents-sdk to match production style * [Agents] Add human-in-the-loop placeholders to coding tools page * 7 issues: code bugs, path mismatches Co-authored-by: threepointone <threepointone@users.noreply.github.com> * Apply suggestions from code review * [Agents] Address x402 docs review feedback - Fix code bugs: async onStart, this.env access, placeholder addresses - Restore sidebar order to 8 (was incorrectly changed to 5) - Add deploy button description - Simplify pay-with-tool-plugins: remove build step, reorder sections - Streamline intro text throughout * Update src/content/docs/agents/x402/charge-for-mcp-tools.mdx Co-authored-by: deathbyknowledge <esteve.jamez@gmail.com> --------- Co-authored-by: ask-bonk[bot] <ask-bonk[bot]@users.noreply.github.com> Co-authored-by: threepointone <threepointone@users.noreply.github.com> Co-authored-by: Jun Lee <junlee@cloudflare.com> Co-authored-by: Sunil Pai <threepointone@gmail.com> Co-authored-by: deathbyknowledge <esteve.jamez@gmail.com>
1 parent f56efa3 commit dc08240

7 files changed

Lines changed: 477 additions & 174 deletions

File tree

‎src/content/docs/agents/x402.mdx‎

Lines changed: 0 additions & 173 deletions
This file was deleted.

‎src/content/docs/agents/x402/charge-for-http-content.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: Charge for HTTP content
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 1
6+
description: Gate HTTP endpoints with x402 payments using a Cloudflare Worker proxy.
7+
---
8+
9+
The x402-proxy template is a Cloudflare Worker that sits in front of any HTTP backend. When a request hits a protected route, the proxy returns a 402 response with payment instructions. After the client pays, the proxy verifies the payment and forwards the request to your origin.
10+
11+
Deploy the x402-proxy template to your Cloudflare account:
12+
13+
[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/x402-proxy-template)
14+
15+
## Prerequisites
16+
17+
- A [Cloudflare account](https://dash.cloudflare.com/sign-up)
18+
- An HTTP backend to gate
19+
- A wallet address to receive payments
20+
21+
## Configuration
22+
23+
Define protected routes in `wrangler.jsonc`:
24+
25+
```json
26+
{
27+
"vars": {
28+
"PAY_TO": "0xYourWalletAddress",
29+
"NETWORK": "base-sepolia",
30+
"PROTECTED_PATTERNS": [
31+
{
32+
"pattern": "/api/premium/*",
33+
"price": "$0.10",
34+
"description": "Premium API access"
35+
}
36+
]
37+
}
38+
}
39+
```
40+
41+
:::note
42+
`base-sepolia` is a test network. Change to `base` for production.
43+
:::
44+
45+
## Selective gating with Bot Management
46+
47+
With [Bot Management](/bots/), the proxy can charge crawlers while keeping the site free for humans:
48+
49+
```json
50+
{
51+
"pattern": "/content/*",
52+
"price": "$0.10",
53+
"description": "Content access",
54+
"bot_score_threshold": 30,
55+
"except_detection_ids": [117479730]
56+
}
57+
```
58+
59+
Requests with a bot score below `bot_score_threshold` are directed to the paywall. Use `except_detection_ids` to allowlist specific crawlers by [detection ID](/ai-crawl-control/reference/bots/).
60+
61+
## Deploy
62+
63+
Clone the template, edit `wrangler.jsonc`, and deploy:
64+
65+
```sh
66+
git clone https://github.com/cloudflare/templates
67+
cd templates/x402-proxy-template
68+
npm install
69+
npx wrangler deploy
70+
```
71+
72+
For full configuration options and Bot Management examples, refer to the [template README](https://github.com/cloudflare/templates/tree/main/x402-proxy-template).
73+
74+
## Custom Worker endpoints
75+
76+
For more control, add x402 middleware directly to your Worker using Hono:
77+
78+
```ts
79+
import { Hono } from "hono";
80+
import { paymentMiddleware } from "x402-hono";
81+
82+
const app = new Hono<{ Bindings: Env }>();
83+
84+
app.use(
85+
paymentMiddleware(
86+
"0xYourWalletAddress" as `0x${string}`,
87+
{
88+
"/premium": {
89+
price: "$0.10",
90+
network: "base-sepolia",
91+
config: { description: "Premium content" },
92+
},
93+
},
94+
{ url: "https://x402.org/facilitator" },
95+
),
96+
);
97+
98+
app.get("/premium", (c) => c.json({ message: "Thanks for paying!" }));
99+
100+
export default app;
101+
```
102+
103+
Refer to the [x402 Workers example](https://github.com/cloudflare/agents/tree/main/examples/x402) for a complete implementation.
104+
105+
## Related
106+
107+
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Native Cloudflare monetization without custom code
108+
- [Charge for MCP tools](/agents/x402/charge-for-mcp-tools/) — Charge per tool call instead of per request
109+
- [x402.org](https://x402.org) — Protocol specification

‎src/content/docs/agents/x402/charge-for-mcp-tools.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
title: Charge for MCP tools
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 2
6+
description: Charge per tool call in an MCP server using paidTool.
7+
---
8+
9+
The Agents SDK provides `paidTool`, a drop-in replacement for `tool` that adds x402 payment requirements. Clients pay per tool call, and you can mix free and paid tools in the same server.
10+
11+
## Setup
12+
13+
Wrap your `McpServer` with `withX402` and use `paidTool` for tools you want to charge for:
14+
15+
```ts
16+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
17+
import { McpAgent } from "agents/mcp";
18+
import { withX402, type X402Config } from "agents/x402";
19+
import { z } from "zod";
20+
21+
const X402_CONFIG: X402Config = {
22+
network: "base",
23+
recipient: "0xYourWalletAddress",
24+
facilitator: { url: "https://x402.org/facilitator" }, // Payment facilitator URL
25+
// To learn more about facilitators: https://docs.x402.org/core-concepts/facilitator
26+
};
27+
28+
export class PaidMCP extends McpAgent<Env> {
29+
server = withX402(
30+
new McpServer({ name: "PaidMCP", version: "1.0.0" }),
31+
X402_CONFIG,
32+
);
33+
34+
async init() {
35+
// Paid tool — $0.01 per call
36+
this.server.paidTool(
37+
"square",
38+
"Squares a number",
39+
0.01, // USD
40+
{ number: z.number() },
41+
{},
42+
async ({ number }) => {
43+
return { content: [{ type: "text", text: String(number ** 2) }] };
44+
},
45+
);
46+
47+
// Free tool
48+
this.server.tool(
49+
"echo",
50+
"Echo a message",
51+
{ message: z.string() },
52+
async ({ message }) => {
53+
return { content: [{ type: "text", text: message }] };
54+
},
55+
);
56+
}
57+
}
58+
```
59+
60+
## Configuration
61+
62+
| Field | Description |
63+
| ------------- | ------------------------------------------------------------ |
64+
| `network` | `base` for production, `base-sepolia` for testing |
65+
| `recipient` | Wallet address to receive payments |
66+
| `facilitator` | Payment facilitator URL (use `https://x402.org/facilitator`) |
67+
68+
## paidTool signature
69+
70+
```ts
71+
this.server.paidTool(
72+
name, // Tool name
73+
description, // Tool description
74+
price, // Price in USD (e.g., 0.01)
75+
inputSchema, // Zod schema for inputs
76+
annotations, // MCP annotations
77+
handler, // Async function that executes the tool
78+
);
79+
```
80+
81+
When a client calls a paid tool without payment, the server returns 402 with payment requirements. The client pays via x402, retries with payment proof, and receives the result.
82+
83+
## Testing
84+
85+
Use `base-sepolia` and get test USDC from the [Circle faucet](https://faucet.circle.com/).
86+
87+
For a complete working example, refer to [x402-mcp on GitHub](https://github.com/cloudflare/agents/tree/main/examples/x402-mcp).
88+
89+
## Related
90+
91+
- [Pay from Agents SDK](/agents/x402/pay-from-agents-sdk/) — Build clients that pay for tools
92+
- [Charge for HTTP content](/agents/x402/charge-for-http-content/) — Gate HTTP endpoints
93+
- [MCP server guide](/agents/guides/remote-mcp-server/) — Build your first MCP server

0 commit comments

Comments
 (0)