[SDK] Accept x402 v2 payment requirements that specify amount

.changeset/x402-v2-amount.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Accept x402 v2 payment requirements that specify `amount`, and enforce `maxValue: 0n` as a cap.

apps/dashboard/src/app/(app)/team/[team_slug]/[project_slug]/(sidebar)/x402/components/X402EmptyState.tsx

@@ -44,7 +44,9 @@ export async function GET(request: Request) {
   const result = await settlePayment({
     resourceUrl: "https://api.example.com/premium-content",
     method: "GET",
-    paymentData: request.headers.get("x-payment"),
+    paymentData:
+      request.headers.get("PAYMENT-SIGNATURE") ||
+      request.headers.get("X-PAYMENT"),
     network: arbitrumSepolia,
     price: "$0.01",
     facilitator: thirdwebX402Facilitator,

apps/playground-web/src/app/x402/components/X402RightSection.tsx

@@ -94,11 +94,13 @@ const client = createThirdwebClient({
 const thirdwebFacilitator = facilitator({
   client,
   serverWalletAddress: "0xYourServerWalletAddress",
-  waitUtil: "${props.options.waitUntil}",
+  waitUntil: "${props.options.waitUntil}",
 });
 
 export async function POST(request: Request) {
-  const paymentData = request.headers.get("x-payment");
+  const paymentData =
+    request.headers.get("PAYMENT-SIGNATURE") ||
+    request.headers.get("X-PAYMENT");
 
   // verify and process the payment
   const result = await settlePayment({

apps/portal/src/app/x402/server/page.mdx

@@ -267,7 +267,7 @@ Protect individual API endpoints with x402 payments:
       const result = await settlePayment({
         resourceUrl: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
         method: req.method,
-        paymentData: req.headers["x-payment"],
+        paymentData: req.headers["payment-signature"] ?? req.headers["x-payment"],
         payTo: "0x1234567890123456789012345678901234567890",
         network: arbitrumSepolia,
         price: "$0.05",
@@ -320,7 +320,7 @@ Protect individual API endpoints with x402 payments:
       const result = await settlePayment({
         resourceUrl: new URL(c.req.url).toString(),
         method: c.req.method,
-        paymentData: c.req.header("x-payment"),
+        paymentData: c.req.header("payment-signature") ?? c.req.header("x-payment"),
         payTo: "0x1234567890123456789012345678901234567890",
         network: arbitrumSepolia,
         price: "$0.05",
@@ -445,7 +445,7 @@ Protect multiple endpoints with a shared middleware:
       const result = await settlePayment({
         resourceUrl: `${req.protocol}://${req.get('host')}${req.originalUrl}`,
         method: req.method,
-        paymentData: req.headers["x-payment"],
+        paymentData: req.headers["payment-signature"] ?? req.headers["x-payment"],
         payTo: "0x1234567890123456789012345678901234567890",
         network: arbitrumSepolia,
         price: "$0.05",
@@ -500,7 +500,7 @@ Protect multiple endpoints with a shared middleware:
       const result = await settlePayment({
         resourceUrl: new URL(c.req.url).toString(),
         method: c.req.method,
-        paymentData: c.req.header("x-payment"),
+        paymentData: c.req.header("payment-signature") ?? c.req.header("x-payment"),
         payTo: "0x1234567890123456789012345678901234567890",
         network: arbitrumSepolia,
         price: "$0.05",

packages/thirdweb/src/react/core/hooks/x402/useFetchWithPaymentCore.ts

@@ -4,7 +4,10 @@ import { useMutation } from "@tanstack/react-query";
 import type { ThirdwebClient } from "../../../../client/client.js";
 import type { AsyncStorage } from "../../../../utils/storage/AsyncStorage.js";
 import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
-import { wrapFetchWithPayment } from "../../../../x402/fetchWithPayment.js";
+import {
+  getRequestUrl,
+  wrapFetchWithPayment,
+} from "../../../../x402/fetchWithPayment.js";
 import type { RequestedPaymentRequirements } from "../../../../x402/schemas.js";
 import type { PaymentRequiredResult } from "../../../../x402/types.js";
 import { useActiveWallet } from "../wallets/useActiveWallet.js";
@@ -24,6 +27,7 @@ export type UseFetchWithPaymentOptions = {
 
 type ShowErrorModalCallback = (data: {
   errorData: PaymentRequiredResult["responseBody"];
+  requestUrl?: string;
   onRetry: () => void;
   onCancel: () => void;
 }) => void;
@@ -107,6 +111,7 @@ export function useFetchWithPaymentCore(
               return new Promise<unknown>((resolve, reject) => {
                 showErrorModal({
                   errorData: errorBody,
+                  requestUrl: getRequestUrl(input),
                   onRetry: async () => {
                     // Retry the entire fetch+error handling logic recursively
                     // Pass currentWallet to avoid re-showing connect modal with stale wallet state

packages/thirdweb/src/react/native/hooks/x402/useFetchWithPayment.ts

@@ -27,7 +27,7 @@ export type { UseFetchWithPaymentOptions };
  *
  * @param client - The thirdweb client used to access RPC infrastructure
  * @param options - Optional configuration for payment handling
- * @param options.maxValue - The maximum allowed payment amount in base units
+ * @param options.maxValue - The maximum allowed payment amount in base units. `0n` only allows zero-amount payments
  * @param options.paymentRequirementsSelector - Custom function to select payment requirements from available options
  * @param options.parseAs - How to parse the response: "json" (default), "text", or "raw"
  * @param options.storage - Storage for caching permit signatures (for "upto" scheme). Provide your own AsyncStorage implementation for React Native.

packages/thirdweb/src/react/web/hooks/x402/useFetchWithPayment.tsx

@@ -78,7 +78,7 @@ type UseFetchWithPaymentConfig = UseFetchWithPaymentOptions & {
  *
  * @param client - The thirdweb client used to access RPC infrastructure
  * @param options - Optional configuration for payment handling
- * @param options.maxValue - The maximum allowed payment amount in base units
+ * @param options.maxValue - The maximum allowed payment amount in base units. `0n` only allows zero-amount payments
  * @param options.paymentRequirementsSelector - Custom function to select payment requirements from available options
  * @param options.parseAs - How to parse the response: "json" (default), "text", or "raw"
  * @param options.uiEnabled - Whether to show the UI for connection, funding or payment retries (defaults to true). Set to false to handle errors yourself
@@ -196,13 +196,15 @@ export function useFetchWithPayment(
   const showErrorModal = showModal
     ? (data: {
         errorData: Parameters<typeof PaymentErrorModal>[0]["errorData"];
+        requestUrl?: string;
         onRetry: () => void;
         onCancel: () => void;
       }) => {
         setRootEl(
           <PaymentErrorModal
             client={client}
             errorData={data.errorData}
+            requestUrl={data.requestUrl}
             onCancel={() => {
               setRootEl(null);
               data.onCancel();

packages/thirdweb/src/react/web/ui/x402/PaymentErrorModal.tsx

@@ -5,6 +5,7 @@ import type { ThirdwebClient } from "../../../../client/client.js";
 import {
   extractEvmChainId,
   networkToCaip2ChainId,
+  parsePaymentRequirementsForDisplay,
   type RequestedPaymentRequirements,
 } from "../../../../x402/schemas.js";
 import type { PaymentRequiredResult } from "../../../../x402/types.js";
@@ -25,6 +26,7 @@ import { Text } from "../components/text.js";
 type PaymentErrorModalProps = {
   client: ThirdwebClient;
   errorData: PaymentRequiredResult["responseBody"];
+  requestUrl?: string;
   onRetry: () => void;
   onCancel: () => void;
   theme: Theme | "light" | "dark";
@@ -54,6 +56,7 @@ export function PaymentErrorModal(props: PaymentErrorModalProps) {
   const {
     client,
     errorData,
+    requestUrl,
     onRetry,
     onCancel,
     theme,
@@ -66,13 +69,15 @@ export function PaymentErrorModal(props: PaymentErrorModalProps) {
 
   // Extract chain and token info from errorData for BuyWidget
   const getBuyWidgetConfig = () => {
-    if (!errorData.accepts || errorData.accepts.length === 0) {
+    // Get payment requirements from errorData
+    const parsedPaymentRequirements = parsePaymentRequirementsForDisplay(
+      errorData,
+      requestUrl,
+    );
+    if (parsedPaymentRequirements.length === 0) {
       return null;
     }
 
-    // Get payment requirements from errorData
-    const parsedPaymentRequirements = errorData.accepts;
-
     // Get the current chain from wallet
     const currentChain = wallet?.getChain();
     const currentChainId = currentChain?.id;

packages/thirdweb/src/x402/encode.ts

@@ -1,4 +1,6 @@
 import type { ExactEvmPayload } from "x402/types";
+import { cachedTextDecoder } from "../utils/text-decoder.js";
+import { cachedTextEncoder } from "../utils/text-encoder.js";
 import type {
   RequestedPaymentPayload,
   RequestedPaymentRequirements,
@@ -27,7 +29,7 @@
       ) as ExactEvmPayload["authorization"],
     },
   };
-  return safeBase64Encode(JSON.stringify(safe));
+  return base64EncodeUtf8(JSON.stringify(safe));
 }
 
 /**
@@ -37,7 +39,7 @@
  * @returns The decoded and validated PaymentPayload object
  */
 export function decodePayment(payment: string): RequestedPaymentPayload {
-  const decoded = safeBase64Decode(payment);
+  const decoded = base64DecodeUtf8(payment);
   const parsed = JSON.parse(decoded);
 
   const obj: RequestedPaymentPayload = {
@@ -93,3 +95,45 @@
   }
   return Buffer.from(data, "base64").toString("utf-8");
 }
+
+/**
+ * Encodes a string as UTF-8 and then to base64
+ *
+ * @param data - The string to encode
+ * @returns The base64 encoded UTF-8 bytes
+ */
+function base64EncodeUtf8(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.btoa === "function"
+  ) {
+    const bytes = cachedTextEncoder().encode(data);
+    let binary = "";
+    for (const byte of bytes) {
+      binary += String.fromCharCode(byte);
+    }
+    return globalThis.btoa(binary);
+  }
+  return Buffer.from(data, "utf-8").toString("base64");
+}
+
+/**
+ * Decodes a base64 string and interprets the bytes as UTF-8
+ *
+ * @param data - The base64 encoded string
+ * @returns The decoded string
+ */
+export function base64DecodeUtf8(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.atob === "function"
+  ) {
+    const binary = globalThis.atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return cachedTextDecoder().decode(bytes);
+  }
+  return Buffer.from(data, "base64").toString("utf-8");
+}