thirdweb 5.112.3 → 5.113.0

package/src/react/web/hooks/x402/useFetchWithPayment.tsx

@@ -0,0 +1,238 @@
+"use client";
+
+import { useContext } from "react";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import type { Theme } from "../../../core/design-system/index.js";
+import {
+  type UseFetchWithPaymentOptions,
+  useFetchWithPaymentCore,
+} from "../../../core/hooks/x402/useFetchWithPaymentCore.js";
+import { SetRootElementContext } from "../../../core/providers/RootElementContext.js";
+import type { BuyWidgetProps } from "../../ui/Bridge/BuyWidget.js";
+import {
+  type UseConnectModalOptions,
+  useConnectModal,
+} from "../../ui/ConnectWallet/useConnectModal.js";
+import { PaymentErrorModal } from "../../ui/x402/PaymentErrorModal.js";
+import { SignInRequiredModal } from "../../ui/x402/SignInRequiredModal.js";
+
+export type { UseFetchWithPaymentOptions };
+
+type UseFetchWithPaymentConfig = UseFetchWithPaymentOptions & {
+  /**
+   * Whether to show the UI for connection, funding or payment retries.
+   * If false, no UI will be shown and errors will have to be handled manually.
+   * @default true
+   */
+  uiEnabled?: boolean;
+  /**
+   * Theme for the payment error modal
+   * @default "dark"
+   */
+  theme?: Theme | "light" | "dark";
+  /**
+   * Options to customize the BuyWidget that appears when the user needs to fund their wallet.
+   * These options will be merged with default values.
+   */
+  fundWalletOptions?: Partial<
+    Omit<
+      BuyWidgetProps,
+      "client" | "chain" | "tokenAddress" | "onSuccess" | "onCancel" | "theme"
+    >
+  >;
+  /**
+   * Options to customize the ConnectModal that appears when the user needs to sign in.
+   * These options will be merged with the client, theme, and chain from the hook.
+   */
+  connectOptions?: Omit<UseConnectModalOptions, "client" | "theme">;
+};
+
+/**
+ * A React hook that wraps the native fetch API to automatically handle 402 Payment Required responses
+ * using the x402 payment protocol with the currently connected wallet.
+ *
+ * This hook enables you to make API calls that require payment without manually handling the payment flow.
+ * Responses are automatically parsed as JSON by default (can be customized with `parseAs` option).
+ *
+ * When a 402 response is received, it will automatically:
+ * 1. Parse the payment requirements
+ * 2. Verify the payment amount is within the allowed maximum
+ * 3. Create a payment header using the connected wallet
+ * 4. Retry the request with the payment header
+ *
+ * If payment fails (e.g. insufficient funds), a modal will be shown to help the user resolve the issue.
+ * If no wallet is connected, a sign-in modal will be shown to connect a wallet.
+ *
+ * @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.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
+ * @param options.theme - Theme for the payment error modal (defaults to "dark")
+ * @param options.fundWalletOptions - Customize the BuyWidget shown when user needs to fund their wallet
+ * @param options.connectOptions - Customize the ConnectModal shown when user needs to sign in
+ * @returns An object containing:
+ * - `fetchWithPayment`: Function to make fetch requests with automatic payment handling (returns parsed data)
+ * - `isPending`: Boolean indicating if a request is in progress
+ * - `error`: Any error that occurred during the request
+ * - `data`: The parsed response data (JSON by default, or based on `parseAs` option)
+ * - Other mutation properties from React Query
+ *
+ * @example
+ * ```tsx
+ * import { useFetchWithPayment } from "thirdweb/react";
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({ clientId: "your-client-id" });
+ *
+ * function MyComponent() {
+ *   const { fetchWithPayment, isPending } = useFetchWithPayment(client);
+ *
+ *   const handleApiCall = async () => {
+ *     // Response is automatically parsed as JSON
+ *     const data = await fetchWithPayment('https://api.example.com/paid-endpoint');
+ *     console.log(data);
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleApiCall} disabled={isPending}>
+ *       {isPending ? 'Loading...' : 'Make Paid API Call'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * ### Customize response parsing
+ * ```tsx
+ * const { fetchWithPayment } = useFetchWithPayment(client, {
+ *   parseAs: "text", // Get response as text instead of JSON
+ * });
+ *
+ * const textData = await fetchWithPayment('https://api.example.com/endpoint');
+ * ```
+ *
+ * ### Customize payment options
+ * ```tsx
+ * const { fetchWithPayment } = useFetchWithPayment(client, {
+ *   maxValue: 5000000n, // 5 USDC in base units
+ *   theme: "light",
+ *   paymentRequirementsSelector: (requirements) => {
+ *     // Custom logic to select preferred payment method
+ *     return requirements[0];
+ *   }
+ * });
+ * ```
+ *
+ * ### Customize the fund wallet widget
+ * ```tsx
+ * const { fetchWithPayment } = useFetchWithPayment(client, {
+ *   fundWalletOptions: {
+ *     title: "Add Funds",
+ *     description: "You need more tokens to complete this payment",
+ *     buttonLabel: "Get Tokens",
+ *   }
+ * });
+ * ```
+ *
+ * ### Customize the connect modal
+ * ```tsx
+ * const { fetchWithPayment } = useFetchWithPayment(client, {
+ *   connectOptions: {
+ *     wallets: [inAppWallet(), createWallet("io.metamask")],
+ *     title: "Sign in to continue",
+ *   }
+ * });
+ * ```
+ *
+ * ### Disable the UI and handle errors yourself
+ * ```tsx
+ * const { fetchWithPayment, error } = useFetchWithPayment(client, {
+ *   uiEnabled: false,
+ * });
+ *
+ * // Handle the error manually
+ * if (error) {
+ *   console.error("Payment failed:", error);
+ * }
+ * ```
+ *
+ * @x402
+ */
+export function useFetchWithPayment(
+  client: ThirdwebClient,
+  options?: UseFetchWithPaymentConfig,
+) {
+  const setRootEl = useContext(SetRootElementContext);
+  const { connect } = useConnectModal();
+  const theme = options?.theme || "dark";
+  const showModal = options?.uiEnabled !== false; // Default to true
+
+  const showErrorModal = showModal
+    ? (data: {
+        errorData: Parameters<typeof PaymentErrorModal>[0]["errorData"];
+        onRetry: () => void;
+        onCancel: () => void;
+      }) => {
+        setRootEl(
+          <PaymentErrorModal
+            client={client}
+            errorData={data.errorData}
+            onCancel={() => {
+              setRootEl(null);
+              data.onCancel();
+            }}
+            onRetry={() => {
+              setRootEl(null);
+              data.onRetry();
+            }}
+            theme={theme}
+            fundWalletOptions={options?.fundWalletOptions}
+            paymentRequirementsSelector={options?.paymentRequirementsSelector}
+          />,
+        );
+      }
+    : undefined;
+
+  const showConnectModal = showModal
+    ? (data: { onConnect: (wallet: Wallet) => void; onCancel: () => void }) => {
+        // First, show the SignInRequiredModal
+        setRootEl(
+          <SignInRequiredModal
+            theme={theme}
+            onSignIn={async () => {
+              // Close the SignInRequiredModal
+              setRootEl(null);
+
+              // Open the ConnectModal
+              try {
+                const connectedWallet = await connect({
+                  client,
+                  theme,
+                  ...options?.connectOptions,
+                });
+
+                // On successful connection, trigger onConnect callback with the wallet
+                data.onConnect(connectedWallet);
+              } catch (_error) {
+                // User cancelled the connection
+                data.onCancel();
+              }
+            }}
+            onCancel={() => {
+              setRootEl(null);
+              data.onCancel();
+            }}
+          />,
+        );
+      }
+    : undefined;
+
+  return useFetchWithPaymentCore(
+    client,
+    options,
+    showErrorModal,
+    showConnectModal,
+  );
+}

package/src/react/web/ui/components/basic.tsx

@@ -17,7 +17,7 @@ export const ScreenBottomContainer = /* @__PURE__ */ StyledDiv((_) => {
     borderTop: `1px solid ${theme.colors.separatorLine}`,
     display: "flex",
     flexDirection: "column",
-    gap: spacing.lg,
+    gap: spacing.md,
     padding: spacing.lg,
   };
 });

package/src/react/web/ui/x402/PaymentErrorModal.tsx

@@ -0,0 +1,261 @@
+"use client";
+import { useState } from "react";
+import { getCachedChain } from "../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import {
+  extractEvmChainId,
+  networkToCaip2ChainId,
+  type RequestedPaymentRequirements,
+} from "../../../../x402/schemas.js";
+import type { PaymentRequiredResult } from "../../../../x402/types.js";
+import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../../../core/design-system/index.js";
+import { spacing } from "../../../core/design-system/index.js";
+import { useActiveWallet } from "../../../core/hooks/wallets/useActiveWallet.js";
+import { BuyWidget, type BuyWidgetProps } from "../Bridge/BuyWidget.js";
+import {
+  Container,
+  ModalHeader,
+  ScreenBottomContainer,
+} from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Modal } from "../components/Modal.js";
+import { Text } from "../components/text.js";
+
+type PaymentErrorModalProps = {
+  client: ThirdwebClient;
+  errorData: PaymentRequiredResult["responseBody"];
+  onRetry: () => void;
+  onCancel: () => void;
+  theme: Theme | "light" | "dark";
+  fundWalletOptions?: Partial<
+    Omit<
+      BuyWidgetProps,
+      | "client"
+      | "chain"
+      | "tokenAddress"
+      | "amount"
+      | "onSuccess"
+      | "onCancel"
+      | "theme"
+    >
+  >;
+  paymentRequirementsSelector?: (
+    paymentRequirements: RequestedPaymentRequirements[],
+  ) => RequestedPaymentRequirements | undefined;
+};
+
+type Screen = "error" | "buy-widget";
+
+/**
+ * @internal
+ */
+export function PaymentErrorModal(props: PaymentErrorModalProps) {
+  const {
+    client,
+    errorData,
+    onRetry,
+    onCancel,
+    theme,
+    fundWalletOptions,
+    paymentRequirementsSelector,
+  } = props;
+  const [screen, setScreen] = useState<Screen>("error");
+  const isInsufficientFunds = errorData.error === "insufficient_funds";
+  const wallet = useActiveWallet();
+
+  // Extract chain and token info from errorData for BuyWidget
+  const getBuyWidgetConfig = () => {
+    if (!errorData.accepts || errorData.accepts.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;
+
+    // Select payment requirement using the same logic as wrapFetchWithPayment
+    const selectedRequirement = paymentRequirementsSelector
+      ? paymentRequirementsSelector(parsedPaymentRequirements)
+      : defaultPaymentRequirementsSelector(
+          parsedPaymentRequirements,
+          currentChainId,
+          "exact",
+          errorData.error,
+        );
+
+    if (!selectedRequirement) return null;
+
+    const caip2ChainId = networkToCaip2ChainId(selectedRequirement.network);
+    const chainId = extractEvmChainId(caip2ChainId);
+
+    if (!chainId) return null;
+
+    const chain = getCachedChain(chainId);
+    const tokenAddress = selectedRequirement.asset as `0x${string}`;
+
+    return {
+      chain,
+      tokenAddress,
+      amount: undefined,
+    };
+  };
+
+  const buyWidgetConfig = isInsufficientFunds ? getBuyWidgetConfig() : null;
+
+  if (screen === "buy-widget" && buyWidgetConfig) {
+    return (
+      <CustomThemeProvider theme={theme}>
+        <Modal
+          className="tw-payment-error-modal"
+          hideCloseIcon={false}
+          open={true}
+          setOpen={(open) => {
+            if (!open) {
+              onCancel();
+            }
+          }}
+          size="compact"
+          title="Top up your wallet"
+          crossContainerStyles={{
+            position: "absolute",
+            right: spacing.lg,
+            top: spacing.lg,
+            zIndex: 1,
+          }}
+        >
+          {/* BuyWidget without padding */}
+          <BuyWidget
+            client={client}
+            theme={theme}
+            chain={buyWidgetConfig.chain}
+            tokenAddress={buyWidgetConfig.tokenAddress}
+            amount={buyWidgetConfig.amount}
+            style={{
+              border: "none",
+              width: "100%",
+            }}
+            buttonLabel="Continue"
+            title="Get funds"
+            description="Top up your wallet to complete your payment."
+            {...fundWalletOptions}
+            onSuccess={() => {
+              // Close modal and retry the payment
+              onRetry();
+            }}
+            onCancel={() => {
+              // Go back to error screen
+              setScreen("error");
+            }}
+          />
+        </Modal>
+      </CustomThemeProvider>
+    );
+  }
+
+  // Error screen (default)
+  return (
+    <CustomThemeProvider theme={theme}>
+      <Modal
+        className="tw-payment-error-modal"
+        hideCloseIcon={true}
+        open={true}
+        setOpen={(open) => {
+          if (!open) {
+            onCancel();
+          }
+        }}
+        size="compact"
+        title="Payment Failed"
+      >
+        <Container p="lg">
+          <ModalHeader title="Payment failed" />
+
+          <Container
+            flex="column"
+            gap="lg"
+            style={{
+              paddingTop: spacing.lg,
+            }}
+          >
+            {/* Error Message */}
+            <Text
+              size="sm"
+              style={{
+                color: "inherit",
+                lineHeight: 1.5,
+              }}
+            >
+              {isInsufficientFunds
+                ? "Your wallet doesn't have enough funds to complete this payment. Please top up your wallet and try again."
+                : errorData.errorMessage ||
+                  "An error occurred while processing your payment."}
+            </Text>
+          </Container>
+        </Container>
+
+        {/* Action Buttons */}
+        <ScreenBottomContainer>
+          {isInsufficientFunds && buyWidgetConfig ? (
+            <>
+              <Button
+                fullWidth
+                gap="xs"
+                onClick={() => setScreen("buy-widget")}
+                variant="accent"
+              >
+                Top up your wallet
+              </Button>
+              <Button fullWidth gap="xs" onClick={onCancel} variant="secondary">
+                Cancel
+              </Button>
+            </>
+          ) : (
+            <>
+              <Button fullWidth gap="xs" onClick={onRetry} variant="accent">
+                Try Again
+              </Button>
+              <Button fullWidth gap="xs" onClick={onCancel} variant="secondary">
+                Cancel
+              </Button>
+            </>
+          )}
+        </ScreenBottomContainer>
+      </Modal>
+    </CustomThemeProvider>
+  );
+}
+
+// Default payment requirement selector - same logic as in fetchWithPayment.ts
+function defaultPaymentRequirementsSelector(
+  paymentRequirements: RequestedPaymentRequirements[],
+  chainId: number | undefined,
+  scheme: "exact",
+  _error?: string,
+): RequestedPaymentRequirements | undefined {
+  if (!paymentRequirements.length) {
+    return undefined;
+  }
+
+  // If we have a chainId, find matching payment requirements
+  if (chainId !== undefined) {
+    const matchingPaymentRequirements = paymentRequirements.find(
+      (x) =>
+        extractEvmChainId(networkToCaip2ChainId(x.network)) === chainId &&
+        x.scheme === scheme,
+    );
+
+    if (matchingPaymentRequirements) {
+      return matchingPaymentRequirements;
+    }
+  }
+
+  // If no matching payment requirements, use the first payment requirement
+  const firstPaymentRequirement = paymentRequirements.find(
+    (x) => x.scheme === scheme,
+  );
+  return firstPaymentRequirement;
+}

package/src/react/web/ui/x402/SignInRequiredModal.tsx

@@ -0,0 +1,75 @@
+"use client";
+import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../../../core/design-system/index.js";
+import { spacing } from "../../../core/design-system/index.js";
+import {
+  Container,
+  ModalHeader,
+  ScreenBottomContainer,
+} from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Modal } from "../components/Modal.js";
+import { Text } from "../components/text.js";
+
+type SignInRequiredModalProps = {
+  theme: Theme | "light" | "dark";
+  onSignIn: () => void;
+  onCancel: () => void;
+};
+
+/**
+ * @internal
+ */
+export function SignInRequiredModal(props: SignInRequiredModalProps) {
+  const { theme, onSignIn, onCancel } = props;
+
+  return (
+    <CustomThemeProvider theme={theme}>
+      <Modal
+        className="tw-signin-required-modal"
+        hideCloseIcon={true}
+        open={true}
+        setOpen={(open) => {
+          if (!open) {
+            onCancel();
+          }
+        }}
+        size="compact"
+        title="Sign in required"
+      >
+        <Container p="lg">
+          <ModalHeader title="Sign in required" />
+
+          <Container
+            flex="column"
+            gap="lg"
+            style={{
+              paddingTop: spacing.lg,
+            }}
+          >
+            {/* Description */}
+            <Text
+              size="sm"
+              style={{
+                color: "inherit",
+                lineHeight: 1.5,
+              }}
+            >
+              Account required to complete payment, please sign in to continue.
+            </Text>
+          </Container>
+        </Container>
+
+        {/* Action Buttons */}
+        <ScreenBottomContainer>
+          <Button fullWidth gap="xs" onClick={onSignIn} variant="accent">
+            Sign in
+          </Button>
+          <Button fullWidth gap="xs" onClick={onCancel} variant="secondary">
+            Cancel
+          </Button>
+        </ScreenBottomContainer>
+      </Modal>
+    </CustomThemeProvider>
+  );
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = "5.112.3";
+export const version = "5.113.0";

package/src/wallets/coinbase/coinbase-web.ts

@@ -474,6 +474,16 @@ async function switchChainCoinbaseWalletSDK(
   provider: ProviderInterface,
   chain: Chain,
 ) {
+  // check if chain is already connected
+  const connectedChainId = (await provider.request({
+    method: "eth_chainId",
+  })) as string | number;
+  const connectedChain = getCachedChain(normalizeChainId(connectedChainId));
+  if (connectedChain?.id === chain.id) {
+    // chain is already connected, no need to switch
+    return;
+  }
+
   const chainIdHex = numberToHex(chain.id);
 
   try {

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,

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);
@@ -78,12 +83,14 @@ 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,
+          "exact",
+          error,
+        );
 
     if (!selectedPaymentRequirements) {
       throw new Error(
@@ -92,11 +99,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)`,
       );
     }
 

package/src/x402/schemas.ts

@@ -41,6 +41,7 @@ export type RequestedPaymentRequirements = z.infer<
 const FacilitatorSettleResponseSchema = SettleResponseSchema.extend({
   network: FacilitatorNetworkSchema,
   errorMessage: z.string().optional(),
+  fundWalletLink: z.string().optional(),
 });
 export type FacilitatorSettleResponse = z.infer<
   typeof FacilitatorSettleResponseSchema
@@ -48,6 +49,7 @@ export type FacilitatorSettleResponse = z.infer<
 
 const FacilitatorVerifyResponseSchema = VerifyResponseSchema.extend({
   errorMessage: z.string().optional(),
+  fundWalletLink: z.string().optional(),
 });
 
 export type FacilitatorVerifyResponse = z.infer<