[Docs] Add comprehensive x402 payment documentation #8149
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
4 Skipped Deployments
|
|
WalkthroughAdds three x402 documentation pages (client, server, facilitator), updates the x402 overview page (text, examples, and server handler signature changed from Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as User Agent
participant R as Resource Server
participant F as Facilitator
participant X as x402 Backend
participant L as Ledger
rect rgb(238,245,255)
note over U,R: Client requests protected resource
U->>R: GET /resource
R-->>U: 402 Payment Required (price, terms)
end
rect rgb(241,252,240)
note over U,F: Client creates & signs payment
U->>F: createPayment(terms)
F->>X: verify(proof)
X-->>F: verified
F->>X: settle(payment)
X->>L: submit tx
L-->>X: confirmation
X-->>F: settlement result
F-->>U: payment receipt
end
rect rgb(255,249,235)
note over U,R: Client retries request with payment
U->>R: GET /resource (with payment headers)
R->>X: verify/settle as needed
X-->>R: ok
R-->>U: 200 OK (resource)
end
sequenceDiagram
autonumber
participant R as Resource Server
participant X as x402 Backend
participant F as Facilitator
opt Verify then Settle
R->>X: verify(request headers)
X-->>R: verified | error
alt verified
R->>X: settle(payment)
X-->>R: settled | failed
end
end
opt Direct Settle
R->>X: settle(payment)
X-->>R: settled | failed
end
note over R,F: Facilitator can encapsulate verify/settle and manage wait states (simulated/submitted/confirmed)
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro Disabled knowledge base sources:
⛔ Files ignored due to path filters (1)
📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (2)
🧰 Additional context used📓 Path-based instructions (2)**/*.{ts,tsx}📄 CodeRabbit inference engine (CLAUDE.md)
Files:
**/*.{ts,tsx,js,jsx}📄 CodeRabbit inference engine (CLAUDE.md)
Files:
🧠 Learnings (1)📚 Learning: 2025-08-20T10:35:18.543ZApplied to files:
🪛 Gitleaks (8.28.0)apps/portal/src/app/payments/x402/facilitator/page.mdx[high] 296-298: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource. (curl-auth-header) [high] 306-308: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource. (curl-auth-header) [high] 257-257: Detected a Generic API Key, potentially exposing access to various services and sensitive operations. (generic-api-key) ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (1)
Comment |
github-actions
bot
added
the
Portal
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8149 +/- ##
==========================================
- Coverage 56.29% 56.28% -0.01%
==========================================
Files 906 906
Lines 59208 59208
Branches 4177 4176 -1
==========================================
- Hits 33329 33324 -5
- Misses 25774 25779 +5
Partials 105 105
🚀 New features to boost your workflow:
|
size-limit report 📦
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (5)
apps/portal/src/app/payments/sidebar.tsx (1)
69-89: Name nit: consider “Overview” instead of another “Get Started”.You now have “Get Started” at the Payments root and inside the x402 submenu. Renaming the x402 entry to “Overview” avoids duplicate labels in breadcrumbs/search.
apps/portal/src/app/payments/x402/client/page.mdx (2)
43-48: Prefer BigInt literal for clarity.Use an explicit BigInt literal to avoid number-to-BigInt coercion.
- BigInt(1 * 10 ** 6) // max 1 USDC + 1_000_000n // max 1 USDC (in base units)
104-106: Standardize header casing tox-payment.Other pages use
x-payment. Headers are case-insensitive, but consistency helps. Update the curl example to match.- -H "X-PAYMENT: <base64-encoded-payment>" + -H "x-payment: <base64-encoded-payment>"apps/portal/src/app/payments/x402/facilitator/page.mdx (1)
40-47: Avoid hard‑coding secret keys in samples.Use environment variables to discourage bad practices and quiet secret scanners.
- const client = createThirdwebClient({ - secretKey: "your-secret-key", - }); + const client = createThirdwebClient({ + secretKey: process.env.THIRDWEB_SECRET_KEY!, + });Also applies to: 78-86, 171-179, 204-211
apps/portal/src/app/payments/x402/page.mdx (1)
45-49: Prefer env var for secrets in examples.Replace inline
"your-secret-key"withprocess.env.THIRDWEB_SECRET_KEYto model best practices.-const client = createThirdwebClient({ secretKey: "your-secret-key" }); +const client = createThirdwebClient({ secretKey: process.env.THIRDWEB_SECRET_KEY! });
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (1)
apps/portal/src/app/payments/x402/server/x402-protocol-flow.pngis excluded by!**/*.png
📒 Files selected for processing (5)
apps/portal/src/app/payments/sidebar.tsx(1 hunks)apps/portal/src/app/payments/x402/client/page.mdx(1 hunks)apps/portal/src/app/payments/x402/facilitator/page.mdx(1 hunks)apps/portal/src/app/payments/x402/page.mdx(3 hunks)apps/portal/src/app/payments/x402/server/page.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Write idiomatic TypeScript with explicit function declarations and return types
Limit each file to one stateless, single-responsibility function for clarity
Re-use shared types from@/typesor localtypes.tsbarrels
Prefer type aliases over interface except for nominal shapes
Avoidanyandunknownunless unavoidable; narrow generics when possible
Choose composition over inheritance; leverage utility types (Partial,Pick, etc.)
Comment only ambiguous logic; avoid restating TypeScript in prose
**/*.{ts,tsx}: Use explicit function declarations and explicit return types in TypeScript
Limit each file to one stateless, single‑responsibility function
Re‑use shared types from@/typeswhere applicable
Prefertypealiases overinterfaceexcept for nominal shapes
Avoidanyandunknownunless unavoidable; narrow generics when possible
Prefer composition over inheritance; use utility types (Partial, Pick, etc.)
Lazy‑import optional features and avoid top‑level side‑effects to reduce bundle size
Files:
apps/portal/src/app/payments/sidebar.tsx
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Load heavy dependencies inside async paths to keep initial bundle lean (lazy loading)
Files:
apps/portal/src/app/payments/sidebar.tsx
🧠 Learnings (1)
📚 Learning: 2025-08-20T10:35:18.543Z
Learnt from: jnsdls
PR: thirdweb-dev/js#7888
File: apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/payments/page.tsx:77-81
Timestamp: 2025-08-20T10:35:18.543Z
Learning: The webhooks/payments route exists at apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/webhooks/payments/page.tsx and was added as part of the unified project layout changes.
Applied to files:
apps/portal/src/app/payments/sidebar.tsx
🪛 Gitleaks (8.28.0)
apps/portal/src/app/payments/x402/facilitator/page.mdx
[high] 260-260: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.
(generic-api-key)
[high] 299-301: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
[high] 309-311: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Size
- GitHub Check: Lint Packages
- GitHub Check: Analyze (javascript)
🔇 Additional comments (2)
apps/portal/src/app/payments/x402/server/page.mdx (1)
1-4: Image import is valid
The fileapps/portal/src/app/payments/x402/server/x402-protocol-flow.pngexists, so the./x402-protocol-flow.pngimport inpage.mdxis correct and will not break the build.Likely an incorrect or invalid review comment.
apps/portal/src/app/payments/x402/client/page.mdx (1)
64-65: Verify reference URL exists.Confirm this path resolves in the generated docs nav.
joaquim-verges
force-pushed
the
_Docs_Add_comprehensive_x402_payment_documentation
branch
from
3a3bd49 to
f9b75bf
Compare
joaquim-verges
deleted the
_Docs_Add_comprehensive_x402_payment_documentation
branch
PR-Codex overview
This PR primarily enhances the
x402payment protocol documentation, adding detailed guides for client-side and server-side implementations, alongside examples and explanations for payment handling. It also removes outdated files and improves the overall structure of the documentation.Detailed summary
page.tsxandx402-protocol-flow.pngfiles.sidebar.tsxto reflect new payment guides.wrapFetchWithPaymentusage.facilitatorAPI documentation.Summary by CodeRabbit
New Features
Documentation