Skip to content

Update x402 default payment validity window #8317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 27, 2025
Merged

Update x402 default payment validity window #8317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d84c7c1
Update x402 default payment validity window
0xFirekeeper Oct 27, 2025
445e77e
Create good-ducks-eat.md
0xFirekeeper Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/good-ducks-eat.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"thirdweb": patch
---

updates default x402 transfer with authorization timeout
2 changes: 1 addition & 1 deletion packages/thirdweb/src/x402/common.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ export async function decodePaymentRequest(
description: description ?? "",
mimeType: mimeType ?? "application/json",
payTo: getAddress(facilitator.address), // always pay to the facilitator address first
maxTimeoutSeconds: maxTimeoutSeconds ?? 300,
maxTimeoutSeconds: maxTimeoutSeconds ?? 86400,
Copy link
Contributor

@coderabbitai coderabbitai bot Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify that 24-hour timeout aligns with security and UX requirements.

The default maxTimeoutSeconds has been increased from 300 seconds (5 minutes) to 86400 seconds (24 hours). While this supports retry scenarios as mentioned in the PR description, consider the following:

  1. Security: A 24-hour validity window for payment authorizations significantly increases the window for potential replay attacks or misuse of stale authorizations.
  2. User Experience: Users expecting near-instant responses may experience confusion with such a long timeout.
  3. Breaking Change: Existing integrations may have assumptions about the 5-minute default that could affect timeout handling, monitoring, or user flows.

Verify that this timeout duration is appropriate for your payment flow. Consider whether a more granular approach (e.g., different defaults for different scenarios) would be more suitable. You may also want to search for best practices around EIP-2612 and EIP-3009 authorization validity windows:

🌐 Web query:

What are the recommended validity window durations for EIP-2612 Permit and EIP-3009 TransferWithAuthorization signatures?

💡 Result:

Short answer

  • EIP‑2612 (permit): the spec leaves deadline to the signer; common practice is to use short expiries (minutes→hours). Example usages and docs commonly show deadline = now + 3600s (1 hour) or shorter (e.g., 5–20 minutes) as best practice. [EIP‑2612][1][2][3]

  • EIP‑3009 (transferWithAuthorization): the spec provides validAfter/validBefore and recommends bounding authorizations; common examples use validBefore = now + 3600s (1 hour) and validAfter = now (or a short delay), i.e. a validity window (minutes→hours) chosen by the app. [EIP‑3009][4][5][6]

Notes

  • Neither standard mandates a specific duration — choose based on UX/risk (short windows reduce misuse but increase fragility for relayers). See the EIPs and implementation examples. [1][4][5]

Sources

  1. EIP‑2612 specification (permit, deadline discussion). [EIP‑2612]. [2]
  2. OpenZeppelin / ERC20Permit implementation notes (deadline requirement). [3]
  3. Developer examples showing common deadline usage (now + 3600s). [7]
  4. EIP‑3009 specification (validAfter/validBefore fields and rationale). [4]
  5. EIP‑3009 examples and implementations using validBefore = now + 3600s. [5][6]

References
[1] https://eips.ethereum.org/EIPS/eip-2612
[2] https://eips-wg.github.io/EIPs/2612/
[3] https://docs.openzeppelin.com/contracts/ (ERC20Permit)
[4] https://eips.ethereum.org/EIPS/eip-3009
[5] https://eips-wg.github.io/EIPs/3009/
[6] example usages (libraries/docs showing validBefore/deadline = now + 3600s).

🏁 Script executed:

#!/bin/bash
# Inspect the file context to understand maxTimeoutSeconds purpose
cat packages/thirdweb/src/x402/common.ts

Length of output: 10404

🏁 Script executed:

#!/bin/bash
# Search for references to maxTimeoutSeconds to understand its use case
rg -n "maxTimeoutSeconds" --type ts -C 3

Length of output: 3838

🏁 Script executed:

#!/bin/bash
# Check for any comments or documentation about timeout durations
rg -n "timeout|Timeout" packages/thirdweb/src/x402/ --type ts -C 2

Length of output: 1850

Reduce maxTimeoutSeconds default from 86400 to align with EIP-2612/EIP-3009 best practices.

The default timeout was increased from 300 seconds (5 minutes) to 86400 seconds (24 hours). This contradicts established standards:

  • EIP-2612 and EIP-3009 best practice is short expiries of minutes→hours, commonly 1 hour or 5-20 minutes
  • Your documentation examples in verify-payment.ts and settle-payment.ts use maxTimeoutSeconds: 300 (5 minutes)
  • The code sets validBefore for signature validity (line 38 in sign.ts), directly affecting authorization window length

A 24-hour validity window creates a significant security gap: signatures remain valid for an entire day, increasing exposure to replay attacks or misuse of stale authorizations. Reduce the default to 3600 (1 hour) or provide documented security justification for the 24-hour window.

🤖 Prompt for AI Agents 
In packages/thirdweb/src/x402/common.ts around line 110, the default
maxTimeoutSeconds is set to 86400 (24h) which is inconsistent with
EIP-2612/EIP-3009 best practices and existing examples; change the default to
3600 (1 hour) (or 300 if you prefer 5 minutes) to reduce the authorization
window, and ensure any related logic (e.g., the validBefore calculation in
sign.ts line 38) and documentation/examples (verify-payment.ts and
settle-payment.ts) are updated to reflect the new default so defaults remain
consistent across the codebase.

asset: getAddress(asset.address),
outputSchema: {
input: {
Expand Down
2 changes: 1 addition & 1 deletion packages/thirdweb/src/x402/sign.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ function preparePaymentHeader(
nonce: Hex,
): UnsignedPaymentPayload {
const validAfter = BigInt(
Math.floor(Date.now() / 1000) - 600, // 10 minutes before
Math.floor(Date.now() / 1000) - 86400, // 24h before in case weird block timestamp behavior
).toString();
const validBefore = BigInt(
Math.floor(Date.now() / 1000 + paymentRequirements.maxTimeoutSeconds),
Expand Down
Loading