From ffa8874c8e983065fbeac4518c3b793d521ad2fc Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Thu, 15 Oct 2026 23:29:01 +0100 Subject: [PATCH 1/3] docs(x402): define facilitator at first use and add a check-that-it-works step (#2263) Co-Authored-By: Claude Sonnet 5.5 --- build/agents/x402.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/build/agents/x402.mdx b/build/agents/x402.mdx index fc810c6c5..2062d9173 100644 --- a/build/agents/x402.mdx +++ b/build/agents/x402.mdx @@ -31,6 +31,8 @@ Traditional payment systems don't work for AI agents and micropayments: ## How It Works +A *facilitator* is a service that checks a buyer's signed payment and submits it on-chain on the seller's behalf, so the seller does not run a node or hold gas. + ```mermaid sequenceDiagram participant Client as Client (Agent) @@ -155,6 +157,18 @@ Using Hono instead of Express? Swap `@x402/express` → `@x402/hono`; the body i USDT has no `version()` method on-chain — its EIP-712 domain resolves to `name: "Tether USD"`, `version: "1"`. Set those exactly in the `extra` field or signature verification fails. +### Check that it works + +Start the server and request the paid route without a payment: + +```bash +curl -i http://localhost:3000/premium +``` + +The response is `402 Payment Required`, and the payment requirements describe the route's price: `10000` base units of USDC, which is $0.01 because USDC has 6 decimals. That `402` means the middleware is wired to the route. + +A buyer that signs the authorization and retries the request receives `200` with `{"data":"paid content"}`, and the payment settles on Celo for the price above. At that point you have charged an agent $0.01. Settlement needs the API key from the next section. + ### Getting an API Key `/settle` is metered, so accepting real payments requires an API key. To create one: From 56119a5b05eb384c9daae4a64e560be1c1ada78d Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Mon, 19 Oct 2026 11:05:02 +0200 Subject: [PATCH 2/3] docs(x402): address review on the check step (#2263) Show how to read the payment requirements from the PAYMENT-REQUIRED header, say the check needs no API key, point to a buyer, move the step after the API key section and correct the gas wording. Co-Authored-By: Claude Sonnet 5.5 --- build/agents/x402.mdx | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/build/agents/x402.mdx b/build/agents/x402.mdx index 2062d9173..ced07d266 100644 --- a/build/agents/x402.mdx +++ b/build/agents/x402.mdx @@ -31,7 +31,7 @@ Traditional payment systems don't work for AI agents and micropayments: ## How It Works -A *facilitator* is a service that checks a buyer's signed payment and submits it on-chain on the seller's behalf, so the seller does not run a node or hold gas. +A *facilitator* is a service that checks a buyer's signed payment and submits it on-chain on the seller's behalf, so the seller does not run a node or need CELO for gas. ```mermaid sequenceDiagram @@ -157,18 +157,6 @@ Using Hono instead of Express? Swap `@x402/express` → `@x402/hono`; the body i USDT has no `version()` method on-chain — its EIP-712 domain resolves to `name: "Tether USD"`, `version: "1"`. Set those exactly in the `extra` field or signature verification fails. -### Check that it works - -Start the server and request the paid route without a payment: - -```bash -curl -i http://localhost:3000/premium -``` - -The response is `402 Payment Required`, and the payment requirements describe the route's price: `10000` base units of USDC, which is $0.01 because USDC has 6 decimals. That `402` means the middleware is wired to the route. - -A buyer that signs the authorization and retries the request receives `200` with `{"data":"paid content"}`, and the payment settles on Celo for the price above. At that point you have charged an agent $0.01. Settlement needs the API key from the next section. - ### Getting an API Key `/settle` is metered, so accepting real payments requires an API key. To create one: @@ -191,6 +179,25 @@ If a call to `/settle` fails, the status code tells you why: | `402` | Out of free credits and balance — top up on the dashboard. | | `429` | Free-tier rate limit reached. | +### Check that it works + +Start the server and request the paid route without a payment. This step needs no API key: + +```bash +curl -i http://localhost:3000/premium +``` + +The response is `402 Payment Required` with an empty `{}` body. The payment requirements are in the base64-encoded `PAYMENT-REQUIRED` header. To read them: + +```bash +curl -s -o /dev/null -D - http://localhost:3000/premium \ + | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r' | base64 -d +``` + +The decoded JSON shows the route's price: `10000` base units of USDC, which is $0.01 because USDC has 6 decimals. A `402` with that price means the middleware is wired to the route. + +To see a paid response you need a buyer that signs the authorization and retries the request. The `x402` template of Celo Composer includes a buyer script that pays an x402 endpoint in USDC; see [x402 paid API](/build/quickstart#x402-paid-api). The route above uses Celo mainnet and a placeholder `payTo`, so point both at a Celo Sepolia route and an address you control first, using the Celo Sepolia values under [Celo Configuration](#celo-configuration). A paid request returns `200` with `{"data":"paid content"}` and the payment settles on Celo for the price above. At that point you have charged an agent $0.01. Settlement needs the API key from the previous section. + ## x402 on Celo Celo is an ideal network for x402 due to: From 8ba21bf563255e27b7c5bcd5df104f8b6d84781e Mon Sep 17 00:00:00 2001 From: GigaHierz Date: Tue, 20 Oct 2026 18:27:51 +0200 Subject: [PATCH 3/3] docs(x402): switch the facilitator URL for Celo Sepolia and match the Composer buyer to its own seller Co-Authored-By: Claude Sonnet 5.5 --- build/agents/x402.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/build/agents/x402.mdx b/build/agents/x402.mdx index ced07d266..cbe1da1dd 100644 --- a/build/agents/x402.mdx +++ b/build/agents/x402.mdx @@ -196,7 +196,9 @@ curl -s -o /dev/null -D - http://localhost:3000/premium \ The decoded JSON shows the route's price: `10000` base units of USDC, which is $0.01 because USDC has 6 decimals. A `402` with that price means the middleware is wired to the route. -To see a paid response you need a buyer that signs the authorization and retries the request. The `x402` template of Celo Composer includes a buyer script that pays an x402 endpoint in USDC; see [x402 paid API](/build/quickstart#x402-paid-api). The route above uses Celo mainnet and a placeholder `payTo`, so point both at a Celo Sepolia route and an address you control first, using the Celo Sepolia values under [Celo Configuration](#celo-configuration). A paid request returns `200` with `{"data":"paid content"}` and the payment settles on Celo for the price above. At that point you have charged an agent $0.01. Settlement needs the API key from the previous section. +To see a paid response you need a buyer that signs the authorization and retries the request. The simplest way is the `x402` template of Celo Composer, which ships its own seller and buyer wired to Celo Sepolia (see [x402 paid API](/build/quickstart#x402-paid-api)). Run the seller with `pnpm api:dev` and the buyer with `pnpm api:buy`. The buyer pays the template's own route and prints the response and the settlement transaction, so expect that output rather than the `{"data":"paid content"}` from the server above. The buyer wallet needs test USDC on Celo Sepolia and no CELO. + +To charge for the server on this page instead, switch it to Celo Sepolia. Change the `network`, `asset` and `payTo` values to the Celo Sepolia ones under [Celo Configuration](#celo-configuration), and change the facilitator `url` to `https://api.x402.sepolia.celo.org`. The mainnet facilitator does not list Celo Sepolia, so the server fails on startup if the URL stays as it is. Settlement needs the key from the previous section. A paid request then returns `200` with `{"data":"paid content"}` and the payment settles on Celo Sepolia for the price above. At that point you have charged an agent $0.01 in test USDC. ## x402 on Celo