thirdweb 5.107.1-nightly-51177fbe17153b711d80ec87b43aadc8ca12fb9e-20250922000346 → 5.108.0-nightly-a94f22928a662a5aff7a203fc2d383d9fa0907ec-20250923000340

package/src/react/web/ui/Bridge/BridgeOrchestrator.tsx

@@ -82,17 +82,17 @@ export interface BridgeOrchestratorProps {
   /**
    * Called when the flow is completed successfully
    */
-  onComplete: () => void;
+  onComplete: (quote: BridgePrepareResult) => void;
 
   /**
    * Called when the flow encounters an error
    */
-  onError: (error: Error) => void;
+  onError: (error: Error, quote: BridgePrepareResult | undefined) => void;
 
   /**
    * Called when the user cancels the flow
    */
-  onCancel: () => void;
+  onCancel: (quote: BridgePrepareResult | undefined) => void;
 
   /**
    * Connect options for wallet connection
@@ -189,19 +189,22 @@ export function BridgeOrchestrator({
   }, [send, uiOptions.mode]);
 
   // Handle post-buy transaction completion
-  const handlePostBuyTransactionComplete = useCallback(() => {
-    onComplete?.();
-    send({ type: "RESET" });
-  }, [onComplete, send]);
+  const handlePostBuyTransactionComplete = useCallback(
+    (quote: BridgePrepareResult) => {
+      onComplete?.(quote);
+      send({ type: "RESET" });
+    },
+    [onComplete, send],
+  );
 
   // Handle errors
   const handleError = useCallback(
     (error: Error) => {
       console.error(error);
-      onError?.(error);
+      onError?.(error, state.context.quote);
       send({ error, type: "ERROR_OCCURRED" });
     },
-    [onError, send],
+    [onError, send, state.context.quote],
   );
 
   // Handle payment method selection
@@ -227,10 +230,13 @@ export function BridgeOrchestrator({
 
   // Handle execution complete
   const handleExecutionComplete = useCallback(
-    (completedStatuses: CompletedStatusResult[]) => {
+    (
+      completedStatuses: CompletedStatusResult[],
+      quote: BridgePrepareResult,
+    ) => {
       send({ completedStatuses, type: "EXECUTION_COMPLETE" });
       if (uiOptions.mode !== "transaction") {
-        onComplete?.();
+        onComplete?.(quote);
       }
     },
     [send, onComplete, uiOptions.mode],
@@ -241,6 +247,8 @@ export function BridgeOrchestrator({
     send({ type: "RETRY" });
   }, [send]);
 
+  const quote = state.context.quote;
+
   // Handle requirements resolved from FundWallet and DirectPayment
   const handleRequirementsResolved = useCallback(
     (amount: string, token: TokenWithPrices, receiverAddress: Address) => {
@@ -263,7 +271,7 @@ export function BridgeOrchestrator({
           error={state.context.currentError}
           onCancel={() => {
             send({ type: "RESET" });
-            onCancel?.();
+            onCancel?.(quote);
           }}
           onRetry={handleRetry}
         />
@@ -369,31 +377,33 @@ export function BridgeOrchestrator({
           />
         )}
 
-      {state.value === "execute" &&
-        state.context.quote &&
-        state.context.request && (
-          <StepRunner
-            autoStart={true}
-            client={client}
-            onBack={() => {
-              send({ type: "BACK" });
-            }}
-            onCancel={onCancel}
-            onComplete={handleExecutionComplete}
-            request={state.context.request}
-            wallet={state.context.selectedPaymentMethod?.payerWallet}
-            windowAdapter={webWindowAdapter}
-          />
-        )}
+      {state.value === "execute" && quote && state.context.request && (
+        <StepRunner
+          autoStart={true}
+          client={client}
+          onBack={() => {
+            send({ type: "BACK" });
+          }}
+          onCancel={() => {
+            onCancel(quote);
+          }}
+          onComplete={(completedStatuses) => {
+            handleExecutionComplete(completedStatuses, quote);
+          }}
+          request={state.context.request}
+          wallet={state.context.selectedPaymentMethod?.payerWallet}
+          windowAdapter={webWindowAdapter}
+        />
+      )}
 
       {state.value === "success" &&
-        state.context.quote &&
+        quote &&
         state.context.completedStatuses && (
           <SuccessScreen
             client={client}
             completedStatuses={state.context.completedStatuses}
             onDone={handleDoneOrContinueClick}
-            preparedQuote={state.context.quote}
+            preparedQuote={quote}
             uiOptions={uiOptions}
             windowAdapter={webWindowAdapter}
             hasPaymentId={!!paymentLinkId}
@@ -402,9 +412,10 @@ export function BridgeOrchestrator({
 
       {state.value === "post-buy-transaction" &&
         uiOptions.mode === "transaction" &&
+        quote &&
         uiOptions.transaction && (
           <ExecutingTxScreen
-            closeModal={handlePostBuyTransactionComplete}
+            closeModal={() => handlePostBuyTransactionComplete(quote)}
             onTxSent={() => {
               // Do nothing
             }}

package/src/react/web/ui/Bridge/BuyWidget.tsx

@@ -23,6 +23,7 @@ import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProv
 import type { Theme } from "../../../core/design-system/index.js";
 import type { SiweAuthOptions } from "../../../core/hooks/auth/useSiweAuth.js";
 import type { ConnectButton_connectModalOptions } from "../../../core/hooks/connection/ConnectButtonProps.js";
+import type { BridgePrepareResult } from "../../../core/hooks/useBridgePrepare.js";
 import type { SupportedTokens } from "../../../core/utils/defaultTokens.js";
 import { useConnectLocale } from "../ConnectWallet/locale/getConnectLocale.js";
 import { EmbedContainer } from "../ConnectWallet/Modal/ConnectEmbed.js";
@@ -32,6 +33,11 @@ import type { LocaleId } from "../types.js";
 import { BridgeOrchestrator, type UIOptions } from "./BridgeOrchestrator.js";
 import { UnsupportedTokenScreen } from "./UnsupportedTokenScreen.js";
 
+type BuyOrOnrampPrepareResult = Extract<
+  BridgePrepareResult,
+  { type: "buy" | "onramp" }
+>;
+
 export type BuyWidgetProps = {
   /**
    * Customize the supported tokens that users can pay with.
@@ -155,17 +161,17 @@ export type BuyWidgetProps = {
   /**
    * Callback triggered when the purchase is successful.
    */
-  onSuccess?: () => void;
+  onSuccess?: (quote: BuyOrOnrampPrepareResult) => void;
 
   /**
    * Callback triggered when the purchase encounters an error.
    */
-  onError?: (error: Error) => void;
+  onError?: (error: Error, quote: BuyOrOnrampPrepareResult | undefined) => void;
 
   /**
    * Callback triggered when the user cancels the purchase.
    */
-  onCancel?: () => void;
+  onCancel?: (quote: BuyOrOnrampPrepareResult | undefined) => void;
 
   /**
    * @hidden
@@ -447,14 +453,23 @@ export function BuyWidget(props: BuyWidgetProps) {
         client={props.client}
         connectLocale={localeQuery.data}
         connectOptions={props.connectOptions}
-        onCancel={() => {
-          props.onCancel?.();
+        onCancel={(quote) => {
+          // type guard
+          if (quote?.type === "buy" || quote?.type === "onramp") {
+            props.onCancel?.(quote);
+          }
         }}
-        onComplete={() => {
-          props.onSuccess?.();
+        onComplete={(quote) => {
+          // type guard
+          if (quote?.type === "buy" || quote?.type === "onramp") {
+            props.onSuccess?.(quote);
+          }
         }}
-        onError={(err: Error) => {
-          props.onError?.(err);
+        onError={(err: Error, quote) => {
+          // type guard
+          if (quote?.type === "buy" || quote?.type === "onramp") {
+            props.onError?.(err, quote);
+          }
         }}
         paymentLinkId={props.paymentLinkId}
         paymentMethods={props.paymentMethods}

package/src/version.ts

@@ -1 +1 @@
-export const version = "5.107.1-nightly-51177fbe17153b711d80ec87b43aadc8ca12fb9e-20250922000346";
+export const version = "5.108.0-nightly-a94f22928a662a5aff7a203fc2d383d9fa0907ec-20250923000340";

package/src/x402/encode.ts

@@ -0,0 +1,81 @@
+import type { ExactEvmPayload } from "x402/types";
+import {
+  type RequestedPaymentPayload,
+  RequestedPaymentPayloadSchema,
+} from "./schemas.js";
+
+/**
+ * Encodes a payment payload into a base64 string, ensuring bigint values are properly stringified
+ *
+ * @param payment - The payment payload to encode
+ * @returns A base64 encoded string representation of the payment payload
+ */
+export function encodePayment(payment: RequestedPaymentPayload): string {
+  let safe: RequestedPaymentPayload;
+
+  // evm
+  const evmPayload = payment.payload as ExactEvmPayload;
+  safe = {
+    ...payment,
+    payload: {
+      ...evmPayload,
+      authorization: Object.fromEntries(
+        Object.entries(evmPayload.authorization).map(([key, value]) => [
+          key,
+          typeof value === "bigint" ? (value as bigint).toString() : value,
+        ]),
+      ) as ExactEvmPayload["authorization"],
+    },
+  };
+  return safeBase64Encode(JSON.stringify(safe));
+}
+
+/**
+ * Decodes a base64 encoded payment string back into a PaymentPayload object
+ *
+ * @param payment - The base64 encoded payment string to decode
+ * @returns The decoded and validated PaymentPayload object
+ */
+export function decodePayment(payment: string): RequestedPaymentPayload {
+  const decoded = safeBase64Decode(payment);
+  const parsed = JSON.parse(decoded);
+
+  const obj: RequestedPaymentPayload = {
+    ...parsed,
+    payload: parsed.payload as ExactEvmPayload,
+  };
+  const validated = RequestedPaymentPayloadSchema.parse(obj);
+  return validated;
+}
+
+/**
+ * Encodes a string to base64 format
+ *
+ * @param data - The string to be encoded to base64
+ * @returns The base64 encoded string
+ */
+export function safeBase64Encode(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.btoa === "function"
+  ) {
+    return globalThis.btoa(data);
+  }
+  return Buffer.from(data).toString("base64");
+}
+
+/**
+ * Decodes a base64 string back to its original format
+ *
+ * @param data - The base64 encoded string to be decoded
+ * @returns The decoded string in UTF-8 format
+ */
+function safeBase64Decode(data: string): string {
+  if (
+    typeof globalThis !== "undefined" &&
+    typeof globalThis.atob === "function"
+  ) {
+    return globalThis.atob(data);
+  }
+  return Buffer.from(data, "base64").toString("utf-8");
+}

package/src/x402/facilitator.ts

@@ -1,5 +1,12 @@
-import type { FacilitatorConfig } from "x402/types";
+import type { SupportedPaymentKindsResponse, VerifyResponse } from "x402/types";
 import type { ThirdwebClient } from "../client/client.js";
+import { stringify } from "../utils/json.js";
+import { withCache } from "../utils/promise/withCache.js";
+import type {
+  FacilitatorSettleResponse,
+  RequestedPaymentPayload,
+  RequestedPaymentRequirements,
+} from "./schemas.js";
 
 export type ThirdwebX402FacilitatorConfig = {
   client: ThirdwebClient;
@@ -12,7 +19,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
 
 /**
  * Creates a facilitator for the x402 payment protocol.
- * Use this with any x402 middleware to enable settling transactions with your thirdweb server wallet.
+ * You can use this with `verifyPayment` or with any x402 middleware to enable settling transactions with your thirdweb server wallet.
  *
  * @param config - The configuration for the facilitator
  * @returns a x402 compatible FacilitatorConfig
@@ -48,9 +55,7 @@ const DEFAULT_BASE_URL = "https://api.thirdweb.com/v1/payments/x402";
  *
  * @bridge x402
  */
-export function facilitator(
-  config: ThirdwebX402FacilitatorConfig,
-): FacilitatorConfig {
+export function facilitator(config: ThirdwebX402FacilitatorConfig) {
   const secretKey = config.client.secretKey;
   if (!secretKey) {
     throw new Error("Client secret key is required for the x402 facilitator");
@@ -61,7 +66,7 @@ export function facilitator(
       "Server wallet address is required for the x402 facilitator",
     );
   }
-  return {
+  const facilitator = {
     url: (config.baseUrl ?? DEFAULT_BASE_URL) as `${string}://${string}`,
     createAuthHeaders: async () => {
       return {
@@ -83,5 +88,108 @@ export function facilitator(
         },
       };
     },
+    /**
+     * Verifies a payment payload with the facilitator service
+     *
+     * @param payload - The payment payload to verify
+     * @param paymentRequirements - The payment requirements to verify against
+     * @returns A promise that resolves to the verification response
+     */
+    async verify(
+      payload: RequestedPaymentPayload,
+      paymentRequirements: RequestedPaymentRequirements,
+    ): Promise<VerifyResponse> {
+      const url = config.baseUrl ?? DEFAULT_BASE_URL;
+
+      let headers = { "Content-Type": "application/json" };
+      const authHeaders = await facilitator.createAuthHeaders();
+      headers = { ...headers, ...authHeaders.verify };
+
+      const res = await fetch(`${url}/verify`, {
+        method: "POST",
+        headers,
+        body: stringify({
+          x402Version: payload.x402Version,
+          paymentPayload: payload,
+          paymentRequirements: paymentRequirements,
+        }),
+      });
+
+      if (res.status !== 200) {
+        const text = `${res.statusText} ${await res.text()}`;
+        throw new Error(`Failed to verify payment: ${res.status} ${text}`);
+      }
+
+      const data = await res.json();
+      return data as VerifyResponse;
+    },
+
+    /**
+     * Settles a payment with the facilitator service
+     *
+     * @param payload - The payment payload to settle
+     * @param paymentRequirements - The payment requirements for the settlement
+     * @returns A promise that resolves to the settlement response
+     */
+    async settle(
+      payload: RequestedPaymentPayload,
+      paymentRequirements: RequestedPaymentRequirements,
+    ): 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 res = await fetch(`${url}/settle`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          x402Version: payload.x402Version,
+          paymentPayload: payload,
+          paymentRequirements: paymentRequirements,
+        }),
+      });
+
+      if (res.status !== 200) {
+        const text = `${res.statusText} ${await res.text()}`;
+        throw new Error(`Failed to settle payment: ${res.status} ${text}`);
+      }
+
+      const data = await res.json();
+      return data as FacilitatorSettleResponse;
+    },
+
+    /**
+     * Gets the supported payment kinds from the facilitator service.
+     *
+     * @returns A promise that resolves to the supported payment kinds
+     */
+    async supported(): Promise<SupportedPaymentKindsResponse> {
+      const url = config.baseUrl ?? DEFAULT_BASE_URL;
+      return withCache(
+        async () => {
+          let headers = { "Content-Type": "application/json" };
+          const authHeaders = await facilitator.createAuthHeaders();
+          headers = { ...headers, ...authHeaders.supported };
+          const res = await fetch(`${url}/supported`, { headers });
+
+          if (res.status !== 200) {
+            throw new Error(
+              `Failed to get supported payment kinds: ${res.statusText}`,
+            );
+          }
+
+          const data = await res.json();
+          return data as SupportedPaymentKindsResponse;
+        },
+        {
+          cacheKey: `supported-payment-kinds-${url}`,
+          cacheTime: 1000 * 60 * 60 * 24, // 24 hours
+        },
+      );
+    },
   };
+
+  return facilitator;
 }

package/src/x402/fetchWithPayment.ts

@@ -1,15 +1,13 @@
-import { createPaymentHeader } from "x402/client";
-import {
-  ChainIdToNetwork,
-  EvmNetworkToChainId,
-  type PaymentRequirements,
-  PaymentRequirementsSchema,
-  type Signer,
-} from "x402/types";
-import { viemAdapter } from "../adapters/viem.js";
+import { ChainIdToNetwork } from "x402/types";
 import { getCachedChain } from "../chains/utils.js";
 import type { ThirdwebClient } from "../client/client.js";
 import type { Wallet } from "../wallets/interfaces/wallet.js";
+import {
+  networkToChainId,
+  type RequestedPaymentRequirements,
+  RequestedPaymentRequirementsSchema,
+} from "./schemas.js";
+import { createPaymentHeader } from "./sign.js";
 
 /**
  * Enables the payment of APIs using the x402 payment protocol.
@@ -52,7 +50,7 @@ import type { Wallet } from "../wallets/interfaces/wallet.js";
  */
 export function wrapFetchWithPayment(
   fetch: typeof globalThis.fetch,
-  client: ThirdwebClient,
+  _client: ThirdwebClient,
   wallet: Wallet,
   maxValue: bigint = BigInt(1 * 10 ** 6), // Default to 1 USDC
 ) {
@@ -68,7 +66,7 @@ export function wrapFetchWithPayment(
       accepts: unknown[];
     };
     const parsedPaymentRequirements = accepts
-      .map((x) => PaymentRequirementsSchema.parse(x))
+      .map((x) => RequestedPaymentRequirementsSchema.parse(x))
       .filter((x) => x.scheme === "exact"); // TODO (402): accept other schemes
 
     const account = wallet.getAccount();
@@ -89,16 +87,10 @@ export function wrapFetchWithPayment(
       throw new Error("Payment amount exceeds maximum allowed");
     }
 
-    const paymentChainId = EvmNetworkToChainId.get(
+    const paymentChainId = networkToChainId(
       selectedPaymentRequirements.network,
     );
 
-    if (!paymentChainId) {
-      throw new Error(
-        `No chain found for the selected payment requirement: ${selectedPaymentRequirements.network}`,
-      );
-    }
-
     // switch to the payment chain if it's not the current chain
     if (paymentChainId !== chain.id) {
       await wallet.switchChain(getCachedChain(paymentChainId));
@@ -108,14 +100,8 @@ export function wrapFetchWithPayment(
       }
     }
 
-    const walletClient = viemAdapter.wallet.toViem({
-      wallet: wallet,
-      chain,
-      client,
-    }) as Signer;
-
     const paymentHeader = await createPaymentHeader(
-      walletClient,
+      account,
       x402Version,
       selectedPaymentRequirements,
     );
@@ -142,7 +128,7 @@ export function wrapFetchWithPayment(
 }
 
 function defaultPaymentRequirementsSelector(
-  paymentRequirements: PaymentRequirements[],
+  paymentRequirements: RequestedPaymentRequirements[],
   chainId: number,
   scheme: "exact",
 ) {
@@ -151,7 +137,7 @@ function defaultPaymentRequirementsSelector(
       "No valid payment requirements found in server 402 response",
     );
   }
-  const currentWalletNetwork = ChainIdToNetwork[chainId];
+  const currentWalletNetwork = ChainIdToNetwork[chainId] || `eip155:${chainId}`;
   // find the payment requirements matching the connected wallet chain
   const matchingPaymentRequirements = paymentRequirements.find(
     (x) => x.network === currentWalletNetwork && x.scheme === scheme,

package/src/x402/schemas.ts

@@ -0,0 +1,76 @@
+import {
+  EvmNetworkToChainId,
+  type ExactEvmPayload,
+  type Network,
+  PaymentPayloadSchema,
+  PaymentRequirementsSchema,
+  SettleResponseSchema,
+} from "x402/types";
+import { z } from "zod";
+
+const FacilitatorNetworkSchema = z.union([
+  z.literal("base-sepolia"),
+  z.literal("base"),
+  z.literal("avalanche-fuji"),
+  z.literal("avalanche"),
+  z.literal("iotex"),
+  z.literal("solana-devnet"),
+  z.literal("solana"),
+  z.literal("sei"),
+  z.literal("sei-testnet"),
+  z.string().refine((value) => value.startsWith("eip155:"), {
+    message: "Invalid network",
+  }),
+]);
+
+export type FacilitatorNetwork = z.infer<typeof FacilitatorNetworkSchema>;
+
+export const RequestedPaymentPayloadSchema = PaymentPayloadSchema.extend({
+  network: FacilitatorNetworkSchema,
+});
+
+export type RequestedPaymentPayload = z.infer<
+  typeof RequestedPaymentPayloadSchema
+>;
+export type UnsignedPaymentPayload = Omit<
+  RequestedPaymentPayload,
+  "payload"
+> & {
+  payload: Omit<ExactEvmPayload, "signature"> & { signature: undefined };
+};
+
+export const RequestedPaymentRequirementsSchema =
+  PaymentRequirementsSchema.extend({
+    network: FacilitatorNetworkSchema,
+  });
+
+export type RequestedPaymentRequirements = z.infer<
+  typeof RequestedPaymentRequirementsSchema
+>;
+
+const FacilitatorSettleResponseSchema = SettleResponseSchema.extend({
+  network: FacilitatorNetworkSchema,
+});
+export type FacilitatorSettleResponse = z.infer<
+  typeof FacilitatorSettleResponseSchema
+>;
+
+export function networkToChainId(network: string): number {
+  if (network.startsWith("eip155:")) {
+    const chainId = parseInt(network.split(":")[1] ?? "0");
+    if (!Number.isNaN(chainId) && chainId > 0) {
+      return chainId;
+    } else {
+      throw new Error(`Invalid network: ${network}`);
+    }
+  }
+  const mappedChainId = EvmNetworkToChainId.get(network as Network);
+  if (!mappedChainId) {
+    throw new Error(`Invalid network: ${network}`);
+  }
+  // TODO (402): support solana networks
+  if (mappedChainId === 101 || mappedChainId === 103) {
+    throw new Error("Solana networks not supported yet.");
+  }
+  return mappedChainId;
+}