docs: migrate x402 page to v2, fix facilitator host, document API key - #2229
Merged
Conversation
The resource-server sample used the legacy v1 packages (x402-express, nested asset.eip712 price shape, X-PAYMENT header) and pointed at https://x402.celo.org, which serves the dashboard SPA rather than the facilitator API — so it could not work as written. - Migrate to the v2 scoped packages (@x402/express, @x402/core, @x402/evm) with the paymentMiddleware(routes, server) signature; payTo and a flat price object ({ amount, asset, extra }) now live inside each route's accepts[] entry. - Point resource servers at the real facilitator API: https://api.x402.celo.org (mainnet) and https://api.x402.sepolia.celo.org (Celo Sepolia); the dashboard host is called out separately. - Update payment headers to v2 (PAYMENT-SIGNATURE). - Rewrite the Celo Configuration snippet as accepts[] entries with explicit asset addresses; add a Warning that the "$0.01" shorthand is not yet usable on Celo pending the release carrying the default-asset registry. v2 is presented as recommended; the facilitator remains dual-stack and still serves x402Version 1 under the legacy network names. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
GigaHierz
force-pushed
the
GigaHierz/x402-v2-migration
branch
from
August 3, 2026 09:43
71d4a67 to
66472b3
Compare
The facilitator's POST /settle is metered and rejects unauthenticated
requests with 401 {"error":"unauthorized","message":"Missing X-API-Key"}.
/verify, /supported, and /health are open, so an integration looks healthy
until its first settlement — worth calling out explicitly.
- Attach the key in the sample via HTTPFacilitatorClient's createAuthHeaders
(keyed by path: verify/settle/supported), reading X402_API_KEY from the
server environment.
- Add a "Getting an API Key" section: create/sign on the dashboard, store it
as a server-side secret, free credits then USDC-funded credits at $0.001
per settlement, and a 401/402/429 failure-mode table.
- Mark /settle as key-gated (vs. open) in the endpoints table.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
GigaHierz
changed the title
viral-sangani
approved these changes
Aug 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites
build-on-celo/build-with-ai/x402.mdxso the resource-server sample actually works. Three independent problems, all fixed here:x402-express, nestedasset.eip712price shape,X-PAYMENTheader).https://x402.celo.org, which serves the dashboard SPA, not the facilitator API (https://api.x402.celo.org/https://api.x402.sepolia.celo.org).POST /settlerequires — so an integration looks healthy until its first settlement 401s.Changes
paymentMiddleware(routes, server)(routes first);payTo+ a flatpriceobject ({ amount, asset, extra }) inside each route'saccepts[]. Install linenpm i @x402/express @x402/core @x402/evm; Hono users swap@x402/express→@x402/hono.<Note>, endpoints table, Resources table, and the sample distinguish the dashboard (x402.celo.org) from the payment API (api.x402.*).HTTPFacilitatorClient'screateAuthHeaders(keyed by path), readingX402_API_KEYfrom the server env. New Getting an API Key section covers create/sign on the dashboard, treating the key as a server-side secret, free-then-USDC-funded credits at $0.001/settlement, and a401/402/429failure-mode table. The endpoints table marks/settlekey-gated vs. the open/verify//supported//health.PAYMENT-SIGNATURE).accepts[]entries with explicit asset addresses (mainnet + Celo Sepolia).$0.01shorthand<Warning>: use the explicit price object until the release carrying Celo's default-asset registry entry ships.name: "Tether USD",version: "1") moved fromasset.eip712toextra.v2 is presented as recommended; the facilitator is dual-stack and still serves
x402Version: 1under the legacy network names, so v1 clients are not broken.Verification
awk, not by hand) against@x402/express@2.20.0(+@x402/core,@x402/evm,@types/express) withtsc --noEmitunderstrict— exit 0. ThecreateAuthHeadersreturn shape ({ verify, settle, supported }, eachRecord<string,string>) matchesFacilitatorConfig; theconst routes: RoutesConfigannotation is load-bearing (without itnetworkwidens tostringand fails the CAIP-2 type — flagged inline).POST /settle→401 {"error":"unauthorized","message":"Missing X-API-Key"};/verifyreachable without a key (400 on empty body),/supported+/health→ 200.GET /supported→x402Version: 2,eip155:42220(and legacy v1celo); Celo Sepolia mirror confirmed.mint devbuilds; the page renders HTTP 200 warm (the first cold request 500s during Next compile, then 200 in <1s), callout tags balanced (4 open / 4 close).grep -rnE "x402-express|x402-fetch|x402-hono|X-PAYMENT" build-on-celo/→ no hits.🤖 Generated with Claude Code