[SDK] Expose waitUntil parameter in settlePayment()

Author: joaquim-verges

.changeset/yellow-cameras-tease.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": patch
+---
+
+Also expose waitUntil param in settlePayment()

packages/thirdweb/src/exports/x402.ts

@@ -3,12 +3,17 @@ export {
   facilitator,
   type ThirdwebX402Facilitator,
   type ThirdwebX402FacilitatorConfig,
+  type WaitUntil,
 } from "../x402/facilitator.js";
 export { wrapFetchWithPayment } from "../x402/fetchWithPayment.js";
 export { settlePayment } from "../x402/settle-payment.js";
 export type {
+  ERC20TokenAmount,
   PaymentArgs,
+  PaymentRequiredResult,
+  SettlePaymentArgs,
   SettlePaymentResult,
+  SupportedSignatureType,
   VerifyPaymentResult,
 } from "../x402/types.js";
 export { verifyPayment } from "../x402/verify-payment.js";

packages/thirdweb/src/x402/facilitator.ts

@@ -9,10 +9,12 @@ import type {
   RequestedPaymentRequirements,
 } from "./schemas.js";
 
+export type WaitUntil = "simulated" | "submitted" | "confirmed";
+
 export type ThirdwebX402FacilitatorConfig = {
   client: ThirdwebClient;
   serverWalletAddress: string;
-  waitUtil?: "simulated" | "submitted" | "confirmed";
+  waitUtil?: WaitUntil;
   vaultAccessToken?: string;
   baseUrl?: string;
 };
@@ -37,6 +39,7 @@ export type ThirdwebX402Facilitator = {
   settle: (
     payload: RequestedPaymentPayload,
     paymentRequirements: RequestedPaymentRequirements,
+    waitUtil?: WaitUntil,
   ) => Promise<FacilitatorSettleResponse>;
   supported: (filters?: {
     chainId: number;
@@ -81,6 +84,21 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
  *   },
  *   thirdwebX402Facilitator,
  * );
+ * ```
+ * 
+ * #### Configuration Options
+ * 
+ * ```ts
+ * const thirdwebX402Facilitator = facilitator({
+ *   client: client,
+ *   serverWalletAddress: "0x1234567890123456789012345678901234567890",
+ *   // Optional: Wait behavior for settlements
+ *   // - "simulated": Only simulate the transaction (fastest)
+ *   // - "submitted": Wait until transaction is submitted
+ *   // - "confirmed": Wait for full on-chain confirmation (slowest, default)
+ *   waitUntil: "confirmed",
+ * });
+
  * ```
  *
  * @bridge x402
@@ -167,12 +185,14 @@ export function facilitator(
     async settle(
       payload: RequestedPaymentPayload,
       paymentRequirements: RequestedPaymentRequirements,
+      waitUtil?: WaitUntil,
     ): Promise<FacilitatorSettleResponse> {
       const url = config.baseUrl ?? DEFAULT_BASE_URL;
 
       let headers = { "Content-Type": "application/json" };
       const authHeaders = await facilitator.createAuthHeaders();
       headers = { ...headers, ...authHeaders.settle };
+      const waitUtilParam = waitUtil || config.waitUtil;
 
       const res = await fetch(`${url}/settle`, {
         method: "POST",
@@ -181,7 +201,7 @@ export function facilitator(
           x402Version: payload.x402Version,
           paymentPayload: payload,
           paymentRequirements: paymentRequirements,
-          ...(config.waitUtil ? { waitUtil: config.waitUtil } : {}),
+          ...(waitUtilParam ? { waitUtil: waitUtilParam } : {}),
         }),
       });
 

packages/thirdweb/src/x402/settle-payment.ts

@@ -2,7 +2,7 @@ import { stringify } from "../utils/json.js";
 import { decodePaymentRequest } from "./common.js";
 import { safeBase64Encode } from "./encode.js";
 import {
-  type PaymentArgs,
+  type SettlePaymentArgs,
   type SettlePaymentResult,
   x402Version,
 } from "./types.js";
@@ -97,6 +97,7 @@ import {
  *     payTo: "0x1234567890123456789012345678901234567890",
  *     network: arbitrumSepolia, // or any other chain
  *     price: "$0.05",
+ *     waitUntil: "submitted",
  *     facilitator: thirdwebFacilitator,
  *   });
  *
@@ -124,7 +125,7 @@ import {
  * @bridge x402
  */
 export async function settlePayment(
-  args: PaymentArgs,
+  args: SettlePaymentArgs,
 ): Promise<SettlePaymentResult> {
   const { routeConfig = {}, facilitator } = args;
   const { errorMessages } = routeConfig;
@@ -142,6 +143,7 @@ export async function settlePayment(
     const settlement = await facilitator.settle(
       decodedPayment,
       selectedPaymentRequirements,
+      args.waitUntil,
     );
 
     if (settlement.success) {

packages/thirdweb/src/x402/types.ts

@@ -3,7 +3,7 @@ import type z from "zod";
 import type { Chain } from "../chains/types.js";
 import type { Address } from "../utils/address.js";
 import type { Prettify } from "../utils/type-utils.js";
-import type { ThirdwebX402Facilitator } from "./facilitator.js";
+import type { ThirdwebX402Facilitator, WaitUntil } from "./facilitator.js";
 import type {
   FacilitatorNetwork,
   FacilitatorSettleResponse,
@@ -39,6 +39,10 @@ export type PaymentArgs = {
   routeConfig?: PaymentMiddlewareConfig;
 };
 
+export type SettlePaymentArgs = PaymentArgs & {
+  waitUntil?: WaitUntil;
+};
+
 export type PaymentRequiredResult = {
   /** HTTP 402 - Payment Required, verification or processing failed or payment missing */
   status: 402;