[Portal] Improve documentation for upto payment scheme

[joaquim-verges]

---

PR-Codex overview

This PR enhances the documentation for the upto payment scheme, clarifying its functionality, adding configuration details for signature expiration, and providing updated examples for better understanding.

Detailed summary

• Expanded explanation of the upto payment scheme.
• Added details on signature expiration configuration in settlePayment() and verifyPayment().
• Updated examples with clearer syntax and context.
• Increased maxTimeoutSeconds for several API configurations to 1 hour.

✨ Ask PR-Codex anything about this PR by commenting with /codex {your question}

Summary by CodeRabbit

• Documentation
  • Expanded Upto Payment Scheme docs: clarified max-amount verification, multi-settlement behavior, reuse of signed payloads, and added a working example.
  • Added “Signature expiration configuration” guidance with a 24-hour configuration example and updated expiration recommendations (defaults shortened to 1 hour).
  • Updated usage examples to show full settle flow with token and usage-based pricing, fixed formatting/indentation in examples, and minor wording tweaks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
docs-v2	Ready	Preview	Comment	Dec 10, 2025 8:52pm

4 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
nebula	Skipped			Dec 10, 2025 8:52pm
thirdweb_playground	Skipped			Dec 10, 2025 8:52pm
thirdweb-www	Skipped			Dec 10, 2025 8:52pm
wallet-ui	Skipped			Dec 10, 2025 8:52pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: f12fc49

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

Expanded the Upto Payment Scheme documentation: replaced the brief note with a detailed explanation of max-amount verification, multi-settlement behavior up to the authorized maximum, reuse of the same signed payment payload across settlements, and expiration semantics. Added a "Signature expiration configuration" section with a maxTimeoutSeconds example, updated example snippets for the upto flow and settlePayment usage (including token- and usage-based pricing), changed several maxTimeoutSeconds occurrences from 300 to 60 * 60 (1 hour), and applied minor formatting and wording tweaks.

Changes

Cohort / File(s)

Summary

Documentation & examples apps/portal/src/app/x402/server/page.mdx

Expanded Upto Payment Scheme narrative with explicit validation, multi-settlement, reuse-of-signed-payload, and expiration details. Added "Signature expiration configuration" showing maxTimeoutSeconds via routeConfig (24-hour example). Updated example snippets for the upto flow and full settlePayment usage (token-based and usage-based final pricing). Replaced several maxTimeoutSeconds values from 300 to 60 * 60 and adjusted surrounding prose. Applied minor JSX/MDX formatting/indentation fixes and wording tweaks (including a GithubTemplateCard block).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Review focus:
  • Verify all maxTimeoutSeconds value changes (300 → 60 * 60) are consistent and correct in examples.
  • Check placement and accuracy of the "Signature expiration configuration" snippet.
  • Validate updated settlePayment / upto flow examples for correctness and clarity.
  • Confirm MDX/JSX formatting and the GithubTemplateCard render as intended.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description includes a PR-Codex overview with a summary and detailed points about changes, but lacks the required template sections: issue tag, 'Notes for the reviewer', and 'How to test'.	Add the missing sections from the template: include the Linear issue tag (TEAM-0000 format), provide 'Notes for the reviewer' section, and add 'How to test' section with testing instructions.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title '[Portal] Improve documentation for upto payment scheme' directly corresponds to the main changes in the PR, which focus on enhancing documentation for the upto payment scheme.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch _X402_Improve_documentation_for_upto_payment_scheme

---

📜 Recent 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.

📥 Commits

Reviewing files that changed from the base of the PR and between 90f270d and f12fc49.

📒 Files selected for processing (1)

• apps/portal/src/app/x402/server/page.mdx (10 hunks)

⏰ 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)

• GitHub Check: Size
• GitHub Check: Analyze (javascript)

🔇 Additional comments (4)

apps/portal/src/app/x402/server/page.mdx (4)

8-9: Imports are correctly added for new component usage.

The imports of Stack and GithubTemplateCard are necessary for the expanded documentation and are properly placed.

---

127-138: Clear and correct signature expiration configuration section.

The new section correctly demonstrates how to configure maxTimeoutSeconds with accurate calculation (60 * 60 * 24 = 24 hours). This properly addresses the previous timeout calculation error and provides clear guidance.

---

218-218: maxTimeoutSeconds values are consistent across all endpoint and middleware examples.

All examples correctly use 60 * 60 (1 hour) with consistent inline comments. The separation of a 24-hour educational example in the "Signature expiration configuration" section (line 135) from the practical 1-hour defaults in usage examples is pedagogically sound and helps users understand both configuration and typical values.

Also applies to: 268-268, 321-321, 388-388, 446-446, 501-501

---

160-169: ERC20 token example is clear and correctly demonstrates token payment configuration.

The example properly shows how to pass token configuration with amount in base units and asset address. This provides developers with concrete guidance for ERC20 payment integration.

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• TEAM-0000: Entity not found: Issue - Could not find referenced Issue.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[joaquim-verges]

• [Portal] Improve documentation for upto payment scheme #8531 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge-queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.66%. Comparing base (1487de6) to head (f12fc49).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8531   +/-   ##
=======================================
  Coverage   54.66%   54.66%           
=======================================
  Files         921      921           
  Lines       61163    61163           
  Branches     4151     4151           
=======================================
  Hits        33435    33435           
  Misses      27627    27627           
  Partials      101      101           

Flag	Coverage Δ
packages	54.66% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

📜 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.

📥 Commits

Reviewing files that changed from the base of the PR and between 1487de6 and eaf626d.

📒 Files selected for processing (1)

• apps/portal/src/app/x402/server/page.mdx (1 hunks)

⏰ 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: Lint Packages
• GitHub Check: Size
• GitHub Check: Analyze (javascript)

🔇 Additional comments (1)

apps/portal/src/app/x402/server/page.mdx (1)

73-77: Documentation improvements are clear and well-structured.

The expanded explanation of the upto payment scheme provides excellent clarity on the workflow (verify → work → settle) and the key capability of multiple settlements up to the authorized maximum. The three bullet points effectively highlight the benefits and mechanics. The documentation aligns well with the code example provided below.

[github-actions]

size-limit report 📦

Path	Size
@thirdweb-dev/nexus (esm)	105.66 KB (0%)
@thirdweb-dev/nexus (cjs)	319.47 KB (0%)

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

apps/portal/src/app/x402/server/page.mdx (1)

80-80: Add missing comma for readability.

The phrase "For a fully working example check out" would read more naturally with a comma before the verb.

-This is great for AI apis that need to charge based on the token usage for example. For a fully working example check out [this x402 ai inference example](https://github.com/thirdweb-example/x402-ai-inference).
+This is great for AI apis that need to charge based on the token usage for example. For a fully working example, check out [this x402 ai inference example](https://github.com/thirdweb-example/x402-ai-inference).

📜 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.

📥 Commits

Reviewing files that changed from the base of the PR and between a54ef9a and 90f270d.

📒 Files selected for processing (1)

• apps/portal/src/app/x402/server/page.mdx (10 hunks)

⏰ 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). (7)

• GitHub Check: E2E Tests (pnpm, webpack)
• GitHub Check: Build Packages
• GitHub Check: E2E Tests (pnpm, vite)
• GitHub Check: Size
• GitHub Check: Unit Tests
• GitHub Check: Lint Packages
• GitHub Check: Analyze (javascript)

🔇 Additional comments (1)

apps/portal/src/app/x402/server/page.mdx (1)

8-9: LGTM—imports are correctly added for the new components.

Stack and GithubTemplateCard imports are necessary for the card component added at lines 82–88.