Support for x402 protocol v2

Joaquim Verges

The thirdweb SDK now supports x402 protocol version 2, introducing header-based payment flows for improved efficiency and flexibility in blockchain payment integrations.

• New Payment Headers: v2 uses PAYMENT-SIGNATURE for requests and PAYMENT-RESPONSE for responses, replacing the v1 headers (X-PAYMENT and X-PAYMENT-RESPONSE)
• Streamlined Responses: Payment requirements are now encoded in the PAYMENT-REQUIRED header rather than the response body, reducing payload size
• Backward Compatibility: The SDK maintains full backward compatibility with v1, automatically detecting and handling both protocol versions

Payment data retrieval now prioritizes v2 headers with fallback to v1:

// Updated header reading pattern
const paymentData =
  request.headers.get("PAYMENT-SIGNATURE") ||
  request.headers.get("X-PAYMENT");

This change applies to:

• settlePayment() - Server-side payment settlement
• verifyPayment() - Payment verification
• Middleware implementations

New optional x402Version parameter allows explicit version control:

settlePayment({
  // ... other options
  x402Version: 2, // explicitly use v2
});

No breaking changes - existing v1 integrations continue to work unchanged. To adopt v2:

1. Update header reading to check both headers (as shown above)
2. Optionally specify x402Version: 2 in configuration
3. The SDK handles version negotiation automatically

For complete implementation details and examples, see the documentation.