thirdweb 5.112.4 → 5.113.0

package/dist/types/react/web/ui/x402/PaymentErrorModal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PaymentErrorModal.d.ts","sourceRoot":"","sources":["../../../../../../src/react/web/ui/x402/PaymentErrorModal.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sCAAsC,CAAC;AAGlE,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAUxE,KAAK,sBAAsB,GAAG;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,qBAAqB,CAAC,cAAc,CAAC,CAAC;IACjD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,OAAO,CACzB,IAAI,CACF,cAAc,EACZ,QAAQ,GACR,OAAO,GACP,cAAc,GACd,QAAQ,GACR,WAAW,GACX,UAAU,GACV,OAAO,CACV,CACF,CAAC;IACF,2BAA2B,CAAC,EAAE,CAC5B,mBAAmB,EAAE,4BAA4B,EAAE,KAChD,4BAA4B,GAAG,SAAS,CAAC;CAC/C,CAAC;AAIF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,2CAiL9D"}

package/dist/types/react/web/ui/x402/SignInRequiredModal.d.ts

@@ -0,0 +1,12 @@
+import type { Theme } from "../../../core/design-system/index.js";
+type SignInRequiredModalProps = {
+    theme: Theme | "light" | "dark";
+    onSignIn: () => void;
+    onCancel: () => void;
+};
+/**
+ * @internal
+ */
+export declare function SignInRequiredModal(props: SignInRequiredModalProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=SignInRequiredModal.d.ts.map

package/dist/types/react/web/ui/x402/SignInRequiredModal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SignInRequiredModal.d.ts","sourceRoot":"","sources":["../../../../../../src/react/web/ui/x402/SignInRequiredModal.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sCAAsC,CAAC;AAWlE,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;IAChC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,2CAoDlE"}

package/dist/types/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "5.112.4";
+export declare const version = "5.113.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/types/x402/facilitator.d.ts

@@ -82,7 +82,7 @@ export type ThirdwebX402Facilitator = {
 
  * ```
  *
- * @bridge x402
+ * @x402
  */
 export declare function facilitator(config: ThirdwebX402FacilitatorConfig): ThirdwebX402Facilitator;
 //# sourceMappingURL=facilitator.d.ts.map

package/dist/types/x402/fetchWithPayment.d.ts

@@ -1,5 +1,6 @@
 import type { ThirdwebClient } from "../client/client.js";
 import type { Wallet } from "../wallets/interfaces/wallet.js";
+import { type RequestedPaymentRequirements } from "./schemas.js";
 /**
  * Enables the payment of APIs using the x402 payment protocol.
  *
@@ -14,7 +15,7 @@ import type { Wallet } from "../wallets/interfaces/wallet.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
@@ -37,7 +38,10 @@ import type { Wallet } from "../wallets/interfaces/wallet.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 declare function wrapFetchWithPayment(fetch: typeof globalThis.fetch, client: ThirdwebClient, wallet: Wallet, maxValue?: bigint): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+export declare function wrapFetchWithPayment(fetch: typeof globalThis.fetch, client: ThirdwebClient, wallet: Wallet, options?: {
+    maxValue?: bigint;
+    paymentRequirementsSelector?: (paymentRequirements: RequestedPaymentRequirements[]) => RequestedPaymentRequirements | undefined;
+}): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
 //# sourceMappingURL=fetchWithPayment.d.ts.map

package/dist/types/x402/fetchWithPayment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchWithPayment.d.ts","sourceRoot":"","sources":["../../../src/x402/fetchWithPayment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAS9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,EAC9B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,IAEH,OAAO,WAAW,EAAE,OAAO,WAAW,uBA4FrD"}
+{"version":3,"file":"fetchWithPayment.d.ts","sourceRoot":"","sources":["../../../src/x402/fetchWithPayment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAGL,KAAK,4BAA4B,EAElC,MAAM,cAAc,CAAC;AAGtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,EAC9B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2BAA2B,CAAC,EAAE,CAC5B,mBAAmB,EAAE,4BAA4B,EAAE,KAChD,4BAA4B,GAAG,SAAS,CAAC;CAC/C,IAEa,OAAO,WAAW,EAAE,OAAO,WAAW,uBA8FrD"}

package/dist/types/x402/schemas.d.ts

@@ -118,11 +118,11 @@ export declare const RequestedPaymentRequirementsSchema: z.ZodObject<{
     scheme: "exact";
     resource: string;
     mimeType: string;
-    asset: string;
     network: string;
     maxAmountRequired: string;
     payTo: string;
     maxTimeoutSeconds: number;
+    asset: string;
     outputSchema?: Record<string, any> | undefined;
     extra?: Record<string, any> | undefined;
 }, {
@@ -130,11 +130,11 @@ export declare const RequestedPaymentRequirementsSchema: z.ZodObject<{
     scheme: "exact";
     resource: string;
     mimeType: string;
-    asset: string;
     network: string;
     maxAmountRequired: string;
     payTo: string;
     maxTimeoutSeconds: number;
+    asset: string;
     outputSchema?: Record<string, any> | undefined;
     extra?: Record<string, any> | undefined;
 }>;

package/dist/types/x402/settle-payment.d.ts

@@ -114,7 +114,7 @@ import { type SettlePaymentArgs, type SettlePaymentResult } from "./types.js";
  *
  * @public
  * @beta
- * @bridge x402
+ * @x402
  */
 export declare function settlePayment(args: SettlePaymentArgs): Promise<SettlePaymentResult>;
 //# sourceMappingURL=settle-payment.d.ts.map

package/dist/types/x402/verify-payment.d.ts

@@ -64,7 +64,7 @@ import { type PaymentArgs, type VerifyPaymentResult } from "./types.js";
  *
  * @public
  * @beta
- * @bridge x402
+ * @x402
  */
 export declare function verifyPayment(args: PaymentArgs): Promise<VerifyPaymentResult>;
 //# sourceMappingURL=verify-payment.d.ts.map

package/package.json

@@ -399,7 +399,7 @@
     }
   },
   "typings": "./dist/types/exports/thirdweb.d.ts",
-  "version": "5.112.4",
+  "version": "5.113.0",
   "scripts": {
     "bench": "vitest -c ./test/vitest.config.ts bench",
     "bench:compare": "bun run ./benchmarks/run.ts",

package/src/exports/react.native.ts

@@ -114,6 +114,11 @@ export { useAutoConnect } from "../react/native/hooks/wallets/useAutoConnect.js"
 export { useLinkProfile } from "../react/native/hooks/wallets/useLinkProfile.js";
 export { useProfiles } from "../react/native/hooks/wallets/useProfiles.js";
 export { useUnlinkProfile } from "../react/native/hooks/wallets/useUnlinkProfile.js";
+// x402
+export {
+  type UseFetchWithPaymentOptions,
+  useFetchWithPayment,
+} from "../react/native/hooks/x402/useFetchWithPayment.js";
 export { ThirdwebProvider } from "../react/native/providers/thirdweb-provider.js";
 // Components
 export { AutoConnect } from "../react/native/ui/AutoConnect/AutoConnect.js";

package/src/exports/react.ts

@@ -131,6 +131,11 @@ export { useAutoConnect } from "../react/web/hooks/wallets/useAutoConnect.js";
 export { useLinkProfile } from "../react/web/hooks/wallets/useLinkProfile.js";
 export { useProfiles } from "../react/web/hooks/wallets/useProfiles.js";
 export { useUnlinkProfile } from "../react/web/hooks/wallets/useUnlinkProfile.js";
+// x402
+export {
+  type UseFetchWithPaymentOptions,
+  useFetchWithPayment,
+} from "../react/web/hooks/x402/useFetchWithPayment.js";
 export { ThirdwebProvider } from "../react/web/providers/thirdweb-provider.js";
 export { AutoConnect } from "../react/web/ui/AutoConnect/AutoConnect.js";
 export type { BuyOrOnrampPrepareResult } from "../react/web/ui/Bridge/BuyWidget.js";

package/src/react/core/hooks/x402/useFetchWithPaymentCore.ts

@@ -0,0 +1,160 @@
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import { 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";
+
+export type UseFetchWithPaymentOptions = {
+  maxValue?: bigint;
+  paymentRequirementsSelector?: (
+    paymentRequirements: RequestedPaymentRequirements[],
+  ) => RequestedPaymentRequirements | undefined;
+  parseAs?: "json" | "text" | "raw";
+};
+
+type ShowErrorModalCallback = (data: {
+  errorData: PaymentRequiredResult["responseBody"];
+  onRetry: () => void;
+  onCancel: () => void;
+}) => void;
+
+type ShowConnectModalCallback = (data: {
+  onConnect: (wallet: Wallet) => void;
+  onCancel: () => void;
+}) => void;
+
+/**
+ * Core hook for fetch with payment functionality.
+ * This is the platform-agnostic implementation used by both web and native versions.
+ * @internal
+ */
+export function useFetchWithPaymentCore(
+  client: ThirdwebClient,
+  options?: UseFetchWithPaymentOptions,
+  showErrorModal?: ShowErrorModalCallback,
+  showConnectModal?: ShowConnectModalCallback,
+) {
+  const wallet = useActiveWallet();
+
+  const mutation = useMutation({
+    mutationFn: async ({
+      input,
+      init,
+    }: {
+      input: RequestInfo;
+      init?: RequestInit;
+    }) => {
+      // Recursive function that handles fetch + 402 error + retry
+      const executeFetch = async (currentWallet = wallet): Promise<unknown> => {
+        if (!currentWallet) {
+          // If a connect modal handler is provided, show the connect modal
+          if (showConnectModal) {
+            return new Promise<unknown>((resolve, reject) => {
+              showConnectModal({
+                onConnect: async (newWallet) => {
+                  // After connection, retry the fetch with the newly connected wallet
+                  try {
+                    const result = await executeFetch(newWallet);
+                    resolve(result);
+                  } catch (error) {
+                    reject(error);
+                  }
+                },
+                onCancel: () => {
+                  reject(new Error("Wallet connection cancelled by user"));
+                },
+              });
+            });
+          }
+
+          // If no connect modal handler, throw an error
+          throw new Error(
+            "No wallet connected. Please connect your wallet to make paid API calls.",
+          );
+        }
+
+        const wrappedFetch = wrapFetchWithPayment(
+          globalThis.fetch,
+          client,
+          currentWallet,
+          options,
+        );
+
+        const response = await wrappedFetch(input, init);
+
+        // Check if we got a 402 response (payment error)
+        if (response.status === 402) {
+          try {
+            const errorBody =
+              (await response.json()) as PaymentRequiredResult["responseBody"];
+
+            // If a modal handler is provided, show the modal and handle retry/cancel
+            if (showErrorModal) {
+              return new Promise<unknown>((resolve, reject) => {
+                showErrorModal({
+                  errorData: errorBody,
+                  onRetry: async () => {
+                    // Retry the entire fetch+error handling logic recursively
+                    try {
+                      const result = await executeFetch();
+                      resolve(result);
+                    } catch (error) {
+                      reject(error);
+                    }
+                  },
+                  onCancel: () => {
+                    reject(new Error("Payment cancelled by user"));
+                  },
+                });
+              });
+            }
+
+            // If no modal handler, throw the error with details
+            throw new Error(
+              errorBody.errorMessage || `Payment failed: ${errorBody.error}`,
+            );
+          } catch (_parseError) {
+            // If we can't parse the error body, throw a generic error
+            throw new Error("Payment failed with status 402");
+          }
+        }
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(
+            `Payment failed with status ${response.status} ${response.statusText} - ${errorText || "Unknown error"}`,
+          );
+        }
+
+        const parseAs = options?.parseAs ?? "json";
+        return parseResponse(response, parseAs);
+      };
+
+      // Start the fetch process
+      return executeFetch();
+    },
+  });
+
+  return {
+    fetchWithPayment: async (input: RequestInfo, init?: RequestInit) => {
+      return mutation.mutateAsync({ input, init });
+    },
+    ...mutation,
+  };
+}
+
+function parseResponse(response: Response, parseAs: "json" | "text" | "raw") {
+  if (parseAs === "json") {
+    return response.json();
+  } else if (parseAs === "text") {
+    return response.text();
+  } else if (parseAs === "raw") {
+    return response;
+  } else {
+    throw new Error(`Invalid parseAs option: ${parseAs}`);
+  }
+}

package/src/react/native/hooks/x402/useFetchWithPayment.ts

@@ -0,0 +1,96 @@
+"use client";
+
+import type { ThirdwebClient } from "../../../../client/client.js";
+import {
+  type UseFetchWithPaymentOptions,
+  useFetchWithPaymentCore,
+} from "../../../core/hooks/x402/useFetchWithPaymentCore.js";
+
+export type { UseFetchWithPaymentOptions };
+
+/**
+ * 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
+ *
+ * Note: This is the React Native version which does not include modal UI.
+ * Payment errors will be thrown and should be handled by your application.
+ *
+ * @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"
+ * @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, error } = useFetchWithPayment(client);
+ *
+ *   const handleApiCall = async () => {
+ *     try {
+ *       // Response is automatically parsed as JSON
+ *       const data = await fetchWithPayment('https://api.example.com/paid-endpoint');
+ *       console.log(data);
+ *     } catch (err) {
+ *       // Handle payment errors manually in React Native
+ *       console.error("Payment failed:", err);
+ *     }
+ *   };
+ *
+ *   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
+ *   paymentRequirementsSelector: (requirements) => {
+ *     // Custom logic to select preferred payment method
+ *     return requirements[0];
+ *   }
+ * });
+ * ```
+ *
+ * @x402
+ */
+export function useFetchWithPayment(
+  client: ThirdwebClient,
+  options?: UseFetchWithPaymentOptions,
+) {
+  // Native version doesn't show modal, errors bubble up naturally
+  return useFetchWithPaymentCore(client, options);
+}

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,
   };
 });