thirdweb 5.112.4 → 5.114.0

package/src/x402/common.ts

@@ -35,28 +35,10 @@ type GetPaymentRequirementsResult = {
 export async function decodePaymentRequest(
   args: PaymentArgs,
 ): Promise<GetPaymentRequirementsResult | PaymentRequiredResult> {
-  const {
-    price,
-    network,
-    facilitator,
-    payTo,
-    resourceUrl,
-    routeConfig = {},
-    method,
-    paymentData,
-    extraMetadata,
-  } = args;
+  const { facilitator, routeConfig = {}, paymentData } = args;
   const { errorMessages } = routeConfig;
 
-  const paymentRequirementsResult = await facilitator.accepts({
-    resourceUrl,
-    method,
-    network,
-    price,
-    routeConfig,
-    payTo,
-    extraMetadata,
-  });
+  const paymentRequirementsResult = await facilitator.accepts(args);
 
   // Check for payment header, if none, return the payment requirements
   if (!paymentData) {

package/src/x402/facilitator.ts

@@ -107,7 +107,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
 
  * ```
  *
- * @bridge x402
+ * @x402
  */
 export function facilitator(
   config: ThirdwebX402FacilitatorConfig,
@@ -278,6 +278,7 @@ export function facilitator(
           method: args.method,
           network: caip2ChainId,
           price: args.price,
+          scheme: args.scheme,
           routeConfig: args.routeConfig,
           serverWalletAddress: facilitator.address,
           recipientAddress: args.payTo,

package/src/x402/fetchWithPayment.ts

@@ -23,7 +23,7 @@ import { createPaymentHeader } from "./sign.js";
  * @param fetch - The fetch function to wrap (typically globalThis.fetch)
  * @param client - The thirdweb client used to access RPC infrastructure
  * @param wallet - The wallet used to sign payment messages
- * @param maxValue - The maximum allowed payment amount in base units (defaults to 1 USDC)
+ * @param maxValue - The maximum allowed payment amount in base units
  * @returns A wrapped fetch function that handles 402 responses automatically
  *
  * @example
@@ -46,13 +46,18 @@ import { createPaymentHeader } from "./sign.js";
  * @throws {Error} If a payment has already been attempted for this request
  * @throws {Error} If there's an error creating the payment header
  *
- * @bridge x402
+ * @x402
  */
 export function wrapFetchWithPayment(
   fetch: typeof globalThis.fetch,
   client: ThirdwebClient,
   wallet: Wallet,
-  maxValue?: bigint,
+  options?: {
+    maxValue?: bigint;
+    paymentRequirementsSelector?: (
+      paymentRequirements: RequestedPaymentRequirements[],
+    ) => RequestedPaymentRequirements | undefined;
+  },
 ) {
   return async (input: RequestInfo, init?: RequestInit) => {
     const response = await fetch(input, init);
@@ -66,9 +71,9 @@ export function wrapFetchWithPayment(
       accepts: unknown[];
       error?: string;
     };
-    const parsedPaymentRequirements = accepts
-      .map((x) => RequestedPaymentRequirementsSchema.parse(x))
-      .filter((x) => x.scheme === "exact"); // TODO (402): accept other schemes
+    const parsedPaymentRequirements = accepts.map((x) =>
+      RequestedPaymentRequirementsSchema.parse(x),
+    );
 
     const account = wallet.getAccount();
     let chain = wallet.getChain();
@@ -78,12 +83,13 @@ export function wrapFetchWithPayment(
         "Wallet not connected. Please connect your wallet to continue.",
       );
     }
-    const selectedPaymentRequirements = defaultPaymentRequirementsSelector(
-      parsedPaymentRequirements,
-      chain.id,
-      "exact",
-      error,
-    );
+    const selectedPaymentRequirements = options?.paymentRequirementsSelector
+      ? options.paymentRequirementsSelector(parsedPaymentRequirements)
+      : defaultPaymentRequirementsSelector(
+          parsedPaymentRequirements,
+          chain.id,
+          error,
+        );
 
     if (!selectedPaymentRequirements) {
       throw new Error(
@@ -92,11 +98,11 @@ export function wrapFetchWithPayment(
     }
 
     if (
-      maxValue &&
-      BigInt(selectedPaymentRequirements.maxAmountRequired) > maxValue
+      options?.maxValue &&
+      BigInt(selectedPaymentRequirements.maxAmountRequired) > options.maxValue
     ) {
       throw new Error(
-        `Payment amount exceeds maximum allowed (currently set to ${maxValue} in base units)`,
+        `Payment amount exceeds maximum allowed (currently set to ${options.maxValue} in base units)`,
       );
     }
 
@@ -151,7 +157,6 @@ export function wrapFetchWithPayment(
 function defaultPaymentRequirementsSelector(
   paymentRequirements: RequestedPaymentRequirements[],
   chainId: number,
-  scheme: "exact",
   error?: string,
 ) {
   if (!paymentRequirements.length) {
@@ -161,9 +166,7 @@ function defaultPaymentRequirementsSelector(
   }
   // find the payment requirements matching the connected wallet chain
   const matchingPaymentRequirements = paymentRequirements.find(
-    (x) =>
-      extractEvmChainId(networkToCaip2ChainId(x.network)) === chainId &&
-      x.scheme === scheme,
+    (x) => extractEvmChainId(networkToCaip2ChainId(x.network)) === chainId,
   );
 
   if (matchingPaymentRequirements) {
@@ -171,9 +174,7 @@ function defaultPaymentRequirementsSelector(
   } else {
     // if no matching payment requirements, use the first payment requirement
     // and switch the wallet to that chain
-    const firstPaymentRequirement = paymentRequirements.find(
-      (x) => x.scheme === scheme,
-    );
+    const firstPaymentRequirement = paymentRequirements[0];
     return firstPaymentRequirement;
   }
 }

package/src/x402/schemas.ts

@@ -10,6 +10,7 @@ import {
 } from "x402/types";
 import { z } from "zod";
 import type { Chain } from "../chains/types.js";
+import { PaymentSchemeSchema } from "./types.js";
 
 const FacilitatorNetworkSchema = z.string();
 
@@ -17,6 +18,7 @@ export type FacilitatorNetwork = z.infer<typeof FacilitatorNetworkSchema>;
 
 const RequestedPaymentPayloadSchema = PaymentPayloadSchema.extend({
   network: FacilitatorNetworkSchema,
+  scheme: PaymentSchemeSchema,
 });
 
 export type RequestedPaymentPayload = z.infer<
@@ -32,6 +34,7 @@ export type UnsignedPaymentPayload = Omit<
 export const RequestedPaymentRequirementsSchema =
   PaymentRequirementsSchema.extend({
     network: FacilitatorNetworkSchema,
+    scheme: PaymentSchemeSchema,
   });
 
 export type RequestedPaymentRequirements = z.infer<
@@ -76,7 +79,7 @@ const FacilitatorSupportedResponseSchema =
     kinds: z.array(
       z.object({
         x402Version: z.literal(1),
-        scheme: z.literal("exact"),
+        scheme: PaymentSchemeSchema,
         network: FacilitatorNetworkSchema,
         extra: z
           .object({

package/src/x402/settle-payment.ts

@@ -51,7 +51,6 @@ import {
  *     routeConfig: {
  *       description: "Access to premium API content",
  *       mimeType: "application/json",
- *       maxTimeoutSeconds: 300,
  *     },
  *   });
  *
@@ -68,6 +67,18 @@ import {
  * }
  * ```
  *
+ * ### Upto Payment Scheme
+ *
+ * You can also use the `upto` payment scheme to settle the payment dynamically based on the usage.
+ *
+ * ```ts
+ * const result = await settlePayment({
+ *   ...paymentArgs,
+ *   scheme: "upto",
+ *   price: "$0.10", // max payable amount
+ * });
+ * ```
+ *
  * ### Express middleware example
  *
  * ```ts
@@ -122,7 +133,7 @@ import {
  *
  * @public
  * @beta
- * @bridge x402
+ * @x402
  */
 export async function settlePayment(
   args: SettlePaymentArgs,

package/src/x402/types.ts

@@ -1,5 +1,5 @@
 import type { Money, PaymentMiddlewareConfig } from "x402/types";
-import type z from "zod";
+import z from "zod";
 import type { Chain } from "../chains/types.js";
 import type { Prettify } from "../utils/type-utils.js";
 import type { ThirdwebX402Facilitator, WaitUntil } from "./facilitator.js";
@@ -31,6 +31,8 @@ export type PaymentArgs = {
   price: Money | ERC20TokenAmount;
   /** The payment facilitator instance used to verify and settle payments */
   facilitator: ThirdwebX402Facilitator;
+  /** The scheme of the payment, either "exact" or "upto", defaults to "exact" */
+  scheme?: PaymentScheme;
   /** Optional configuration for the payment middleware route */
   routeConfig?: PaymentMiddlewareConfig;
   /** Optional recipient address to receive the payment if different from your facilitator address */
@@ -91,7 +93,9 @@ export type VerifyPaymentResult = Prettify<
   | {
       /** HTTP 200 - Payment was successfully verified */
       status: 200;
+      /** The decoded payment payload */
       decodedPayment: RequestedPaymentPayload;
+      /** The selected payment requirements */
       selectedPaymentRequirements: RequestedPaymentRequirements;
     }
   | PaymentRequiredResult
@@ -101,8 +105,19 @@ export type SupportedSignatureType = z.infer<
   typeof SupportedSignatureTypeSchema
 >;
 
+export const PaymentSchemeSchema = z.union([
+  z.literal("exact"),
+  z.literal("upto"),
+]);
+type PaymentScheme = z.infer<typeof PaymentSchemeSchema>;
+
+/**
+ * The asset, scheme and amount for the payment in base units
+ */
 export type ERC20TokenAmount = {
+  /** The amount of the payment in base units */
   amount: string;
+  /** The asset of the payment, decimals and eip712 data are optional and will be inferred from the address if not provided */
   asset: {
     address: `0x${string}`;
     decimals?: number;

package/src/x402/verify-payment.ts

@@ -42,7 +42,6 @@ import {
  *     routeConfig: {
  *       description: "Access to premium API content",
  *       mimeType: "application/json",
- *       maxTimeoutSeconds: 300,
  *     },
  *   };
  *
@@ -68,9 +67,20 @@ import {
  * }
  * ```
  *
+ * ### Upto Payment Scheme
+ *
+ * You can also use the `upto` payment scheme to verify a payment where the final price is dynamically calculated based on the usage.
+ *
+ * ```ts
+ * const result = await verifyPayment({
+ *   ...paymentArgs,
+ *   scheme: "upto",
+ *   price: "$0.10", // max payable amount
+ * });
+ * ```
  * @public
  * @beta
- * @bridge x402
+ * @x402
  */
 export async function verifyPayment(
   args: PaymentArgs,