diff --git a/build/agents/x402.mdx b/build/agents/x402.mdx index fc810c6c5..cbe1da1dd 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 need CELO for gas. + ```mermaid sequenceDiagram participant Client as Client (Agent) @@ -177,6 +179,27 @@ 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 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 Celo is an ideal network for x402 due to: