add agents x402 docs #25326

deathbyknowledge · 2025-09-22T14:53:08Z

Summary

Screenshots (optional)

Documentation checklist

Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
The documentation style guide has been adhered to.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
Files which have changed name or location have been allocated redirects.

src/content/docs/agents/x402.mdx

irvinebroque · 2025-09-22T15:23:42Z

src/content/docs/agents/x402.mdx

+	onStart() {
+		// We instantiate a wallet from which the agent will pay
+		const pk = process.env.CLIENT_TEST_PK as `0x${string}`;
+		const agentAccount = privateKeyToAccount(pk);


should this be called "wallet"?

(Since that's how it is described in the sentence above the code snippet and is most specific)

I'm not entirely sure on the difference on wallet vs account. Since the x402 types are Account I'll stick to that wording. I've updated the comments to make it more clear as well.

irvinebroque · 2025-09-22T15:24:40Z

src/content/docs/agents/x402.mdx

+	fetchWithPay!: ReturnType<typeof wrapFetchWithPayment>;
+
+	onStart() {
+		// We instantiate a wallet from which the agent will pay


Suggested change

// We instantiate a wallet from which the agent will pay

// Create a temporary wallet that the agent will use to pay

My understanding is this is a temporary wallet. Yes? No?

No, privateKeyToAccount is deterministic and always derives the same wallet (I'm not sure of the naming either) from a given private key.
So what's expected is that you only need to load your private key into your Worker's secrets and your wallet will be ready to use.

src/content/docs/agents/x402.mdx

irvinebroque · 2025-09-22T15:27:56Z

src/content/docs/agents/x402.mdx

+		const url = new URL(req.url);
+		console.log("Trying to fetch paid API");
+
+		// We use the x402 fetch to access our paid endpoint


Suggested change

// We use the x402 fetch to access our paid endpoint

// Use the x402 compatible fetch (fetchWithPay) to access the paid endpoint

irvinebroque · 2025-09-22T15:45:53Z

src/content/docs/agents/x402.mdx

+		// The first parameter becomes the confirmation callback.
+		// We can set it to `null` if we want the agent to pay automatically.
+		const res = await this.x402Client.callTool(this.onPaymentRequired, {
+			name: toolName,


Should this be an example tool? Otherwise I read this and wondered what this was referencing

I've added toolName and toolArgs as parameters to fix this

irvinebroque · 2025-09-22T15:46:09Z

src/content/docs/agents/x402.mdx

+	}
+
+	onPaymentRequired(paymentRequirements): Promise<boolean> {
+		// Your HIL confirmation flow...


What's HIL?

"Human-in-the-loop", updated it to use that instead to make it more clear

irvinebroque · 2025-09-22T15:46:51Z

src/content/docs/agents/x402.mdx

+}
+```
+
+We also include an MCP client that you can use from anywhere (not just your Agents!) to pay for these tools.


Where would someone use this outside of an agent? Example might help

Any application that connects to MCP servers is using some version of an MCP client. The wrapper agents wraps the official MCP client to support paid tool calls (which are not officially part of the spec)

e.g. Windsurf wants to support MCPs with paid tools, so they'll need an MCP client that can handle payments

irvinebroque · 2025-09-22T15:47:39Z

src/content/docs/agents/x402.mdx

+const X402_CONFIG: X402Config = {
+	network: "base",
+	recipient: env.MCP_ADDRESS,
+	facilitator: { url: "https://x402.org/facilitator" }, // Payment facilitator URL


Is this something that I need to set myself or do I just use this URL as the default?

AFAIK this one is the official (?) supported payment facilitator that handles payment verifications/settling for servers, and should work for most networks. Some users might want to use different facilitators so they could update it.

In any case, I've added an inline comment to docs on facilitators (https://x402.gitbook.io/x402/core-concepts/facilitator)

irvinebroque

Stamp so you have it, see comments

Co-authored-by: Brendan Irvine-Broque <[email protected]>

threepointone · 2025-09-22T17:23:07Z

let's land this tomorrow right before the announcement

add x402 docs

e702040

deathbyknowledge requested review from a team, elithrar, irvinebroque, rita3ko, thomasgauvin and threepointone as code owners September 22, 2025 14:53

github-actions bot added size/m product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. September 2025 labels Sep 22, 2025

github-actions bot assigned elithrar, irvinebroque, rita3ko, thomasgauvin and threepointone Sep 22, 2025

irvinebroque reviewed Sep 22, 2025

View reviewed changes

irvinebroque approved these changes Sep 22, 2025

View reviewed changes

deathbyknowledge and others added 3 commits September 22, 2025 18:28

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

d8caedb

Co-authored-by: Brendan Irvine-Broque <[email protected]>

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

5c71b61

Co-authored-by: Brendan Irvine-Broque <[email protected]>

amends

5fc4913

deathbyknowledge requested a review from irvinebroque September 22, 2025 16:56

threepointone approved these changes Sep 22, 2025

View reviewed changes

threepointone merged commit a294db3 into cloudflare:production Sep 23, 2025
2 checks passed

	// We instantiate a wallet from which the agent will pay
	// Create a temporary wallet that the agent will use to pay

	// We use the x402 fetch to access our paid endpoint
	// Use the x402 compatible fetch (fetchWithPay) to access the paid endpoint

add agents x402 docs #25326

add agents x402 docs #25326

Uh oh!

Conversation

deathbyknowledge commented Sep 22, 2025

Summary

Screenshots (optional)

Documentation checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

irvinebroque left a comment

Choose a reason for hiding this comment

Uh oh!

threepointone commented Sep 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants