Skip to content

Commit 1de35ea

Browse files
rohinloherohinlohe
authored
[Agents] Add Machine Payments Protocol (MPP) to agentic payments docs… (#29088)
1 parent 8c264b6 commit 1de35ea

File tree

10 files changed

+262
-14
lines changed

10 files changed

+262
-14
lines changed

‎public/__redirects‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2637,6 +2637,9 @@
26372637
# Main catch-all redirect (must be last)
26382638
/cloudflare-one/team-and-resources/devices/warp/* /cloudflare-one/team-and-resources/devices/cloudflare-one-client/:splat 301
26392639

2640+
# Agents x402 (moved under agentic-payments)
2641+
/agents/x402/* /agents/agentic-payments/x402/:splat 301
2642+
26402643
# Changelog (individual entry route moved to /post/)
26412644
/changelog/2024-* /changelog/post/2024-:splat 301
26422645
/changelog/2025-* /changelog/post/2025-:splat 301

‎src/content/docs/agents/agentic-payments/index.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Agentic Payments
3+
pcx_content_type: overview
4+
sidebar:
5+
order: 8
6+
group:
7+
hideIndex: false
8+
description: Let AI agents pay for services programmatically using payment protocols like MPP and x402 with Cloudflare's Agents SDK.
9+
---
10+
11+
import { LinkCard, CardGrid } from "~/components";
12+
13+
AI agents need to discover, pay for, and consume resources and services programmatically. Traditional onboarding requires account creation, a payment method, and an API key before an agent can pay for a service. Agentic payments let AI agents purchase resources and services directly through the HTTP `402 Payment Required` response code.
14+
15+
Cloudflare's [Agents SDK](/agents/) supports agentic payments through two protocols built on the HTTP `402 Payment Required` status code: **x402** and **Machine Payments Protocol (MPP)**. Both follow the same core flow:
16+
17+
1. A client requests a resource or calls a tool.
18+
2. The server responds with `402` and a payment challenge describing what to pay, how much, and where.
19+
3. The client fulfills the payment and retries the request with a payment credential.
20+
4. The server verifies the payment (optionally through a facilitator service) and returns the resource along with a receipt.
21+
22+
No accounts, sessions, or pre-shared API keys are required. Agents handle the entire exchange programmatically.
23+
24+
## x402 and Machine Payments Protocol
25+
26+
### x402
27+
28+
[x402](https://www.x402.org/) is a payment standard created by Coinbase. It uses on-chain stablecoin payments (USDC on Base, Ethereum, Solana, and other networks) and defines three HTTP headers — `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE` — to carry challenges, credentials, and receipts. Servers can offload verification and settlement to a **facilitator** service so they do not need direct blockchain connectivity. It is governed by Coinbase and Cloudflare, two of the founding members of the x402 Foundation.
29+
30+
The Agents SDK provides first-class x402 integration:
31+
32+
- **Server-side**: `withX402` and `paidTool` for MCP servers, plus `x402-hono` middleware for HTTP Workers.
33+
- **Client-side**: `withX402Client` wraps MCP client connections with automatic 402 handling and optional human-in-the-loop confirmation.
34+
35+
### Machine Payments Protocol
36+
37+
[Machine Payments Protocol (MPP)](https://mpp.dev) is a protocol co-authored by Tempo Labs and Stripe. It extends the HTTP `402` pattern with a formal `WWW-Authenticate: Payment` / `Authorization: Payment` header scheme and is on the IETF standards track.
38+
39+
MPP supports multiple payment methods beyond blockchain — including cards (via Stripe), Bitcoin Lightning, and stablecoins — and introduces **sessions** for streaming and pay-as-you-go use cases with sub-millisecond latency and sub-cent costs. MPP is backwards-compatible with x402: MPP clients can consume existing x402 services without modification.
40+
41+
## Charge for resources
42+
43+
<CardGrid>
44+
<LinkCard
45+
title="HTTP content (x402)"
46+
description="Gate APIs, web pages, and files with a Worker proxy"
47+
href="/agents/agentic-payments/x402/charge-for-http-content/"
48+
/>
49+
<LinkCard
50+
title="HTTP content (MPP)"
51+
description="Gate APIs, web pages, and files with a Worker proxy"
52+
href="/agents/agentic-payments/mpp/charge-for-http-content/"
53+
/>
54+
</CardGrid>
55+
56+
## Related
57+
58+
- [x402.org](https://x402.org) — x402 protocol specification
59+
- [mpp.dev](https://mpp.dev) — MPP protocol specification
60+
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Cloudflare-native monetization for web content
61+
- [x402 examples](https://github.com/cloudflare/agents/tree/main/examples) — Complete working code

‎src/content/docs/agents/agentic-payments/mpp/charge-for-http-content.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Charge for HTTP content
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 1
6+
description: Gate HTTP endpoints with MPP payments using the mpp-proxy template on Cloudflare Workers.
7+
---
8+
9+
The [mpp-proxy](https://github.com/cloudflare/mpp-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 an MPP payment challenge. After the client pays, the proxy verifies the payment, forwards the request to your origin, and issues a 1-hour session cookie.
10+
11+
Deploy the mpp-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/mpp-proxy)
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+
```jsonc
26+
{
27+
"vars": {
28+
"PAY_TO": "0xYourWalletAddress",
29+
"TEMPO_TESTNET": false,
30+
"PAYMENT_CURRENCY": "0x20c000000000000000000000b9537d11c60e8b50",
31+
"PROTECTED_PATTERNS": [
32+
{
33+
"pattern": "/premium/*",
34+
"amount": "0.01",
35+
"description": "Access to premium content for 1 hour"
36+
}
37+
]
38+
}
39+
}
40+
```
41+
42+
:::note
43+
Set `TEMPO_TESTNET` to `true` and `PAYMENT_CURRENCY` to `0x20c0000000000000000000000000000000000000` for testnet development.
44+
:::
45+
46+
## Selective gating with Bot Management
47+
48+
With [Bot Management](/bots/), the proxy can charge crawlers while keeping the site free for humans:
49+
50+
```jsonc
51+
{
52+
"pattern": "/content/*",
53+
"amount": "0.25",
54+
"description": "Content access for 1 hour",
55+
"bot_score_threshold": 30,
56+
"except_detection_ids": [120623194, 117479730]
57+
}
58+
```
59+
60+
Requests with a bot score at or 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/).
61+
62+
## Deploy
63+
64+
Clone the template, edit `wrangler.jsonc`, and deploy:
65+
66+
```sh
67+
git clone https://github.com/cloudflare/mpp-proxy
68+
cd mpp-proxy
69+
npm install
70+
npx wrangler secret put JWT_SECRET
71+
npx wrangler secret put MPP_SECRET_KEY
72+
npx wrangler deploy
73+
```
74+
75+
For full configuration options, proxy modes, and Bot Management examples, refer to the [mpp-proxy README](https://github.com/cloudflare/mpp-proxy).
76+
77+
## Custom Worker endpoints
78+
79+
For more control, add MPP middleware directly to your Worker using Hono:
80+
81+
```ts
82+
import { Hono } from "hono";
83+
import { Mppx, tempo } from "mppx/hono";
84+
85+
const app = new Hono();
86+
87+
const mppx = Mppx.create({
88+
methods: [
89+
tempo({
90+
currency: "0x20c0000000000000000000000000000000000000",
91+
recipient: "0xYourWalletAddress",
92+
}),
93+
],
94+
});
95+
96+
app.get("/premium", mppx.charge({ amount: "0.10" }), (c) =>
97+
c.json({ data: "Thanks for paying!" }),
98+
);
99+
100+
export default app;
101+
```
102+
103+
Refer to the [Hono middleware reference](https://mpp.dev/sdk/typescript/middlewares/hono) for the full API, including session payments and payer identification.
104+
105+
## Related
106+
107+
- [mpp.dev](https://mpp.dev) — Protocol specification
108+
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Cloudflare-native monetization without custom code

‎src/content/docs/agents/agentic-payments/mpp/index.mdx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: MPP (Machine Payments Protocol)
3+
pcx_content_type: overview
4+
sidebar:
5+
order: 9
6+
group:
7+
hideIndex: false
8+
description: Accept and make payments using the Machine Payments Protocol (MPP) on Cloudflare Workers.
9+
---
10+
11+
import { LinkCard, CardGrid } from "~/components";
12+
13+
[Machine Payments Protocol (MPP)](https://mpp.dev) is a protocol for machine-to-machine payments, co-authored by [Tempo Labs](https://tempo.xyz) and [Stripe](https://stripe.com). It standardizes the HTTP `402 Payment Required` status code with a formal authentication scheme proposed to the [IETF](https://paymentauth.org). MPP gives agents, apps, and humans a single interface to pay for any service in the same HTTP request.
14+
15+
MPP is payment-method agnostic. A single endpoint can accept stablecoins (Tempo), credit cards (Stripe), or Bitcoin (Lightning).
16+
17+
## How it works
18+
19+
1. A client requests a resource — `GET /resource`.
20+
2. The server returns `402 Payment Required` with a `WWW-Authenticate: Payment` header containing a payment challenge.
21+
3. The client fulfills the payment — signs a transaction, pays an invoice, or completes a card payment.
22+
4. The client retries the request with an `Authorization: Payment` header containing a payment credential.
23+
5. The server verifies the payment and returns the resource with a `Payment-Receipt` header.
24+
25+
## Payment methods
26+
27+
MPP supports multiple payment methods through a single protocol:
28+
29+
| Method | Description | Status |
30+
| ------------------------------------------------------ | ---------------------------------------------------------------------------- | ---------- |
31+
| [Tempo](https://mpp.dev/payment-methods/tempo) | Stablecoin payments on the Tempo blockchain with sub-second settlement | Production |
32+
| [Stripe](https://mpp.dev/payment-methods/stripe) | Cards, wallets, and other Stripe-supported methods via Shared Payment Tokens | Production |
33+
| [Lightning](https://mpp.dev/payment-methods/lightning) | Bitcoin payments over the Lightning Network | Available |
34+
| [Card](https://mpp.dev/payment-methods/card) | Card payments via encrypted network tokens | Available |
35+
| [Custom](https://mpp.dev/payment-methods/custom) | Build your own payment method using the MPP SDK | Available |
36+
37+
Servers can offer multiple methods simultaneously. Clients choose the method that works for them.
38+
39+
## Payment intents
40+
41+
MPP defines two payment intents:
42+
43+
- **`charge`** — A one-time payment that settles immediately. Use for per-request billing.
44+
- **`session`** — A streaming payment over a payment channel. Use for pay-as-you-go or per-token billing with sub-cent costs and sub-millisecond latency.
45+
46+
## Compatibility with x402
47+
48+
MPP is backwards-compatible with [x402](/agents/agentic-payments/x402/). The core x402 `exact` payment flows map directly onto MPP's `charge` intent, so MPP clients can consume existing x402 services without modification.
49+
50+
## Charge for resources
51+
52+
<CardGrid>
53+
<LinkCard
54+
title="HTTP content"
55+
description="Gate APIs, web pages, and files with MPP middleware"
56+
href="/agents/agentic-payments/mpp/charge-for-http-content/"
57+
/>
58+
</CardGrid>
59+
60+
## SDKs
61+
62+
MPP provides official SDKs in three languages:
63+
64+
| SDK | Package | Install |
65+
| ---------- | -------- | ------------------- |
66+
| TypeScript | `mppx` | `npm install mppx` |
67+
| Python | `pympp` | `pip install pympp` |
68+
| Rust | `mpp-rs` | `cargo add mpp` |
69+
70+
The TypeScript SDK includes framework middleware for [Hono](https://mpp.dev/sdk/typescript/middlewares/hono), [Express](https://mpp.dev/sdk/typescript/middlewares/express), [Next.js](https://mpp.dev/sdk/typescript/middlewares/nextjs), and [Elysia](https://mpp.dev/sdk/typescript/middlewares/elysia), as well as a [CLI](https://mpp.dev/sdk/typescript/cli) for testing paid endpoints.
71+
72+
## Related
73+
74+
- [mpp.dev](https://mpp.dev) — Protocol documentation and quickstart guides
75+
- [IETF specification](https://paymentauth.org) — Full Payment HTTP Authentication Scheme specification
76+
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Cloudflare-native monetization for web content

src/content/docs/agents/x402/charge-for-http-content.mdx renamed to src/content/docs/agents/agentic-payments/x402/charge-for-http-content.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,5 +105,5 @@ Refer to the [x402 Workers example](https://github.com/cloudflare/agents/tree/ma
105105
## Related
106106

107107
- [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
108+
- [Charge for MCP tools](/agents/agentic-payments/x402/charge-for-mcp-tools/) — Charge per tool call instead of per request
109109
- [x402.org](https://x402.org) — Protocol specification

src/content/docs/agents/x402/charge-for-mcp-tools.mdx renamed to src/content/docs/agents/agentic-payments/x402/charge-for-mcp-tools.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,6 @@ For a complete working example, refer to [x402-mcp on GitHub](https://github.com
8888

8989
## Related
9090

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
91+
- [Pay from Agents SDK](/agents/agentic-payments/x402/pay-from-agents-sdk/) — Build clients that pay for tools
92+
- [Charge for HTTP content](/agents/agentic-payments/x402/charge-for-http-content/) — Gate HTTP endpoints
9393
- [MCP server guide](/agents/guides/remote-mcp-server/) — Build your first MCP server

src/content/docs/agents/x402/index.mdx renamed to src/content/docs/agents/agentic-payments/x402/index.mdx

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,20 +9,20 @@ sidebar:
99

1010
import { LinkCard, CardGrid } from "~/components";
1111

12-
[x402](https://www.x402.org/) is an open payment standard built around HTTP 402 (Payment Required). Services return a 402 response with payment instructions, and clients pay programmatically without accounts, sessions, or API keys.
12+
[x402](https://www.x402.org/) is a payment standard built around HTTP 402 (Payment Required). Services return a 402 response with payment instructions, and clients pay programmatically without accounts, sessions, or API keys.
1313

1414
## Charge for resources
1515

1616
<CardGrid>
1717
<LinkCard
1818
title="HTTP content"
1919
description="Gate APIs, web pages, and files with a Worker proxy"
20-
href="/agents/x402/charge-for-http-content/"
20+
href="/agents/agentic-payments/x402/charge-for-http-content/"
2121
/>
2222
<LinkCard
2323
title="MCP tools"
2424
description="Charge per tool call using paidTool"
25-
href="/agents/x402/charge-for-mcp-tools/"
25+
href="/agents/agentic-payments/x402/charge-for-mcp-tools/"
2626
/>
2727
</CardGrid>
2828

@@ -32,17 +32,17 @@ import { LinkCard, CardGrid } from "~/components";
3232
<LinkCard
3333
title="Agents SDK"
3434
description="Wrap MCP clients with withX402Client"
35-
href="/agents/x402/pay-from-agents-sdk/"
35+
href="/agents/agentic-payments/x402/pay-from-agents-sdk/"
3636
/>
3737
<LinkCard
3838
title="Coding tools"
3939
description="OpenCode plugin and Claude Code hook"
40-
href="/agents/x402/pay-with-tool-plugins/"
40+
href="/agents/agentic-payments/x402/pay-with-tool-plugins/"
4141
/>
4242
</CardGrid>
4343

4444
## Related
4545

4646
- [x402.org](https://x402.org) — Protocol specification
47-
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Cloudflare-native monetization
4847
- [x402 examples](https://github.com/cloudflare/agents/tree/main/examples) — Complete working code
48+
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/) — Cloudflare-native monetization

src/content/docs/agents/x402/pay-from-agents-sdk.mdx renamed to src/content/docs/agents/agentic-payments/x402/pay-from-agents-sdk.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,6 @@ Use `base-sepolia` for testing. Get test USDC from the [Circle faucet](https://f
5959

6060
## Related
6161

62-
- [Charge for MCP tools](/agents/x402/charge-for-mcp-tools/) — Build servers that charge for tools
63-
- [Pay from coding tools](/agents/x402/pay-with-tool-plugins/) — Add payments to OpenCode or Claude Code
62+
- [Charge for MCP tools](/agents/agentic-payments/x402/charge-for-mcp-tools/) — Build servers that charge for tools
63+
- [Pay from coding tools](/agents/agentic-payments/x402/pay-with-tool-plugins/) — Add payments to OpenCode or Claude Code
6464
- [Human-in-the-loop guide](/agents/guides/human-in-the-loop/) — Implement approval workflows

src/content/docs/agents/x402/pay-with-tool-plugins.mdx renamed to src/content/docs/agents/agentic-payments/x402/pay-with-tool-plugins.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ Register the hook in `.claude/settings.json`:
156156
157157
## Related
158158
159-
- [Pay from Agents SDK](/agents/x402/pay-from-agents-sdk/) — Use the Agents SDK for more control
160-
- [Charge for HTTP content](/agents/x402/charge-for-http-content/) — Build the server side
159+
- [Pay from Agents SDK](/agents/agentic-payments/x402/pay-from-agents-sdk/) — Use the Agents SDK for more control
160+
- [Charge for HTTP content](/agents/agentic-payments/x402/charge-for-http-content/) — Build the server side
161161
- [Human-in-the-loop guide](/agents/guides/human-in-the-loop/) — Implement approval workflows
162162
- [x402.org](https://x402.org) — Protocol specification

‎src/content/docs/ai-crawl-control/reference/worker-templates.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,4 @@ For setup instructions and Bot Management integration examples, see the [templat
2222
- [Cloudflare Workers](/workers/) — Build and deploy serverless applications
2323
- [Workers templates](https://github.com/cloudflare/templates) — More templates on GitHub
2424
- [Pay Per Crawl](/ai-crawl-control/features/pay-per-crawl/what-is-pay-per-crawl/) — Native Cloudflare integration for monetizing crawler access
25-
- [x402 payments](/agents/x402/) — Gate resources, charge for MCP tools, add payments to coding agents
25+
- [x402 payments](/agents/agentic-payments/x402/) — Gate resources, charge for MCP tools, add payments to coding agents

0 commit comments

Comments
 (0)