- {/*
-
- */}
-
-
+
{
- setOptions((v) => ({
- ...v,
- payOptions: {
- ...v.payOptions,
- mode: value as
- | "fund_wallet"
- | "direct_payment"
- | "transaction",
- },
- }));
+ setOptions(
+ (v) =>
+ ({
+ ...v,
+ payOptions: {
+ ...v.payOptions,
+ widget: value as "buy" | "checkout" | "transaction",
+ },
+ }) satisfies BridgeComponentsPlaygroundOptions,
+ );
}}
- value={payOptions.mode || "fund_wallet"}
+ value={payOptions.widget || "buy"}
/>
{/* Conditional form fields based on selected mode */}
diff --git a/apps/playground-web/src/app/connect/pay/embed/RightSection.tsx b/apps/playground-web/src/app/connect/pay/embed/RightSection.tsx
index 18b939a2983..ab3d57adb6a 100644
--- a/apps/playground-web/src/app/connect/pay/embed/RightSection.tsx
+++ b/apps/playground-web/src/app/connect/pay/embed/RightSection.tsx
@@ -1,11 +1,15 @@
"use client";
+import { useQuery } from "@tanstack/react-query";
import { usePathname } from "next/navigation";
import { useState } from "react";
-import { ZERO_ADDRESS, getContract } from "thirdweb";
+import { getContract, toUnits } from "thirdweb";
import { base } from "thirdweb/chains";
+import { getCurrencyMetadata } from "thirdweb/extensions/erc20";
import { claimTo } from "thirdweb/extensions/erc1155";
import {
- PayEmbed,
+ BuyWidget,
+ CheckoutWidget,
+ TransactionWidget,
darkTheme,
lightTheme,
useActiveAccount,
@@ -14,7 +18,7 @@ import { Button } from "../../../../components/ui/button";
import { THIRDWEB_CLIENT } from "../../../../lib/client";
import { cn } from "../../../../lib/utils";
import { CodeGen } from "../components/CodeGen";
-import type { PayEmbedPlaygroundOptions } from "../components/types";
+import type { BridgeComponentsPlaygroundOptions } from "../components/types";
const nftContract = getContract({
address: "0xf0d0CBf84005Dd4eC81364D1f5D7d896Bd53D1B8",
@@ -25,7 +29,7 @@ const nftContract = getContract({
type Tab = "ui" | "code";
export function RightSection(props: {
- options: PayEmbedPlaygroundOptions;
+ options: BridgeComponentsPlaygroundOptions;
tab?: string;
}) {
const pathname = usePathname();
@@ -39,6 +43,18 @@ export function RightSection(props: {
}
const account = useActiveAccount();
+ const { data: tokenData } = useQuery({
+ queryKey: ["token", props.options.payOptions.buyTokenAddress],
+ queryFn: () =>
+ getCurrencyMetadata({
+ contract: getContract({
+ address: props.options.payOptions.buyTokenAddress,
+ chain: props.options.payOptions.buyTokenChain,
+ client: THIRDWEB_CLIENT,
+ }),
+ }),
+ enabled: !!props.options.payOptions.buyTokenAddress,
+ });
const themeObj =
props.options.theme.type === "dark"
@@ -49,98 +65,64 @@ export function RightSection(props: {
colors: props.options.theme.lightColorOverrides,
});
- const embed = (
-
{/* Fund Wallet Mode Options */}
- {(!payOptions.mode || payOptions.mode === "fund_wallet") && (
+ {(!payOptions.widget || payOptions.widget === "buy") && (
)}
{/* Transaction Mode Options */}
- {payOptions.mode === "transaction" && (
+ {payOptions.widget === "transaction" && (
-
-
@@ -545,18 +372,6 @@ export function LeftSection(props: {
{
- setOptions((v) => ({
- ...v,
- connectOptions: {
- ...v.connectOptions,
- enableAccountAbstraction: checked,
- },
- }));
- }}
- />
@@ -180,78 +129,33 @@ export function LeftSection(props: {
{/* Token selection for fund_wallet mode */}
)}
{/* Direct Payment Mode Options */}
- {payOptions.mode === "direct_payment" && (
+ {payOptions.widget === "checkout" && (
-
- {needsHighlighting && (
-
-
-
- setTokenName(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting && !tokenName && "border-red-500",
- )}
- />
-
-
-
- setTokenSymbol(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting &&
- !tokenSymbol &&
- "border-red-500",
- )}
- />
-
-
setTokenAddress(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting &&
- !tokenAddress &&
- "border-red-500",
- )}
- />
-
-
-
- setTokenIcon(e.target.value)}
- className="bg-card"
+ value={payOptions.buyTokenAddress}
+ onChange={(e) => {
+ setOptions((v) => ({
+ ...v,
+ payOptions: {
+ ...v.payOptions,
+ buyTokenAddress: e.target.value as Address,
+ },
+ }));
+ }}
+ className={cn("bg-card")}
/>
- All three token fields (Name, Symbol, and Address) are
- required
-
- )}
@@ -260,15 +164,15 @@ export function LeftSection(props: {
placeholder="0x..."
className="bg-card"
value={payOptions.sellerAddress || ""}
- onChange={(e) =>
+ onChange={(e) => {
setOptions((v) => ({
...v,
payOptions: {
...v.payOptions,
- sellerAddress: e.target.value,
+ sellerAddress: e.target.value as Address,
},
- }))
- }
+ }));
+ }}
/>
@@ -321,36 +225,6 @@ export function LeftSection(props: {
{/* Token selection for direct_payment mode - shares state with fund_wallet mode */}
-
- {needsHighlighting && (
-
-
-
- setTokenName(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting && !tokenName && "border-red-500",
- )}
- />
-
-
-
- setTokenSymbol(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting &&
- !tokenSymbol &&
- "border-red-500",
- )}
- />
-
-
@@ -359,40 +233,17 @@ export function LeftSection(props: {
placeholder="0x..."
value={tokenAddress}
onChange={(e) => setTokenAddress(e.target.value)}
- className={cn(
- "bg-card",
- needsHighlighting &&
- !tokenAddress &&
- "border-red-500",
- )}
- />
-
-
-
- setTokenIcon(e.target.value)}
- className="bg-card"
+ className={cn("bg-card")}
/>
- All three token fields (Name, Symbol, and Address) are
- required
-
- )}
@@ -406,55 +257,11 @@ export function LeftSection(props: {
)}
-
-
-
-
-
- setOptions((v) => ({
- ...v,
- payOptions: {
- ...v.payOptions,
- buyWithCrypto: checked === true,
- },
- }))
- }
- />
-
-
-
-
- setOptions((v) => ({
- ...v,
- payOptions: {
- ...v.payOptions,
- buyWithFiat: checked === true,
- },
- }))
- }
- />
-
-
-
- {/* Locale TODO (pay) */}
- {/*
{/* Modal title */}
+
+ {/* Modal description */}
+
@@ -496,6 +303,26 @@ export function LeftSection(props: {
/>
+
+
+ setOptions((v) => ({
+ ...v,
+ payOptions: {
+ ...payOptions,
+ description: e.target.value,
+ },
+ }))
+ }
+ />
+
diff --git a/apps/playground-web/src/app/connect/pay/embed/page.tsx b/apps/playground-web/src/app/connect/pay/embed/page.tsx
index ccf7cef3e0d..4268cf37732 100644
--- a/apps/playground-web/src/app/connect/pay/embed/page.tsx
+++ b/apps/playground-web/src/app/connect/pay/embed/page.tsx
@@ -1,57 +1,37 @@
"use client";
import { use, useState } from "react";
import { NATIVE_TOKEN_ADDRESS } from "thirdweb";
-import { base } from "thirdweb/chains";
-import type { PayEmbedPlaygroundOptions } from "../components/types";
+import { arbitrum } from "thirdweb/chains";
+import { checksumAddress } from "thirdweb/utils";
+import type { BridgeComponentsPlaygroundOptions } from "../components/types";
import { LeftSection } from "./LeftSection";
import { RightSection } from "./RightSection";
// NOTE: Only set the values that are actually the default values used by PayEmbed component
-const defaultConnectOptions: PayEmbedPlaygroundOptions = {
+const defaultConnectOptions: BridgeComponentsPlaygroundOptions = {
theme: {
type: "dark",
darkColorOverrides: {},
lightColorOverrides: {},
},
payOptions: {
- mode: "fund_wallet",
+ widget: "buy",
title: "",
image: "",
- buyTokenAddress: NATIVE_TOKEN_ADDRESS,
- buyTokenAmount: "0.01",
- buyTokenChain: base,
- sellerAddress: "",
+ description: "",
+ buyTokenAddress: checksumAddress(NATIVE_TOKEN_ADDRESS),
+ buyTokenAmount: "0.002",
+ buyTokenChain: arbitrum,
+ sellerAddress: "0x0000000000000000000000000000000000000000",
transactionData: "",
- buyTokenInfo: undefined,
- buyWithCrypto: true,
- buyWithFiat: true,
- },
- connectOptions: {
- walletIds: [
- "io.metamask",
- "com.coinbase.wallet",
- "me.rainbow",
- "io.rabby",
- "io.zerion.wallet",
- ],
- modalTitle: undefined,
- modalTitleIcon: undefined,
- localeId: "en_US",
- enableAuth: false,
- termsOfServiceLink: undefined,
- privacyPolicyLink: undefined,
- enableAccountAbstraction: false,
- buttonLabel: undefined,
- ShowThirdwebBranding: true,
- requireApproval: false,
},
};
-export default function PayEmbedPlayground(props: {
+export default function BridgeComponentsPlayground(props: {
searchParams: Promise<{ tab: string }>;
}) {
const searchParams = use(props.searchParams);
- const [options, setOptions] = useState(
+ const [options, setOptions] = useState(
defaultConnectOptions,
);
diff --git a/apps/playground-web/src/app/connect/pay/fund-wallet/page.tsx b/apps/playground-web/src/app/connect/pay/fund-wallet/page.tsx
index 122ce8865d9..89e49d55264 100644
--- a/apps/playground-web/src/app/connect/pay/fund-wallet/page.tsx
+++ b/apps/playground-web/src/app/connect/pay/fund-wallet/page.tsx
@@ -1,7 +1,7 @@
import { PageLayout } from "@/components/blocks/APIHeader";
import { CodeExample } from "@/components/code/code-example";
-import { StyledPayEmbedPreview } from "@/components/pay/embed";
import ThirdwebProvider from "@/components/thirdweb-provider";
+import { StyledBuyWidgetPreview } from "@/components/universal-bridge/buy";
import { metadataBase } from "@/lib/constants";
import type { Metadata } from "next";
@@ -25,17 +25,17 @@ export default function Page() {
}
docsLink="https://portal.thirdweb.com/connect/pay/get-started?utm_source=playground"
>
-
Inline component that allows users to buy any currency.
@@ -44,26 +44,19 @@ function StyledPayEmbed() {
),
}}
- preview={ {
sortBy,
limit,
offset,
+ includePrices,
} = options;
const clientFetch = getClientFetch(client);
@@ -159,6 +160,9 @@ export async function routes(options: routes.Options): Promise {
if (sortBy) {
url.searchParams.set("sortBy", sortBy);
}
+ if (includePrices) {
+ url.searchParams.set("includePrices", includePrices.toString());
+ }
const response = await clientFetch(url.toString());
if (!response.ok) {
@@ -185,6 +189,7 @@ export declare namespace routes {
transactionHash?: ox__Hex.Hex;
sortBy?: "popularity";
maxSteps?: number;
+ includePrices?: boolean;
limit?: number;
offset?: number;
};
diff --git a/packages/thirdweb/src/bridge/Token.ts b/packages/thirdweb/src/bridge/Token.ts
index 68699915fb9..29a67e8d45f 100644
--- a/packages/thirdweb/src/bridge/Token.ts
+++ b/packages/thirdweb/src/bridge/Token.ts
@@ -158,7 +158,7 @@ export async function tokens(options: tokens.Options): Promise {
export declare namespace tokens {
/**
- * Input parameters for {@link Bridge.tokens}.
+ * Input parameters for {@link tokens}.
*/
type Options = {
/** Your {@link ThirdwebClient} instance. */
@@ -182,3 +182,84 @@ export declare namespace tokens {
*/
type Result = Token[];
}
+
+/**
+ * Adds a token to the Universal Bridge for indexing.
+ *
+ * This function requests the Universal Bridge to index a specific token on a given chain.
+ * Once indexed, the token will be available for cross-chain operations.
+ *
+ * @example
+ * ```typescript
+ * import { Bridge } from "thirdweb";
+ *
+ * // Add a token for indexing
+ * const result = await Bridge.add({
+ * client: thirdwebClient,
+ * chainId: 1,
+ * tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ * });
+ * ```
+ *
+ * @param options - The options for adding a token.
+ * @param options.client - Your thirdweb client.
+ * @param options.chainId - The chain ID where the token is deployed.
+ * @param options.tokenAddress - The contract address of the token to add.
+ *
+ * @returns A promise that resolves when the token has been successfully submitted for indexing.
+ *
+ * @throws Will throw an error if there is an issue adding the token.
+ * @bridge
+ * @beta
+ */
+export async function add(options: add.Options): Promise {
+ const { client, chainId, tokenAddress } = options;
+
+ const clientFetch = getClientFetch(client);
+ const url = `${getThirdwebBaseUrl("bridge")}/v1/tokens`;
+
+ const requestBody = {
+ chainId,
+ tokenAddress,
+ };
+
+ const response = await clientFetch(url, {
+ method: "POST",
+ headers: {
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify(requestBody),
+ });
+
+ if (!response.ok) {
+ const errorJson = await response.json();
+ throw new ApiError({
+ code: errorJson.code || "UNKNOWN_ERROR",
+ message: errorJson.message || response.statusText,
+ correlationId: errorJson.correlationId || undefined,
+ statusCode: response.status,
+ });
+ }
+
+ const { data }: { data: Token } = await response.json();
+ return data;
+}
+
+export declare namespace add {
+ /**
+ * Input parameters for {@link add}.
+ */
+ type Options = {
+ /** Your {@link ThirdwebClient} instance. */
+ client: ThirdwebClient;
+ /** The chain ID where the token is deployed. */
+ chainId: number;
+ /** The contract address of the token to add. */
+ tokenAddress: string;
+ };
+
+ /**
+ * The result returned from {@link Bridge.add}.
+ */
+ type Result = Token;
+}
diff --git a/packages/thirdweb/src/bridge/types/BridgeAction.ts b/packages/thirdweb/src/bridge/types/BridgeAction.ts
index 7a83d5c9d3a..ffc4d58a31e 100644
--- a/packages/thirdweb/src/bridge/types/BridgeAction.ts
+++ b/packages/thirdweb/src/bridge/types/BridgeAction.ts
@@ -1 +1 @@
-export type Action = "approval" | "transfer" | "buy" | "sell";
+export type Action = "approval" | "transfer" | "buy" | "sell" | "fee";
diff --git a/packages/thirdweb/src/bridge/types/Errors.ts b/packages/thirdweb/src/bridge/types/Errors.ts
index ffa8da23164..f7f2074da20 100644
--- a/packages/thirdweb/src/bridge/types/Errors.ts
+++ b/packages/thirdweb/src/bridge/types/Errors.ts
@@ -1,3 +1,5 @@
+import { stringify } from "../../utils/json.js";
+
type ErrorCode =
| "INVALID_INPUT"
| "ROUTE_NOT_FOUND"
@@ -22,4 +24,13 @@ export class ApiError extends Error {
this.correlationId = args.correlationId;
this.statusCode = args.statusCode;
}
+
+ override toString() {
+ return stringify({
+ code: this.code,
+ message: this.message,
+ statusCode: this.statusCode,
+ correlationId: this.correlationId,
+ });
+ }
}
diff --git a/packages/thirdweb/src/exports/react.ts b/packages/thirdweb/src/exports/react.ts
index 5434611744b..dc3a0fe36f5 100644
--- a/packages/thirdweb/src/exports/react.ts
+++ b/packages/thirdweb/src/exports/react.ts
@@ -130,6 +130,22 @@ export type { AutoConnectProps } from "../wallets/connection/types.js";
// auth
export type { SiweAuthOptions } from "../react/core/hooks/auth/useSiweAuth.js";
+export {
+ BuyWidget,
+ type BuyWidgetProps,
+} from "../react/web/ui/Bridge/BuyWidget.js";
+export {
+ CheckoutWidget,
+ type CheckoutWidgetProps,
+} from "../react/web/ui/Bridge/CheckoutWidget.js";
+export {
+ TransactionWidget,
+ type TransactionWidgetProps,
+} from "../react/web/ui/Bridge/TransactionWidget.js";
+export {
+ useBridgeRoutes,
+ type UseBridgeRoutesParams,
+} from "../react/core/hooks/useBridgeRoutes.js";
export {
PayEmbed,
type PayEmbedProps,
diff --git a/packages/thirdweb/src/pay/buyWithFiat/getQuote.ts b/packages/thirdweb/src/pay/buyWithFiat/getQuote.ts
index 2ce99e691be..d7c722f2b9f 100644
--- a/packages/thirdweb/src/pay/buyWithFiat/getQuote.ts
+++ b/packages/thirdweb/src/pay/buyWithFiat/getQuote.ts
@@ -291,9 +291,9 @@ export async function getBuyWithFiatQuote(
provider?: FiatProvider,
): "stripe" | "coinbase" | "transak" => {
switch (provider) {
- case "STRIPE":
+ case "stripe":
return "stripe";
- case "TRANSAK":
+ case "transak":
return "transak";
default: // default to coinbase when undefined or any other value
return "coinbase";
diff --git a/packages/thirdweb/src/pay/convert/cryptoToFiat.ts b/packages/thirdweb/src/pay/convert/cryptoToFiat.ts
index fc6b04b0d81..6b80fd3a353 100644
--- a/packages/thirdweb/src/pay/convert/cryptoToFiat.ts
+++ b/packages/thirdweb/src/pay/convert/cryptoToFiat.ts
@@ -2,7 +2,7 @@ import type { Address } from "abitype";
import type { Chain } from "../../chains/types.js";
import type { ThirdwebClient } from "../../client/client.js";
import { isAddress } from "../../utils/address.js";
-import { getTokenPrice } from "./get-token.js";
+import { getToken } from "./get-token.js";
import type { SupportedFiatCurrency } from "./type.js";
/**
@@ -73,11 +73,11 @@ export async function convertCryptoToFiat(
"Invalid fromTokenAddress. Expected a valid EVM contract address",
);
}
- const price = await getTokenPrice(client, fromTokenAddress, chain.id);
- if (!price) {
+ const token = await getToken(client, fromTokenAddress, chain.id);
+ if (token.priceUsd === 0) {
throw new Error(
`Error: Failed to fetch price for token ${fromTokenAddress} on chainId: ${chain.id}`,
);
}
- return { result: price * fromAmount };
+ return { result: token.priceUsd * fromAmount };
}
diff --git a/packages/thirdweb/src/pay/convert/fiatToCrypto.ts b/packages/thirdweb/src/pay/convert/fiatToCrypto.ts
index 82ab392727e..f0843f0974d 100644
--- a/packages/thirdweb/src/pay/convert/fiatToCrypto.ts
+++ b/packages/thirdweb/src/pay/convert/fiatToCrypto.ts
@@ -2,7 +2,7 @@ import type { Address } from "abitype";
import type { Chain } from "../../chains/types.js";
import type { ThirdwebClient } from "../../client/client.js";
import { isAddress } from "../../utils/address.js";
-import { getTokenPrice } from "./get-token.js";
+import { getToken } from "./get-token.js";
import type { SupportedFiatCurrency } from "./type.js";
/**
@@ -72,11 +72,11 @@ export async function convertFiatToCrypto(
if (!isAddress(to)) {
throw new Error("Invalid `to`. Expected a valid EVM contract address");
}
- const price = await getTokenPrice(client, to, chain.id);
- if (!price || price === 0) {
+ const token = await getToken(client, to, chain.id);
+ if (!token || token.priceUsd === 0) {
throw new Error(
`Error: Failed to fetch price for token ${to} on chainId: ${chain.id}`,
);
}
- return { result: fromAmount / price };
+ return { result: fromAmount / token.priceUsd };
}
diff --git a/packages/thirdweb/src/pay/convert/get-token.ts b/packages/thirdweb/src/pay/convert/get-token.ts
index 6ec2eace996..351f7cdce9d 100644
--- a/packages/thirdweb/src/pay/convert/get-token.ts
+++ b/packages/thirdweb/src/pay/convert/get-token.ts
@@ -1,12 +1,13 @@
-import { tokens } from "../../bridge/Token.js";
+import { add, tokens } from "../../bridge/Token.js";
+import type { Token } from "../../bridge/types/Token.js";
import type { ThirdwebClient } from "../../client/client.js";
import { withCache } from "../../utils/promise/withCache.js";
-export async function getTokenPrice(
+export async function getToken(
client: ThirdwebClient,
tokenAddress: string,
chainId: number,
-) {
+): Promise {
return withCache(
async () => {
const result = await tokens({
@@ -14,7 +15,19 @@ export async function getTokenPrice(
tokenAddress,
chainId,
});
- return result[0]?.priceUsd;
+ const token = result[0];
+ if (!token) {
+ // Attempt to add the token
+ const tokenResult = await add({
+ client,
+ chainId,
+ tokenAddress,
+ }).catch(() => {
+ throw new Error("Token not supported");
+ });
+ return tokenResult;
+ }
+ return token;
},
{
cacheKey: `get-token-price-${tokenAddress}-${chainId}`,
diff --git a/packages/thirdweb/src/pay/utils/commonTypes.ts b/packages/thirdweb/src/pay/utils/commonTypes.ts
index 2f8fc723a4d..ef94c3fef4d 100644
--- a/packages/thirdweb/src/pay/utils/commonTypes.ts
+++ b/packages/thirdweb/src/pay/utils/commonTypes.ts
@@ -19,4 +19,4 @@ export type PayOnChainTransactionDetails = {
export type FiatProvider = (typeof FiatProviders)[number];
-export const FiatProviders = ["COINBASE", "STRIPE", "TRANSAK"] as const;
+export const FiatProviders = ["coinbase", "stripe", "transak"] as const;
diff --git a/packages/thirdweb/src/react/components.md b/packages/thirdweb/src/react/components.md
new file mode 100644
index 00000000000..7c47a245182
--- /dev/null
+++ b/packages/thirdweb/src/react/components.md
@@ -0,0 +1,134 @@
+# Web UI Components Catalog
+
+This document catalogs the UI components found within `packages/thirdweb/src/react/web/ui`.
+
+## Core Components (`packages/thirdweb/src/react/web/ui/components`)
+
+| Component | Occurrences |
+| ------------------- | ----------- |
+| Container | 100+ |
+| Text | 93 |
+| Spacer | 85 |
+| Button | 58 |
+| Skeleton | 40 |
+| ModalHeader | 40 |
+| Spinner | 31 |
+| Img | 31 |
+| Line | 28 |
+| ChainIcon | 19 |
+| TokenIcon | 16 |
+| Input | 11 |
+| SwitchNetworkButton | 10 |
+| WalletImage | 11 |
+| ToolTip | 6 |
+| Drawer | 5 |
+| QRCode | 5 |
+| CopyIcon | 4 |
+| ChainActiveDot | 3 |
+| Label | 3 |
+| ModalTitle | 3 |
+| TextDivider | 3 |
+| DynamicHeight | 3 |
+| StepBar | 2 |
+| IconContainer | 2 |
+| OTPInput | 2 |
+| ChainName | 1 |
+| BackButton | 1 |
+| IconButton | 1 |
+| ButtonLink | 1 |
+| Overlay | 1 |
+| Tabs | 1 |
+| FadeIn | 0 |
+| InputContainer | 0 |
+
+## Prebuilt Components (`packages/thirdweb/src/react/web/ui/prebuilt`)
+
+### NFT
+
+| Component | Occurrences (internal) |
+| -------------- | ---------------------- |
+| NFTName | 0 |
+| NFTMedia | 0 |
+| NFTDescription | 0 |
+| NFTProvider | 0 |
+
+### Account
+
+| Component | Occurrences (internal) |
+| -------------- | ---------------------- |
+| AccountBalance | 6 |
+| AccountAvatar | 2 |
+| AccountBlobbie | 4 |
+| AccountName | 2 |
+| AccountAddress | 4 |
+
+### Chain
+
+| Component | Occurrences (internal) |
+| ------------- | ---------------------- |
+| ChainName | 5 |
+| ChainIcon | 7 |
+| ChainProvider | 2 |
+
+### Token
+
+| Component | Occurrences (internal) |
+| ------------- | ---------------------- |
+| TokenName | 0 |
+| TokenSymbol | 12 |
+| TokenIcon | 7 |
+| TokenProvider | 0 |
+
+### Wallet
+
+| Component | Occurrences (internal) |
+| ---------- | ---------------------- |
+| WalletName | 0 |
+| WalletIcon | 0 |
+
+### Thirdweb
+
+| Component | Occurrences (internal) |
+| ------------------------- | ---------------------- |
+| ClaimButton | 0 |
+| BuyDirectListingButton | 0 |
+| CreateDirectListingButton | 0 |
+
+## Re-used Components (`packages/thirdweb/src/react/web/ui`)
+
+### Non-Core/Non-Prebuilt Components (ConnectWallet folder analysis)
+
+| Component | Occurrences | Source/Type |
+| ------------------------------ | ----------- | ---------------------------- |
+| LoadingScreen | 19 | Wallets shared component |
+| Suspense | 8 | React built-in |
+| WalletRow | 8 | Buy/swap utility component |
+| PoweredByThirdweb | 6 | Custom branding component |
+| Modal | 5 | Core UI component |
+| WalletUIStatesProvider | 4 | Wallet state management |
+| NetworkSelectorContent | 4 | Network selection component |
+| PayTokenIcon | 3 | Buy screen utility component |
+| FiatValue | 3 | Buy/swap utility component |
+| TOS | 3 | Terms of service component |
+| ErrorState | 3 | Error handling component |
+| AnimatedButton | 3 | Animation component |
+| ConnectModalContent | 3 | Modal content layout |
+| AnyWalletConnectUI | 2 | Wallet connection screen |
+| SmartConnectUI | 2 | Smart wallet connection UI |
+| WalletEntryButton | 2 | Wallet selection button |
+| TokenSelector | 2 | Token selection component |
+| SignatureScreen | 2 | Wallet signature screen |
+| WalletSwitcherConnectionScreen | 2 | Wallet switching UI |
+| ErrorText | 2 | Error display component |
+| SwapSummary | 2 | Swap transaction summary |
+| EstimatedTimeAndFees | 2 | Transaction info component |
+
+### Other Re-used Components
+
+| Component | Occurrences |
+| --------- | ----------- |
+| PayEmbed | 1 |
+| SiteEmbed | 0 |
+| SiteLink | 0 |
+
+**Note:** Occurrences are based on direct import and usage (e.g., `;
+}
diff --git a/packages/thirdweb/src/react/core/errors/.keep b/packages/thirdweb/src/react/core/errors/.keep
new file mode 100644
index 00000000000..fa0e58ded98
--- /dev/null
+++ b/packages/thirdweb/src/react/core/errors/.keep
@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain error mapping and normalization utilities
\ No newline at end of file
diff --git a/packages/thirdweb/src/react/core/errors/mapBridgeError.test.ts b/packages/thirdweb/src/react/core/errors/mapBridgeError.test.ts
new file mode 100644
index 00000000000..57c2d357243
--- /dev/null
+++ b/packages/thirdweb/src/react/core/errors/mapBridgeError.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { isRetryable, mapBridgeError } from "./mapBridgeError.js";
+
+describe("mapBridgeError", () => {
+ it("should return the same error for INVALID_INPUT", () => {
+ const error = new ApiError({
+ code: "INVALID_INPUT",
+ message: "Invalid input provided",
+ statusCode: 400,
+ correlationId: "test-correlation-id",
+ });
+
+ const result = mapBridgeError(error);
+
+ expect(result).toBe(error);
+ expect(result.code).toBe("INVALID_INPUT");
+ expect(result.message).toBe("Invalid input provided");
+ expect(result.statusCode).toBe(400);
+ expect(result.correlationId).toBe("test-correlation-id");
+ });
+
+ it("should return the same error for INTERNAL_SERVER_ERROR", () => {
+ const error = new ApiError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Internal server error occurred",
+ statusCode: 500,
+ correlationId: "internal-error-id",
+ });
+
+ const result = mapBridgeError(error);
+
+ expect(result).toBe(error);
+ expect(result.code).toBe("INTERNAL_SERVER_ERROR");
+ expect(result.message).toBe("Internal server error occurred");
+ expect(result.statusCode).toBe(500);
+ expect(result.correlationId).toBe("internal-error-id");
+ });
+
+ it("should return the same error for ROUTE_NOT_FOUND", () => {
+ const error = new ApiError({
+ code: "ROUTE_NOT_FOUND",
+ message: "No route found for the requested parameters",
+ statusCode: 404,
+ });
+
+ const result = mapBridgeError(error);
+
+ expect(result).toBe(error);
+ expect(result.code).toBe("ROUTE_NOT_FOUND");
+ expect(result.message).toBe("No route found for the requested parameters");
+ expect(result.statusCode).toBe(404);
+ expect(result.correlationId).toBeUndefined();
+ });
+
+ it("should return the same error for AMOUNT_TOO_LOW", () => {
+ const error = new ApiError({
+ code: "AMOUNT_TOO_LOW",
+ message: "Amount is below minimum threshold",
+ statusCode: 400,
+ correlationId: "amount-validation-id",
+ });
+
+ const result = mapBridgeError(error);
+
+ expect(result).toBe(error);
+ expect(result.code).toBe("AMOUNT_TOO_LOW");
+ expect(result.message).toBe("Amount is below minimum threshold");
+ expect(result.statusCode).toBe(400);
+ expect(result.correlationId).toBe("amount-validation-id");
+ });
+});
+
+describe("isRetryable", () => {
+ it("should return true for INTERNAL_SERVER_ERROR", () => {
+ expect(isRetryable("INTERNAL_SERVER_ERROR")).toBe(true);
+ });
+
+ it("should return true for UNKNOWN_ERROR", () => {
+ expect(isRetryable("UNKNOWN_ERROR")).toBe(true);
+ });
+
+ it("should return false for INVALID_INPUT", () => {
+ expect(isRetryable("INVALID_INPUT")).toBe(false);
+ });
+
+ it("should return false for ROUTE_NOT_FOUND", () => {
+ expect(isRetryable("ROUTE_NOT_FOUND")).toBe(false);
+ });
+
+ it("should return false for AMOUNT_TOO_LOW", () => {
+ expect(isRetryable("AMOUNT_TOO_LOW")).toBe(false);
+ });
+
+ it("should return false for AMOUNT_TOO_HIGH", () => {
+ expect(isRetryable("AMOUNT_TOO_HIGH")).toBe(false);
+ });
+});
diff --git a/packages/thirdweb/src/react/core/errors/mapBridgeError.ts b/packages/thirdweb/src/react/core/errors/mapBridgeError.ts
new file mode 100644
index 00000000000..d9159410fe3
--- /dev/null
+++ b/packages/thirdweb/src/react/core/errors/mapBridgeError.ts
@@ -0,0 +1,25 @@
+import type { ApiError } from "../../../bridge/types/Errors.js";
+
+/**
+ * Maps raw ApiError instances from the Bridge SDK into UI-friendly domain errors.
+ * Currently returns the same error; will evolve to provide better user-facing messages.
+ *
+ * @param e - The raw ApiError from the Bridge SDK
+ * @returns The mapped ApiError (currently unchanged)
+ */
+export function mapBridgeError(e: ApiError): ApiError {
+ // For now, return the same error
+ // TODO: This will evolve to provide better user-facing error messages
+ return e;
+}
+
+/**
+ * Determines if an error code represents a retryable error condition.
+ *
+ * @param code - The error code from ApiError
+ * @returns true if the error is retryable, false otherwise
+ */
+export function isRetryable(code: ApiError["code"]): boolean {
+ // Treat INTERNAL_SERVER_ERROR & UNKNOWN_ERROR as retryable
+ return code === "INTERNAL_SERVER_ERROR" || code === "UNKNOWN_ERROR";
+}
diff --git a/packages/thirdweb/src/react/core/hooks/connection/ConnectButtonProps.ts b/packages/thirdweb/src/react/core/hooks/connection/ConnectButtonProps.ts
index aa2b40bef3e..56f70df16ca 100644
--- a/packages/thirdweb/src/react/core/hooks/connection/ConnectButtonProps.ts
+++ b/packages/thirdweb/src/react/core/hooks/connection/ConnectButtonProps.ts
@@ -25,40 +25,42 @@ import type {
} from "../../utils/defaultTokens.js";
import type { SiweAuthOptions } from "../auth/useSiweAuth.js";
-export type PaymentInfo = {
- /**
- * The chain to receive the payment on.
- */
- chain: Chain;
- /**
- * The address of the seller wallet to receive the payment on.
- */
- sellerAddress: string;
- /**
- * Optional ERC20 token to receive the payment on.
- * If not provided, the native token will be used.
- */
- token?: TokenInfo;
- /**
- * For direct transfers, specify who will pay the transfer fee. Can be "sender" or "receiver".
- */
- feePayer?: "sender" | "receiver";
-} & (
- | {
- /**
- * The amount of tokens to receive in ETH or tokens.
- * ex: 0.1 ETH or 100 USDC
- */
- amount: string;
- }
- | {
- /**
- * The amount of tokens to receive in wei.
- * ex: 1000000000000000000 wei
- */
- amountWei: bigint;
- }
-);
+export type PaymentInfo = Prettify<
+ {
+ /**
+ * The chain to receive the payment on.
+ */
+ chain: Chain;
+ /**
+ * The address of the seller wallet to receive the payment on.
+ */
+ sellerAddress: string;
+ /**
+ * Optional ERC20 token to receive the payment on.
+ * If not provided, the native token will be used.
+ */
+ token?: Partial & { address: string };
+ /**
+ * For direct transfers, specify who will pay the transfer fee. Can be "sender" or "receiver".
+ */
+ feePayer?: "sender" | "receiver";
+ } & (
+ | {
+ /**
+ * The amount of tokens to receive in ETH or tokens.
+ * ex: 0.1 ETH or 100 USDC
+ */
+ amount: string;
+ }
+ | {
+ /**
+ * The amount of tokens to receive in wei.
+ * ex: 1000000000000000000 wei
+ */
+ amountWei: bigint;
+ }
+ )
+>;
export type PayUIOptions = Prettify<
{
@@ -78,7 +80,7 @@ export type PayUIOptions = Prettify<
testMode?: boolean;
prefillSource?: {
chain: Chain;
- token?: TokenInfo;
+ token?: Partial & { address: string };
allowEdits?: {
token: boolean;
chain: boolean;
@@ -115,7 +117,8 @@ export type PayUIOptions = Prettify<
* Callback to be called when the user successfully completes the purchase.
*/
onPurchaseSuccess?: (
- info:
+ // TODO: remove this type from the callback entirely or adapt it from the new format
+ info?:
| {
type: "crypto";
status: BuyWithCryptoStatus;
@@ -135,6 +138,7 @@ export type PayUIOptions = Prettify<
*/
metadata?: {
name?: string;
+ description?: string;
image?: string;
};
@@ -160,13 +164,14 @@ export type FundWalletOptions = {
*/
prefillBuy?: {
chain: Chain;
- token?: TokenInfo;
+ token?: Partial & { address: string };
amount?: string;
allowEdits?: {
amount: boolean;
token: boolean;
chain: boolean;
};
+ presetOptions?: [number, number, number];
};
};
diff --git a/packages/thirdweb/src/react/core/hooks/others/useChainQuery.ts b/packages/thirdweb/src/react/core/hooks/others/useChainQuery.ts
index 4cda3eab0e9..0eb36c2f7f0 100644
--- a/packages/thirdweb/src/react/core/hooks/others/useChainQuery.ts
+++ b/packages/thirdweb/src/react/core/hooks/others/useChainQuery.ts
@@ -137,7 +137,7 @@ export function useChainExplorers(chain?: Chain) {
function getQueryOptions(chain?: Chain) {
return {
- queryKey: ["chain", chain],
+ queryKey: ["chain", chain?.id],
enabled: !!chain,
staleTime: 1000 * 60 * 60, // 1 hour
} as const;
diff --git a/packages/thirdweb/src/react/core/hooks/pay/useBuyWithFiatQuotesForProviders.ts b/packages/thirdweb/src/react/core/hooks/pay/useBuyWithFiatQuotesForProviders.ts
new file mode 100644
index 00000000000..77619e4c59b
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/pay/useBuyWithFiatQuotesForProviders.ts
@@ -0,0 +1,100 @@
+import { type UseQueryOptions, useQueries } from "@tanstack/react-query";
+import { prepare as prepareOnramp } from "../../../../bridge/Onramp.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { getToken } from "../../../../pay/convert/get-token.js";
+import type { Address } from "../../../../utils/address.js";
+import { toUnits } from "../../../../utils/units.js";
+
+/**
+ * @internal
+ */
+type UseBuyWithFiatQuotesForProvidersParams = {
+ /**
+ * A client is the entry point to the thirdweb SDK.
+ */
+ client: ThirdwebClient;
+ /**
+ * The destination chain ID.
+ */
+ chainId: number;
+ /**
+ * The destination token address.
+ */
+ tokenAddress: Address;
+ /**
+ * The address that will receive the tokens.
+ */
+ receiver: Address;
+ /**
+ * The desired token amount in wei.
+ */
+ amount: string;
+ /**
+ * The fiat currency (e.g., "USD"). Defaults to "USD".
+ */
+ currency?: string;
+};
+
+/**
+ * @internal
+ */
+type OnrampQuoteQueryOptions = Omit<
+ UseQueryOptions>>,
+ "queryFn" | "queryKey" | "enabled"
+>;
+
+/**
+ * @internal
+ */
+type UseBuyWithFiatQuotesForProvidersResult = {
+ data: Awaited> | undefined;
+ isLoading: boolean;
+ error: Error | null;
+ isError: boolean;
+ isSuccess: boolean;
+}[];
+
+/**
+ * @internal
+ * Hook to get prepared onramp quotes from Coinbase, Stripe, and Transak providers.
+ */
+export function useBuyWithFiatQuotesForProviders(
+ params?: UseBuyWithFiatQuotesForProvidersParams,
+ queryOptions?: OnrampQuoteQueryOptions,
+): UseBuyWithFiatQuotesForProvidersResult {
+ const providers = ["coinbase", "stripe", "transak"] as const;
+
+ const queries = useQueries({
+ queries: providers.map((provider) => ({
+ ...queryOptions,
+ queryKey: ["onramp-prepare", provider, params],
+ queryFn: async () => {
+ if (!params) {
+ throw new Error("No params provided");
+ }
+
+ const token = await getToken(
+ params.client,
+ params.tokenAddress,
+ params.chainId,
+ );
+
+ const amountWei = toUnits(params.amount, token.decimals);
+
+ return prepareOnramp({
+ client: params.client,
+ onramp: provider,
+ chainId: params.chainId,
+ tokenAddress: params.tokenAddress,
+ receiver: params.receiver,
+ amount: amountWei,
+ currency: params.currency || "USD",
+ });
+ },
+ enabled: !!params,
+ retry: false,
+ })),
+ });
+
+ return queries;
+}
diff --git a/packages/thirdweb/src/react/core/hooks/transaction/useSendTransaction.ts b/packages/thirdweb/src/react/core/hooks/transaction/useSendTransaction.ts
index 78fbcfa3e60..8498ec5ff31 100644
--- a/packages/thirdweb/src/react/core/hooks/transaction/useSendTransaction.ts
+++ b/packages/thirdweb/src/react/core/hooks/transaction/useSendTransaction.ts
@@ -70,7 +70,7 @@ export type SendTransactionPayModalConfig =
* Callback to be called when the user successfully completes the purchase.
*/
onPurchaseSuccess?: (
- info:
+ info?:
| {
type: "crypto";
status: BuyWithCryptoStatus;
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgeError.test.ts b/packages/thirdweb/src/react/core/hooks/useBridgeError.test.ts
new file mode 100644
index 00000000000..b47fa3b8654
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgeError.test.ts
@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { useBridgeError } from "./useBridgeError.js";
+
+describe("useBridgeError", () => {
+ it("should handle null error", () => {
+ const result = useBridgeError({ error: null });
+
+ expect(result).toEqual({
+ mappedError: null,
+ isRetryable: false,
+ userMessage: "",
+ errorCode: null,
+ statusCode: null,
+ isClientError: false,
+ isServerError: false,
+ });
+ });
+
+ it("should handle undefined error", () => {
+ const result = useBridgeError({ error: undefined });
+
+ expect(result).toEqual({
+ mappedError: null,
+ isRetryable: false,
+ userMessage: "",
+ errorCode: null,
+ statusCode: null,
+ isClientError: false,
+ isServerError: false,
+ });
+ });
+
+ it("should process ApiError correctly", () => {
+ const apiError = new ApiError({
+ code: "INVALID_INPUT",
+ message: "Invalid parameters provided",
+ statusCode: 400,
+ });
+
+ const result = useBridgeError({ error: apiError });
+
+ expect(result.mappedError).toBeInstanceOf(ApiError);
+ expect(result.errorCode).toBe("INVALID_INPUT");
+ expect(result.statusCode).toBe(400);
+ expect(result.isClientError).toBe(true);
+ expect(result.isServerError).toBe(false);
+ expect(result.isRetryable).toBe(false); // INVALID_INPUT is not retryable
+ expect(result.userMessage).toBe(
+ "Invalid input provided. Please check your parameters and try again.",
+ );
+ });
+
+ it("should convert generic Error to ApiError", () => {
+ const genericError = new Error("Network connection failed");
+
+ const result = useBridgeError({ error: genericError });
+
+ expect(result.mappedError).toBeInstanceOf(ApiError);
+ expect(result.errorCode).toBe("UNKNOWN_ERROR");
+ expect(result.statusCode).toBe(500);
+ expect(result.isClientError).toBe(false);
+ expect(result.isServerError).toBe(true);
+ expect(result.isRetryable).toBe(true);
+ expect(result.userMessage).toBe(
+ "An unexpected error occurred. Please try again.",
+ );
+ });
+
+ it("should identify server errors correctly", () => {
+ const serverError = new ApiError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Server error",
+ statusCode: 500,
+ });
+
+ const result = useBridgeError({ error: serverError });
+
+ expect(result.statusCode).toBe(500);
+ expect(result.isClientError).toBe(false);
+ expect(result.isServerError).toBe(true);
+ expect(result.isRetryable).toBe(true); // INTERNAL_SERVER_ERROR is retryable
+ expect(result.userMessage).toBe(
+ "A temporary error occurred. Please try again in a moment.",
+ );
+ });
+
+ it("should provide user-friendly messages for known error codes", () => {
+ // Test INVALID_INPUT
+ const invalidInputError = new ApiError({
+ code: "INVALID_INPUT",
+ message: "Technical error message",
+ statusCode: 400,
+ });
+ const invalidInputResult = useBridgeError({ error: invalidInputError });
+ expect(invalidInputResult.userMessage).toBe(
+ "Invalid input provided. Please check your parameters and try again.",
+ );
+
+ // Test INTERNAL_SERVER_ERROR
+ const serverError = new ApiError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Technical error message",
+ statusCode: 500,
+ });
+ const serverResult = useBridgeError({ error: serverError });
+ expect(serverResult.userMessage).toBe(
+ "A temporary error occurred. Please try again in a moment.",
+ );
+ });
+
+ it("should use original error message for unknown error codes", () => {
+ const unknownError = new ApiError({
+ code: "UNKNOWN_ERROR",
+ message: "Custom error message",
+ statusCode: 418,
+ });
+
+ const result = useBridgeError({ error: unknownError });
+
+ expect(result.userMessage).toBe(
+ "An unexpected error occurred. Please try again.",
+ );
+ expect(result.errorCode).toBe("UNKNOWN_ERROR");
+ });
+
+ it("should detect client vs server errors correctly", () => {
+ // Client error (4xx)
+ const clientError = new ApiError({
+ code: "INVALID_INPUT",
+ message: "Bad request",
+ statusCode: 400,
+ });
+
+ const clientResult = useBridgeError({ error: clientError });
+ expect(clientResult.isClientError).toBe(true);
+ expect(clientResult.isServerError).toBe(false);
+
+ // Server error (5xx)
+ const serverError = new ApiError({
+ code: "INTERNAL_SERVER_ERROR",
+ message: "Internal error",
+ statusCode: 503,
+ });
+
+ const serverResult = useBridgeError({ error: serverError });
+ expect(serverResult.isClientError).toBe(false);
+ expect(serverResult.isServerError).toBe(true);
+
+ // No status code
+ const noStatusError = new ApiError({
+ code: "UNKNOWN_ERROR",
+ message: "Unknown error",
+ statusCode: 500,
+ });
+
+ const noStatusResult = useBridgeError({ error: noStatusError });
+ expect(noStatusResult.isClientError).toBe(false);
+ expect(noStatusResult.isServerError).toBe(true); // 500 is a server error
+ });
+
+ it("should handle Error without message", () => {
+ const errorWithoutMessage = new Error();
+
+ const result = useBridgeError({ error: errorWithoutMessage });
+
+ expect(result.userMessage).toBe(
+ "An unexpected error occurred. Please try again.",
+ );
+ expect(result.errorCode).toBe("UNKNOWN_ERROR");
+ });
+});
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgeError.ts b/packages/thirdweb/src/react/core/hooks/useBridgeError.ts
new file mode 100644
index 00000000000..ea4b7751648
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgeError.ts
@@ -0,0 +1,149 @@
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { isRetryable, mapBridgeError } from "../errors/mapBridgeError.js";
+
+/**
+ * Parameters for the useBridgeError hook
+ */
+interface UseBridgeErrorParams {
+ /**
+ * The error to process. Can be an ApiError or generic Error.
+ */
+ error: Error | ApiError | null | undefined;
+}
+
+/**
+ * Result returned by the useBridgeError hook
+ */
+interface UseBridgeErrorResult {
+ /**
+ * The mapped/normalized error, null if no error provided
+ */
+ mappedError: ApiError | null;
+
+ /**
+ * Whether this error can be retried
+ */
+ isRetryable: boolean;
+
+ /**
+ * User-friendly error message
+ */
+ userMessage: string;
+
+ /**
+ * Technical error code for debugging
+ */
+ errorCode: string | null;
+
+ /**
+ * HTTP status code if available
+ */
+ statusCode: number | null;
+
+ /**
+ * Whether this is a client-side error (4xx)
+ */
+ isClientError: boolean;
+
+ /**
+ * Whether this is a server-side error (5xx)
+ */
+ isServerError: boolean;
+}
+
+/**
+ * Hook that processes bridge errors using mapBridgeError and isRetryable
+ *
+ * @param params - Parameters containing the error to process
+ * @returns Processed error information with retry logic and user-friendly messages
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = useBridgeRoutes({ client, originChainId: 1 });
+ * const {
+ * mappedError,
+ * isRetryable,
+ * userMessage,
+ * isClientError
+ * } = useBridgeError({ error });
+ *
+ * if (error) {
+ * return (
+ * => {
+ switch (type) {
+ case "buy": {
+ const result = await Bridge.Buy.prepare(
+ prepareParams as BuyPrepare.Options,
+ );
+ return { type: "buy", ...result };
+ }
+ case "sell": {
+ const result = await Bridge.Sell.prepare(
+ prepareParams as SellPrepare.Options,
+ );
+ return { type: "sell", ...result };
+ }
+ case "transfer": {
+ const result = await Bridge.Transfer.prepare(
+ prepareParams as TransferPrepare.Options,
+ );
+ return { type: "transfer", ...result };
+ }
+ case "onramp": {
+ const result = await Bridge.Onramp.prepare(
+ prepareParams as OnrampPrepare.Options,
+ );
+ return { type: "onramp", ...result };
+ }
+ default:
+ throw new Error(`Unsupported bridge prepare type: ${type}`);
+ }
+ },
+ enabled: enabled && !!prepareParams.client,
+ staleTime: 2 * 60 * 1000, // 2 minutes - prepared quotes have shorter validity
+ gcTime: 5 * 60 * 1000, // 5 minutes garbage collection
+ retry: (failureCount, error) => {
+ // Handle both ApiError and generic Error instances
+ if (error instanceof ApiError) {
+ const bridgeError = mapBridgeError(error);
+
+ // Don't retry on client-side errors (4xx)
+ if (
+ bridgeError.statusCode &&
+ bridgeError.statusCode >= 400 &&
+ bridgeError.statusCode < 500
+ ) {
+ return false;
+ }
+ }
+
+ // Retry up to 2 times for prepared quotes (they're more time-sensitive)
+ return failureCount < 2;
+ },
+ retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 10000), // Exponential backoff, max 10s
+ });
+}
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgeQuote.ts b/packages/thirdweb/src/react/core/hooks/useBridgeQuote.ts
new file mode 100644
index 00000000000..5d1661e7a55
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgeQuote.ts
@@ -0,0 +1,67 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import * as Buy from "../../../bridge/Buy.js";
+import * as Transfer from "../../../bridge/Transfer.js";
+import type { Token } from "../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { checksumAddress } from "../../../utils/address.js";
+
+interface UseBridgeQuoteParams {
+ originToken: Token;
+ destinationToken: Token;
+ destinationAmount: bigint;
+ client: ThirdwebClient;
+ enabled?: boolean;
+}
+
+export function useBridgeQuote({
+ originToken,
+ destinationToken,
+ destinationAmount,
+ client,
+ enabled = true,
+}: UseBridgeQuoteParams) {
+ return useQuery({
+ queryKey: [
+ "bridge-quote",
+ originToken.chainId,
+ originToken.address,
+ destinationToken.chainId,
+ destinationToken.address,
+ destinationAmount.toString(),
+ ],
+ queryFn: async () => {
+ // if ssame token and chain, use transfer
+ if (
+ checksumAddress(originToken.address) ===
+ checksumAddress(destinationToken.address) &&
+ originToken.chainId === destinationToken.chainId
+ ) {
+ const transfer = await Transfer.prepare({
+ client,
+ chainId: originToken.chainId,
+ tokenAddress: originToken.address,
+ sender: originToken.address,
+ receiver: destinationToken.address,
+ amount: destinationAmount,
+ });
+ return transfer;
+ }
+ const quote = await Buy.quote({
+ originChainId: originToken.chainId,
+ originTokenAddress: originToken.address,
+ destinationChainId: destinationToken.chainId,
+ destinationTokenAddress: destinationToken.address,
+ amount: destinationAmount,
+ client,
+ });
+
+ return quote;
+ },
+ enabled:
+ enabled && !!originToken && !!destinationToken && !!destinationAmount,
+ staleTime: 30000, // 30 seconds
+ refetchInterval: 60000, // 1 minute
+ retry: 3,
+ });
+}
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.test.ts b/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.test.ts
new file mode 100644
index 00000000000..8a539cbe9ee
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.test.ts
@@ -0,0 +1,137 @@
+import {
+ type MockedFunction,
+ beforeEach,
+ describe,
+ expect,
+ it,
+ vi,
+} from "vitest";
+import { routes } from "../../../bridge/Routes.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import type { Route } from "../../../bridge/types/Route.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import type { UseBridgeRoutesParams } from "./useBridgeRoutes.js";
+
+// Mock the Bridge routes function
+vi.mock("../../../bridge/Routes.js", () => ({
+ routes: vi.fn(),
+}));
+
+const mockRoutes = routes as MockedFunction;
+
+// Mock client
+const mockClient = { clientId: "test" } as ThirdwebClient;
+
+// Mock route data
+const mockRouteData: Route[] = [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ symbol: "ETH",
+ name: "Ethereum",
+ decimals: 18,
+ priceUsd: 2000.0,
+ },
+ destinationToken: {
+ chainId: 137,
+ address: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ symbol: "WETH",
+ name: "Wrapped Ethereum",
+ decimals: 18,
+ priceUsd: 2000.0,
+ },
+ },
+];
+
+describe("useBridgeRoutes", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it("should export correct hook parameters type", () => {
+ // Type-only test to verify UseBridgeRoutesParams interface
+ const params: UseBridgeRoutesParams = {
+ client: mockClient,
+ originChainId: 1,
+ destinationChainId: 137,
+ enabled: true,
+ };
+
+ expect(params).toBeDefined();
+ expect(params.client).toBe(mockClient);
+ expect(params.originChainId).toBe(1);
+ expect(params.destinationChainId).toBe(137);
+ expect(params.enabled).toBe(true);
+ });
+
+ it("should handle different parameter combinations", () => {
+ const fullParams: UseBridgeRoutesParams = {
+ client: mockClient,
+ originChainId: 1,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ maxSteps: 3,
+ sortBy: "popularity",
+ limit: 10,
+ offset: 0,
+ enabled: false,
+ };
+
+ expect(fullParams).toBeDefined();
+ expect(fullParams.sortBy).toBe("popularity");
+ expect(fullParams.maxSteps).toBe(3);
+ expect(fullParams.limit).toBe(10);
+ expect(fullParams.offset).toBe(0);
+ });
+
+ it("should have optional enabled parameter defaulting to true", () => {
+ const paramsWithoutEnabled: UseBridgeRoutesParams = {
+ client: mockClient,
+ originChainId: 1,
+ destinationChainId: 137,
+ };
+
+ expect(paramsWithoutEnabled.enabled).toBeUndefined(); // Should be optional
+ });
+
+ it("should validate that Bridge.routes would be called with correct parameters", async () => {
+ const testParams = {
+ client: mockClient,
+ originChainId: 1,
+ destinationChainId: 137,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" as const,
+ };
+
+ // Mock the routes function to return our test data
+ mockRoutes.mockResolvedValue(mockRouteData);
+
+ // Directly call the routes function to verify it works with our parameters
+ const result = await routes(testParams);
+
+ expect(mockRoutes).toHaveBeenCalledWith(testParams);
+ expect(result).toEqual(mockRouteData);
+ });
+
+ it("should handle API errors properly", async () => {
+ const apiError = new ApiError({
+ code: "INVALID_INPUT",
+ message: "Invalid parameters",
+ statusCode: 400,
+ });
+
+ mockRoutes.mockRejectedValue(apiError);
+
+ try {
+ await routes({
+ client: mockClient,
+ originChainId: 1,
+ destinationChainId: 137,
+ });
+ } catch (error) {
+ expect(error).toBe(apiError);
+ expect(error).toBeInstanceOf(ApiError);
+ }
+ });
+});
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.ts b/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.ts
new file mode 100644
index 00000000000..39eddea54f8
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgeRoutes.ts
@@ -0,0 +1,75 @@
+import { useQuery } from "@tanstack/react-query";
+import { routes } from "../../../bridge/Routes.js";
+import type { routes as RoutesTypes } from "../../../bridge/Routes.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { mapBridgeError } from "../errors/mapBridgeError.js";
+
+/**
+ * Parameters for the useBridgeRoutes hook
+ */
+export type UseBridgeRoutesParams = RoutesTypes.Options & {
+ /**
+ * Whether to enable the query. Useful for conditional fetching.
+ * @default true
+ */
+ enabled?: boolean;
+};
+
+/**
+ * Hook that fetches available bridge routes with caching and retry logic
+ *
+ * @param params - Parameters for fetching routes including client and filter options
+ * @returns React Query result with routes data, loading state, and error handling
+ *
+ * @example
+ * ```tsx
+ * const { data: routes, isLoading, error } = useBridgeRoutes({
+ * client: thirdwebClient,
+ * originChainId: 1,
+ * destinationChainId: 137,
+ * originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"
+ * });
+ * ```
+ */
+export function useBridgeRoutes(params: UseBridgeRoutesParams) {
+ const { enabled = true, ...routeParams } = params;
+
+ return useQuery({
+ queryKey: [
+ "bridge-routes",
+ {
+ originChainId: routeParams.originChainId,
+ originTokenAddress: routeParams.originTokenAddress,
+ destinationChainId: routeParams.destinationChainId,
+ destinationTokenAddress: routeParams.destinationTokenAddress,
+ maxSteps: routeParams.maxSteps,
+ sortBy: routeParams.sortBy,
+ limit: routeParams.limit,
+ offset: routeParams.offset,
+ },
+ ],
+ queryFn: () => routes(routeParams),
+ enabled: enabled && !!routeParams.client,
+ staleTime: 5 * 60 * 1000, // 5 minutes - routes are relatively stable
+ gcTime: 10 * 60 * 1000, // 10 minutes garbage collection
+ retry: (failureCount, error) => {
+ // Handle both ApiError and generic Error instances
+ if (error instanceof ApiError) {
+ const bridgeError = mapBridgeError(error);
+
+ // Don't retry on client-side errors (4xx)
+ if (
+ bridgeError.statusCode &&
+ bridgeError.statusCode >= 400 &&
+ bridgeError.statusCode < 500
+ ) {
+ return false;
+ }
+ }
+
+ // Retry up to 3 times for server errors or network issues
+ return failureCount < 3;
+ },
+ retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000), // Exponential backoff, max 30s
+ });
+}
diff --git a/packages/thirdweb/src/react/core/hooks/usePaymentMethods.test.ts b/packages/thirdweb/src/react/core/hooks/usePaymentMethods.test.ts
new file mode 100644
index 00000000000..92a68f5da1e
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/usePaymentMethods.test.ts
@@ -0,0 +1,336 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderHook, waitFor } from "@testing-library/react";
+import { createElement } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { routes } from "../../../bridge/Routes.js";
+import type { Token } from "../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { usePaymentMethods } from "./usePaymentMethods.js";
+
+// Mock the routes API
+vi.mock("../../../bridge/Routes.js", () => ({
+ routes: vi.fn(),
+}));
+
+const mockRoutes = vi.mocked(routes);
+
+// Mock data
+const mockDestinationToken: Token = {
+ chainId: 1,
+ address: "0xA0b86a33E6441aA7A6fbEEc9bb27e5e8bc3b8eD7",
+ decimals: 6,
+ symbol: "USDC",
+ name: "USD Coin",
+ priceUsd: 1.0,
+};
+
+const mockClient = {
+ clientId: "test-client-id",
+} as ThirdwebClient;
+
+const mockRouteData = [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xA0b86a33E6441aA7A6fbEEc9bb27e5e8bc3b8eD7",
+ decimals: 18,
+ symbol: "ETH",
+ name: "Ethereum",
+ priceUsd: 2000,
+ },
+ destinationToken: mockDestinationToken,
+ steps: [],
+ },
+ {
+ originToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ decimals: 6,
+ symbol: "USDC",
+ name: "USD Coin",
+ priceUsd: 1.0,
+ },
+ destinationToken: mockDestinationToken,
+ steps: [],
+ },
+ {
+ originToken: {
+ chainId: 42161,
+ address: "0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8",
+ decimals: 6,
+ symbol: "USDC",
+ name: "USD Coin",
+ priceUsd: 1.0,
+ },
+ destinationToken: mockDestinationToken,
+ steps: [],
+ },
+];
+
+// Test wrapper component
+const createWrapper = () => {
+ const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: {
+ retry: false,
+ },
+ },
+ });
+
+ return ({ children }: { children: React.ReactNode }) =>
+ createElement(QueryClientProvider, { client: queryClient }, children);
+};
+
+describe("usePaymentMethods", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it("should require destinationToken and client parameters", () => {
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ expect(result.current).toBeDefined();
+ expect(result.current.isLoading).toBe(true);
+ });
+
+ it("should fetch routes and transform data correctly", async () => {
+ mockRoutes.mockResolvedValueOnce(mockRouteData);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ // Initially loading
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.data).toEqual([]);
+
+ // Wait for query to resolve
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ // Should have transformed data
+ expect(result.current.data).toHaveLength(4); // 3 wallet methods + 1 fiat method
+
+ const walletMethod = result.current.data[0];
+ expect(walletMethod?.type).toBe("wallet");
+ if (walletMethod?.type === "wallet") {
+ expect(walletMethod.originToken).toEqual(mockRouteData[0]?.originToken);
+ }
+
+ const fiatMethod = result.current.data[3];
+ expect(fiatMethod?.type).toBe("fiat");
+ if (fiatMethod?.type === "fiat") {
+ expect(fiatMethod.currency).toBe("USD");
+ }
+ });
+
+ it("should call routes API with correct parameters", async () => {
+ mockRoutes.mockResolvedValueOnce(mockRouteData);
+ const wrapper = createWrapper();
+
+ renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(mockRoutes).toHaveBeenCalledWith({
+ client: mockClient,
+ destinationChainId: mockDestinationToken.chainId,
+ destinationTokenAddress: mockDestinationToken.address,
+ sortBy: "popularity",
+ limit: 50,
+ });
+ });
+ });
+
+ it("should handle empty routes data", async () => {
+ mockRoutes.mockResolvedValueOnce([]);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ // Should only have fiat method when no routes
+ expect(result.current.data).toHaveLength(1);
+ expect(result.current.data[0]).toEqual({
+ type: "fiat",
+ currency: "USD",
+ });
+ });
+
+ it("should handle API errors gracefully", async () => {
+ const mockError = new Error("API Error");
+ mockRoutes.mockRejectedValueOnce(mockError);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.isError).toBe(true);
+ });
+
+ expect(result.current.error).toBeTruthy();
+ expect(result.current.data).toEqual([]);
+ });
+
+ it("should deduplicate origin tokens", async () => {
+ // Mock data with duplicate origin tokens
+ const firstRoute = mockRouteData[0];
+ if (!firstRoute) {
+ throw new Error("Mock data is invalid");
+ }
+
+ const mockDataWithDuplicates = [
+ ...mockRouteData,
+ {
+ originToken: firstRoute.originToken, // Duplicate ETH
+ destinationToken: mockDestinationToken,
+ steps: [],
+ },
+ ];
+
+ mockRoutes.mockResolvedValueOnce(mockDataWithDuplicates);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ // Should still have only 4 methods (3 unique wallet + 1 fiat)
+ expect(result.current.data).toHaveLength(4);
+
+ // Check that ETH only appears once
+ const walletMethods = result.current.data.filter(
+ (m) => m.type === "wallet",
+ );
+ const ethMethods = walletMethods.filter(
+ (m) => m.type === "wallet" && m.originToken?.symbol === "ETH",
+ );
+ expect(ethMethods).toHaveLength(1);
+ });
+
+ it("should always include fiat payment option", async () => {
+ mockRoutes.mockResolvedValueOnce(mockRouteData);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ const fiatMethods = result.current.data.filter((m) => m.type === "fiat");
+ expect(fiatMethods).toHaveLength(1);
+ expect(fiatMethods[0]).toEqual({
+ type: "fiat",
+ currency: "USD",
+ });
+ });
+
+ it("should have correct query key for caching", async () => {
+ mockRoutes.mockResolvedValueOnce(mockRouteData);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ // The hook should use a query key that includes chain ID and token address
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(mockRoutes).toHaveBeenCalledTimes(1);
+ });
+
+ it("should provide refetch functionality", async () => {
+ mockRoutes.mockResolvedValueOnce(mockRouteData);
+ const wrapper = createWrapper();
+
+ const { result } = renderHook(
+ () =>
+ usePaymentMethods({
+ destinationToken: mockDestinationToken,
+ destinationAmount: "1",
+ client: mockClient,
+ }),
+ { wrapper },
+ );
+
+ await waitFor(() => {
+ expect(result.current.isSuccess).toBe(true);
+ });
+
+ expect(typeof result.current.refetch).toBe("function");
+ });
+});
diff --git a/packages/thirdweb/src/react/core/hooks/usePaymentMethods.ts b/packages/thirdweb/src/react/core/hooks/usePaymentMethods.ts
new file mode 100644
index 00000000000..1083259071a
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/usePaymentMethods.ts
@@ -0,0 +1,203 @@
+import { useQuery } from "@tanstack/react-query";
+import { routes } from "../../../bridge/Routes.js";
+import type { Token } from "../../../bridge/types/Token.js";
+import { getCachedChain } from "../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { isInsightEnabled } from "../../../insight/common.js";
+import { getOwnedTokens } from "../../../insight/get-tokens.js";
+import { toTokens } from "../../../utils/units.js";
+import type { Wallet } from "../../../wallets/interfaces/wallet.js";
+import type { PaymentMethod } from "../machines/paymentMachine.js";
+import { useActiveWallet } from "./wallets/useActiveWallet.js";
+
+type OwnedTokenWithQuote = {
+ originToken: Token;
+ balance: bigint;
+ originAmount: bigint;
+};
+
+/**
+ * Hook that returns available payment methods for BridgeEmbed
+ * Fetches real routes data based on the destination token
+ *
+ * @param options - Configuration options
+ * @param options.destinationToken - The destination token to find routes for
+ * @param options.client - ThirdwebClient for API calls
+ * @returns Available payment methods with route data
+ *
+ * @example
+ * ```tsx
+ * const { data: paymentMethods, isLoading, error } = usePaymentMethods({
+ * destinationToken,
+ * client
+ * });
+ * ```
+ */
+export function usePaymentMethods(options: {
+ destinationToken: Token;
+ destinationAmount: string;
+ client: ThirdwebClient;
+ payerWallet?: Wallet;
+ includeDestinationToken?: boolean;
+}) {
+ const {
+ destinationToken,
+ destinationAmount,
+ client,
+ payerWallet,
+ includeDestinationToken,
+ } = options;
+ const localWallet = useActiveWallet(); // TODO (bridge): get all connected wallets
+ const wallet = payerWallet || localWallet;
+
+ const routesQuery = useQuery({
+ queryKey: [
+ "bridge-routes",
+ destinationToken.chainId,
+ destinationToken.address,
+ destinationAmount,
+ payerWallet?.getAccount()?.address,
+ includeDestinationToken,
+ ],
+ queryFn: async (): Promise => {
+ if (!wallet) {
+ throw new Error("No wallet connected");
+ }
+ const allRoutes = await routes({
+ client,
+ destinationChainId: destinationToken.chainId,
+ destinationTokenAddress: destinationToken.address,
+ sortBy: "popularity",
+ includePrices: true,
+ maxSteps: 3,
+ limit: 100, // Get top 100 most popular routes
+ });
+
+ const allOriginTokens = includeDestinationToken
+ ? [destinationToken, ...allRoutes.map((route) => route.originToken)]
+ : allRoutes.map((route) => route.originToken);
+
+ // 1. Resolve all unique chains in the supported token map
+ const uniqueChains = Array.from(
+ new Set(allOriginTokens.map((t) => t.chainId)),
+ );
+
+ // 2. Check insight availability once per chain
+ const insightSupport = await Promise.all(
+ uniqueChains.map(async (c) => ({
+ chain: getCachedChain(c),
+ enabled: await isInsightEnabled(getCachedChain(c)),
+ })),
+ );
+ const insightEnabledChains = insightSupport.filter((c) => c.enabled);
+
+ // 3. ERC-20 balances for insight-enabled chains (batched 5 chains / call)
+ let owned: OwnedTokenWithQuote[] = [];
+ let page = 0;
+ const limit = 100;
+
+ while (true) {
+ const batch = await getOwnedTokens({
+ ownerAddress: wallet.getAccount()?.address || "",
+ chains: insightEnabledChains.map((c) => c.chain),
+ client,
+ queryOptions: {
+ limit,
+ page,
+ metadata: "false",
+ },
+ });
+
+ if (batch.length === 0) {
+ break;
+ }
+
+ // find matching origin token in allRoutes
+ const tokensWithBalance = batch
+ .map((b) => ({
+ originToken: allOriginTokens.find(
+ (t) =>
+ t.address.toLowerCase() === b.tokenAddress.toLowerCase() &&
+ t.chainId === b.chainId,
+ ),
+ balance: b.value,
+ originAmount: 0n,
+ }))
+ .filter((t) => !!t.originToken) as OwnedTokenWithQuote[];
+
+ owned = [...owned, ...tokensWithBalance];
+ page += 1;
+ }
+
+ const requiredDollarAmount =
+ Number.parseFloat(destinationAmount) * destinationToken.priceUsd;
+
+ // sort by dollar balance descending
+ owned.sort((a, b) => {
+ const aDollarBalance =
+ Number.parseFloat(toTokens(a.balance, a.originToken.decimals)) *
+ a.originToken.priceUsd;
+ const bDollarBalance =
+ Number.parseFloat(toTokens(b.balance, b.originToken.decimals)) *
+ b.originToken.priceUsd;
+ return bDollarBalance - aDollarBalance;
+ });
+
+ const suitableOriginTokens: OwnedTokenWithQuote[] = [];
+
+ for (const b of owned) {
+ if (b.originToken && b.balance > 0n) {
+ const dollarBalance =
+ Number.parseFloat(toTokens(b.balance, b.originToken.decimals)) *
+ b.originToken.priceUsd;
+ if (b.originToken.priceUsd && dollarBalance < requiredDollarAmount) {
+ continue;
+ }
+
+ if (
+ includeDestinationToken &&
+ b.originToken.address.toLowerCase() ===
+ destinationToken.address.toLowerCase() &&
+ b.originToken.chainId === destinationToken.chainId
+ ) {
+ // add same token to the front of the list
+ suitableOriginTokens.unshift({
+ balance: b.balance,
+ originAmount: 0n,
+ originToken: b.originToken,
+ });
+ continue;
+ }
+
+ suitableOriginTokens.push({
+ balance: b.balance,
+ originAmount: 0n,
+ originToken: b.originToken,
+ });
+ }
+ }
+
+ const transformedRoutes = [
+ ...suitableOriginTokens.map((s) => ({
+ type: "wallet" as const,
+ payerWallet: wallet,
+ originToken: s.originToken,
+ balance: s.balance,
+ })),
+ ];
+ return transformedRoutes;
+ },
+ staleTime: 5 * 60 * 1000, // 5 minutes
+ refetchOnWindowFocus: false,
+ enabled: !!wallet,
+ });
+
+ return {
+ data: routesQuery.data || [],
+ isLoading: routesQuery.isLoading,
+ error: routesQuery.error,
+ isError: routesQuery.isError,
+ isSuccess: routesQuery.isSuccess,
+ refetch: routesQuery.refetch,
+ };
+}
diff --git a/packages/thirdweb/src/react/core/hooks/useStepExecutor.ts b/packages/thirdweb/src/react/core/hooks/useStepExecutor.ts
new file mode 100644
index 00000000000..fe6e1825cc0
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useStepExecutor.ts
@@ -0,0 +1,606 @@
+import { useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { status as OnrampStatus } from "../../../bridge/OnrampStatus.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import type {
+ RouteStep,
+ RouteTransaction,
+} from "../../../bridge/types/Route.js";
+import type { Status } from "../../../bridge/types/Status.js";
+import { getCachedChain } from "../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { waitForReceipt } from "../../../transaction/actions/wait-for-tx-receipt.js";
+import { stringify } from "../../../utils/json.js";
+import type { Account, Wallet } from "../../../wallets/interfaces/wallet.js";
+import type { WindowAdapter } from "../adapters/WindowAdapter.js";
+import {
+ type BridgePrepareRequest,
+ type BridgePrepareResult,
+ useBridgePrepare,
+} from "./useBridgePrepare.js";
+
+/**
+ * Type for completed status results from Bridge.status and Onramp.status
+ */
+export type CompletedStatusResult =
+ | ({ type: "buy" } & Extract)
+ | ({ type: "sell" } & Extract)
+ | ({ type: "transfer" } & Extract)
+ | ({ type: "onramp" } & Extract<
+ OnrampStatus.Result,
+ { status: "COMPLETED" }
+ >);
+
+/**
+ * Options for the step executor hook
+ */
+interface StepExecutorOptions {
+ /** Prepared quote returned by Bridge.prepare */
+ request: BridgePrepareRequest;
+ /** Wallet instance providing getAccount() & sendTransaction */
+ wallet: Wallet;
+ /** Window adapter for opening on-ramp URLs (web / RN) */
+ windowAdapter: WindowAdapter;
+ /** Thirdweb client for API calls */
+ client: ThirdwebClient;
+ /** Auto start execution as soon as hook mounts */
+ autoStart?: boolean;
+ /** Callback when all steps complete successfully - receives array of all completed status results */
+ onComplete?: (completedStatuses: CompletedStatusResult[]) => void;
+}
+
+/**
+ * Internal flattened transaction type
+ */
+interface FlattenedTx extends RouteTransaction {
+ /** Index in flat array */
+ _index: number;
+ /** Parent step index */
+ _stepIndex: number;
+}
+
+/**
+ * Public return type of useStepExecutor
+ */
+interface StepExecutorResult {
+ currentStep?: RouteStep;
+ currentTxIndex?: number;
+ progress: number; // 0–100
+ onrampStatus?: "pending" | "executing" | "completed" | "failed";
+ executionState: "fetching" | "idle" | "executing" | "auto-starting";
+ steps?: RouteStep[];
+ error?: ApiError;
+ start: () => void;
+ cancel: () => void;
+ retry: () => void;
+}
+
+/**
+ * Flatten RouteStep[] into a linear list of transactions preserving ordering & indices.
+ */
+function flattenRouteSteps(steps: RouteStep[]): FlattenedTx[] {
+ const out: FlattenedTx[] = [];
+ steps.forEach((step, stepIdx) => {
+ step.transactions?.forEach((tx, _txIdx) => {
+ out.push({
+ ...(tx as RouteTransaction),
+ _index: out.length,
+ _stepIndex: stepIdx,
+ });
+ });
+ });
+ return out;
+}
+
+/**
+ * Hook that sequentially executes prepared steps.
+ * NOTE: initial implementation only exposes progress + basic state machine. Actual execution logic will follow in later subtasks.
+ */
+export function useStepExecutor(
+ options: StepExecutorOptions,
+): StepExecutorResult {
+ const {
+ request,
+ wallet,
+ windowAdapter,
+ client,
+ autoStart = false,
+ onComplete,
+ } = options;
+
+ const { data: preparedQuote, isLoading } = useBridgePrepare(request);
+
+ // Flatten all transactions upfront
+ const flatTxs = useMemo(
+ () => (preparedQuote?.steps ? flattenRouteSteps(preparedQuote.steps) : []),
+ [preparedQuote?.steps],
+ );
+
+ // State management
+ const [currentTxIndex, setCurrentTxIndex] = useState(
+ undefined,
+ );
+ const [executionState, setExecutionState] = useState<
+ "fetching" | "idle" | "executing" | "auto-starting"
+ >("idle");
+ const [error, setError] = useState(undefined);
+ const [completedTxs, setCompletedTxs] = useState>(new Set());
+ const [onrampStatus, setOnrampStatus] = useState<
+ "pending" | "executing" | "completed" | "failed" | undefined
+ >(preparedQuote?.type === "onramp" ? "pending" : undefined);
+
+ useQuery({
+ queryKey: [
+ "bridge-quote-execution-state",
+ stringify(preparedQuote?.steps),
+ isLoading,
+ ],
+ queryFn: async () => {
+ if (!isLoading) {
+ setExecutionState("idle");
+ } else {
+ setExecutionState("fetching");
+ }
+ return executionState;
+ },
+ });
+
+ // Cancellation tracking
+ const abortControllerRef = useRef(null);
+
+ // Get current step based on current tx index
+ const currentStep = useMemo(() => {
+ if (typeof preparedQuote?.steps === "undefined") return undefined;
+ if (currentTxIndex === undefined) {
+ return undefined;
+ }
+ const tx = flatTxs[currentTxIndex];
+ return tx ? preparedQuote.steps[tx._stepIndex] : undefined;
+ }, [currentTxIndex, flatTxs, preparedQuote?.steps]);
+
+ // Calculate progress including onramp step
+ const progress = useMemo(() => {
+ if (typeof preparedQuote?.type === "undefined") return 0;
+ const totalSteps =
+ flatTxs.length + (preparedQuote.type === "onramp" ? 1 : 0);
+ if (totalSteps === 0) {
+ return 0;
+ }
+ const completedSteps =
+ completedTxs.size + (onrampStatus === "completed" ? 1 : 0);
+ return Math.round((completedSteps / totalSteps) * 100);
+ }, [completedTxs.size, flatTxs.length, preparedQuote?.type, onrampStatus]);
+
+ // Exponential backoff polling utility
+ const poller = useCallback(
+ async (
+ pollFn: () => Promise<{
+ completed: boolean;
+ }>,
+ abortSignal: AbortSignal,
+ ) => {
+ const delay = 2000; // 2 second poll interval
+
+ while (!abortSignal.aborted) {
+ const result = await pollFn();
+ if (result.completed) {
+ return;
+ }
+
+ await new Promise((resolve) => {
+ const timeout = setTimeout(resolve, delay);
+ abortSignal.addEventListener("abort", () => clearTimeout(timeout), {
+ once: true,
+ });
+ });
+ }
+
+ throw new Error("Polling aborted");
+ },
+ [],
+ );
+
+ // Execute a single transaction
+ const executeSingleTx = useCallback(
+ async (
+ tx: FlattenedTx,
+ account: Account,
+ completedStatusResults: CompletedStatusResult[],
+ abortSignal: AbortSignal,
+ ) => {
+ if (typeof preparedQuote?.type === "undefined") {
+ throw new Error("No quote generated. This is unexpected.");
+ }
+ const { prepareTransaction } = await import(
+ "../../../transaction/prepare-transaction.js"
+ );
+ const { sendTransaction } = await import(
+ "../../../transaction/actions/send-transaction.js"
+ );
+
+ // Prepare the transaction
+ const preparedTx = prepareTransaction({
+ chain: tx.chain,
+ client: tx.client,
+ to: tx.to,
+ data: tx.data,
+ value: tx.value,
+ });
+
+ // Send the transaction
+ const result = await sendTransaction({
+ account,
+ transaction: preparedTx,
+ });
+ const hash = result.transactionHash;
+
+ if (tx.action === "approval" || tx.action === "fee") {
+ // don't poll status for approval transactions, just wait for confirmation
+ await waitForReceipt(result);
+ return;
+ }
+
+ // Poll for completion
+ const { status } = await import("../../../bridge/Status.js");
+ await poller(async () => {
+ const statusResult = await status({
+ transactionHash: hash,
+ chainId: tx.chainId,
+ client: tx.client,
+ });
+
+ if (statusResult.status === "COMPLETED") {
+ // Add type field from preparedQuote for discriminated union
+ const typedStatusResult = {
+ type: preparedQuote.type,
+ ...statusResult,
+ };
+ completedStatusResults.push(typedStatusResult);
+ return { completed: true };
+ }
+
+ if (statusResult.status === "FAILED") {
+ throw new Error("Payment failed");
+ }
+
+ return { completed: false };
+ }, abortSignal);
+ },
+ [poller, preparedQuote?.type],
+ );
+
+ // Execute batch transactions
+ const executeBatch = useCallback(
+ async (
+ txs: FlattenedTx[],
+ account: Account,
+ completedStatusResults: CompletedStatusResult[],
+ abortSignal: AbortSignal,
+ ) => {
+ if (typeof preparedQuote?.type === "undefined") {
+ throw new Error("No quote generated. This is unexpected.");
+ }
+ if (!account.sendBatchTransaction) {
+ throw new Error("Account does not support batch transactions");
+ }
+
+ const { prepareTransaction } = await import(
+ "../../../transaction/prepare-transaction.js"
+ );
+ const { sendBatchTransaction } = await import(
+ "../../../transaction/actions/send-batch-transaction.js"
+ );
+
+ // Prepare and convert all transactions
+ const serializableTxs = await Promise.all(
+ txs.map(async (tx) => {
+ const preparedTx = prepareTransaction({
+ chain: tx.chain,
+ client: tx.client,
+ to: tx.to,
+ data: tx.data,
+ value: tx.value,
+ });
+ return preparedTx;
+ }),
+ );
+
+ // Send batch
+ const result = await sendBatchTransaction({
+ account,
+ transactions: serializableTxs,
+ });
+ // Batch transactions return a single receipt, we need to handle this differently
+ // For now, we'll assume all transactions in the batch succeed together
+
+ // Poll for the first transaction's completion (representative of the batch)
+ if (txs.length === 0) {
+ throw new Error("No transactions to batch");
+ }
+ const firstTx = txs[0];
+ if (!firstTx) {
+ throw new Error("Invalid batch transaction");
+ }
+
+ const { status } = await import("../../../bridge/Status.js");
+ await poller(async () => {
+ const statusResult = await status({
+ transactionHash: result.transactionHash,
+ chainId: firstTx.chainId,
+ client: firstTx.client,
+ });
+
+ if (statusResult.status === "COMPLETED") {
+ // Add type field from preparedQuote for discriminated union
+ const typedStatusResult = {
+ type: preparedQuote.type,
+ ...statusResult,
+ };
+ completedStatusResults.push(typedStatusResult);
+ return { completed: true };
+ }
+
+ if (statusResult.status === "FAILED") {
+ throw new Error("Payment failed");
+ }
+
+ return { completed: false };
+ }, abortSignal);
+ },
+ [poller, preparedQuote?.type],
+ );
+
+ // Execute onramp step
+ const executeOnramp = useCallback(
+ async (
+ onrampQuote: Extract,
+ completedStatusResults: CompletedStatusResult[],
+ abortSignal: AbortSignal,
+ ) => {
+ setOnrampStatus("executing");
+ // Open the payment URL
+ windowAdapter.open(onrampQuote.link);
+
+ // Poll for completion using the session ID
+ const { Onramp } = await import("../../../bridge/index.js");
+ await poller(async () => {
+ const statusResult = await Onramp.status({
+ id: onrampQuote.id,
+ client: client,
+ });
+
+ const status = statusResult.status;
+ if (status === "COMPLETED") {
+ setOnrampStatus("completed");
+ // Add type field for discriminated union
+ const typedStatusResult = {
+ type: "onramp" as const,
+ ...statusResult,
+ };
+ completedStatusResults.push(typedStatusResult);
+ return { completed: true };
+ } else if (status === "FAILED") {
+ setOnrampStatus("failed");
+ }
+
+ return { completed: false };
+ }, abortSignal);
+ },
+ [poller, client, windowAdapter],
+ );
+
+ // Main execution function
+ const execute = useCallback(async () => {
+ if (typeof preparedQuote?.type === "undefined") {
+ throw new Error("No quote generated. This is unexpected.");
+ }
+ if (executionState !== "idle") {
+ return;
+ }
+
+ setExecutionState("executing");
+ setError(undefined);
+ const completedStatusResults: CompletedStatusResult[] = [];
+
+ // Create new abort controller
+ const abortController = new AbortController();
+ abortControllerRef.current = abortController;
+
+ try {
+ // Execute onramp first if configured and not already completed
+ if (preparedQuote.type === "onramp" && onrampStatus === "pending") {
+ await executeOnramp(
+ preparedQuote,
+ completedStatusResults,
+ abortController.signal,
+ );
+ }
+
+ // Then execute transactions
+ const account = wallet.getAccount();
+ if (!account) {
+ throw new ApiError({
+ code: "INVALID_INPUT",
+ message: "Wallet not connected",
+ statusCode: 400,
+ });
+ }
+
+ // Start from where we left off, or from the beginning
+ const startIndex = currentTxIndex ?? 0;
+
+ for (let i = startIndex; i < flatTxs.length; i++) {
+ if (abortController.signal.aborted) {
+ break;
+ }
+
+ const currentTx = flatTxs[i];
+ if (!currentTx) {
+ continue; // Skip invalid index
+ }
+
+ setCurrentTxIndex(i);
+ const currentStepData = preparedQuote.steps[currentTx._stepIndex];
+ if (!currentStepData) {
+ throw new Error(`Invalid step index: ${currentTx._stepIndex}`);
+ }
+
+ // switch chain if needed
+ if (currentTx.chainId !== wallet.getChain()?.id) {
+ await wallet.switchChain(getCachedChain(currentTx.chainId));
+ }
+
+ // Check if we can batch transactions
+ const canBatch =
+ account.sendBatchTransaction !== undefined && i < flatTxs.length - 1; // Not the last transaction
+
+ if (canBatch) {
+ // Find consecutive transactions on the same chain
+ const batchTxs: FlattenedTx[] = [currentTx];
+ let j = i + 1;
+ while (j < flatTxs.length) {
+ const nextTx = flatTxs[j];
+ if (!nextTx || nextTx.chainId !== currentTx.chainId) {
+ break;
+ }
+ batchTxs.push(nextTx);
+ j++;
+ }
+
+ // Execute batch if we have multiple transactions
+ if (batchTxs.length > 1) {
+ await executeBatch(
+ batchTxs,
+ account,
+ completedStatusResults,
+ abortController.signal,
+ );
+
+ // Mark all batched transactions as completed
+ for (const tx of batchTxs) {
+ setCompletedTxs((prev) => new Set(prev).add(tx._index));
+ }
+
+ // Skip ahead
+ i = j - 1;
+ continue;
+ }
+ }
+
+ // Execute single transaction
+ await executeSingleTx(
+ currentTx,
+ account,
+ completedStatusResults,
+ abortController.signal,
+ );
+
+ // Mark transaction as completed
+ setCompletedTxs((prev) => new Set(prev).add(currentTx._index));
+ }
+
+ // All done - check if we actually completed everything
+ if (!abortController.signal.aborted) {
+ setCurrentTxIndex(undefined);
+
+ // Call completion callback with all completed status results
+ if (onComplete) {
+ onComplete(completedStatusResults);
+ }
+ }
+ } catch (err) {
+ console.error("Error executing payment", err);
+ if (err instanceof ApiError) {
+ setError(err);
+ } else {
+ setError(
+ new ApiError({
+ code: "UNKNOWN_ERROR",
+ message: (err as Error)?.message || "An unknown error occurred",
+ statusCode: 500,
+ }),
+ );
+ }
+ } finally {
+ setExecutionState("idle");
+ abortControllerRef.current = null;
+ }
+ }, [
+ executionState,
+ wallet,
+ currentTxIndex,
+ flatTxs,
+ executeSingleTx,
+ executeBatch,
+ onrampStatus,
+ executeOnramp,
+ onComplete,
+ preparedQuote,
+ ]);
+
+ // Start execution
+ const start = useCallback(() => {
+ if (executionState === "idle") {
+ execute();
+ }
+ }, [execute, executionState]);
+
+ // Cancel execution
+ const cancel = useCallback(() => {
+ if (abortControllerRef.current) {
+ abortControllerRef.current.abort();
+ }
+ setExecutionState("idle");
+ if (onrampStatus === "executing") {
+ setOnrampStatus("pending");
+ }
+ }, [onrampStatus]);
+
+ // Retry from failed transaction
+ const retry = useCallback(() => {
+ if (error) {
+ setError(undefined);
+ execute();
+ }
+ }, [error, execute]);
+
+ const hasInitialized = useRef(false);
+
+ useEffect(() => {
+ if (
+ autoStart &&
+ executionState === "idle" &&
+ currentTxIndex === undefined &&
+ !hasInitialized.current
+ ) {
+ hasInitialized.current = true;
+ setExecutionState("auto-starting");
+ // add a delay to ensure the UI is ready
+ setTimeout(() => {
+ start();
+ }, 500);
+ }
+ }, [autoStart, executionState, currentTxIndex, start]);
+
+ // Cleanup on unmount
+ useEffect(() => {
+ return () => {
+ if (abortControllerRef.current) {
+ abortControllerRef.current.abort();
+ }
+ };
+ }, []);
+
+ return {
+ currentStep,
+ currentTxIndex,
+ progress,
+ executionState,
+ steps: preparedQuote?.steps,
+ onrampStatus,
+ error,
+ start,
+ cancel,
+ retry,
+ };
+}
diff --git a/packages/thirdweb/src/react/core/hooks/useTransactionDetails.ts b/packages/thirdweb/src/react/core/hooks/useTransactionDetails.ts
new file mode 100644
index 00000000000..a6c79f48a48
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useTransactionDetails.ts
@@ -0,0 +1,177 @@
+import { useQuery } from "@tanstack/react-query";
+import type { AbiFunction } from "abitype";
+import { toFunctionSelector } from "viem";
+import type { Token } from "../../../bridge/index.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../constants/addresses.js";
+import type { CompilerMetadata } from "../../../contract/actions/compiler-metadata.js";
+import { getCompilerMetadata } from "../../../contract/actions/get-compiler-metadata.js";
+import { getContract } from "../../../contract/contract.js";
+import { decimals } from "../../../extensions/erc20/read/decimals.js";
+import { getToken } from "../../../pay/convert/get-token.js";
+import { encode } from "../../../transaction/actions/encode.js";
+import type { PreparedTransaction } from "../../../transaction/prepare-transaction.js";
+import { getTransactionGasCost } from "../../../transaction/utils.js";
+import { resolvePromisedValue } from "../../../utils/promise/resolve-promised-value.js";
+import { toTokens } from "../../../utils/units.js";
+import {
+ formatCurrencyAmount,
+ formatTokenAmount,
+} from "../../web/ui/ConnectWallet/screens/formatTokenBalance.js";
+import { useChainMetadata } from "./others/useChainQuery.js";
+
+interface TransactionDetails {
+ contractMetadata: CompilerMetadata | null;
+ functionInfo: {
+ functionName: string;
+ selector: string;
+ description?: string;
+ };
+ usdValueDisplay: string | null;
+ txCostDisplay: string;
+ gasCostDisplay: string | null;
+ tokenInfo: Token | null;
+ costWei: bigint;
+ gasCostWei: bigint | null;
+ totalCost: string;
+ totalCostWei: bigint;
+}
+
+interface UseTransactionDetailsOptions {
+ transaction: PreparedTransaction;
+ client: ThirdwebClient;
+}
+
+/**
+ * Hook to fetch comprehensive transaction details including contract metadata,
+ * function information, cost calculations, and gas estimates.
+ */
+export function useTransactionDetails({
+ transaction,
+ client,
+}: UseTransactionDetailsOptions) {
+ const chainMetadata = useChainMetadata(transaction.chain);
+
+ return useQuery({
+ queryKey: [
+ "transaction-details",
+ transaction.to,
+ transaction.chain.id,
+ transaction.erc20Value,
+ ],
+ queryFn: async (): Promise => {
+ // Create contract instance for metadata fetching
+ const contract = getContract({
+ client,
+ chain: transaction.chain,
+ address: transaction.to as string,
+ });
+
+ const [contractMetadata, value, erc20Value, transactionData] =
+ await Promise.all([
+ getCompilerMetadata(contract).catch(() => null),
+ resolvePromisedValue(transaction.value),
+ resolvePromisedValue(transaction.erc20Value),
+ encode(transaction).catch(() => "0x"),
+ ]);
+
+ const [tokenInfo, gasCostWei] = await Promise.all([
+ getToken(
+ client,
+ erc20Value ? erc20Value.tokenAddress : NATIVE_TOKEN_ADDRESS,
+ transaction.chain.id,
+ ).catch(() => null),
+ getTransactionGasCost(transaction).catch(() => null),
+ ]);
+
+ // Process function info from ABI if available
+ let functionInfo = {
+ functionName: "Contract Call",
+ selector: "0x",
+ description: undefined,
+ };
+
+ if (contractMetadata?.abi && transactionData.length >= 10) {
+ try {
+ const selector = transactionData.slice(0, 10) as `0x${string}`;
+ const abi = contractMetadata.abi;
+
+ // Find matching function in ABI
+ const abiItems = Array.isArray(abi) ? abi : [];
+ const functions = abiItems
+ .filter(
+ (item) =>
+ item &&
+ typeof item === "object" &&
+ "type" in item &&
+ (item as { type: string }).type === "function",
+ )
+ .map((item) => item as AbiFunction);
+
+ const matchingFunction = functions.find((fn) => {
+ return toFunctionSelector(fn) === selector;
+ });
+
+ if (matchingFunction) {
+ functionInfo = {
+ functionName: matchingFunction.name,
+ selector,
+ description: undefined, // Skip devdoc for now
+ };
+ }
+ } catch {
+ // Keep default values
+ }
+ }
+
+ const resolveDecimals = async () => {
+ if (tokenInfo) {
+ return tokenInfo.decimals;
+ }
+ if (erc20Value) {
+ return decimals({
+ contract: getContract({
+ client,
+ chain: transaction.chain,
+ address: erc20Value.tokenAddress,
+ }),
+ });
+ }
+ return 18;
+ };
+
+ const decimal = await resolveDecimals();
+ const costWei = erc20Value ? erc20Value.amountWei : value || 0n;
+ const nativeTokenSymbol =
+ chainMetadata.data?.nativeCurrency?.symbol || "ETH";
+ const tokenSymbol = tokenInfo?.symbol || nativeTokenSymbol;
+
+ const totalCostWei = erc20Value
+ ? erc20Value.amountWei
+ : (value || 0n) + (gasCostWei || 0n);
+ const totalCost = toTokens(totalCostWei, decimal);
+
+ const usdValue = tokenInfo?.priceUsd
+ ? Number(totalCost) * tokenInfo.priceUsd
+ : null;
+
+ return {
+ contractMetadata,
+ functionInfo,
+ usdValueDisplay: usdValue
+ ? formatCurrencyAmount("USD", usdValue)
+ : null,
+ txCostDisplay: `${formatTokenAmount(costWei, decimal)} ${tokenSymbol}`,
+ gasCostDisplay: gasCostWei
+ ? `${formatTokenAmount(gasCostWei, 18)} ${nativeTokenSymbol}`
+ : null,
+ tokenInfo,
+ costWei,
+ gasCostWei,
+ totalCost,
+ totalCostWei,
+ };
+ },
+ enabled: !!transaction.to && !!chainMetadata.data,
+ });
+}
diff --git a/packages/thirdweb/src/react/core/hooks/wallets/useAutoConnectCore.test.tsx b/packages/thirdweb/src/react/core/hooks/wallets/useAutoConnectCore.test.tsx
index 5cb10c093b6..be98b304186 100644
--- a/packages/thirdweb/src/react/core/hooks/wallets/useAutoConnectCore.test.tsx
+++ b/packages/thirdweb/src/react/core/hooks/wallets/useAutoConnectCore.test.tsx
@@ -1,6 +1,6 @@
import { renderHook, waitFor } from "@testing-library/react";
import type { ReactNode } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
import { MockStorage } from "~test/mocks/storage.js";
import { TEST_CLIENT } from "~test/test-clients.js";
import { TEST_ACCOUNT_A } from "~test/test-wallets.js";
@@ -98,60 +98,4 @@ describe("useAutoConnectCore", () => {
{ timeout: 1000 },
);
});
-
- it("should call onTimeout on ... timeout", async () => {
- const wallet = createWalletAdapter({
- adaptedAccount: TEST_ACCOUNT_A,
- client: TEST_CLIENT,
- chain: ethereum,
- onDisconnect: () => {},
- switchChain: () => {},
- });
- mockStorage.setItem("thirdweb:active-wallet-id", wallet.id);
- const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
- const infoSpy = vi.spyOn(console, "info").mockImplementation(() => {});
- // Purposefully mock the wallet.autoConnect method to test the timeout logic
- wallet.autoConnect = () =>
- new Promise((resolve) => {
- setTimeout(() => {
- // @ts-ignore Mock purpose
- resolve("Connection successful");
- }, 2100);
- });
- renderHook(
- () =>
- useAutoConnectCore(
- mockStorage,
- {
- wallets: [wallet],
- client: TEST_CLIENT,
- onTimeout: () => console.info("TIMEOUTTED"),
- timeout: 0,
- },
- (id: WalletId) =>
- createWalletAdapter({
- adaptedAccount: TEST_ACCOUNT_A,
- client: TEST_CLIENT,
- chain: ethereum,
- onDisconnect: () => {
- console.warn(id);
- },
- switchChain: () => {},
- }),
- ),
- { wrapper },
- );
- await waitFor(
- () => {
- expect(warnSpy).toHaveBeenCalled();
- expect(warnSpy).toHaveBeenCalledWith(
- "AutoConnect timeout: 0ms limit exceeded.",
- );
- expect(infoSpy).toHaveBeenCalled();
- expect(infoSpy).toHaveBeenCalledWith("TIMEOUTTED");
- warnSpy.mockRestore();
- },
- { timeout: 2000 },
- );
- });
});
diff --git a/packages/thirdweb/src/react/core/machines/.keep b/packages/thirdweb/src/react/core/machines/.keep
new file mode 100644
index 00000000000..f5a7aa3fffa
--- /dev/null
+++ b/packages/thirdweb/src/react/core/machines/.keep
@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain XState machine definitions for payment flows
\ No newline at end of file
diff --git a/packages/thirdweb/src/react/core/machines/paymentMachine.test.ts b/packages/thirdweb/src/react/core/machines/paymentMachine.test.ts
new file mode 100644
index 00000000000..f720770eaa6
--- /dev/null
+++ b/packages/thirdweb/src/react/core/machines/paymentMachine.test.ts
@@ -0,0 +1,691 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { act, renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { TEST_CLIENT } from "../../../../test/src/test-clients.js";
+import { TEST_IN_APP_WALLET_A } from "../../../../test/src/test-wallets.js";
+import type { Token } from "../../../bridge/types/Token.js";
+import { defineChain } from "../../../chains/utils.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../constants/addresses.js";
+import type { AsyncStorage } from "../../../utils/storage/AsyncStorage.js";
+import type { WindowAdapter } from "../adapters/WindowAdapter.js";
+import type { BridgePrepareResult } from "../hooks/useBridgePrepare.js";
+import {
+ type PaymentMachineContext,
+ type PaymentMethod,
+ usePaymentMachine,
+} from "./paymentMachine.js";
+
+// Mock adapters
+const mockWindowAdapter: WindowAdapter = {
+ open: vi.fn().mockResolvedValue(undefined),
+};
+
+const mockStorage: AsyncStorage = {
+ getItem: vi.fn().mockResolvedValue(null),
+ setItem: vi.fn().mockResolvedValue(undefined),
+ removeItem: vi.fn().mockResolvedValue(undefined),
+};
+
+// Test token objects
+const testUSDCToken: Token = {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+};
+
+const testETHToken: Token = {
+ chainId: 1,
+ address: NATIVE_TOKEN_ADDRESS,
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+};
+
+const testTokenForPayment: Token = {
+ chainId: 1,
+ address: "0xA0b86a33E6425c03e54c4b45DCb6d75b6B72E2AA",
+ name: "Test Token",
+ symbol: "TT",
+ decimals: 18,
+ priceUsd: 1.0,
+};
+
+const mockBuyQuote: BridgePrepareResult = {
+ type: "buy",
+ originAmount: 1000000000000000000n, // 1 ETH
+ destinationAmount: 100000000n, // 100 USDC
+ timestamp: Date.now(),
+ estimatedExecutionTimeMs: 120000, // 2 minutes
+ steps: [
+ {
+ originToken: testETHToken,
+ destinationToken: testUSDCToken,
+ originAmount: 1000000000000000000n,
+ destinationAmount: 100000000n,
+ estimatedExecutionTimeMs: 120000,
+ transactions: [
+ {
+ action: "approval" as const,
+ id: "0x123" as const,
+ to: "0x456" as const,
+ data: "0x789" as const,
+ chainId: 1,
+ client: TEST_CLIENT,
+ chain: defineChain(1),
+ },
+ {
+ action: "buy" as const,
+ id: "0xabc" as const,
+ to: "0xdef" as const,
+ data: "0x012" as const,
+ value: 1000000000000000000n,
+ chainId: 1,
+ client: TEST_CLIENT,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ ],
+ intent: {
+ originChainId: 1,
+ originTokenAddress: NATIVE_TOKEN_ADDRESS,
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 100000000n,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ },
+};
+
+describe("PaymentMachine", () => {
+ let adapters: PaymentMachineContext["adapters"];
+
+ beforeEach(() => {
+ adapters = {
+ window: mockWindowAdapter,
+ storage: mockStorage,
+ };
+ });
+
+ it("should initialize in init state", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+ const [state] = result.current;
+
+ expect(state.value).toBe("init");
+ expect(state.context.mode).toBe("fund_wallet");
+ expect(state.context.adapters).toBe(adapters);
+ });
+
+ it("should transition through happy path with wallet payment method", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Confirm destination
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("methodSelection");
+ expect(state.context.destinationToken).toEqual(testTokenForPayment);
+ expect(state.context.destinationAmount).toBe("100");
+ expect(state.context.receiverAddress).toBe(
+ "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ );
+
+ // Select wallet payment method
+ const walletPaymentMethod: PaymentMethod = {
+ type: "wallet",
+ originToken: testUSDCToken,
+ payerWallet: TEST_IN_APP_WALLET_A,
+ balance: 1000000000000000000n,
+ };
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: walletPaymentMethod,
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("quote");
+ expect(state.context.selectedPaymentMethod).toEqual(walletPaymentMethod);
+
+ // Receive quote
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "QUOTE_RECEIVED",
+ preparedQuote: mockBuyQuote,
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("preview");
+ expect(state.context.preparedQuote).toBe(mockBuyQuote);
+
+ // Confirm route
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ROUTE_CONFIRMED",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("execute");
+ expect(state.context.selectedPaymentMethod).toBe(walletPaymentMethod);
+
+ // Complete execution
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "EXECUTION_COMPLETE",
+ completedStatuses: [
+ {
+ type: "buy",
+ status: "COMPLETED",
+ paymentId: "test-payment-id",
+ originAmount: 1000000000000000000n,
+ destinationAmount: 100000000n,
+ originChainId: 1,
+ destinationChainId: 137,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationTokenAddress:
+ "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ originToken: testETHToken,
+ destinationToken: testUSDCToken,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ transactions: [
+ {
+ chainId: 1,
+ transactionHash: "0xtest123",
+ },
+ ],
+ },
+ ],
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("success");
+ expect(state.context.completedStatuses).toBeDefined();
+ expect(state.context.completedStatuses).toHaveLength(1);
+ expect(state.context.completedStatuses?.[0]?.status).toBe("COMPLETED");
+ });
+
+ it("should handle errors and allow retry", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ const testError = new Error("Network error");
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ERROR_OCCURRED",
+ error: testError,
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("error");
+ expect(state.context.currentError).toBe(testError);
+ expect(state.context.retryState).toBe("init");
+
+ // Retry should clear error and return to beginning
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "RETRY",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("init");
+ expect(state.context.currentError).toBeUndefined();
+ expect(state.context.retryState).toBeUndefined();
+ });
+
+ it("should preserve context data through transitions", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ const testToken: Token = {
+ chainId: 42,
+ address: "0xtest",
+ name: "Test Token",
+ symbol: "TEST",
+ decimals: 18,
+ priceUsd: 1.0,
+ };
+
+ // Confirm destination
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testToken,
+ destinationAmount: "50",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ // Select payment method
+ const paymentMethod: PaymentMethod = {
+ type: "wallet",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ originToken: testUSDCToken,
+ balance: 1000000000000000000n,
+ };
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod,
+ });
+ });
+
+ const [state] = result.current;
+ // All context should be preserved
+ expect(state.context.destinationToken).toEqual(testToken);
+ expect(state.context.destinationAmount).toBe("50");
+ expect(state.context.selectedPaymentMethod).toEqual(paymentMethod);
+ expect(state.context.mode).toBe("fund_wallet");
+ expect(state.context.adapters).toBe(adapters);
+ });
+
+ it("should handle state transitions correctly", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ const [initialState] = result.current;
+ expect(initialState.value).toBe("init");
+
+ // Only DESTINATION_CONFIRMED should be valid from initial state
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "fiat",
+ currency: "USD",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ onramp: "stripe",
+ },
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("init"); // Should stay in same state for invalid transition
+
+ // Valid transition
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("methodSelection");
+ });
+
+ it("should reset to initial state", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Go through some states
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "fiat",
+ currency: "USD",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ onramp: "stripe",
+ },
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("quote");
+
+ // Trigger error
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ERROR_OCCURRED",
+ error: new Error("Test error"),
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("error");
+
+ // Reset
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "RESET",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("init");
+ // Context should still have adapters and mode but other data should be cleared
+ expect(state.context.adapters).toBe(adapters);
+ expect(state.context.mode).toBe("fund_wallet");
+ });
+
+ it("should handle error states from all major states", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Test error from init
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ERROR_OCCURRED",
+ error: new Error("Init error"),
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("error");
+ expect(state.context.retryState).toBe("init");
+
+ // Reset and test error from methodSelection
+ act(() => {
+ const [, send] = result.current;
+ send({ type: "RESET" });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ERROR_OCCURRED",
+ error: new Error("Method selection error"),
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("error");
+ expect(state.context.retryState).toBe("methodSelection");
+ });
+
+ it("should handle back navigation", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Go to methodSelection
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ // Go to quote
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "fiat",
+ currency: "USD",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ onramp: "stripe",
+ },
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("quote");
+
+ // Navigate back to methodSelection
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "BACK",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("methodSelection");
+
+ // Navigate back to init
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "BACK",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("init");
+ });
+
+ it("should clear prepared quote when payment method changes", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Go to methodSelection
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ // Select first payment method and get quote
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "fiat",
+ currency: "USD",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ onramp: "stripe",
+ },
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "QUOTE_RECEIVED",
+ preparedQuote: mockBuyQuote,
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.context.preparedQuote).toBe(mockBuyQuote);
+
+ // Go back and select different payment method
+ act(() => {
+ const [, send] = result.current;
+ send({ type: "BACK" });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "wallet",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ originToken: testUSDCToken,
+ balance: 1000000000000000000n,
+ },
+ });
+ });
+
+ [state] = result.current;
+ expect(state.context.preparedQuote).toBeUndefined(); // Should be cleared
+ });
+
+ it("should handle post-buy-transaction state flow", () => {
+ const { result } = renderHook(() =>
+ usePaymentMachine(adapters, "fund_wallet"),
+ );
+
+ // Go through the complete happy path to reach success state
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: testTokenForPayment,
+ destinationAmount: "100",
+ receiverAddress: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "PAYMENT_METHOD_SELECTED",
+ paymentMethod: {
+ type: "wallet",
+ payerWallet: TEST_IN_APP_WALLET_A,
+ originToken: testUSDCToken,
+ balance: 1000000000000000000n,
+ },
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "QUOTE_RECEIVED",
+ preparedQuote: mockBuyQuote,
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "ROUTE_CONFIRMED",
+ });
+ });
+
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "EXECUTION_COMPLETE",
+ completedStatuses: [
+ {
+ type: "buy",
+ status: "COMPLETED",
+ paymentId: "test-payment-id",
+ originAmount: 1000000000000000000n,
+ destinationAmount: 100000000n,
+ originChainId: 1,
+ destinationChainId: 137,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationTokenAddress:
+ "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ originToken: testETHToken,
+ destinationToken: testUSDCToken,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ transactions: [
+ {
+ chainId: 1,
+ transactionHash: "0xtest123",
+ },
+ ],
+ },
+ ],
+ });
+ });
+
+ let [state] = result.current;
+ expect(state.value).toBe("success");
+
+ // Continue to post-buy transaction
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "CONTINUE_TO_TRANSACTION",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("post-buy-transaction");
+
+ // Reset from post-buy-transaction should go back to init
+ act(() => {
+ const [, send] = result.current;
+ send({
+ type: "RESET",
+ });
+ });
+
+ [state] = result.current;
+ expect(state.value).toBe("init");
+ // Context should be reset to initial state with only adapters and mode
+ expect(state.context.adapters).toBe(adapters);
+ expect(state.context.mode).toBe("fund_wallet");
+ expect(state.context.destinationToken).toBeUndefined();
+ expect(state.context.selectedPaymentMethod).toBeUndefined();
+ expect(state.context.preparedQuote).toBeUndefined();
+ expect(state.context.completedStatuses).toBeUndefined();
+ });
+});
diff --git a/packages/thirdweb/src/react/core/machines/paymentMachine.ts b/packages/thirdweb/src/react/core/machines/paymentMachine.ts
new file mode 100644
index 00000000000..4f0b8fc35ef
--- /dev/null
+++ b/packages/thirdweb/src/react/core/machines/paymentMachine.ts
@@ -0,0 +1,290 @@
+import { useCallback, useState } from "react";
+import type { Token } from "../../../bridge/types/Token.js";
+import type { Address } from "../../../utils/address.js";
+import type { AsyncStorage } from "../../../utils/storage/AsyncStorage.js";
+import type { Wallet } from "../../../wallets/interfaces/wallet.js";
+import type { WindowAdapter } from "../adapters/WindowAdapter.js";
+import type {
+ BridgePrepareRequest,
+ BridgePrepareResult,
+} from "../hooks/useBridgePrepare.js";
+import type { CompletedStatusResult } from "../hooks/useStepExecutor.js";
+
+/**
+ * Payment modes supported by BridgeEmbed
+ */
+type PaymentMode = "fund_wallet" | "direct_payment" | "transaction";
+
+/**
+ * Payment method types with their required data
+ */
+export type PaymentMethod =
+ | {
+ type: "wallet";
+ payerWallet: Wallet;
+ originToken: Token;
+ balance: bigint;
+ }
+ | {
+ type: "fiat";
+ payerWallet: Wallet;
+ currency: string;
+ onramp: "stripe" | "coinbase" | "transak";
+ };
+
+/**
+ * Payment machine context - holds all flow state data
+ */
+export interface PaymentMachineContext {
+ // Flow configuration
+ mode: PaymentMode;
+
+ // Target requirements (resolved in init state)
+ destinationAmount?: string;
+ destinationToken?: Token;
+ receiverAddress?: Address;
+
+ // User selections (set in methodSelection state)
+ selectedPaymentMethod?: PaymentMethod;
+
+ // Prepared quote data (set in quote state)
+ quote?: BridgePrepareResult;
+ request?: BridgePrepareRequest;
+
+ // Execution results (set in execute state on completion)
+ completedStatuses?: CompletedStatusResult[];
+
+ // Error handling
+ currentError?: Error;
+ retryState?: PaymentMachineState; // State to retry from
+
+ // Dependency injection
+ adapters: {
+ window: WindowAdapter;
+ storage: AsyncStorage;
+ };
+}
+
+/**
+ * Events that can be sent to the payment machine
+ */
+type PaymentMachineEvent =
+ | {
+ type: "DESTINATION_CONFIRMED";
+ destinationToken: Token;
+ destinationAmount: string;
+ receiverAddress: Address;
+ }
+ | { type: "PAYMENT_METHOD_SELECTED"; paymentMethod: PaymentMethod }
+ | {
+ type: "QUOTE_RECEIVED";
+ quote: BridgePrepareResult;
+ request: BridgePrepareRequest;
+ }
+ | { type: "ROUTE_CONFIRMED" }
+ | { type: "EXECUTION_COMPLETE"; completedStatuses: CompletedStatusResult[] }
+ | { type: "ERROR_OCCURRED"; error: Error }
+ | { type: "CONTINUE_TO_TRANSACTION" }
+ | { type: "RETRY" }
+ | { type: "RESET" }
+ | { type: "BACK" };
+
+type PaymentMachineState =
+ | "init"
+ | "methodSelection"
+ | "quote"
+ | "preview"
+ | "execute"
+ | "success"
+ | "post-buy-transaction"
+ | "error";
+
+/**
+ * Hook to create and use the payment machine
+ */
+export function usePaymentMachine(
+ adapters: PaymentMachineContext["adapters"],
+ mode: PaymentMode = "fund_wallet",
+) {
+ const [currentState, setCurrentState] = useState("init");
+ const [context, setContext] = useState({
+ mode,
+ adapters,
+ });
+
+ const send = useCallback(
+ (event: PaymentMachineEvent) => {
+ setCurrentState((state) => {
+ setContext((ctx) => {
+ switch (state) {
+ case "init":
+ if (event.type === "DESTINATION_CONFIRMED") {
+ return {
+ ...ctx,
+ destinationToken: event.destinationToken,
+ destinationAmount: event.destinationAmount,
+ receiverAddress: event.receiverAddress,
+ };
+ } else if (event.type === "ERROR_OCCURRED") {
+ return {
+ ...ctx,
+ currentError: event.error,
+ retryState: "init",
+ };
+ }
+ break;
+
+ case "methodSelection":
+ if (event.type === "PAYMENT_METHOD_SELECTED") {
+ return {
+ ...ctx,
+ quote: undefined, // reset quote when method changes
+ selectedPaymentMethod: event.paymentMethod,
+ };
+ } else if (event.type === "ERROR_OCCURRED") {
+ return {
+ ...ctx,
+ currentError: event.error,
+ retryState: "methodSelection",
+ };
+ }
+ break;
+
+ case "quote":
+ if (event.type === "QUOTE_RECEIVED") {
+ return {
+ ...ctx,
+ quote: event.quote,
+ request: event.request,
+ };
+ } else if (event.type === "ERROR_OCCURRED") {
+ return {
+ ...ctx,
+ currentError: event.error,
+ retryState: "quote",
+ };
+ }
+ break;
+
+ case "preview":
+ if (event.type === "ERROR_OCCURRED") {
+ return {
+ ...ctx,
+ currentError: event.error,
+ retryState: "preview",
+ };
+ }
+ break;
+
+ case "execute":
+ if (event.type === "EXECUTION_COMPLETE") {
+ return {
+ ...ctx,
+ completedStatuses: event.completedStatuses,
+ };
+ } else if (event.type === "ERROR_OCCURRED") {
+ return {
+ ...ctx,
+ currentError: event.error,
+ retryState: "execute",
+ };
+ }
+ break;
+
+ case "error":
+ if (event.type === "RETRY" || event.type === "RESET") {
+ return {
+ ...ctx,
+ currentError: undefined,
+ retryState: undefined,
+ };
+ }
+ break;
+
+ case "success":
+ if (event.type === "RESET") {
+ return {
+ mode: ctx.mode,
+ adapters: ctx.adapters,
+ };
+ }
+ break;
+
+ case "post-buy-transaction":
+ if (event.type === "RESET") {
+ return {
+ mode: ctx.mode,
+ adapters: ctx.adapters,
+ };
+ }
+ break;
+ }
+ return ctx;
+ });
+
+ // State transitions
+ switch (state) {
+ case "init":
+ if (event.type === "DESTINATION_CONFIRMED")
+ return "methodSelection";
+ if (event.type === "ERROR_OCCURRED") return "error";
+ break;
+
+ case "methodSelection":
+ if (event.type === "PAYMENT_METHOD_SELECTED") return "quote";
+ if (event.type === "BACK") return "init";
+ if (event.type === "ERROR_OCCURRED") return "error";
+ break;
+
+ case "quote":
+ if (event.type === "QUOTE_RECEIVED") return "preview";
+ if (event.type === "BACK") return "methodSelection";
+ if (event.type === "ERROR_OCCURRED") return "error";
+ break;
+
+ case "preview":
+ if (event.type === "ROUTE_CONFIRMED") return "execute";
+ if (event.type === "BACK") return "methodSelection";
+ if (event.type === "ERROR_OCCURRED") return "error";
+ break;
+
+ case "execute":
+ if (event.type === "EXECUTION_COMPLETE") return "success";
+ if (event.type === "BACK") return "preview";
+ if (event.type === "ERROR_OCCURRED") return "error";
+ break;
+
+ case "success":
+ if (event.type === "CONTINUE_TO_TRANSACTION")
+ return "post-buy-transaction";
+ if (event.type === "RESET") return "init";
+ break;
+
+ case "post-buy-transaction":
+ if (event.type === "RESET") return "init";
+ break;
+
+ case "error":
+ if (event.type === "RETRY") {
+ return context.retryState ?? "init";
+ }
+ if (event.type === "RESET") {
+ return "init";
+ }
+ break;
+ }
+
+ return state;
+ });
+ },
+ [context.retryState],
+ );
+
+ return [
+ {
+ value: currentState,
+ context,
+ },
+ send,
+ ] as const;
+}
diff --git a/packages/thirdweb/src/react/core/types/.keep b/packages/thirdweb/src/react/core/types/.keep
new file mode 100644
index 00000000000..aacf1fca1d1
--- /dev/null
+++ b/packages/thirdweb/src/react/core/types/.keep
@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain shared type definitions and interfaces
\ No newline at end of file
diff --git a/packages/thirdweb/src/react/core/utils/wallet.test.ts b/packages/thirdweb/src/react/core/utils/wallet.test.ts
new file mode 100644
index 00000000000..37d8d5af4b0
--- /dev/null
+++ b/packages/thirdweb/src/react/core/utils/wallet.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import type { Wallet } from "../../../wallets/interfaces/wallet.js";
+import { hasSponsoredTransactionsEnabled } from "../../../wallets/smart/is-smart-wallet.js";
+
+describe("hasSponsoredTransactionsEnabled", () => {
+ it("should return false for undefined wallet", () => {
+ expect(hasSponsoredTransactionsEnabled(undefined)).toBe(false);
+ });
+
+ it("should handle smart wallet with sponsorGas config", () => {
+ const mockSmartWallet = {
+ id: "smart",
+ getConfig: () => ({ sponsorGas: true }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockSmartWallet)).toBe(true);
+
+ const mockSmartWalletDisabled = {
+ id: "smart",
+ getConfig: () => ({ sponsorGas: false }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockSmartWalletDisabled)).toBe(
+ false,
+ );
+ });
+
+ it("should handle smart wallet with gasless config", () => {
+ const mockSmartWallet = {
+ id: "smart",
+ getConfig: () => ({ gasless: true }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockSmartWallet)).toBe(true);
+ });
+
+ it("should handle inApp wallet with smartAccount config", () => {
+ const mockInAppWallet = {
+ id: "inApp",
+ getConfig: () => ({
+ smartAccount: {
+ sponsorGas: true,
+ },
+ }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockInAppWallet)).toBe(true);
+
+ const mockInAppWalletDisabled = {
+ id: "inApp",
+ getConfig: () => ({
+ smartAccount: {
+ sponsorGas: false,
+ },
+ }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockInAppWalletDisabled)).toBe(
+ false,
+ );
+ });
+
+ it("should handle inApp wallet with gasless config", () => {
+ const mockInAppWallet = {
+ id: "inApp",
+ getConfig: () => ({
+ smartAccount: {
+ gasless: true,
+ },
+ }),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockInAppWallet)).toBe(true);
+ });
+
+ it("should return false for regular wallet without smart account config", () => {
+ const mockRegularWallet = {
+ id: "inApp",
+ getConfig: () => ({}),
+ } as Wallet;
+ expect(hasSponsoredTransactionsEnabled(mockRegularWallet)).toBe(false);
+ });
+});
diff --git a/packages/thirdweb/src/react/native/flows/.keep b/packages/thirdweb/src/react/native/flows/.keep
new file mode 100644
index 00000000000..9a920ca00f5
--- /dev/null
+++ b/packages/thirdweb/src/react/native/flows/.keep
@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain React Native composite and flow components
\ No newline at end of file
diff --git a/packages/thirdweb/src/react/web/adapters/WindowAdapter.ts b/packages/thirdweb/src/react/web/adapters/WindowAdapter.ts
new file mode 100644
index 00000000000..db6347bdc5a
--- /dev/null
+++ b/packages/thirdweb/src/react/web/adapters/WindowAdapter.ts
@@ -0,0 +1,23 @@
+import type { WindowAdapter } from "../../core/adapters/WindowAdapter.js";
+
+/**
+ * Web implementation of WindowAdapter using the browser's window.open API.
+ * Opens URLs in a new tab/window.
+ */
+export class WebWindowAdapter implements WindowAdapter {
+ /**
+ * Opens a URL in a new browser tab/window.
+ *
+ * @param url - The URL to open
+ * @returns Promise that resolves when the operation is initiated
+ */
+ async open(url: string): Promise {
+ // Use window.open to open URL in new tab
+ window.open(url, "_blank", "noopener,noreferrer");
+ }
+}
+
+/**
+ * Default instance of the Web WindowAdapter.
+ */
+export const webWindowAdapter = new WebWindowAdapter();
diff --git a/packages/thirdweb/src/react/web/adapters/adapters.test.ts b/packages/thirdweb/src/react/web/adapters/adapters.test.ts
new file mode 100644
index 00000000000..612fcf34bd1
--- /dev/null
+++ b/packages/thirdweb/src/react/web/adapters/adapters.test.ts
@@ -0,0 +1,38 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { WebWindowAdapter } from "./WindowAdapter.js";
+
+describe("WebWindowAdapter", () => {
+ let windowAdapter: WebWindowAdapter;
+ let mockOpen: ReturnType;
+
+ beforeEach(() => {
+ windowAdapter = new WebWindowAdapter();
+
+ // Mock window.open using vi.stubGlobal
+ mockOpen = vi.fn();
+ vi.stubGlobal("window", {
+ open: mockOpen,
+ });
+ });
+
+ it("should open URL in new tab with correct parameters", async () => {
+ const mockWindow = {} as Partial;
+ mockOpen.mockReturnValue(mockWindow);
+
+ await windowAdapter.open("https://example.com");
+
+ expect(mockOpen).toHaveBeenCalledWith(
+ "https://example.com",
+ "_blank",
+ "noopener,noreferrer",
+ );
+ });
+
+ it("should throw error when popup is blocked", async () => {
+ mockOpen.mockReturnValue(null);
+
+ await expect(windowAdapter.open("https://example.com")).rejects.toThrow(
+ "Failed to open URL - popup may be blocked",
+ );
+ });
+});
diff --git a/packages/thirdweb/src/react/web/flows/.keep b/packages/thirdweb/src/react/web/flows/.keep
new file mode 100644
index 00000000000..c8a98fb3bdc
--- /dev/null
+++ b/packages/thirdweb/src/react/web/flows/.keep
@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain web-specific composite and flow components
\ No newline at end of file
diff --git a/packages/thirdweb/src/react/web/hooks/transaction/useSendTransaction.tsx b/packages/thirdweb/src/react/web/hooks/transaction/useSendTransaction.tsx
index 6348602db0c..16117a6cdd5 100644
--- a/packages/thirdweb/src/react/web/hooks/transaction/useSendTransaction.tsx
+++ b/packages/thirdweb/src/react/web/hooks/transaction/useSendTransaction.tsx
@@ -83,6 +83,11 @@ import { TransactionModal } from "../../ui/TransactionButton/TransactionModal.js
* value: toWei("0.1"),
* chain: sepolia,
* client: thirdwebClient,
+ * // Specify a token required for the transaction
+ * erc20Value: {
+ * amountWei: toWei("0.1"),
+ * tokenAddress: "0x...",
+ * },
* });
* sendTx(transaction);
* };
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx b/packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx
new file mode 100644
index 00000000000..670145ea8e0
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/BridgeOrchestrator.tsx
@@ -0,0 +1,357 @@
+"use client";
+import { useCallback, useMemo } from "react";
+import type { Token } from "../../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import type { PreparedTransaction } from "../../../../transaction/prepare-transaction.js";
+import type { Address } from "../../../../utils/address.js";
+import { webLocalStorage } from "../../../../utils/storage/webStorage.js";
+import type { Prettify } from "../../../../utils/type-utils.js";
+import type {
+ BridgePrepareRequest,
+ BridgePrepareResult,
+} from "../../../core/hooks/useBridgePrepare.js";
+import type { CompletedStatusResult } from "../../../core/hooks/useStepExecutor.js";
+import {
+ type PaymentMethod,
+ usePaymentMachine,
+} from "../../../core/machines/paymentMachine.js";
+import { webWindowAdapter } from "../../adapters/WindowAdapter.js";
+import en from "../ConnectWallet/locale/en.js";
+import type { ConnectLocale } from "../ConnectWallet/locale/types.js";
+import type { PayEmbedConnectOptions } from "../PayEmbed.js";
+import { ExecutingTxScreen } from "../TransactionButton/ExecutingScreen.js";
+import { Container } from "../components/basic.js";
+import { DirectPayment } from "./DirectPayment.js";
+import { ErrorBanner } from "./ErrorBanner.js";
+import { FundWallet } from "./FundWallet.js";
+import { QuoteLoader } from "./QuoteLoader.js";
+import { StepRunner } from "./StepRunner.js";
+import { TransactionPayment } from "./TransactionPayment.js";
+import { PaymentDetails } from "./payment-details/PaymentDetails.js";
+import { PaymentSelection } from "./payment-selection/PaymentSelection.js";
+import { SuccessScreen } from "./payment-success/SuccessScreen.js";
+
+export type UIOptions = Prettify<
+ {
+ metadata?: {
+ title?: string;
+ description?: string;
+ image?: string;
+ };
+ } & (
+ | {
+ mode: "fund_wallet";
+ destinationToken: Token;
+ initialAmount?: string;
+ presetOptions?: [number, number, number];
+ }
+ | {
+ mode: "direct_payment";
+ paymentInfo: {
+ sellerAddress: Address;
+ token: Token;
+ amount: string;
+ feePayer?: "sender" | "receiver";
+ };
+ }
+ | { mode: "transaction"; transaction: PreparedTransaction }
+ )
+>;
+
+export interface BridgeOrchestratorProps {
+ /**
+ * UI configuration and mode
+ */
+ uiOptions: UIOptions;
+
+ /**
+ * The receiver address, defaults to the connected wallet address
+ */
+ receiverAddress: Address | undefined;
+
+ /**
+ * ThirdwebClient for blockchain interactions
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when the flow is completed successfully
+ */
+ onComplete: () => void;
+
+ /**
+ * Called when the flow encounters an error
+ */
+ onError: (error: Error) => void;
+
+ /**
+ * Called when the user cancels the flow
+ */
+ onCancel: () => void;
+
+ /**
+ * Connect options for wallet connection
+ */
+ connectOptions: PayEmbedConnectOptions | undefined;
+
+ /**
+ * Locale for connect UI
+ */
+ connectLocale: ConnectLocale | undefined;
+
+ /**
+ * Optional purchase data for the payment
+ */
+ purchaseData: object | undefined;
+
+ /**
+ * Optional payment link ID for the payment
+ */
+ paymentLinkId: string | undefined;
+
+ /**
+ * Quick buy amounts
+ */
+ presetOptions: [number, number, number] | undefined;
+}
+
+export function BridgeOrchestrator({
+ client,
+ uiOptions,
+ receiverAddress,
+ onComplete,
+ onError,
+ onCancel,
+ connectOptions,
+ connectLocale,
+ purchaseData,
+ paymentLinkId,
+ presetOptions,
+}: BridgeOrchestratorProps) {
+ // Initialize adapters
+ const adapters = useMemo(
+ () => ({
+ window: webWindowAdapter,
+ storage: webLocalStorage,
+ }),
+ [],
+ );
+
+ // Use the payment machine hook
+ const [state, send] = usePaymentMachine(adapters, uiOptions.mode);
+
+ // Handle buy completion
+ const handleBuyComplete = useCallback(() => {
+ if (uiOptions.mode === "transaction") {
+ send({ type: "CONTINUE_TO_TRANSACTION" });
+ } else {
+ onComplete?.();
+ send({ type: "RESET" });
+ }
+ }, [onComplete, send, uiOptions.mode]);
+
+ // Handle post-buy transaction completion
+ const handlePostBuyTransactionComplete = useCallback(() => {
+ onComplete?.();
+ send({ type: "RESET" });
+ }, [onComplete, send]);
+
+ // Handle errors
+ const handleError = useCallback(
+ (error: Error) => {
+ onError?.(error);
+ send({ type: "ERROR_OCCURRED", error });
+ },
+ [onError, send],
+ );
+
+ // Handle payment method selection
+ const handlePaymentMethodSelected = useCallback(
+ (paymentMethod: PaymentMethod) => {
+ send({ type: "PAYMENT_METHOD_SELECTED", paymentMethod });
+ },
+ [send],
+ );
+
+ // Handle quote received
+ const handleQuoteReceived = useCallback(
+ (quote: BridgePrepareResult, request: BridgePrepareRequest) => {
+ send({ type: "QUOTE_RECEIVED", quote, request });
+ },
+ [send],
+ );
+
+ // Handle route confirmation
+ const handleRouteConfirmed = useCallback(() => {
+ send({ type: "ROUTE_CONFIRMED" });
+ }, [send]);
+
+ // Handle execution complete
+ const handleExecutionComplete = useCallback(
+ (completedStatuses: CompletedStatusResult[]) => {
+ send({ type: "EXECUTION_COMPLETE", completedStatuses });
+ },
+ [send],
+ );
+
+ // Handle retry
+ const handleRetry = useCallback(() => {
+ send({ type: "RETRY" });
+ }, [send]);
+
+ // Handle requirements resolved from FundWallet and DirectPayment
+ const handleRequirementsResolved = useCallback(
+ (amount: string, token: Token, receiverAddress: Address) => {
+ send({
+ type: "DESTINATION_CONFIRMED",
+ destinationToken: token,
+ receiverAddress,
+ destinationAmount: amount,
+ });
+ },
+ [send],
+ );
+
+ return (
+
+ {/* Error Banner */}
+ {state.value === "error" && state.context.currentError && (
+ {
+ send({ type: "BACK" });
+ }}
+ connectOptions={connectOptions}
+ connectLocale={connectLocale || en}
+ includeDestinationToken={uiOptions.mode !== "fund_wallet"}
+ />
+ )}
+
+ {state.value === "quote" &&
+ state.context.selectedPaymentMethod &&
+ state.context.receiverAddress &&
+ state.context.destinationToken &&
+ state.context.destinationAmount && (
+ {
+ send({ type: "BACK" });
+ }}
+ />
+ )}
+
+ {state.value === "preview" &&
+ state.context.selectedPaymentMethod &&
+ state.context.quote && (
+ {
+ send({ type: "BACK" });
+ }}
+ onError={handleError}
+ />
+ )}
+
+ {state.value === "execute" &&
+ state.context.quote &&
+ state.context.request &&
+ state.context.selectedPaymentMethod?.payerWallet && (
+ {
+ send({ type: "BACK" });
+ }}
+ />
+ )}
+
+ {state.value === "success" &&
+ state.context.quote &&
+ state.context.completedStatuses && (
+ {
+ // Do nothing
+ }}
+ />
+ )}
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx
new file mode 100644
index 00000000000..0a8841fa07e
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/BuyWidget.tsx
@@ -0,0 +1,494 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import type { Token } from "../../../../bridge/index.js";
+import type { Chain } from "../../../../chains/types.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../constants/addresses.js";
+import { getToken } from "../../../../pay/convert/get-token.js";
+import {
+ type Address,
+ checksumAddress,
+ isAddress,
+} from "../../../../utils/address.js";
+import { stringify } from "../../../../utils/json.js";
+import { toTokens } from "../../../../utils/units.js";
+import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import type { SmartWalletOptions } from "../../../../wallets/smart/types.js";
+import type { AppMetadata } from "../../../../wallets/types.js";
+import type { WalletId } from "../../../../wallets/wallet-types.js";
+import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProvider.js";
+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 { SupportedTokens } from "../../../core/utils/defaultTokens.js";
+import { EmbedContainer } from "../ConnectWallet/Modal/ConnectEmbed.js";
+import { useConnectLocale } from "../ConnectWallet/locale/getConnectLocale.js";
+import { DynamicHeight } from "../components/DynamicHeight.js";
+import { Spinner } from "../components/Spinner.js";
+import type { LocaleId } from "../types.js";
+import { BridgeOrchestrator, type UIOptions } from "./BridgeOrchestrator.js";
+import { UnsupportedTokenScreen } from "./UnsupportedTokenScreen.js";
+
+export type BuyWidgetProps = {
+ supportedTokens?: SupportedTokens;
+ /**
+ * A client is the entry point to the thirdweb SDK.
+ * It is required for all other actions.
+ * You can create a client using the `createThirdwebClient` function. Refer to the [Creating a Client](https://portal.thirdweb.com/typescript/v5/client) documentation for more information.
+ *
+ * You must provide a `clientId` or `secretKey` in order to initialize a client. Pass `clientId` if you want for client-side usage and `secretKey` for server-side usage.
+ *
+ * ```tsx
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ * clientId: "",
+ * })
+ * ```
+ */
+ client: ThirdwebClient;
+ /**
+ * By default - ConnectButton UI uses the `en-US` locale for english language users.
+ *
+ * You can customize the language used in the ConnectButton UI by setting the `locale` prop.
+ *
+ * Refer to the [`LocaleId`](https://portal.thirdweb.com/references/typescript/v5/LocaleId) type for supported locales.
+ */
+ locale?: LocaleId;
+ /**
+ * Set the theme for the `BuyWidget` component. By default it is set to `"dark"`
+ *
+ * theme can be set to either `"dark"`, `"light"` or a custom theme object.
+ * You can also import [`lightTheme`](https://portal.thirdweb.com/references/typescript/v5/lightTheme)
+ * or [`darkTheme`](https://portal.thirdweb.com/references/typescript/v5/darkTheme)
+ * functions from `thirdweb/react` to use the default themes as base and overrides parts of it.
+ * @example
+ * ```ts
+ * import { lightTheme } from "thirdweb/react";
+ *
+ * const customTheme = lightTheme({
+ * colors: {
+ * modalBg: 'red'
+ * }
+ * })
+ *
+ * function Example() {
+ * return ;
+
+ /**
+ * Callback triggered when the purchase is successful.
+ */
+ onSuccess?: () => void;
+
+ /**
+ * Callback triggered when the purchase encounters an error.
+ */
+ onError?: (error: Error) => void;
+
+ /**
+ * Callback triggered when the user cancels the purchase.
+ */
+ onCancel?: () => void;
+
+ /**
+ * @hidden
+ */
+ paymentLinkId?: string;
+};
+
+// Enhanced UIOptions to handle unsupported token state
+type UIOptionsResult =
+ | { type: "success"; data: UIOptions }
+ | {
+ type: "indexing_token";
+ token: Token;
+ chain: Chain;
+ }
+ | {
+ type: "unsupported_token";
+ tokenAddress: Address;
+ chain: Chain;
+ };
+
+/**
+ * Widget is a prebuilt UI for purchasing a specific token.
+ *
+ * @param props - Props of type [`BuyWidgetProps`](https://portal.thirdweb.com/references/typescript/v5/BuyWidgetProps) to configure the BuyWidget component.
+ *
+ * @example
+ * ### Basic usage
+ *
+ * The `BuyWidget` component requires `client`, `chain`, and `amount` props to function.
+ *
+ * ```tsx
+ * import { ethereum } from "thirdweb/chains";
+ * import { toWei } from "thirdweb";
+ *
+ * => {
+ if (
+ !props.tokenAddress ||
+ (isAddress(props.tokenAddress) &&
+ checksumAddress(props.tokenAddress) ===
+ checksumAddress(NATIVE_TOKEN_ADDRESS))
+ ) {
+ const ETH = await getToken(
+ props.client,
+ NATIVE_TOKEN_ADDRESS,
+ props.chain.id,
+ );
+ return {
+ type: "success",
+ data: {
+ mode: "fund_wallet",
+ destinationToken: ETH,
+ initialAmount: toTokens(props.amount, ETH.decimals),
+ },
+ };
+ }
+
+ const token = await getToken(
+ props.client,
+ props.tokenAddress,
+ props.chain.id,
+ ).catch((err) => {
+ err.message.includes("not supported") ? undefined : Promise.reject(err);
+ });
+ if (!token) {
+ return {
+ type: "unsupported_token",
+ tokenAddress: props.tokenAddress,
+ chain: props.chain,
+ };
+ }
+ return {
+ type: "success",
+ data: {
+ mode: "fund_wallet",
+ destinationToken: token,
+ initialAmount: toTokens(props.amount, token.decimals),
+ metadata: {
+ title: props.title,
+ },
+ },
+ };
+ },
+ });
+
+ let content = null;
+ if (!localeQuery.data || bridgeDataQuery.isLoading) {
+ content = (
+ {
+ props.onSuccess?.();
+ }}
+ onError={(err: Error) => {
+ props.onError?.(err);
+ }}
+ onCancel={() => {
+ props.onCancel?.();
+ }}
+ presetOptions={props.presetOptions}
+ receiverAddress={undefined}
+ />
+ );
+ }
+
+ return (
+
+
+ {content}
+
+
+ );
+}
+
+/**
+ * Connection options for the `BuyWidget` component
+ *
+ * @example
+ * ```tsx
+ * ",
+ * })
+ * ```
+ */
+ client: ThirdwebClient;
+ /**
+ * By default - ConnectButton UI uses the `en-US` locale for english language users.
+ *
+ * You can customize the language used in the ConnectButton UI by setting the `locale` prop.
+ *
+ * Refer to the [`LocaleId`](https://portal.thirdweb.com/references/typescript/v5/LocaleId) type for supported locales.
+ */
+ locale?: LocaleId;
+ /**
+ * Set the theme for the `CheckoutWidget` component. By default it is set to `"dark"`
+ *
+ * theme can be set to either `"dark"`, `"light"` or a custom theme object.
+ * You can also import [`lightTheme`](https://portal.thirdweb.com/references/typescript/v5/lightTheme)
+ * or [`darkTheme`](https://portal.thirdweb.com/references/typescript/v5/darkTheme)
+ * functions from `thirdweb/react` to use the default themes as base and overrides parts of it.
+ * @example
+ * ```ts
+ * import { lightTheme } from "thirdweb/react";
+ *
+ * const customTheme = lightTheme({
+ * colors: {
+ * modalBg: 'red'
+ * }
+ * })
+ *
+ * function Example() {
+ * return ;
+
+ /**
+ * Callback triggered when the purchase is successful.
+ */
+ onSuccess?: () => void;
+
+ /**
+ * Callback triggered when the purchase encounters an error.
+ */
+ onError?: (error: Error) => void;
+
+ /**
+ * Callback triggered when the user cancels the purchase.
+ */
+ onCancel?: () => void;
+
+ /**
+ * @hidden
+ */
+ paymentLinkId?: string;
+};
+
+// Enhanced UIOptions to handle unsupported token state
+type UIOptionsResult =
+ | { type: "success"; data: UIOptions }
+ | {
+ type: "indexing_token";
+ token: Token;
+ chain: Chain;
+ }
+ | {
+ type: "unsupported_token";
+ tokenAddress: Address;
+ chain: Chain;
+ };
+
+/**
+ * Widget a prebuilt UI for purchasing a specific token.
+ *
+ * @param props - Props of type [`CheckoutWidgetProps`](https://portal.thirdweb.com/references/typescript/v5/CheckoutWidgetProps) to configure the CheckoutWidget component.
+ *
+ * @example
+ * ### Default configuration
+ *
+ * By default, the `CheckoutWidget` component will allows users to fund their wallets with crypto or fiat on any of the supported chains..
+ *
+ * ```tsx
+ * => {
+ const token = await getToken(
+ props.client,
+ checksumAddress(props.tokenAddress || NATIVE_TOKEN_ADDRESS),
+ props.chain.id,
+ ).catch((err) =>
+ err.message.includes("not supported") ? undefined : Promise.reject(err),
+ );
+ if (!token) {
+ return {
+ type: "unsupported_token",
+ tokenAddress: checksumAddress(
+ props.tokenAddress || NATIVE_TOKEN_ADDRESS,
+ ),
+ chain: props.chain,
+ };
+ }
+ return {
+ type: "success",
+ data: {
+ mode: "direct_payment",
+ metadata: {
+ title: props.name,
+ image: props.image,
+ description: props.description,
+ },
+ paymentInfo: {
+ token,
+ amount: toTokens(props.amount, token.decimals),
+ sellerAddress: props.seller,
+ feePayer: props.feePayer === "seller" ? "receiver" : "sender", // User is sender, seller is receiver
+ },
+ },
+ };
+ },
+ });
+
+ let content = null;
+ if (!localeQuery.data || bridgeDataQuery.isLoading) {
+ content = (
+ {
+ props.onSuccess?.();
+ }}
+ onError={(err: Error) => {
+ props.onError?.(err);
+ }}
+ onCancel={() => {
+ props.onCancel?.();
+ }}
+ presetOptions={props.presetOptions}
+ receiverAddress={props.seller}
+ />
+ );
+ }
+
+ return (
+
+
+ {content}
+
+
+ );
+}
+
+/**
+ * Connection options for the `CheckoutWidget` component
+ *
+ * @example
+ * ```tsx
+ * ;
+
+ /**
+ * ThirdwebClient for blockchain interactions
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when user continues with the payment
+ */
+ onContinue: (amount: string, token: Token, receiverAddress: Address) => void;
+
+ /**
+ * Connect options for wallet connection
+ */
+ connectOptions?: PayEmbedConnectOptions;
+}
+
+export function DirectPayment({
+ uiOptions,
+ client,
+ onContinue,
+ connectOptions,
+}: DirectPaymentProps) {
+ const activeAccount = useActiveAccount();
+ const chain = defineChain(uiOptions.paymentInfo.token.chainId);
+ const theme = useCustomTheme();
+ const handleContinue = () => {
+ onContinue(
+ uiOptions.paymentInfo.amount,
+ uiOptions.paymentInfo.token,
+ uiOptions.paymentInfo.sellerAddress,
+ );
+ };
+ const ensName = useEnsName({
+ address: uiOptions.paymentInfo.sellerAddress,
+ client,
+ });
+ const sellerAddress =
+ ensName.data || shortenAddress(uiOptions.paymentInfo.sellerAddress);
+
+ const buyNow = (
+
+
+ Buy Now ·
+
+
+ );
+
+ return (
+
+ {/* Price section */}
+
+
+
+ One-time payment
+
+
+
+
+
+
+ Sold by
+
+
+ {sellerAddress}
+
+
+
+
+
+ Price
+
+
+ {`${uiOptions.paymentInfo.amount} ${uiOptions.paymentInfo.token.symbol}`}
+
+
+
+
+
+ Network
+
+
+
+
+
+
+ {activeAccount ? (
+
+ ) : (
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/ErrorBanner.tsx b/packages/thirdweb/src/react/web/ui/Bridge/ErrorBanner.tsx
new file mode 100644
index 00000000000..25ee7648dee
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/ErrorBanner.tsx
@@ -0,0 +1,86 @@
+"use client";
+import { CrossCircledIcon } from "@radix-ui/react-icons";
+import { useCustomTheme } from "../../../core/design-system/CustomThemeProvider.js";
+import { iconSize } from "../../../core/design-system/index.js";
+import { useBridgeError } from "../../../core/hooks/useBridgeError.js";
+import { Container } from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Text } from "../components/text.js";
+
+interface ErrorBannerProps {
+ /**
+ * The error to display
+ */
+ error: Error;
+
+ /**
+ * Called when user wants to retry
+ */
+ onRetry: () => void;
+
+ /**
+ * Called when user wants to cancel
+ */
+ onCancel?: () => void;
+}
+
+export function ErrorBanner({ error, onRetry, onCancel }: ErrorBannerProps) {
+ const theme = useCustomTheme();
+
+ const { userMessage } = useBridgeError({ error });
+
+ return (
+
+ {/* Error Icon and Message */}
+
+
+
+
+
+
+ Error
+
+
+
+
+ {userMessage}
+
+
+
+
+ {/* Action Buttons */}
+
+
+ {onCancel && (
+
+ )}
+
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx b/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx
new file mode 100644
index 00000000000..5591e316f17
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/FundWallet.tsx
@@ -0,0 +1,341 @@
+"use client";
+import { useState } from "react";
+import type { Token } from "../../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { type Address, getAddress } from "../../../../utils/address.js";
+import { useCustomTheme } from "../../../core/design-system/CustomThemeProvider.js";
+import {
+ fontSize,
+ iconSize,
+ radius,
+ spacing,
+} from "../../../core/design-system/index.js";
+import { useActiveAccount } from "../../../core/hooks/wallets/useActiveAccount.js";
+import { ConnectButton } from "../ConnectWallet/ConnectButton.js";
+import { PoweredByThirdweb } from "../ConnectWallet/PoweredByTW.js";
+import { OutlineWalletIcon } from "../ConnectWallet/icons/OutlineWalletIcon.js";
+import { WalletRow } from "../ConnectWallet/screens/Buy/swap/WalletRow.js";
+import type { PayEmbedConnectOptions } from "../PayEmbed.js";
+import { Spacer } from "../components/Spacer.js";
+import { Container } from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Input } from "../components/formElements.js";
+import { Text } from "../components/text.js";
+import type { UIOptions } from "./BridgeOrchestrator.js";
+import { TokenAndChain } from "./common/TokenAndChain.js";
+import { WithHeader } from "./common/WithHeader.js";
+
+export interface FundWalletProps {
+ /**
+ * UI configuration and mode
+ */
+ uiOptions: Extract;
+
+ /**
+ * The receiver address, defaults to the connected wallet address
+ */
+ receiverAddress?: Address;
+ /**
+ * ThirdwebClient for price fetching
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when continue is clicked with the resolved requirements
+ */
+ onContinue: (amount: string, token: Token, receiverAddress: Address) => void;
+
+ /**
+ * Quick buy amounts
+ */
+ presetOptions?: [number, number, number];
+
+ /**
+ * Connect options for wallet connection
+ */
+ connectOptions?: PayEmbedConnectOptions;
+}
+
+export function FundWallet({
+ client,
+ receiverAddress,
+ uiOptions,
+ onContinue,
+ presetOptions = [5, 10, 20],
+ connectOptions,
+}: FundWalletProps) {
+ const [amount, setAmount] = useState(uiOptions.initialAmount ?? "");
+ const theme = useCustomTheme();
+ const account = useActiveAccount();
+ const receiver = receiverAddress ?? account?.address;
+ const handleAmountChange = (inputValue: string) => {
+ let processedValue = inputValue;
+
+ // Replace comma with period if it exists
+ processedValue = processedValue.replace(",", ".");
+
+ if (processedValue.startsWith(".")) {
+ processedValue = `0${processedValue}`;
+ }
+
+ const numValue = Number(processedValue);
+ if (Number.isNaN(numValue)) {
+ return;
+ }
+
+ if (processedValue.startsWith("0") && !processedValue.startsWith("0.")) {
+ setAmount(processedValue.slice(1));
+ } else {
+ setAmount(processedValue);
+ }
+ };
+
+ const getAmountFontSize = () => {
+ const length = amount.length;
+ if (length > 12) return fontSize.md;
+ if (length > 8) return fontSize.lg;
+ return fontSize.xl;
+ };
+
+ const isValidAmount = amount && Number(amount) > 0;
+
+ const focusInput = () => {
+ const input = document.querySelector("#amount-input") as HTMLInputElement;
+ input?.focus();
+ };
+
+ const handleQuickAmount = (usdAmount: number) => {
+ if (uiOptions.destinationToken.priceUsd === 0) {
+ return;
+ }
+ // Convert USD amount to token amount using token price
+ const tokenAmount = usdAmount / uiOptions.destinationToken.priceUsd;
+ // Format to reasonable decimal places (up to 6 decimals, remove trailing zeros)
+ const formattedAmount = Number.parseFloat(
+ tokenAmount.toFixed(6),
+ ).toString();
+ setAmount(formattedAmount);
+ };
+
+ return (
+
+
+ {/* Token Info */}
+
+
+
+
+ ≈ $
+ {(Number(amount) * uiOptions.destinationToken.priceUsd).toFixed(
+ 2,
+ )}
+
+
+
+
+
+ {/* Quick Amount Buttons */}
+ {presetOptions && (
+ <>
+
+ {presetOptions?.map((amount) => (
+
+ ))}
+
+
+ )}
+
+
+ {receiver ? (
+
+ No Wallet Connected
+
+
+ )}
+
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/QuoteLoader.tsx b/packages/thirdweb/src/react/web/ui/Bridge/QuoteLoader.tsx
new file mode 100644
index 00000000000..9690b5abf95
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/QuoteLoader.tsx
@@ -0,0 +1,219 @@
+"use client";
+import { useEffect } from "react";
+import type { Token } from "../../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../constants/addresses.js";
+import { toUnits } from "../../../../utils/units.js";
+import {
+ type BridgePrepareRequest,
+ type BridgePrepareResult,
+ type UseBridgePrepareParams,
+ useBridgePrepare,
+} from "../../../core/hooks/useBridgePrepare.js";
+import type { PaymentMethod } from "../../../core/machines/paymentMachine.js";
+import { Spacer } from "../components/Spacer.js";
+import { Spinner } from "../components/Spinner.js";
+import { Container } from "../components/basic.js";
+import { Text } from "../components/text.js";
+
+interface QuoteLoaderProps {
+ /**
+ * The destination token to bridge to
+ */
+ destinationToken: Token;
+
+ /**
+ * The payment method to use
+ */
+ paymentMethod: PaymentMethod;
+
+ /**
+ * The amount to bridge (as string)
+ */
+ amount: string;
+
+ /**
+ * The sender address
+ */
+ sender?: string;
+
+ /**
+ * The receiver address (defaults to sender for fund_wallet mode)
+ */
+ receiver: string;
+
+ /**
+ * ThirdwebClient for API calls
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when a quote is successfully received
+ */
+ onQuoteReceived: (
+ preparedQuote: BridgePrepareResult,
+ request: BridgePrepareRequest,
+ ) => void;
+
+ /**
+ * Called when an error occurs
+ */
+ onError: (error: Error) => void;
+
+ /**
+ * Called when user wants to go back
+ */
+ onBack?: () => void;
+
+ /**
+ * Optional purchase data for the payment
+ */
+ purchaseData?: object;
+
+ /**
+ * Optional payment link ID for the payment
+ */
+ paymentLinkId?: string;
+
+ /**
+ * Fee payer for direct transfers (defaults to sender)
+ */
+ feePayer?: "sender" | "receiver";
+}
+
+export function QuoteLoader({
+ destinationToken,
+ paymentMethod,
+ amount,
+ sender,
+ receiver,
+ client,
+ onQuoteReceived,
+ onError,
+ purchaseData,
+ paymentLinkId,
+ feePayer,
+}: QuoteLoaderProps) {
+ // For now, we'll use a simple buy operation
+ // This will be expanded to handle different bridge types based on the payment method
+ const request: BridgePrepareRequest = getBridgeParams({
+ paymentMethod,
+ amount,
+ destinationToken,
+ receiver,
+ sender,
+ client,
+ purchaseData,
+ paymentLinkId,
+ feePayer,
+ });
+ const prepareQuery = useBridgePrepare(request);
+
+ // Handle successful quote
+ useEffect(() => {
+ if (prepareQuery.data) {
+ onQuoteReceived(prepareQuery.data, request);
+ }
+ }, [prepareQuery.data, onQuoteReceived, request]);
+
+ // Handle errors
+ useEffect(() => {
+ if (prepareQuery.error) {
+ onError(prepareQuery.error as Error);
+ }
+ }, [prepareQuery.error, onError]);
+
+ return (
+
+
+ Finding the best route...
+
+
+ We're searching for the most efficient path for this payment.
+
+
+ );
+}
+
+function getBridgeParams(args: {
+ paymentMethod: PaymentMethod;
+ amount: string;
+ destinationToken: Token;
+ receiver: string;
+ client: ThirdwebClient;
+ sender?: string;
+ feePayer?: "sender" | "receiver";
+ purchaseData?: object;
+ paymentLinkId?: string;
+}): UseBridgePrepareParams {
+ const { paymentMethod, amount, destinationToken, receiver, client, sender } =
+ args;
+
+ switch (paymentMethod.type) {
+ case "fiat":
+ return {
+ type: "onramp",
+ client,
+ amount: toUnits(amount, destinationToken.decimals),
+ receiver,
+ sender,
+ chainId: destinationToken.chainId,
+ tokenAddress: destinationToken.address,
+ onramp: paymentMethod.onramp || "coinbase",
+ purchaseData: args.purchaseData,
+ currency: paymentMethod.currency,
+ onrampTokenAddress: NATIVE_TOKEN_ADDRESS, // always onramp to native token
+ paymentLinkId: args.paymentLinkId,
+ enabled: !!(destinationToken && amount && client),
+ };
+ case "wallet":
+ // if the origin token is the same as the destination token, use transfer type
+ if (
+ paymentMethod.originToken.chainId === destinationToken.chainId &&
+ paymentMethod.originToken.address.toLowerCase() ===
+ destinationToken.address.toLowerCase()
+ ) {
+ return {
+ type: "transfer",
+ client,
+ chainId: destinationToken.chainId,
+ tokenAddress: destinationToken.address,
+ feePayer: args.feePayer || "sender",
+ amount: toUnits(amount, destinationToken.decimals),
+ sender:
+ sender ||
+ paymentMethod.payerWallet.getAccount()?.address ||
+ receiver,
+ receiver,
+ purchaseData: args.purchaseData,
+ paymentLinkId: args.paymentLinkId,
+ enabled: !!(destinationToken && amount && client),
+ };
+ }
+
+ return {
+ type: "buy",
+ client,
+ originChainId: paymentMethod.originToken.chainId,
+ originTokenAddress: paymentMethod.originToken.address,
+ destinationChainId: destinationToken.chainId,
+ destinationTokenAddress: destinationToken.address,
+ amount: toUnits(amount, destinationToken.decimals),
+ sender:
+ sender || paymentMethod.payerWallet.getAccount()?.address || receiver,
+ receiver,
+ purchaseData: args.purchaseData,
+ paymentLinkId: args.paymentLinkId,
+ enabled: !!(destinationToken && amount && client),
+ };
+ }
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/StepRunner.tsx b/packages/thirdweb/src/react/web/ui/Bridge/StepRunner.tsx
new file mode 100644
index 00000000000..f543410ae17
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/StepRunner.tsx
@@ -0,0 +1,417 @@
+"use client";
+import { CheckIcon, ClockIcon, Cross1Icon } from "@radix-ui/react-icons";
+import type { RouteStep } from "../../../../bridge/types/Route.js";
+import type { Chain } from "../../../../chains/types.js";
+import { defineChain } from "../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import type { WindowAdapter } from "../../../core/adapters/WindowAdapter.js";
+import { useCustomTheme } from "../../../core/design-system/CustomThemeProvider.js";
+import {
+ iconSize,
+ radius,
+ spacing,
+} from "../../../core/design-system/index.js";
+import type { BridgePrepareRequest } from "../../../core/hooks/useBridgePrepare.js";
+import {
+ type CompletedStatusResult,
+ useStepExecutor,
+} from "../../../core/hooks/useStepExecutor.js";
+import { ChainName } from "../components/ChainName.js";
+import { Spacer } from "../components/Spacer.js";
+import { Spinner } from "../components/Spinner.js";
+import { Container, ModalHeader } from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Text } from "../components/text.js";
+
+interface StepRunnerProps {
+ request: BridgePrepareRequest;
+
+ /**
+ * Wallet instance for executing transactions
+ */
+ wallet: Wallet;
+
+ /**
+ * Thirdweb client for API calls
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Window adapter for opening URLs (web/RN)
+ */
+ windowAdapter: WindowAdapter;
+
+ /**
+ * Whether to automatically start the transaction process
+ */
+ autoStart?: boolean;
+
+ /**
+ * Called when all steps are completed - receives array of completed status results
+ */
+ onComplete: (completedStatuses: CompletedStatusResult[]) => void;
+
+ /**
+ * Called when user cancels the flow
+ */
+ onCancel?: () => void;
+
+ /**
+ * Called when user clicks the back button
+ */
+ onBack?: () => void;
+}
+
+export function StepRunner({
+ request,
+ wallet,
+ client,
+ windowAdapter,
+ onComplete,
+ onCancel,
+ onBack,
+ autoStart,
+}: StepRunnerProps) {
+ const theme = useCustomTheme();
+
+ // Use the real step executor hook
+ const {
+ currentStep,
+ progress,
+ executionState,
+ onrampStatus,
+ steps,
+ error,
+ start,
+ cancel,
+ retry,
+ } = useStepExecutor({
+ request,
+ wallet,
+ client,
+ windowAdapter,
+ autoStart,
+ onComplete: (completedStatuses: CompletedStatusResult[]) => {
+ onComplete(completedStatuses);
+ },
+ });
+
+ const handleCancel = () => {
+ cancel();
+ if (onCancel) {
+ onCancel();
+ }
+ };
+
+ const handleRetry = () => {
+ retry();
+ };
+
+ const getStepStatus = (
+ stepIndex: number,
+ ): "pending" | "executing" | "completed" | "failed" => {
+ if (!currentStep || !steps) {
+ // Not started yet
+ return stepIndex === 0 ? (error ? "failed" : "pending") : "pending";
+ }
+
+ const currentStepIndex = steps.findIndex((step) => step === currentStep);
+
+ if (stepIndex < currentStepIndex) return "completed";
+ if (stepIndex === currentStepIndex && executionState === "executing")
+ return "executing";
+ if (stepIndex === currentStepIndex && error) return "failed";
+ if (
+ stepIndex === currentStepIndex &&
+ executionState === "idle" &&
+ progress === 100
+ )
+ return "completed";
+
+ return "pending";
+ };
+
+ const getStatusIcon = (
+ status: "pending" | "executing" | "completed" | "failed",
+ ) => {
+ switch (status) {
+ case "completed":
+ return (
+
+
+ Bridge {originToken.symbol} to{" "}
+
+
+ );
+ }
+
+ // If different tokens on same chain, it's a swap
+ if (originToken.symbol !== destinationToken.symbol) {
+ return (
+
+ Swap {originToken.symbol} to {destinationToken.symbol}
+
+ );
+ }
+
+ // Fallback to step number
+ return (
+
+ Process transaction
+
+ );
+ };
+
+ const getStepStatusText = (
+ status: "pending" | "executing" | "completed" | "failed",
+ ) => {
+ switch (status) {
+ case "executing":
+ return "Processing...";
+ case "completed":
+ return "Completed";
+ case "pending":
+ return "Waiting...";
+ case "failed":
+ return "Failed";
+ default:
+ return "Unknown";
+ }
+ };
+
+ return (
+
+
+ {/* Progress Bar */}
+
+
+
+ Progress
+
+
+ {progress}%
+
+
+
+
+
+
+
+
+
+
+ {request.type === "onramp" && onrampStatus ? (
+
+
+ {getStatusIcon(onrampStatus)}
+
+
+
+
+ TEST
+
+
+ {getStepStatusText(onrampStatus)}
+
+
+
+ ) : null}
+ {steps?.map((step, index) => {
+ const status = getStepStatus(index);
+
+ return (
+
+
+ {getStatusIcon(status)}
+
+
+
+ {getStepDescription(step)}
+
+ {getStepStatusText(status)}
+
+
+
+ );
+ })}
+
+
+
+ Keep this window open until all
+
transactions are complete. +
+
+
+
+
+ ) : executionState === "idle" && progress === 0 ? (
+
+ ) : executionState === "executing" ||
+ executionState === "auto-starting" ? (
+
+ ) : null}
+
+
+ );
+}
+
+function getDestinationChain(request: BridgePrepareRequest): Chain {
+ switch (request.type) {
+ case "onramp":
+ return defineChain(request.chainId);
+ case "buy":
+ case "sell":
+ return defineChain(request.destinationChainId);
+ case "transfer":
+ return defineChain(request.chainId);
+ default:
+ throw new Error("Invalid quote type");
+ }
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx b/packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx
new file mode 100644
index 00000000000..f847b1ec3b5
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/TransactionPayment.tsx
@@ -0,0 +1,403 @@
+"use client";
+import type { Token } from "../../../../bridge/index.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import {
+ type Address,
+ getAddress,
+ shortenAddress,
+} from "../../../../utils/address.js";
+import { useCustomTheme } from "../../../core/design-system/CustomThemeProvider.js";
+import { fontSize, spacing } from "../../../core/design-system/index.js";
+import { useChainMetadata } from "../../../core/hooks/others/useChainQuery.js";
+import { useTransactionDetails } from "../../../core/hooks/useTransactionDetails.js";
+import { useActiveAccount } from "../../../core/hooks/wallets/useActiveAccount.js";
+import { ConnectButton } from "../ConnectWallet/ConnectButton.js";
+import { PoweredByThirdweb } from "../ConnectWallet/PoweredByTW.js";
+import type { PayEmbedConnectOptions } from "../PayEmbed.js";
+import { ChainName } from "../components/ChainName.js";
+import { Spacer } from "../components/Spacer.js";
+import { Container, Line } from "../components/basic.js";
+import { Button } from "../components/buttons.js";
+import { Text } from "../components/text.js";
+import type { UIOptions } from "./BridgeOrchestrator.js";
+import { ChainIcon } from "./common/TokenAndChain.js";
+import { WithHeader } from "./common/WithHeader.js";
+
+export interface TransactionPaymentProps {
+ /**
+ * UI configuration and mode
+ */
+ uiOptions: Extract;
+
+ /**
+ * ThirdwebClient for blockchain interactions
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when user confirms transaction execution
+ */
+ onContinue: (amount: string, token: Token, receiverAddress: Address) => void;
+
+ /**
+ * Connect options for wallet connection
+ */
+ connectOptions?: PayEmbedConnectOptions;
+}
+
+export function TransactionPayment({
+ uiOptions,
+ client,
+ onContinue,
+ connectOptions,
+}: TransactionPaymentProps) {
+ const theme = useCustomTheme();
+ const activeAccount = useActiveAccount();
+
+ // Get chain metadata for native currency symbol
+ const chainMetadata = useChainMetadata(uiOptions.transaction.chain);
+
+ // Use the extracted hook for transaction details
+ const transactionDataQuery = useTransactionDetails({
+ transaction: uiOptions.transaction,
+ client,
+ });
+
+ const contractName =
+ transactionDataQuery.data?.contractMetadata?.name || "Unknown Contract";
+ const functionName =
+ transactionDataQuery.data?.functionInfo?.functionName || "Contract Call";
+ const isLoading = transactionDataQuery.isLoading || chainMetadata.isLoading;
+
+ const buttonLabel = `Execute ${functionName}`;
+
+ // Skeleton component for loading state
+ const SkeletonRow = ({ width = "100%" }: { width?: string }) => (
+
+
+
+
+ );
+
+ const SkeletonHeader = () => (
+
+ {/* USD Value Skeleton */}
+
+
+ {/* Function Name Skeleton */}
+
+
+ );
+
+ if (isLoading) {
+ return (
+
+ {/* Loading Header */}
+
+ );
+ }
+
+ return (
+
+ {/* Cost and Function Name section */}
+
+ {/* USD Value */}
+
+ {transactionDataQuery.data?.usdValueDisplay ||
+ transactionDataQuery.data?.txCostDisplay}
+
+
+ {/* Function Name */}
+
+ {functionName}
+
+
+
+
+
+ Contract
+
+
+ {contractName}
+
+
+
+
+
+ Address
+
+
+ {shortenAddress(uiOptions.transaction.to as string)}
+
+
+
+
+
+ Network
+
+
+
+
+
+
+
+ Cost
+
+
+ {transactionDataQuery.data?.txCostDisplay}
+
+
+
+
+
+ Network fees
+
+
+ {transactionDataQuery.data?.gasCostDisplay}
+
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx b/packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx
new file mode 100644
index 00000000000..6d32d79aadb
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/TransactionWidget.tsx
@@ -0,0 +1,502 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import type { Token } from "../../../../bridge/index.js";
+import type { Chain } from "../../../../chains/types.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../constants/addresses.js";
+import {
+ type PreparedTransaction,
+ prepareTransaction,
+} from "../../../../transaction/prepare-transaction.js";
+import { type Address, checksumAddress } from "../../../../utils/address.js";
+import { stringify } from "../../../../utils/json.js";
+import type { Wallet } from "../../../../wallets/interfaces/wallet.js";
+import type { SmartWalletOptions } from "../../../../wallets/smart/types.js";
+import type { AppMetadata } from "../../../../wallets/types.js";
+import type { WalletId } from "../../../../wallets/wallet-types.js";
+import { CustomThemeProvider } from "../../../core/design-system/CustomThemeProvider.js";
+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 { SupportedTokens } from "../../../core/utils/defaultTokens.js";
+import { EmbedContainer } from "../ConnectWallet/Modal/ConnectEmbed.js";
+import { useConnectLocale } from "../ConnectWallet/locale/getConnectLocale.js";
+import { DynamicHeight } from "../components/DynamicHeight.js";
+import { Spinner } from "../components/Spinner.js";
+import type { LocaleId } from "../types.js";
+import { BridgeOrchestrator, type UIOptions } from "./BridgeOrchestrator.js";
+import { UnsupportedTokenScreen } from "./UnsupportedTokenScreen.js";
+
+export type TransactionWidgetProps = {
+ supportedTokens?: SupportedTokens;
+ /**
+ * A client is the entry point to the thirdweb SDK.
+ * It is required for all other actions.
+ * You can create a client using the `createThirdwebClient` function. Refer to the [Creating a Client](https://portal.thirdweb.com/typescript/v5/client) documentation for more information.
+ *
+ * You must provide a `clientId` or `secretKey` in order to initialize a client. Pass `clientId` if you want for client-side usage and `secretKey` for server-side usage.
+ *
+ * ```tsx
+ * import { createThirdwebClient } from "thirdweb";
+ *
+ * const client = createThirdwebClient({
+ * clientId: "",
+ * })
+ * ```
+ */
+ client: ThirdwebClient;
+ /**
+ * By default - ConnectButton UI uses the `en-US` locale for english language users.
+ *
+ * You can customize the language used in the ConnectButton UI by setting the `locale` prop.
+ *
+ * Refer to the [`LocaleId`](https://portal.thirdweb.com/references/typescript/v5/LocaleId) type for supported locales.
+ */
+ locale?: LocaleId;
+ /**
+ * Set the theme for the `TransactionWidget` component. By default it is set to `"dark"`
+ *
+ * theme can be set to either `"dark"`, `"light"` or a custom theme object.
+ * You can also import [`lightTheme`](https://portal.thirdweb.com/references/typescript/v5/lightTheme)
+ * or [`darkTheme`](https://portal.thirdweb.com/references/typescript/v5/darkTheme)
+ * functions from `thirdweb/react` to use the default themes as base and overrides parts of it.
+ * @example
+ * ```ts
+ * import { lightTheme } from "thirdweb/react";
+ *
+ * const customTheme = lightTheme({
+ * colors: {
+ * modalBg: 'red'
+ * }
+ * })
+ *
+ * function Example() {
+ * return ;
+
+ /**
+ * Callback triggered when the purchase is successful.
+ */
+ onSuccess?: () => void;
+
+ /**
+ * Callback triggered when the purchase encounters an error.
+ */
+ onError?: (error: Error) => void;
+
+ /**
+ * Callback triggered when the user cancels the purchase.
+ */
+ onCancel?: () => void;
+
+ /**
+ * Arbitrary data to be included in the returned status and webhook events.
+ */
+ transaction: PreparedTransaction;
+
+ /**
+ * @hidden
+ */
+ paymentLinkId?: string;
+};
+
+// Enhanced UIOptions to handle unsupported token state
+type UIOptionsResult =
+ | { type: "success"; data: UIOptions }
+ | {
+ type: "indexing_token";
+ token: Token;
+ chain: Chain;
+ }
+ | {
+ type: "unsupported_token";
+ tokenAddress: Address;
+ chain: Chain;
+ };
+
+/**
+ * Widget a prebuilt UI for purchasing a specific token.
+ *
+ * @param props - Props of type [`TransactionWidgetProps`](https://portal.thirdweb.com/references/typescript/v5/TransactionWidgetProps) to configure the TransactionWidget component.
+ *
+ * @example
+ * ### Default configuration
+ *
+ * By default, the `TransactionWidget` component will allows users to fund their wallets with crypto or fiat on any of the supported chains..
+ *
+ * ```tsx
+ * => {
+ const transaction = prepareTransaction({
+ ...props.transaction,
+ erc20Value: props.amount
+ ? {
+ amountWei: props.amount,
+ tokenAddress: checksumAddress(
+ props.tokenAddress || NATIVE_TOKEN_ADDRESS,
+ ),
+ }
+ : props.transaction.erc20Value,
+ });
+
+ return {
+ type: "success",
+ data: {
+ mode: "transaction",
+ metadata: {
+ title: props.title,
+ description: props.description,
+ image: props.image,
+ },
+ transaction,
+ },
+ };
+ },
+ });
+
+ let content = null;
+ if (!localeQuery.data || bridgeDataQuery.isLoading) {
+ content = (
+ {
+ props.onSuccess?.();
+ }}
+ onError={(err: Error) => {
+ props.onError?.(err);
+ }}
+ onCancel={() => {
+ props.onCancel?.();
+ }}
+ presetOptions={props.presetOptions}
+ receiverAddress={undefined}
+ />
+ );
+ }
+
+ return (
+
+
+ {content}
+
+
+ );
+}
+
+/**
+ * Connection options for the `TransactionWidget` component
+ *
+ * @example
+ * ```tsx
+ *
+ {/* Error Icon */}
+
+ Testnet Not Supported
+
+
+ The Universal Bridge does not support testnets at this time.
+
+
+ );
+ }
+
+ return (
+
+ {/* Error Icon */}
+
+ Token Not Supported
+
+
+ This token or chain is not supported by the Universal Bridge.
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/common/TokenAndChain.tsx b/packages/thirdweb/src/react/web/ui/Bridge/common/TokenAndChain.tsx
new file mode 100644
index 00000000000..4b195daf67a
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/common/TokenAndChain.tsx
@@ -0,0 +1,203 @@
+import { useMemo } from "react";
+import type { Token } from "../../../../../bridge/index.js";
+import type { Chain } from "../../../../../chains/types.js";
+import { getCachedChain } from "../../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { resolveScheme } from "../../../../../utils/ipfs.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { iconSize, spacing } from "../../../../core/design-system/index.js";
+import {
+ useChainIconUrl,
+ useChainMetadata,
+} from "../../../../core/hooks/others/useChainQuery.js";
+import { genericTokenIcon } from "../../../../core/utils/walletIcon.js";
+import { isNativeToken } from "../../ConnectWallet/screens/nativeToken.js";
+import { ChainName } from "../../components/ChainName.js";
+import { Img } from "../../components/Img.js";
+import { Container } from "../../components/basic.js";
+import { fallbackChainIcon } from "../../components/fallbackChainIcon.js";
+import { Text } from "../../components/text.js";
+
+export function TokenAndChain({
+ token,
+ client,
+ size,
+ style,
+}: {
+ token: Omit;
+ client: ThirdwebClient;
+ size: keyof typeof iconSize;
+ style?: React.CSSProperties;
+}) {
+ const theme = useCustomTheme();
+ const chain = getCachedChain(token.chainId);
+ return (
+
+
+
+
+ )}
+
+
+
+
+ {token.name}
+
+
+
+ );
+}
+
+function TokenIconWithFallback(props: {
+ token: Omit;
+ size: keyof typeof iconSize;
+ client: ThirdwebClient;
+}) {
+ const chain = getCachedChain(props.token.chainId);
+ const chainMeta = useChainMetadata(chain).data;
+ const theme = useCustomTheme();
+
+ const tokenImage = useMemo(() => {
+ if (
+ isNativeToken(props.token) ||
+ props.token.address === NATIVE_TOKEN_ADDRESS
+ ) {
+ if (chainMeta?.nativeCurrency.symbol === "ETH") {
+ return "ipfs://QmcxZHpyJa8T4i63xqjPYrZ6tKrt55tZJpbXcjSDKuKaf9/ethereum/512.png"; // ETH icon
+ }
+ return chainMeta?.icon?.url;
+ }
+ return props.token.iconUri;
+ }, [props.token, chainMeta?.icon?.url, chainMeta?.nativeCurrency.symbol]);
+
+ return tokenImage ? (
+ 
+ ) : (
+
+
+ {props.token.symbol.slice(0, 1)}
+
+
+ );
+}
+
+export const ChainIcon: React.FC<{
+ chain: Chain;
+ size: keyof typeof iconSize;
+ client: ThirdwebClient;
+}> = (props) => {
+ const { url } = useChainIconUrl(props.chain);
+ return (
+
+ 
+
+ );
+};
+
+const getSrcChainIcon = (props: {
+ client: ThirdwebClient;
+ chainIconUrl?: string;
+}) => {
+ const url = props.chainIconUrl;
+ if (!url) {
+ return fallbackChainIcon;
+ }
+ try {
+ return resolveScheme({
+ uri: url,
+ client: props.client,
+ });
+ } catch {
+ return fallbackChainIcon;
+ }
+};
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/common/TokenBalanceRow.tsx b/packages/thirdweb/src/react/web/ui/Bridge/common/TokenBalanceRow.tsx
new file mode 100644
index 00000000000..6f5ba2a3312
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/common/TokenBalanceRow.tsx
@@ -0,0 +1,112 @@
+import styled from "@emotion/styled";
+import type { Token } from "../../../../../bridge/index.js";
+import { getCachedChain } from "../../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { spacing } from "../../../../core/design-system/index.js";
+import { FiatValue } from "../../ConnectWallet/screens/Buy/swap/FiatValue.js";
+import { Container } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+import { TokenAndChain } from "./TokenAndChain.js";
+
+export function TokenBalanceRow({
+ client,
+ token,
+ amount,
+ onClick,
+ style,
+}: {
+ client: ThirdwebClient;
+ token: Token;
+ amount: string;
+ onClick: (token: Token) => void;
+ style?: React.CSSProperties;
+}) {
+ const chain = getCachedChain(token.chainId);
+ return (
+ onClick(token)}
+ variant="secondary"
+ style={{
+ display: "flex",
+ justifyContent: "space-between",
+ padding: `${spacing.sm} ${spacing.md}`,
+ ...style,
+ }}
+ >
+
+
+
+ {`${Number(amount).toLocaleString(undefined, {
+ maximumFractionDigits: 6,
+ minimumFractionDigits: 0,
+ })} ${token.symbol}`}
+
+
+
+
+ );
+}
+
+const StyledButton = /* @__PURE__ */ styled(Button)((props) => {
+ const theme = useCustomTheme();
+ return {
+ background: "transparent",
+ justifyContent: "space-between",
+ flexWrap: "nowrap",
+ flexDirection: "row",
+ padding: spacing.sm,
+ paddingRight: spacing.xs,
+ gap: spacing.sm,
+ "&:hover": {
+ background: theme.colors.secondaryButtonBg,
+ },
+ transition: "background 200ms ease, transform 150ms ease",
+ ...props.style,
+ };
+});
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/common/WithHeader.tsx b/packages/thirdweb/src/react/web/ui/Bridge/common/WithHeader.tsx
new file mode 100644
index 00000000000..359006e00ba
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/common/WithHeader.tsx
@@ -0,0 +1,65 @@
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { resolveScheme } from "../../../../../utils/ipfs.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { radius } from "../../../../core/design-system/index.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container } from "../../components/basic.js";
+import { Text } from "../../components/text.js";
+import type { UIOptions } from "../BridgeOrchestrator.js";
+
+export function WithHeader({
+ children,
+ uiOptions,
+ defaultTitle,
+ client,
+}: {
+ children: React.ReactNode;
+ uiOptions: UIOptions;
+ defaultTitle: string;
+ client: ThirdwebClient;
+}) {
+ const theme = useCustomTheme();
+ return (
+
+ {/* image */}
+ {uiOptions.metadata?.image && (
+
+ )}
+
+
+ {uiOptions.metadata?.title || defaultTitle}
+
+
+ {/* Description */}
+ {uiOptions.metadata?.description && (
+ <>
+
+ {uiOptions.metadata?.description}
+
+
+ )}
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentDetails.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentDetails.tsx
new file mode 100644
index 00000000000..13e1fba6f20
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentDetails.tsx
@@ -0,0 +1,318 @@
+"use client";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { radius, spacing } from "../../../../core/design-system/index.js";
+import type { BridgePrepareResult } from "../../../../core/hooks/useBridgePrepare.js";
+import type { PaymentMethod } from "../../../../core/machines/paymentMachine.js";
+import {} from "../../ConnectWallet/screens/Buy/fiat/currencies.js";
+import {
+ formatCurrencyAmount,
+ formatTokenAmount,
+} from "../../ConnectWallet/screens/formatTokenBalance.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container, ModalHeader } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+import type { UIOptions } from "../BridgeOrchestrator.js";
+import { PaymentOverview } from "./PaymentOverview.js";
+
+export interface PaymentDetailsProps {
+ /**
+ * The UI mode to use
+ */
+ uiOptions: UIOptions;
+ /**
+ * The client to use
+ */
+ client: ThirdwebClient;
+ /**
+ * The payment method to use
+ */
+ paymentMethod: PaymentMethod;
+ /**
+ * The prepared quote to preview
+ */
+ preparedQuote: BridgePrepareResult;
+
+ /**
+ * Called when user confirms the route
+ */
+ onConfirm: () => void;
+
+ /**
+ * Called when user wants to go back
+ */
+ onBack: () => void;
+
+ /**
+ * Called when an error occurs
+ */
+ onError: (error: Error) => void;
+}
+
+export function PaymentDetails({
+ uiOptions,
+ client,
+ paymentMethod,
+ preparedQuote,
+ onConfirm,
+ onBack,
+ onError,
+}: PaymentDetailsProps) {
+ const theme = useCustomTheme();
+
+ const handleConfirm = () => {
+ try {
+ onConfirm();
+ } catch (error) {
+ onError(error as Error);
+ }
+ };
+
+ // Extract common data based on quote type
+ const getDisplayData = () => {
+ switch (preparedQuote.type) {
+ case "transfer": {
+ const token =
+ paymentMethod.type === "wallet"
+ ? paymentMethod.originToken
+ : undefined;
+ if (!token) {
+ // can never happen
+ onError(new Error("Invalid payment method"));
+ return {
+ originToken: undefined,
+ destinationToken: undefined,
+ originAmount: "0",
+ destinationAmount: "0",
+ estimatedTime: 0,
+ };
+ }
+ return {
+ originToken: token,
+ destinationToken: token,
+ originAmount: formatTokenAmount(
+ preparedQuote.originAmount,
+ token.decimals,
+ ),
+ destinationAmount: formatTokenAmount(
+ preparedQuote.destinationAmount,
+ token.decimals,
+ ),
+ estimatedTime: preparedQuote.estimatedExecutionTimeMs,
+ };
+ }
+ case "buy": {
+ const method =
+ paymentMethod.type === "wallet" ? paymentMethod : undefined;
+ if (!method) {
+ // can never happen
+ onError(new Error("Invalid payment method"));
+ return {
+ originToken: undefined,
+ destinationToken: undefined,
+ originAmount: "0",
+ destinationAmount: "0",
+ estimatedTime: 0,
+ };
+ }
+ return {
+ originToken:
+ paymentMethod.type === "wallet"
+ ? paymentMethod.originToken
+ : undefined,
+ destinationToken:
+ preparedQuote.steps[preparedQuote.steps.length - 1]
+ ?.destinationToken,
+ originAmount: formatTokenAmount(
+ preparedQuote.originAmount,
+ method.originToken.decimals,
+ ),
+ destinationAmount: formatTokenAmount(
+ preparedQuote.destinationAmount,
+ preparedQuote.steps[preparedQuote.steps.length - 1]
+ ?.destinationToken?.decimals ?? 18,
+ ),
+ estimatedTime: preparedQuote.estimatedExecutionTimeMs,
+ };
+ }
+ case "onramp": {
+ const method =
+ paymentMethod.type === "fiat" ? paymentMethod : undefined;
+ if (!method) {
+ // can never happen
+ onError(new Error("Invalid payment method"));
+ return {
+ originToken: undefined,
+ destinationToken: undefined,
+ originAmount: "0",
+ destinationAmount: "0",
+ estimatedTime: 0,
+ };
+ }
+ return {
+ originToken: undefined, // Onramp starts with fiat
+ destinationToken: preparedQuote.destinationToken,
+ originAmount: formatCurrencyAmount(
+ method.currency,
+ Number(preparedQuote.currencyAmount),
+ ),
+ destinationAmount: formatTokenAmount(
+ preparedQuote.destinationAmount,
+ preparedQuote.destinationToken.decimals,
+ ),
+ estimatedTime: undefined,
+ };
+ }
+ default: {
+ throw new Error(
+ `Unsupported bridge prepare type: ${preparedQuote.type}`,
+ );
+ }
+ }
+ };
+
+ const displayData = getDisplayData();
+
+ return (
+
+
+ {/* Quote Summary */}
+
+ {displayData.destinationToken && (
+
+
+
+ Estimated Time
+
+
+ {displayData.estimatedTime
+ ? `~${Math.ceil(displayData.estimatedTime / 60000)} min`
+ : "~2 min"}
+
+
+
+ {preparedQuote.steps.length > 1 ? (
+
+
+ Route Length
+
+
+ {preparedQuote.steps.length} step
+ {preparedQuote.steps.length !== 1 ? "s" : ""}
+
+
+ ) : null}
+
+
+
+ {/* Route Steps */}
+ {preparedQuote.steps.length > 1 && (
+
+
+ {preparedQuote.steps.map((step, stepIndex) => (
+
+ {/* Step Header */}
+
+
+
+ {stepIndex + 1}
+
+
+
+
+
+
+ {step.originToken.symbol} →{" "}
+ {step.destinationToken.symbol}
+
+
+ {step.originToken.name} to{" "}
+ {step.destinationToken.name}
+
+
+
+
+
+ ))}
+
+
+ )}
+
+
+
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentOverview.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentOverview.tsx
new file mode 100644
index 00000000000..d51918c5380
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-details/PaymentOverview.tsx
@@ -0,0 +1,301 @@
+import type { Token } from "../../../../../bridge/index.js";
+import { defineChain } from "../../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { radius, spacing } from "../../../../core/design-system/index.js";
+import { useTransactionDetails } from "../../../../core/hooks/useTransactionDetails.js";
+import type { PaymentMethod } from "../../../../core/machines/paymentMachine.js";
+import { getFiatCurrencyIcon } from "../../ConnectWallet/screens/Buy/fiat/currencies.js";
+import { FiatValue } from "../../ConnectWallet/screens/Buy/swap/FiatValue.js";
+import { StepConnectorArrow } from "../../ConnectWallet/screens/Buy/swap/StepConnector.js";
+import { WalletRow } from "../../ConnectWallet/screens/Buy/swap/WalletRow.js";
+import { Container } from "../../components/basic.js";
+import { Text } from "../../components/text.js";
+import type { UIOptions } from "../BridgeOrchestrator.js";
+import { TokenBalanceRow } from "../common/TokenBalanceRow.js";
+
+export function PaymentOverview(props: {
+ uiOptions: UIOptions;
+ receiver: string;
+ sender?: string;
+ client: ThirdwebClient;
+ paymentMethod: PaymentMethod;
+ toToken: Token;
+ fromAmount: string;
+ toAmount: string;
+}) {
+ const theme = useCustomTheme();
+ const sender =
+ props.sender ||
+ (props.paymentMethod.type === "wallet"
+ ? props.paymentMethod.payerWallet.getAccount()?.address
+ : undefined);
+ const isDifferentRecipient =
+ props.receiver.toLowerCase() !== sender?.toLowerCase();
+ return (
+
+ {/* Sell */}
+
+ {sender && (
+
+
+ )}
+ {props.paymentMethod.type === "wallet" && (
+ {}}
+ style={{
+ background: "transparent",
+ borderRadius: 0,
+ border: "none",
+ }}
+ />
+ )}
+ {props.paymentMethod.type === "fiat" && (
+
+
+ {getFiatCurrencyIcon({
+ currency: props.paymentMethod.currency,
+ size: "lg",
+ })}
+
+
+ {props.paymentMethod.currency}
+
+
+ {props.paymentMethod.onramp.charAt(0).toUpperCase() +
+ props.paymentMethod.onramp.slice(1)}
+
+
+
+
+ {props.fromAmount}
+
+
+ )}
+
+ {/* Connector Icon */}
+
+ {isDifferentRecipient && (
+
+
+ )}
+ {props.uiOptions.mode === "direct_payment" && (
+
+
+
+ {props.uiOptions.metadata?.title || "Payment"}
+
+ {props.uiOptions.metadata?.description && (
+
+ {props.uiOptions.metadata.description}
+
+ )}
+
+
+
+ {props.uiOptions.paymentInfo.amount} {props.toToken.symbol}
+
+
+
+ )}
+ {props.uiOptions.mode === "fund_wallet" && (
+ {}}
+ style={{
+ background: "transparent",
+ borderRadius: 0,
+ border: "none",
+ }}
+ />
+ )}
+ {props.uiOptions.mode === "transaction" && (
+
+
+ );
+}
+
+const TransactionOverViewCompact = (props: {
+ uiOptions: Extract;
+ client: ThirdwebClient;
+}) => {
+ const theme = useCustomTheme();
+ const txInfo = useTransactionDetails({
+ transaction: props.uiOptions.transaction,
+ client: props.client,
+ });
+
+ if (!txInfo.data) {
+ // Skeleton loading state
+ return (
+
+
+ {/* Title skeleton */}
+
+ {/* Description skeleton - only if metadata exists */}
+ {props.uiOptions.metadata?.description && (
+
+ )}
+
+
+ {/* Function name skeleton */}
+
+
+
+ );
+ }
+
+ return (
+
+
+
+ {props.uiOptions.metadata?.title || "Transaction"}
+
+ {props.uiOptions.metadata?.description && (
+
+ {props.uiOptions.metadata.description}
+
+ )}
+
+
+
+ {txInfo.data.functionInfo.functionName}
+
+
+
+ );
+};
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/FiatProviderSelection.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/FiatProviderSelection.tsx
new file mode 100644
index 00000000000..3611b05cd12
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/FiatProviderSelection.tsx
@@ -0,0 +1,186 @@
+"use client";
+import { useMemo } from "react";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { checksumAddress } from "../../../../../utils/address.js";
+import { toTokens } from "../../../../../utils/units.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import {
+ iconSize,
+ radius,
+ spacing,
+} from "../../../../core/design-system/index.js";
+import { useBuyWithFiatQuotesForProviders } from "../../../../core/hooks/pay/useBuyWithFiatQuotesForProviders.js";
+import { Img } from "../../components/Img.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Spinner } from "../../components/Spinner.js";
+import { Container } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+
+interface FiatProviderSelectionProps {
+ client: ThirdwebClient;
+ onProviderSelected: (provider: "coinbase" | "stripe" | "transak") => void;
+ toChainId: number;
+ toTokenAddress: string;
+ toAddress: string;
+ toAmount?: string;
+}
+
+const PROVIDERS = [
+ {
+ id: "coinbase" as const,
+ name: "Coinbase",
+ description: "Fast and secure payments",
+ iconUri: "https://i.ibb.co/LDJ3Rk2t/Frame-5.png",
+ },
+ {
+ id: "stripe" as const,
+ name: "Stripe",
+ description: "Trusted payment processing",
+ iconUri: "https://i.ibb.co/CpgQC2Lf/images-3.png",
+ },
+ {
+ id: "transak" as const,
+ name: "Transak",
+ description: "Global payment solution",
+ iconUri: "https://i.ibb.co/Xx2r882p/Transak-official-symbol-1.png",
+ },
+];
+
+export function FiatProviderSelection({
+ onProviderSelected,
+ client,
+ toChainId,
+ toTokenAddress,
+ toAddress,
+ toAmount,
+}: FiatProviderSelectionProps) {
+ const theme = useCustomTheme();
+
+ // Fetch quotes for all providers
+ const quoteQueries = useBuyWithFiatQuotesForProviders({
+ client,
+ chainId: toChainId,
+ tokenAddress: checksumAddress(toTokenAddress),
+ receiver: checksumAddress(toAddress),
+ amount: toAmount || "0",
+ currency: "USD",
+ });
+
+ const quotes = useMemo(() => {
+ return quoteQueries.map((q) => q.data).filter((q) => !!q);
+ }, [quoteQueries]);
+
+ // TODO: add a "remember my choice" checkbox
+
+ return (
+ <>
+
+ {quotes.length > 0 ? (
+ quotes
+ .sort((a, b) => a.currencyAmount - b.currencyAmount)
+ .map((quote, index) => {
+ const provider = PROVIDERS.find(
+ (p) => p.id === quote.intent.onramp,
+ );
+ if (!provider) {
+ return null;
+ }
+
+ return (
+
+
+
+ );
+ })
+ ) : (
+
+
+ Generating quotes...
+
+
+ )}
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/PaymentSelection.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/PaymentSelection.tsx
new file mode 100644
index 00000000000..fc97f34e969
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/PaymentSelection.tsx
@@ -0,0 +1,268 @@
+"use client";
+import { useEffect, useState } from "react";
+import type { Token } from "../../../../../bridge/types/Token.js";
+import { defineChain } from "../../../../../chains/utils.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import type { Address } from "../../../../../utils/address.js";
+import { toUnits } from "../../../../../utils/units.js";
+import type { Wallet } from "../../../../../wallets/interfaces/wallet.js";
+import { usePaymentMethods } from "../../../../core/hooks/usePaymentMethods.js";
+import { useActiveWallet } from "../../../../core/hooks/wallets/useActiveWallet.js";
+import { useConnectedWallets } from "../../../../core/hooks/wallets/useConnectedWallets.js";
+import type { PaymentMethod } from "../../../../core/machines/paymentMachine.js";
+import type { ConnectLocale } from "../../ConnectWallet/locale/types.js";
+import { WalletSwitcherConnectionScreen } from "../../ConnectWallet/screens/WalletSwitcherConnectionScreen.js";
+import type { PayEmbedConnectOptions } from "../../PayEmbed.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container, ModalHeader } from "../../components/basic.js";
+import { FiatProviderSelection } from "./FiatProviderSelection.js";
+import { TokenSelection } from "./TokenSelection.js";
+import { WalletFiatSelection } from "./WalletFiatSelection.js";
+
+export interface PaymentSelectionProps {
+ /**
+ * The destination token to bridge to
+ */
+ destinationToken: Token;
+
+ /**
+ * The destination amount to bridge
+ */
+ destinationAmount: string;
+
+ /**
+ * The receiver address
+ */
+ receiverAddress?: Address;
+
+ /**
+ * ThirdwebClient for API calls
+ */
+ client: ThirdwebClient;
+
+ /**
+ * Called when user selects a payment method
+ */
+ onPaymentMethodSelected: (paymentMethod: PaymentMethod) => void;
+
+ /**
+ * Called when an error occurs
+ */
+ onError: (error: Error) => void;
+
+ /**
+ * Called when user wants to go back
+ */
+ onBack?: () => void;
+
+ /**
+ * Connect options for wallet connection
+ */
+ connectOptions?: PayEmbedConnectOptions;
+
+ /**
+ * Locale for connect UI
+ */
+ connectLocale: ConnectLocale;
+
+ /**
+ * Whether to include the destination token in the payment methods
+ */
+ includeDestinationToken?: boolean;
+}
+
+type Step =
+ | { type: "walletSelection" }
+ | { type: "tokenSelection"; selectedWallet: Wallet }
+ | { type: "fiatProviderSelection" }
+ | { type: "walletConnection" };
+
+export function PaymentSelection({
+ destinationToken,
+ client,
+ destinationAmount,
+ receiverAddress,
+ onPaymentMethodSelected,
+ onError,
+ onBack,
+ connectOptions,
+ connectLocale,
+ includeDestinationToken,
+}: PaymentSelectionProps) {
+ const connectedWallets = useConnectedWallets();
+ const activeWallet = useActiveWallet();
+
+ const [currentStep, setCurrentStep] = useState({
+ type: "walletSelection",
+ });
+
+ const payerWallet =
+ currentStep.type === "tokenSelection"
+ ? currentStep.selectedWallet
+ : activeWallet;
+ const {
+ data: paymentMethods,
+ isLoading: paymentMethodsLoading,
+ error: paymentMethodsError,
+ } = usePaymentMethods({
+ destinationToken,
+ destinationAmount,
+ client,
+ includeDestinationToken:
+ includeDestinationToken ||
+ receiverAddress?.toLowerCase() !==
+ payerWallet?.getAccount()?.address?.toLowerCase(),
+ payerWallet,
+ });
+
+ // Handle error from usePaymentMethods
+ useEffect(() => {
+ if (paymentMethodsError) {
+ onError(paymentMethodsError as Error);
+ }
+ }, [paymentMethodsError, onError]);
+
+ const handlePaymentMethodSelected = (paymentMethod: PaymentMethod) => {
+ try {
+ onPaymentMethodSelected(paymentMethod);
+ } catch (error) {
+ onError(error as Error);
+ }
+ };
+
+ const handleWalletSelected = (wallet: Wallet) => {
+ setCurrentStep({ type: "tokenSelection", selectedWallet: wallet });
+ };
+
+ const handleConnectWallet = async () => {
+ setCurrentStep({ type: "walletConnection" });
+ };
+
+ const handleFiatSelected = () => {
+ setCurrentStep({ type: "fiatProviderSelection" });
+ };
+
+ const handleBackToWalletSelection = () => {
+ setCurrentStep({ type: "walletSelection" });
+ };
+
+ const handleOnrampProviderSelected = (
+ provider: "coinbase" | "stripe" | "transak",
+ ) => {
+ if (!payerWallet) {
+ onError(new Error("No wallet available for fiat payment"));
+ return;
+ }
+
+ const fiatPaymentMethod: PaymentMethod = {
+ type: "fiat",
+ payerWallet,
+ currency: "USD", // Default to USD for now
+ onramp: provider,
+ };
+ handlePaymentMethodSelected(fiatPaymentMethod);
+ };
+
+ const getStepTitle = () => {
+ switch (currentStep.type) {
+ case "walletSelection":
+ return "Choose Payment Method";
+ case "tokenSelection":
+ return "Select Token";
+ case "fiatProviderSelection":
+ return "Select Payment Provider";
+ case "walletConnection":
+ return "Connect Wallet";
+ }
+ };
+
+ const getBackHandler = () => {
+ switch (currentStep.type) {
+ case "walletSelection":
+ return onBack;
+ case "tokenSelection":
+ case "fiatProviderSelection":
+ case "walletConnection":
+ return handleBackToWalletSelection;
+ }
+ };
+
+ // Handle rendering WalletSwitcherConnectionScreen
+ if (currentStep.type === "walletConnection") {
+ const destinationChain = destinationToken
+ ? defineChain(destinationToken.chainId)
+ : undefined;
+ const chains = destinationChain
+ ? [destinationChain, ...(connectOptions?.chains || [])]
+ : connectOptions?.chains;
+
+ return (
+ w.id !== "inApp")}
+ />
+ );
+ }
+
+ return (
+
+
+ {currentStep.type === "walletSelection" && (
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/TokenSelection.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/TokenSelection.tsx
new file mode 100644
index 00000000000..cc1f8e83778
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/TokenSelection.tsx
@@ -0,0 +1,282 @@
+"use client";
+import type { Token } from "../../../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { radius, spacing } from "../../../../core/design-system/index.js";
+import { useBridgeQuote } from "../../../../core/hooks/useBridgeQuote.js";
+import type { PaymentMethod } from "../../../../core/machines/paymentMachine.js";
+import { formatTokenAmount } from "../../ConnectWallet/screens/formatTokenBalance.js";
+import { Skeleton } from "../../components/Skeleton.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+import { TokenAndChain } from "../common/TokenAndChain.js";
+
+interface TokenSelectionProps {
+ paymentMethods: PaymentMethod[];
+ paymentMethodsLoading: boolean;
+ client: ThirdwebClient;
+ onPaymentMethodSelected: (paymentMethod: PaymentMethod) => void;
+ onBack: () => void;
+ destinationToken: Token;
+ destinationAmount: bigint;
+}
+
+// Individual payment method token row component
+interface PaymentMethodTokenRowProps {
+ paymentMethod: PaymentMethod & { type: "wallet" };
+ destinationToken: Token;
+ destinationAmount: bigint;
+ client: ThirdwebClient;
+ onPaymentMethodSelected: (paymentMethod: PaymentMethod) => void;
+}
+
+function PaymentMethodTokenRow({
+ paymentMethod,
+ destinationToken,
+ destinationAmount,
+ client,
+ onPaymentMethodSelected,
+}: PaymentMethodTokenRowProps) {
+ const theme = useCustomTheme();
+
+ // Fetch individual quote for this specific token pair
+ const {
+ data: quote,
+ isLoading: quoteLoading,
+ error: quoteError,
+ } = useBridgeQuote({
+ originToken: paymentMethod.originToken,
+ destinationToken,
+ destinationAmount,
+ client,
+ });
+
+ // Use the fetched originAmount if available, otherwise fall back to the one from paymentMethod
+ const displayOriginAmount = quote?.originAmount;
+ const hasEnoughBalance = displayOriginAmount
+ ? paymentMethod.balance >= displayOriginAmount
+ : false;
+
+ return (
+
+ );
+}
+
+export function TokenSelection({
+ paymentMethods,
+ paymentMethodsLoading,
+ client,
+ onPaymentMethodSelected,
+ onBack,
+ destinationToken,
+ destinationAmount,
+}: TokenSelectionProps) {
+ const theme = useCustomTheme();
+
+ if (paymentMethodsLoading) {
+ return (
+ <>
+
+ Loading your tokens
+
+
+ {/* Skeleton rows matching PaymentMethodTokenRow structure */}
+ {[1, 2, 3].map((i) => (
+
+
+ {/* Left side: Token icon and name skeleton */}
+
+ {/* Token icon skeleton */}
+
+
+ {/* Token name skeleton */}
+
+
+
+ {/* Right side: Price and balance skeleton */}
+
+ {/* Price amount skeleton */}
+
+
+
+
+
+ ))}
+
+
+ );
+ }
+
+ if (paymentMethods.length === 0) {
+ return (
+
+
+ No available tokens found for this wallet
+
+
+ Try connecting a different wallet or pay with card
+
+
+ );
+ }
+
+ return (
+ <>
+
+ Select payment token
+
+
+ {paymentMethods
+ .filter((method) => method.type === "wallet")
+ .map((method) => (
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/WalletFiatSelection.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/WalletFiatSelection.tsx
new file mode 100644
index 00000000000..fc83b6adf93
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-selection/WalletFiatSelection.tsx
@@ -0,0 +1,172 @@
+"use client";
+import { ChevronRightIcon, PlusIcon } from "@radix-ui/react-icons";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+import type { Wallet } from "../../../../../wallets/interfaces/wallet.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import {
+ iconSize,
+ radius,
+ spacing,
+} from "../../../../core/design-system/index.js";
+import { CreditCardIcon } from "../../ConnectWallet/icons/CreditCardIcon.js";
+import { WalletRow } from "../../ConnectWallet/screens/Buy/swap/WalletRow.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+
+interface WalletFiatSelectionProps {
+ connectedWallets: Wallet[];
+ client: ThirdwebClient;
+ onWalletSelected: (wallet: Wallet) => void;
+ onFiatSelected: () => void;
+ onConnectWallet: () => void;
+}
+
+export function WalletFiatSelection({
+ connectedWallets,
+ client,
+ onWalletSelected,
+ onFiatSelected,
+ onConnectWallet,
+}: WalletFiatSelectionProps) {
+ const theme = useCustomTheme();
+
+ return (
+ <>
+
+ Pay with Crypto
+
+
+ {connectedWallets.map((wallet) => {
+ const account = wallet.getAccount();
+ if (!account?.address) {
+ return null;
+ }
+ return (
+
+ );
+ })}
+
+
+ Pay with Fiat
+
+
+ => {
+ const isOnramp = status.type === "onramp";
+
+ if (isOnramp && preparedQuote.type === "onramp") {
+ // For onramp, create a display ID since OnrampStatus doesn't have paymentId
+ return {
+ type: "paymentId" as const,
+ id: preparedQuote.id,
+ label: "Onramp Payment",
+ destinationToken: preparedQuote.destinationToken,
+ chain: await getChainMetadata(
+ defineChain(preparedQuote.destinationToken.chainId),
+ ),
+ amountPaid: `${preparedQuote.currencyAmount} ${preparedQuote.currency}`,
+ amountReceived: `${formatTokenAmount(
+ preparedQuote.destinationAmount,
+ preparedQuote.destinationToken.decimals,
+ )} ${preparedQuote.destinationToken.symbol}`,
+ };
+ } else if (
+ status.type === "buy" ||
+ status.type === "sell" ||
+ status.type === "transfer"
+ ) {
+ if (status.transactions.length > 0) {
+ // get the last transaction hash
+ const tx = status.transactions[status.transactions.length - 1];
+ if (tx) {
+ const [destinationChain, originChain] = await Promise.all([
+ getChainMetadata(getCachedChain(status.destinationToken.chainId)),
+ getChainMetadata(getCachedChain(status.originToken.chainId)),
+ ]);
+ return {
+ type: "transactionHash" as const,
+ id: tx.transactionHash,
+ label: "Transaction",
+ chain: destinationChain,
+ originToken: status.originToken,
+ originChain,
+ destinationToken: status.destinationToken,
+ amountReceived: `${formatTokenAmount(
+ status.destinationAmount,
+ status.destinationToken.decimals,
+ )} ${status.destinationToken.symbol}`,
+ amountPaid: `${formatTokenAmount(
+ status.originAmount,
+ status.originToken.decimals,
+ )} ${status.originToken.symbol}`,
+ };
+ }
+ }
+ }
+
+ return null;
+ },
+ enabled: true,
+ staleTime: 5 * 60 * 1000, // 5 minutes
+ });
+}
+
+interface CompletedStepDetailCardProps {
+ status: CompletedStatusResult;
+ preparedQuote: BridgePrepareResult;
+ windowAdapter: WindowAdapter;
+ onCopyToClipboard: (text: string) => Promise;
+}
+
+/**
+ * Component to display details for a completed transaction step
+ */
+function CompletedStepDetailCard({
+ status,
+ preparedQuote,
+ windowAdapter,
+ onCopyToClipboard,
+}: CompletedStepDetailCardProps) {
+ const theme = useCustomTheme();
+ const { data: txInfo, isLoading } = useTransactionInfo(status, preparedQuote);
+
+ if (isLoading) {
+ return (
+
+
+ );
+ }
+
+ if (!txInfo) {
+ return null;
+ }
+
+ return (
+
+ {/* Status Badge */}
+
+
+ {txInfo.label}
+
+
+
+ COMPLETED
+
+
+
+
+ {/* Amount Paid */}
+ {txInfo.amountPaid && (
+
+
+ Amount Paid
+
+
+ {txInfo.amountPaid}
+
+
+ )}
+
+ {/* Origin Chain */}
+ {txInfo.originChain && (
+
+
+ Origin Chain
+
+
+ {shorterChainName(txInfo.chain.name)}
+
+
+ )}
+
+ {/* Amount Received */}
+ {txInfo.amountReceived && (
+
+
+ Amount Received
+
+
+ {txInfo.amountReceived}
+
+
+ )}
+
+ {/* Chain */}
+
+
+ Chain
+
+
+ {shorterChainName(txInfo.chain.name)}
+
+
+
+ {/* Transaction Info */}
+
+
+ {txInfo.type === "paymentId" ? "Payment ID" : "Transaction Hash"}
+
+
+ onCopyToClipboard(txInfo.id)
+ : () => {
+ const explorer = txInfo.chain.explorers?.[0];
+ if (explorer) {
+ windowAdapter.open(
+ formatExplorerTxUrl(explorer.url, txInfo.id),
+ );
+ }
+ }
+ }
+ >
+ {shortenHex(txInfo.id)}
+
+
+ {txInfo.type === "paymentId" ? (
+
+ ) : null}
+
+
+
+ );
+}
+
+interface PaymentReceitProps {
+ /**
+ * Prepared quote from Bridge.prepare
+ */
+ preparedQuote: BridgePrepareResult;
+
+ /**
+ * Completed status results from step execution
+ */
+ completedStatuses: CompletedStatusResult[];
+
+ /**
+ * Called when user goes back to success screen
+ */
+ onBack: () => void;
+
+ /**
+ * Window adapter for opening URLs
+ */
+ windowAdapter: WindowAdapter;
+}
+
+export function PaymentReceipt({
+ preparedQuote,
+ completedStatuses,
+ onBack,
+ windowAdapter,
+}: PaymentReceitProps) {
+ // Copy to clipboard
+ const copyToClipboard = useCallback(async (text: string) => {
+ try {
+ await navigator.clipboard.writeText(text);
+ // Could add a toast notification here
+ } catch (error) {
+ console.warn("Failed to copy to clipboard:", error);
+ }
+ }, []);
+
+ return (
+
+
+ {/* Status Results */}
+
+
+ Transactions
+
+
+ {completedStatuses.map((status, index) => (
+
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/Bridge/payment-success/SuccessScreen.tsx b/packages/thirdweb/src/react/web/ui/Bridge/payment-success/SuccessScreen.tsx
new file mode 100644
index 00000000000..54b72c25e60
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/Bridge/payment-success/SuccessScreen.tsx
@@ -0,0 +1,155 @@
+"use client";
+import { CheckIcon } from "@radix-ui/react-icons";
+import { useState } from "react";
+import type { WindowAdapter } from "../../../../core/adapters/WindowAdapter.js";
+import { useCustomTheme } from "../../../../core/design-system/CustomThemeProvider.js";
+import { iconSize } from "../../../../core/design-system/index.js";
+import type { BridgePrepareResult } from "../../../../core/hooks/useBridgePrepare.js";
+import type { CompletedStatusResult } from "../../../../core/hooks/useStepExecutor.js";
+import { Spacer } from "../../components/Spacer.js";
+import { Container, ModalHeader } from "../../components/basic.js";
+import { Button } from "../../components/buttons.js";
+import { Text } from "../../components/text.js";
+import type { UIOptions } from "../BridgeOrchestrator.js";
+import { PaymentReceipt } from "./PaymentReceipt.js";
+
+export interface SuccessScreenProps {
+ /**
+ * UI options
+ */
+ uiOptions: UIOptions;
+ /**
+ * Prepared quote from Bridge.prepare
+ */
+ preparedQuote: BridgePrepareResult;
+
+ /**
+ * Completed status results from step execution
+ */
+ completedStatuses: CompletedStatusResult[];
+
+ /**
+ * Called when user closes the success screen
+ */
+ onDone: () => void;
+
+ /**
+ * Window adapter for opening URLs
+ */
+ windowAdapter: WindowAdapter;
+}
+
+type ViewState = "success" | "detail";
+
+export function SuccessScreen({
+ uiOptions,
+ preparedQuote,
+ completedStatuses,
+ onDone,
+ windowAdapter,
+}: SuccessScreenProps) {
+ const theme = useCustomTheme();
+ const [viewState, setViewState] = useState("success");
+
+ if (viewState === "detail") {
+ return (
+ setViewState("success")}
+ />
+ );
+ }
+
+ return (
+
+
+ {/* Success Icon with Animation */}
+
+
+
+
+ Payment Successful!
+
+
+
+ Your cross-chain payment has been completed successfully.
+
+
+
+
+
+
+
+
+ {/* CSS Animations */}
+
+
+ );
+}
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/Details.test.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/Details.test.tsx
index 84fced21fd7..56e9dd47961 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/Details.test.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/Details.test.tsx
@@ -591,7 +591,7 @@ describe("Details Modal", () => {
const { container } = render(
console.log(scr)}
+ setScreen={(_scr) => {}}
disableSwitchChain={false}
displayBalanceToken={undefined}
client={client}
@@ -616,7 +616,7 @@ describe("Details Modal", () => {
const { container } = render(
console.log(scr)}
+ setScreen={(_scr) => {}}
disableSwitchChain={false}
displayBalanceToken={undefined}
client={client}
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/WalletSelector.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/WalletSelector.tsx
index e0c485c69c7..8fa694d2a91 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/WalletSelector.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/WalletSelector.tsx
@@ -699,8 +699,8 @@ const ButtonContainer = /* @__PURE__ */ StyledDiv(() => {
const ShowAllWalletsIcon = /* @__PURE__ */ StyledDiv(() => {
const theme = useCustomTheme();
return {
- width: `${iconSize.xl}px`,
- height: `${iconSize.xl}px`,
+ width: `${iconSize.lg}px`,
+ height: `${iconSize.lg}px`,
backgroundColor: theme.colors.tertiaryBg,
border: `2px solid ${theme.colors.borderColor}`,
borderRadius: radius.md,
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/constants.ts b/packages/thirdweb/src/react/web/ui/ConnectWallet/constants.ts
index aa8386cf093..739d518f3df 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/constants.ts
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/constants.ts
@@ -5,7 +5,7 @@ export const reservedScreens = {
showAll: "showAll",
};
-export const modalMaxWidthCompact = "360px";
+export const modalMaxWidthCompact = "400px";
const wideModalWidth = 730;
export const modalMaxWidthWide = `${wideModalWidth}px`;
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/icons/CreditCardIcon.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/icons/CreditCardIcon.tsx
new file mode 100644
index 00000000000..c7a7a38e291
--- /dev/null
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/icons/CreditCardIcon.tsx
@@ -0,0 +1,24 @@
+import type { IconFC } from "./types.js";
+
+/**
+ * @internal
+ */
+export const CreditCardIcon: IconFC = (props) => {
+ return (
+
+ );
+};
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/BuyScreen.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/BuyScreen.tsx
index 61567c33c3b..b132713e40e 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/BuyScreen.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/BuyScreen.tsx
@@ -24,7 +24,10 @@ import type {
} from "../../../../../core/hooks/connection/ConnectButtonProps.js";
import { useActiveAccount } from "../../../../../core/hooks/wallets/useActiveAccount.js";
import { invalidateWalletBalance } from "../../../../../core/providers/invalidateWalletBalance.js";
-import type { SupportedTokens } from "../../../../../core/utils/defaultTokens.js";
+import type {
+ SupportedTokens,
+ TokenInfo,
+} from "../../../../../core/utils/defaultTokens.js";
import { ErrorState } from "../../../../wallets/shared/ErrorState.js";
import { LoadingScreen } from "../../../../wallets/shared/LoadingScreen.js";
import type { PayEmbedConnectOptions } from "../../../PayEmbed.js";
@@ -539,7 +542,7 @@ function BuyScreenContent(props: BuyScreenContentProps) {
toChain={toChain}
toToken={toToken}
fromChain={fromChain}
- fromToken={fromToken}
+ fromToken={fromToken as TokenInfo}
showFromTokenSelector={() => {
setScreen({
id: "select-from-token",
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/DirectPaymentModeScreen.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/DirectPaymentModeScreen.tsx
index 348d460e974..c92395f7e7e 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/DirectPaymentModeScreen.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/DirectPaymentModeScreen.tsx
@@ -90,7 +90,9 @@ export function DirectPaymentModeScreen(props: {
const token: TokenInfo = paymentInfo.token
? {
- ...paymentInfo.token,
+ name: paymentInfo.token.name || chainData.nativeCurrency.name,
+ symbol: paymentInfo.token.symbol || chainData.nativeCurrency.symbol,
+ address: paymentInfo.token.address || NATIVE_TOKEN_ADDRESS,
icon:
paymentInfo.token?.icon ||
supportedDestinations
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/fiat/currencies.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/fiat/currencies.tsx
index 694da52dbda..996937f421b 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/fiat/currencies.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/fiat/currencies.tsx
@@ -99,6 +99,14 @@ export function getFiatIcon(
/>
);
}
+
+export function getFiatCurrencyIcon(props: {
+ currency: string;
+ size: keyof typeof iconSize;
+}): React.ReactNode {
+ return getFiatIcon(getCurrencyMeta(props.currency), props.size);
+}
+
const UnknownCurrencyIcon: IconFC = (props) => {
return (
- prefillBuy?.token ||
+ (prefillBuy?.token as TokenInfo) ||
(payOptions.mode === "direct_payment" && payOptions.paymentInfo.token) ||
NATIVE_TOKEN,
);
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/FiatValue.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/FiatValue.tsx
index 366b6ae54cc..75fc29ca35f 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/FiatValue.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/FiatValue.tsx
@@ -43,7 +43,13 @@ export function FiatValue(
return cryptoToFiatQuery.data?.result ? (
- ${formatNumber(cryptoToFiatQuery.data.result, 2).toFixed(2)}
+ $
+ {Number(
+ formatNumber(cryptoToFiatQuery.data.result, 2).toFixed(2),
+ ).toLocaleString(undefined, {
+ minimumFractionDigits: 2,
+ maximumFractionDigits: 2,
+ })}
) : null;
}
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/StepConnector.tsx b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/StepConnector.tsx
index 16b1a2601c1..8648c9b4dd8 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/StepConnector.tsx
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/Buy/swap/StepConnector.tsx
@@ -19,6 +19,7 @@ export function StepConnectorArrow() {
-
+
{wallet ? (
+
{props.label ? (
{props.label}
) : null}
-
+
{addressOrENS || shortenAddress(props.address)}
{profile.isLoading ? (
diff --git a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/formatTokenBalance.ts b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/formatTokenBalance.ts
index c29fcbe9ecc..d5a9cca35d2 100644
--- a/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/formatTokenBalance.ts
+++ b/packages/thirdweb/src/react/web/ui/ConnectWallet/screens/formatTokenBalance.ts
@@ -1,4 +1,6 @@
import { formatNumber } from "../../../../../utils/formatNumber.js";
+import { toTokens } from "../../../../../utils/units.js";
+import { getCurrencyMeta } from "./Buy/fiat/currencies.js";
/**
* @internal
@@ -20,3 +22,23 @@ export function formatTokenBalance(
(showSymbol ? ` ${balanceData.symbol}` : "")
);
}
+
+export function formatTokenAmount(
+ amount: bigint,
+ decimals: number,
+ decimalsToShow = 5,
+) {
+ return formatNumber(
+ Number.parseFloat(toTokens(amount, decimals)),
+ decimalsToShow,
+ ).toString();
+}
+
+export function formatCurrencyAmount(
+ currency: string,
+ amount: number,
+ decimals = 2,
+) {
+ const symbol = getCurrencyMeta(currency).symbol;
+ return `${symbol}${formatNumber(amount, decimals).toFixed(decimals)}`;
+}
diff --git a/packages/thirdweb/src/react/web/ui/PayEmbed.tsx b/packages/thirdweb/src/react/web/ui/PayEmbed.tsx
index cea1ada5907..6f640791fe1 100644
--- a/packages/thirdweb/src/react/web/ui/PayEmbed.tsx
+++ b/packages/thirdweb/src/react/web/ui/PayEmbed.tsx
@@ -22,6 +22,7 @@ import { useActiveWallet } from "../../core/hooks/wallets/useActiveWallet.js";
import { useConnectionManager } from "../../core/providers/connection-manager.js";
import type { SupportedTokens } from "../../core/utils/defaultTokens.js";
import { AutoConnect } from "../../web/ui/AutoConnect/AutoConnect.js";
+import { webWindowAdapter } from "../adapters/WindowAdapter.js";
import { EmbedContainer } from "./ConnectWallet/Modal/ConnectEmbed.js";
import { useConnectLocale } from "./ConnectWallet/locale/getConnectLocale.js";
import BuyScreen from "./ConnectWallet/screens/Buy/BuyScreen.js";
@@ -404,6 +405,7 @@ export function PayEmbed(props: PayEmbedProps) {
transactionHash: data.transactionHash,
});
}}
+ windowAdapter={webWindowAdapter}
/>
)}
diff --git a/packages/thirdweb/src/react/web/ui/TransactionButton/DepositScreen.tsx b/packages/thirdweb/src/react/web/ui/TransactionButton/DepositScreen.tsx
index 3bfd1a51644..bfdad370482 100644
--- a/packages/thirdweb/src/react/web/ui/TransactionButton/DepositScreen.tsx
+++ b/packages/thirdweb/src/react/web/ui/TransactionButton/DepositScreen.tsx
@@ -168,10 +168,9 @@ export function DepositScreen(props: {
style={{
justifyContent: "space-between",
padding: spacing.sm,
- marginBottom: spacing.sm,
- borderRadius: spacing.md,
- backgroundColor: theme.colors.tertiaryBg,
+ borderRadius: `${radius.md} ${radius.md} 0 0`,
border: `1px solid ${theme.colors.borderColor}`,
+ borderBottom: "none",
}}
>
{activeAccount && (
@@ -223,7 +222,13 @@ export function DepositScreen(props: {
/>
-
+
{address ? shortenAddress(address) : ""}
{
display: "flex",
justifyContent: "space-between",
border: `1px solid ${theme.colors.borderColor}`,
- borderRadius: radius.lg,
+ borderRadius: `0 0 ${radius.md} ${radius.md}`,
transition: "border-color 200ms ease",
"&:hover": {
borderColor: theme.colors.accentText,
diff --git a/packages/thirdweb/src/react/web/ui/TransactionButton/ExecutingScreen.tsx b/packages/thirdweb/src/react/web/ui/TransactionButton/ExecutingScreen.tsx
index 2d060e0692b..0322b6caae4 100644
--- a/packages/thirdweb/src/react/web/ui/TransactionButton/ExecutingScreen.tsx
+++ b/packages/thirdweb/src/react/web/ui/TransactionButton/ExecutingScreen.tsx
@@ -1,9 +1,11 @@
-import { CheckCircledIcon, ExternalLinkIcon } from "@radix-ui/react-icons";
+import { CheckIcon, ExternalLinkIcon } from "@radix-ui/react-icons";
import { useCallback, useEffect, useRef, useState } from "react";
import type { Hex } from "viem";
import type { WaitForReceiptOptions } from "../../../../transaction/actions/wait-for-tx-receipt.js";
import type { PreparedTransaction } from "../../../../transaction/prepare-transaction.js";
import { formatExplorerTxUrl } from "../../../../utils/url.js";
+import type { WindowAdapter } from "../../../core/adapters/WindowAdapter.js";
+import { useCustomTheme } from "../../../core/design-system/CustomThemeProvider.js";
import { iconSize } from "../../../core/design-system/index.js";
import { useChainExplorers } from "../../../core/hooks/others/useChainQuery.js";
import { useSendTransaction } from "../../hooks/transaction/useSendTransaction.js";
@@ -11,7 +13,7 @@ import { AccentFailIcon } from "../ConnectWallet/icons/AccentFailIcon.js";
import { Spacer } from "../components/Spacer.js";
import { Spinner } from "../components/Spinner.js";
import { Container, ModalHeader } from "../components/basic.js";
-import { Button, ButtonLink } from "../components/buttons.js";
+import { Button } from "../components/buttons.js";
import { Text } from "../components/text.js";
export function ExecutingTxScreen(props: {
@@ -19,6 +21,7 @@ export function ExecutingTxScreen(props: {
closeModal: () => void;
onTxSent: (data: WaitForReceiptOptions) => void;
onBack?: () => void;
+ windowAdapter: WindowAdapter;
}) {
const sendTxCore = useSendTransaction({
payModal: false,
@@ -29,6 +32,7 @@ export function ExecutingTxScreen(props: {
const [status, setStatus] = useState<"loading" | "failed" | "sent">(
"loading",
);
+ const theme = useCustomTheme();
const sendTx = useCallback(async () => {
setStatus("loading");
@@ -67,15 +71,32 @@ export function ExecutingTxScreen(props: {
{status === "loading" &&
-
+
)}
-
{status === "loading" && "Sending transaction"}
@@ -87,7 +108,7 @@ export function ExecutingTxScreen(props: {
{status === "failed" && txError ? txError.message || "" : ""}
-
);
}
diff --git a/packages/thirdweb/src/react/web/ui/TransactionButton/TransactionModal.tsx b/packages/thirdweb/src/react/web/ui/TransactionButton/TransactionModal.tsx
index c76cb25644b..c8ace7fa0e3 100644
--- a/packages/thirdweb/src/react/web/ui/TransactionButton/TransactionModal.tsx
+++ b/packages/thirdweb/src/react/web/ui/TransactionButton/TransactionModal.tsx
@@ -11,9 +11,10 @@ import type { PayUIOptions } from "../../../core/hooks/connection/ConnectButtonP
import { useActiveAccount } from "../../../core/hooks/wallets/useActiveAccount.js";
import { useActiveWallet } from "../../../core/hooks/wallets/useActiveWallet.js";
import type { SupportedTokens } from "../../../core/utils/defaultTokens.js";
+import { webWindowAdapter } from "../../adapters/WindowAdapter.js";
import { LoadingScreen } from "../../wallets/shared/LoadingScreen.js";
+import { BridgeOrchestrator } from "../Bridge/BridgeOrchestrator.js";
import { useConnectLocale } from "../ConnectWallet/locale/getConnectLocale.js";
-import { LazyBuyScreen } from "../ConnectWallet/screens/Buy/LazyBuyScreen.js";
import { Modal } from "../components/Modal.js";
import type { LocaleId } from "../types.js";
import { DepositScreen } from "./DepositScreen.js";
@@ -94,6 +95,7 @@ function TransactionModalContent(props: ModalProps & { onBack?: () => void }) {
tx={props.tx}
closeModal={props.onClose}
onTxSent={props.onTxSent}
+ windowAdapter={webWindowAdapter}
/>
);
}
@@ -113,19 +115,23 @@ function TransactionModalContent(props: ModalProps & { onBack?: () => void }) {
}
return (
- {
+ onComplete={() => {
setScreen("execute-tx");
}}
+ onError={(_error) => {}}
+ onCancel={props.onClose}
connectOptions={undefined}
+ receiverAddress={undefined}
+ purchaseData={undefined}
+ paymentLinkId={undefined}
+ presetOptions={undefined}
/>
);
}
diff --git a/packages/thirdweb/src/react/web/ui/components/ChainName.tsx b/packages/thirdweb/src/react/web/ui/components/ChainName.tsx
index 8543c4936ba..d685e066660 100644
--- a/packages/thirdweb/src/react/web/ui/components/ChainName.tsx
+++ b/packages/thirdweb/src/react/web/ui/components/ChainName.tsx
@@ -11,14 +11,16 @@ import { Text } from "./text.js";
export const ChainName: React.FC<{
chain: Chain;
size: "xs" | "sm" | "md" | "lg";
+ color?: "primaryText" | "secondaryText";
client: ThirdwebClient;
short?: boolean;
+ style?: React.CSSProperties;
}> = (props) => {
const { name } = useChainName(props.chain);
if (name) {
return (
-
+
{props.short ? shorterChainName(name) : name}
);
@@ -27,7 +29,7 @@ export const ChainName: React.FC<{
return ![]()
{
border: `1px solid ${theme.colors.borderColor}`,
"&:hover": {
borderColor: theme.colors.accentText,
- transform: "scale(1.01)",
},
'&[aria-selected="true"]': {
borderColor: theme.colors.accentText,
@@ -106,7 +105,6 @@ export const Button = /* @__PURE__ */ StyledButton((props: ButtonProps) => {
border: "1px solid transparent",
"&:hover": {
borderColor: theme.colors.accentText,
- transform: "scale(1.01)",
},
};
}
@@ -114,7 +112,7 @@ export const Button = /* @__PURE__ */ StyledButton((props: ButtonProps) => {
if (props.variant === "accent") {
return {
"&:hover": {
- transform: "scale(1.01)",
+ opacity: 0.8,
},
};
}
@@ -123,7 +121,6 @@ export const Button = /* @__PURE__ */ StyledButton((props: ButtonProps) => {
return {
"&:hover": {
background: theme.colors.secondaryButtonHoverBg,
- transform: "scale(1.01)",
},
};
}
@@ -133,7 +130,6 @@ export const Button = /* @__PURE__ */ StyledButton((props: ButtonProps) => {
padding: 0,
"&:hover": {
color: theme.colors.primaryText,
- transform: "scale(1.01)",
},
};
}
diff --git a/packages/thirdweb/src/stories/Bridge/BridgeOrchestrator.stories.tsx b/packages/thirdweb/src/stories/Bridge/BridgeOrchestrator.stories.tsx
new file mode 100644
index 00000000000..af8088b7fbd
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/BridgeOrchestrator.stories.tsx
@@ -0,0 +1,267 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {} from "../../react/core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../../react/core/design-system/index.js";
+import {
+ BridgeOrchestrator,
+ type BridgeOrchestratorProps,
+} from "../../react/web/ui/Bridge/BridgeOrchestrator.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import {
+ DIRECT_PAYMENT_UI_OPTIONS,
+ FUND_WALLET_UI_OPTIONS,
+ TRANSACTION_UI_OPTIONS,
+} from "./fixtures.js";
+
+/**
+ * BridgeOrchestrator is the main orchestrator component for the Bridge payment flow.
+ * It manages the complete state machine navigation between different screens and
+ * handles the coordination of payment methods, routes, and execution.
+ */
+
+// Props interface for the wrapper component
+interface BridgeOrchestratorWithThemeProps extends BridgeOrchestratorProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const BridgeOrchestratorWithTheme = (
+ props: BridgeOrchestratorWithThemeProps,
+) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/BridgeOrchestrator",
+ component: BridgeOrchestratorWithTheme,
+ parameters: {
+ layout: "fullscreen",
+ docs: {
+ description: {
+ component:
+ "**BridgeOrchestrator** is the main orchestrator component that manages the complete Bridge payment flow using XState FSM.\n\n" +
+ "## Features\n" +
+ "- **State Machine Navigation**: Uses XState v5 for predictable state transitions\n" +
+ "- **Payment Method Selection**: Supports wallet and fiat payment methods\n" +
+ "- **Route Preview**: Shows detailed transaction steps and fees\n" +
+ "- **Step Execution**: Real-time progress tracking\n" +
+ "- **Error Handling**: Comprehensive error states with retry functionality\n" +
+ "- **Theme Support**: Works with both light and dark themes\n\n" +
+ "## State Flow\n" +
+ "1. **Resolve Requirements** → 2. **Method Selection** → 3. **Quote** → 4. **Preview** → 5. **Prepare** → 6. **Execute** → 7. **Success**\n\n" +
+ "Each state can transition to the **Error** state, which provides retry functionality.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ client: storyClient,
+ uiOptions: FUND_WALLET_UI_OPTIONS.usdcDefault,
+ onComplete: () => {},
+ onError: (error) => console.error("Bridge error:", error),
+ onCancel: () => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ presetOptions: {
+ control: "object",
+ description: "Quick buy options",
+ },
+ onComplete: { action: "flow completed" },
+ onError: { action: "error occurred" },
+ onCancel: { action: "flow cancelled" },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/**
+ * Default BridgeOrchestrator in light theme.
+ */
+export const Light: Story = {
+ args: {
+ theme: "light",
+ uiOptions: FUND_WALLET_UI_OPTIONS.usdcDefault,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+/**
+ * BridgeOrchestrator in dark theme.
+ */
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.usdcDefault,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+/**
+ * Direct payment mode for purchasing a specific product/service.
+ */
+export const DirectPayment: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.digitalArt,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Direct payment mode shows a product purchase interface with the item image, price, seller address, and network information. The user can connect their wallet and proceed with the payment.",
+ },
+ },
+ },
+};
+
+/**
+ * Direct payment mode in light theme.
+ */
+export const DirectPaymentLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.concertTicket,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of direct payment mode, showing a different product example with USDC payment.",
+ },
+ },
+ },
+};
+
+/**
+ * Transaction mode showing a complex contract interaction.
+ */
+export const Transaction: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Transaction mode showing a complex contract interaction (claimTo function) with function name extraction from contract ABI and detailed cost breakdown.",
+ },
+ },
+ },
+};
+
+/**
+ * Transaction mode in light theme showing an ERC20 token transfer.
+ */
+export const TransactionLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: TRANSACTION_UI_OPTIONS.erc20Transfer,
+ presetOptions: undefined,
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of transaction mode showing an ERC20 token transfer with proper token amount formatting and USD conversion.",
+ },
+ },
+ },
+};
+
+export const CustompresetOptions: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethDefault,
+ presetOptions: [1, 2, 3],
+ onComplete: undefined,
+ onError: undefined,
+ onCancel: undefined,
+ receiverAddress: undefined,
+ connectOptions: undefined,
+ connectLocale: undefined,
+ purchaseData: undefined,
+ paymentLinkId: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Fund wallet mode with custom quick options showing ETH with [1, 2, 3] preset amounts.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx b/packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx
new file mode 100644
index 00000000000..1f90fc4150c
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/DirectPayment.stories.tsx
@@ -0,0 +1,225 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Theme } from "../../react/core/design-system/index.js";
+import {
+ DirectPayment,
+ type DirectPaymentProps,
+} from "../../react/web/ui/Bridge/DirectPayment.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import { DIRECT_PAYMENT_UI_OPTIONS } from "./fixtures.js";
+
+// Props interface for the wrapper component
+interface DirectPaymentWithThemeProps extends DirectPaymentProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const DirectPaymentWithTheme = (props: DirectPaymentWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/DirectPayment",
+ component: DirectPaymentWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "DirectPayment component displays a product/service purchase interface with payment details.\n\n" +
+ "## Features\n" +
+ "- **Product Display**: Shows product name, image, and pricing\n" +
+ "- **Payment Details**: Token amount, network information, and seller address\n" +
+ "- **Wallet Integration**: Connect button or continue with active wallet\n" +
+ "- **Responsive Design**: Adapts to different screen sizes and themes\n" +
+ "- **Fee Configuration**: Support for sender or receiver paying fees\n\n" +
+ "This component is used in the 'direct_payment' mode of BridgeOrchestrator for purchasing specific items or services. It now accepts uiOptions directly to configure payment info and metadata.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ client: storyClient,
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.digitalArt,
+ onContinue: (_amount, _token, _receiverAddress) => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onContinue: {
+ action: "continue clicked",
+ description: "Called when user continues with the payment",
+ },
+ uiOptions: {
+ description:
+ "UI configuration for direct payment mode including payment info and metadata",
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const DigitalArt: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.digitalArt,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example of purchasing a digital art NFT with ETH payment. Shows the product image, pricing in ETH, and seller information with sender paying fees.",
+ },
+ },
+ },
+};
+
+export const DigitalArtLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.digitalArt,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version of the digital art purchase interface.",
+ },
+ },
+ },
+};
+
+export const ConcertTicket: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.concertTicket,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example of purchasing a concert ticket with USDC payment. Shows different product type, stable token pricing, and receiver paying fees.",
+ },
+ },
+ },
+};
+
+export const ConcertTicketLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.concertTicket,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version of the concert ticket purchase.",
+ },
+ },
+ },
+};
+
+export const SubscriptionService: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.subscription,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example of a subscription service payment with detailed description. Shows how the component works for recurring service payments with comprehensive product information.",
+ },
+ },
+ },
+};
+
+export const SubscriptionServiceLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.subscription,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of subscription service payment with full description text.",
+ },
+ },
+ },
+};
+
+export const PhysicalProduct: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.sneakers,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example of purchasing physical products with crypto payments. Shows how the component adapts to different product types with ETH payment.",
+ },
+ },
+ },
+};
+
+export const PhysicalProductLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.sneakers,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version of physical product purchase.",
+ },
+ },
+ },
+};
+
+export const NoImage: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.credits,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example of purchasing digital credits without product image. Shows how the component handles text-only products with description fallback.",
+ },
+ },
+ },
+};
+
+export const NoImageLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.credits,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version of credits purchase without image.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/ErrorBanner.stories.tsx b/packages/thirdweb/src/stories/Bridge/ErrorBanner.stories.tsx
new file mode 100644
index 00000000000..69ce8143254
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/ErrorBanner.stories.tsx
@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Theme } from "../../react/core/design-system/index.js";
+import { ErrorBanner } from "../../react/web/ui/Bridge/ErrorBanner.js";
+import { ModalThemeWrapper } from "../utils.js";
+
+const mockNetworkError = new Error(
+ "Network connection failed. Please check your internet connection and try again.",
+);
+const mockUserRejectedError = new Error("Transaction was rejected by user.");
+const mockInsufficientFundsError = new Error(
+ "Insufficient funds to complete this transaction.",
+);
+const mockGenericError = new Error("An unexpected error occurred.");
+
+// Props interface for the wrapper component
+interface ErrorBannerWithThemeProps {
+ error: Error;
+ onRetry: () => void;
+ onCancel?: () => void;
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const ErrorBannerWithTheme = (props: ErrorBannerWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/ErrorBanner",
+ component: ErrorBannerWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Error banner component that displays user-friendly error messages with retry functionality and optional cancel action.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ error: mockNetworkError,
+ onRetry: () => {},
+ onCancel: () => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onRetry: { action: "retry clicked" },
+ onCancel: { action: "cancel clicked" },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Light: Story = {
+ args: {
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const NetworkError: Story = {
+ args: {
+ theme: "dark",
+ error: mockNetworkError,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const NetworkErrorLight: Story = {
+ args: {
+ theme: "light",
+ error: mockNetworkError,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const UserRejectedError: Story = {
+ args: {
+ theme: "dark",
+ error: mockUserRejectedError,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const UserRejectedErrorLight: Story = {
+ args: {
+ theme: "light",
+ error: mockUserRejectedError,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const InsufficientFundsError: Story = {
+ args: {
+ theme: "dark",
+ error: mockInsufficientFundsError,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const InsufficientFundsErrorLight: Story = {
+ args: {
+ theme: "light",
+ error: mockInsufficientFundsError,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const WithoutCancelButton: Story = {
+ args: {
+ theme: "dark",
+ error: mockGenericError,
+ onCancel: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const WithoutCancelButtonLight: Story = {
+ args: {
+ theme: "light",
+ error: mockGenericError,
+ onCancel: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const EmptyMessage: Story = {
+ args: {
+ theme: "dark",
+ error: new Error(""),
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const EmptyMessageLight: Story = {
+ args: {
+ theme: "light",
+ error: new Error(""),
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx b/packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx
new file mode 100644
index 00000000000..224e30cf87a
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/FundWallet.stories.tsx
@@ -0,0 +1,196 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Theme } from "../../react/core/design-system/index.js";
+import { FundWallet } from "../../react/web/ui/Bridge/FundWallet.js";
+import type { FundWalletProps } from "../../react/web/ui/Bridge/FundWallet.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import { FUND_WALLET_UI_OPTIONS, RECEIVER_ADDRESSES } from "./fixtures.js";
+
+// Props interface for the wrapper component
+interface FundWalletWithThemeProps extends FundWalletProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const FundWalletWithTheme = (props: FundWalletWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/FundWallet",
+ component: FundWalletWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "FundWallet component allows users to specify the amount they want to add to their wallet. This is the first screen in the fund_wallet flow before method selection.\n\n" +
+ "## Features\n" +
+ "- **Token Selection**: Choose from different tokens (ETH, USDC, UNI)\n" +
+ "- **Amount Input**: Enter custom amount or use quick options\n" +
+ "- **Receiver Address**: Optional receiver address (defaults to connected wallet)\n" +
+ "- **Quick Options**: Preset amounts for faster selection\n" +
+ "- **Theme Support**: Works with both light and dark themes\n\n" +
+ "This component now accepts uiOptions directly to configure the destination token, initial amount, and quick options.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethDefault,
+ client: storyClient,
+ onContinue: (amount, token, receiverAddress) => {
+ alert(`Continue with ${amount} ${token.symbol} to ${receiverAddress}`);
+ },
+ receiverAddress: RECEIVER_ADDRESSES.primary,
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onContinue: { action: "continue clicked" },
+ uiOptions: {
+ description: "UI configuration for fund wallet mode",
+ },
+ receiverAddress: {
+ description: "Optional receiver address (defaults to connected wallet)",
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Light: Story = {
+ args: {
+ theme: "light",
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethDefault,
+ receiverAddress: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Default fund wallet interface in light theme with ETH token.",
+ },
+ },
+ },
+};
+
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethDefault,
+ receiverAddress: undefined,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story: "Default fund wallet interface in dark theme with ETH token.",
+ },
+ },
+ },
+};
+
+export const WithInitialAmount: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethWithAmount,
+ receiverAddress: RECEIVER_ADDRESSES.secondary,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Fund wallet with pre-filled amount and specified receiver address.",
+ },
+ },
+ },
+};
+
+export const WithInitialAmountLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethWithAmount,
+ receiverAddress: RECEIVER_ADDRESSES.secondary,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version with pre-filled amount and receiver address.",
+ },
+ },
+ },
+};
+
+export const USDCToken: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.usdcDefault,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story: "Fund wallet configured for USDC token with initial amount.",
+ },
+ },
+ },
+};
+
+export const USDCTokenLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: FUND_WALLET_UI_OPTIONS.usdcDefault,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version for USDC token funding.",
+ },
+ },
+ },
+};
+
+export const LargeAmount: Story = {
+ args: {
+ theme: "dark",
+ uiOptions: FUND_WALLET_UI_OPTIONS.uniLarge,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Fund wallet with UNI token and large pre-filled amount to test formatting.",
+ },
+ },
+ },
+};
+
+export const LargeAmountLight: Story = {
+ args: {
+ theme: "light",
+ uiOptions: FUND_WALLET_UI_OPTIONS.uniLarge,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Light theme version with UNI token and large amount.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/PaymentDetails.stories.tsx b/packages/thirdweb/src/stories/Bridge/PaymentDetails.stories.tsx
new file mode 100644
index 00000000000..aeb9e3632e5
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/PaymentDetails.stories.tsx
@@ -0,0 +1,501 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Theme } from "../../react/core/design-system/index.js";
+import type { PaymentMethod } from "../../react/core/machines/paymentMachine.js";
+import {
+ PaymentDetails,
+ type PaymentDetailsProps,
+} from "../../react/web/ui/Bridge/payment-details/PaymentDetails.js";
+import { stringify } from "../../utils/json.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import {
+ DIRECT_PAYMENT_UI_OPTIONS,
+ STORY_MOCK_WALLET,
+ TRANSACTION_UI_OPTIONS,
+ USDC,
+ buyWithApprovalQuote,
+ complexBuyQuote,
+ longTextBuyQuote,
+ onrampWithSwapsQuote,
+ simpleBuyQuote,
+ simpleOnrampQuote,
+} from "./fixtures.js";
+
+const fiatPaymentMethod: PaymentMethod = {
+ type: "fiat",
+ currency: "USD",
+ onramp: "coinbase",
+ payerWallet: STORY_MOCK_WALLET,
+};
+
+const cryptoPaymentMethod: PaymentMethod = JSON.parse(
+ stringify({
+ type: "wallet",
+ payerWallet: STORY_MOCK_WALLET,
+ balance: 100000000n,
+ originToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ name: "USD Coin",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ }),
+);
+
+const ethCryptoPaymentMethod: PaymentMethod = JSON.parse(
+ stringify({
+ type: "wallet",
+ payerWallet: STORY_MOCK_WALLET,
+ balance: 1000000000000000000n,
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ }),
+);
+
+// Props interface for the wrapper component
+interface PaymentDetailsWithThemeProps extends PaymentDetailsProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const PaymentDetailsWithTheme = (props: PaymentDetailsWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/PaymentDetails",
+ component: PaymentDetailsWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Route preview screen that displays prepared quote details, fees, estimated time, and transaction steps for user confirmation.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ preparedQuote: simpleOnrampQuote,
+ onConfirm: () => {},
+ onBack: () => {},
+ onError: (error) => console.error("Error:", error),
+ theme: "dark",
+ uiOptions: {
+ mode: "fund_wallet",
+ destinationToken: USDC,
+ },
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onConfirm: { action: "route confirmed" },
+ onBack: { action: "back clicked" },
+ onError: { action: "error occurred" },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const OnrampSimple: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleOnrampQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Simple onramp quote with no extra steps - direct fiat to crypto.",
+ },
+ },
+ },
+};
+
+export const OnrampSimpleLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleOnrampQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Simple onramp quote with no extra steps (light theme).",
+ },
+ },
+ },
+};
+
+export const OnrampSimpleDirectPayment: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleOnrampQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.credits,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Simple onramp quote with no extra steps - direct fiat to crypto.",
+ },
+ },
+ },
+};
+
+export const OnrampSimpleLightDirectPayment: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleOnrampQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.concertTicket,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Simple onramp quote with no extra steps (light theme).",
+ },
+ },
+ },
+};
+
+export const OnrampWithSwaps: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: onrampWithSwapsQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Onramp quote with 2 additional swap steps after the fiat purchase.",
+ },
+ },
+ },
+};
+
+export const OnrampWithSwapsLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: onrampWithSwapsQuote,
+ paymentMethod: fiatPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Onramp quote with 2 additional swap steps (light theme).",
+ },
+ },
+ },
+};
+
+export const BuySimple: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Simple buy quote with a single transaction (no approval needed).",
+ },
+ },
+ },
+};
+
+export const BuySimpleLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Simple buy quote with a single transaction (light theme).",
+ },
+ },
+ },
+};
+
+export const BuySimpleDirectPayment: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.digitalArt,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Simple buy quote with a single transaction (no approval needed).",
+ },
+ },
+ },
+};
+
+export const BuySimpleLightDirectPayment: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: DIRECT_PAYMENT_UI_OPTIONS.subscription,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Simple buy quote with a single transaction (light theme).",
+ },
+ },
+ },
+};
+
+export const BuyWithLongText: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: longTextBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story: "Simple buy quote with a single transaction (light theme).",
+ },
+ },
+ },
+};
+
+export const BuyWithApproval: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: buyWithApprovalQuote,
+ paymentMethod: cryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Buy quote requiring both approval and buy transactions in a single step.",
+ },
+ },
+ },
+};
+
+export const BuyWithApprovalLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: buyWithApprovalQuote,
+ paymentMethod: cryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story: "Buy quote with approval and buy transactions (light theme).",
+ },
+ },
+ },
+};
+
+export const BuyComplex: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: complexBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Complex buy quote with 3 steps, each requiring approval and execution transactions across multiple chains.",
+ },
+ },
+ },
+};
+
+export const BuyComplexLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: complexBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Complex multi-step buy quote spanning multiple chains (light theme).",
+ },
+ },
+ },
+};
+
+// ========== TRANSACTION MODE STORIES ========== //
+
+export const TransactionEthTransfer: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.ethTransfer,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Transaction mode showing ETH transfer payment details with function name and contract information displayed in the PaymentDetails screen.",
+ },
+ },
+ },
+};
+
+export const TransactionEthTransferLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.ethTransfer,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of transaction mode for ETH transfer with detailed payment overview.",
+ },
+ },
+ },
+};
+
+export const TransactionERC20Transfer: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: cryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.erc20Transfer,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Transaction mode for ERC20 token transfer showing token details and transfer function in payment preview.",
+ },
+ },
+ },
+};
+
+export const TransactionERC20TransferLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: cryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.erc20Transfer,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of ERC20 token transfer transaction mode with payment details.",
+ },
+ },
+ },
+};
+
+export const TransactionContractInteraction: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Transaction mode for complex contract interaction (claimTo function) showing detailed contract information and function details in payment preview.",
+ },
+ },
+ },
+};
+
+export const TransactionContractInteractionLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ paymentMethod: ethCryptoPaymentMethod,
+ client: storyClient,
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version of contract interaction transaction mode with comprehensive payment details.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/PaymentSelection.stories.tsx b/packages/thirdweb/src/stories/Bridge/PaymentSelection.stories.tsx
new file mode 100644
index 00000000000..8126617b63a
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/PaymentSelection.stories.tsx
@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Theme } from "../../react/core/design-system/index.js";
+import {
+ PaymentSelection,
+ type PaymentSelectionProps,
+} from "../../react/web/ui/Bridge/payment-selection/PaymentSelection.js";
+import en from "../../react/web/ui/ConnectWallet/locale/en.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import { UNI, USDC } from "./fixtures.js";
+
+// Props interface for the wrapper component
+interface PaymentSelectionWithThemeProps extends PaymentSelectionProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const PaymentSelectionWithTheme = (props: PaymentSelectionWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/PaymentSelection",
+ component: PaymentSelectionWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Payment method selection screen with a 2-step flow:\n\n" +
+ "**Step 1:** Choose payment method - shows connected wallets, connect wallet option, and pay with fiat option\n\n" +
+ "**Step 2a:** If wallet selected - shows available origin tokens for bridging to the destination token (fetches real routes data from the Bridge API)\n\n" +
+ "**Step 2b:** If fiat selected - shows onramp provider options (Coinbase, Stripe, Transak)\n\n" +
+ "The component intelligently manages wallet context and provides proper error handling for each step.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ destinationToken: USDC,
+ client: storyClient,
+ onPaymentMethodSelected: (_paymentMethod) => {},
+ onError: (error) => console.error("Error:", error),
+ theme: "dark",
+ destinationAmount: "1",
+ connectLocale: en,
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ destinationToken: {
+ description: "The target token to bridge to",
+ },
+ destinationAmount: {
+ description: "Amount of destination token to bridge",
+ },
+ onPaymentMethodSelected: {
+ action: "payment method selected",
+ description: "Called when user selects a wallet token or fiat provider",
+ },
+ onError: {
+ action: "error occurred",
+ description: "Called when an error occurs during the flow",
+ },
+ onBack: {
+ action: "back clicked",
+ description: "Called when user wants to go back (only shown in Step 1)",
+ },
+ connectLocale: {
+ description: "Locale for connecting wallets",
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Light: Story = {
+ args: {
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version showing the initial wallet selection step. Click on a connected wallet to see token selection, or click 'Pay with Fiat' to see provider selection.",
+ },
+ },
+ },
+};
+
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Dark theme version of the payment selection flow. The component starts with wallet selection and provides navigation through the 2-step process.",
+ },
+ },
+ },
+};
+
+export const WithBackButton: Story = {
+ args: {
+ theme: "dark",
+ onBack: () => {},
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Version with a back button in the header. The back behavior changes based on the current step - Step 1 calls onBack, Steps 2a/2b return to Step 1.",
+ },
+ },
+ },
+};
+
+export const WithBackButtonLight: Story = {
+ args: {
+ theme: "light",
+ onBack: () => {},
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Light theme version with back button functionality. Demonstrates the navigation flow between steps.",
+ },
+ },
+ },
+};
+
+export const DifferentDestinationToken: Story = {
+ args: {
+ theme: "dark",
+ destinationToken: UNI,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example with a different destination token (UNI). This will show different available origin tokens in Step 2a when a wallet is selected.",
+ },
+ },
+ },
+};
+
+export const LargeAmount: Story = {
+ args: {
+ theme: "dark",
+ destinationAmount: "1000",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Example with a larger destination amount (1000 USDC). This may affect which origin tokens are available based on user balances.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/StepRunner.stories.tsx b/packages/thirdweb/src/stories/Bridge/StepRunner.stories.tsx
new file mode 100644
index 00000000000..b23cedbd0ba
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/StepRunner.stories.tsx
@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { ThirdwebClient } from "../../client/client.js";
+import type { WindowAdapter } from "../../react/core/adapters/WindowAdapter.js";
+import type { Theme } from "../../react/core/design-system/index.js";
+import type { BridgePrepareRequest } from "../../react/core/hooks/useBridgePrepare.js";
+import type { CompletedStatusResult } from "../../react/core/hooks/useStepExecutor.js";
+import { StepRunner } from "../../react/web/ui/Bridge/StepRunner.js";
+import type { Wallet } from "../../wallets/interfaces/wallet.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import { STORY_MOCK_WALLET, simpleBuyRequest } from "./fixtures.js";
+
+// Mock window adapter
+const mockWindowAdapter: WindowAdapter = {
+ open: async (_url: string) => {},
+};
+
+// Props interface for the wrapper component
+interface StepRunnerWithThemeProps {
+ request: BridgePrepareRequest;
+ wallet: Wallet;
+ client: ThirdwebClient;
+ windowAdapter: WindowAdapter;
+ onComplete: (completedStatuses: CompletedStatusResult[]) => void;
+ onError: (error: Error) => void;
+ onCancel?: () => void;
+ onBack?: () => void;
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const StepRunnerWithTheme = (props: StepRunnerWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/StepRunner",
+ component: StepRunnerWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "**StepRunner** executes prepared route steps sequentially, showing real-time progress and transaction status.\n\n" +
+ "## Features\n" +
+ "- **Real Execution**: Uses useStepExecutor hook for actual transaction processing\n" +
+ "- **Progress Tracking**: Visual progress bar and step-by-step status updates\n" +
+ "- **Error Handling**: Retry functionality for failed transactions\n" +
+ "- **Transaction Batching**: Optimizes multiple transactions when possible\n" +
+ "- **Onramp Support**: Handles fiat-to-crypto onramp flows\n\n" +
+ "## Props\n" +
+ "- `steps`: Array of RouteStep objects from Bridge.prepare()\n" +
+ "- `wallet`: Connected wallet for transaction signing\n" +
+ "- `client`: ThirdwebClient instance\n" +
+ "- `windowAdapter`: Platform-specific window/URL handler\n" +
+ "- `onramp`: Optional onramp configuration\n\n" +
+ "## Integration\n" +
+ "This component is typically used within the BridgeOrchestrator after route preparation.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ wallet: STORY_MOCK_WALLET,
+ client: storyClient,
+ windowAdapter: mockWindowAdapter,
+ onComplete: (_completedStatuses: CompletedStatusResult[]) => {},
+ onError: (error: Error) => console.error("Error:", error),
+ onCancel: () => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onComplete: { action: "execution completed" },
+ onError: { action: "error occurred" },
+ onCancel: { action: "execution cancelled" },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Light: Story = {
+ args: {
+ theme: "light",
+ request: simpleBuyRequest,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ request: simpleBuyRequest,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/SuccessScreen.stories.tsx b/packages/thirdweb/src/stories/Bridge/SuccessScreen.stories.tsx
new file mode 100644
index 00000000000..1d11e8d3161
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/SuccessScreen.stories.tsx
@@ -0,0 +1,217 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { stringify } from "viem";
+import type { Theme } from "../../react/core/design-system/index.js";
+import type { CompletedStatusResult } from "../../react/core/hooks/useStepExecutor.js";
+import { webWindowAdapter } from "../../react/web/adapters/WindowAdapter.js";
+import {
+ SuccessScreen,
+ type SuccessScreenProps,
+} from "../../react/web/ui/Bridge/payment-success/SuccessScreen.js";
+import { ModalThemeWrapper } from "../utils.js";
+import {
+ FUND_WALLET_UI_OPTIONS,
+ TRANSACTION_UI_OPTIONS,
+ simpleBuyQuote,
+ simpleOnrampQuote,
+} from "./fixtures.js";
+
+const mockBuyCompletedStatuses: CompletedStatusResult[] = JSON.parse(
+ stringify([
+ {
+ type: "buy",
+ status: "COMPLETED",
+ paymentId: "payment-12345",
+ originAmount: 1000000000000000000n,
+ destinationAmount: 100000000n,
+ originChainId: 1,
+ destinationChainId: 1,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ destinationTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ symbol: "ETH",
+ name: "Ethereum",
+ decimals: 18,
+ priceUsd: 2500,
+ },
+ destinationToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ symbol: "USDC",
+ name: "USD Coin",
+ decimals: 6,
+ priceUsd: 1,
+ },
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ transactions: [
+ {
+ chainId: 1,
+ transactionHash:
+ "0x1234567890abcdef1234567890abcdef12345678901234567890abcdef123456",
+ },
+ ],
+ },
+ ]),
+);
+
+const mockOnrampCompletedStatuses: CompletedStatusResult[] = JSON.parse(
+ stringify([
+ {
+ type: "onramp",
+ status: "COMPLETED",
+ transactions: [
+ {
+ chainId: 137,
+ transactionHash:
+ "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+ },
+ ],
+ purchaseData: {
+ orderId: "stripe-order-abc123",
+ },
+ },
+ ]),
+);
+
+// Props interface for the wrapper component
+interface SuccessScreenWithThemeProps extends SuccessScreenProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const SuccessScreenWithTheme = (props: SuccessScreenWithThemeProps) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/SuccessScreen",
+ component: SuccessScreenWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Success screen that displays completion confirmation with transaction summary, payment details, and action buttons for next steps. Includes animated success icon and detailed transaction view.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ preparedQuote: simpleBuyQuote,
+ completedStatuses: mockBuyCompletedStatuses,
+ onDone: () => {},
+ theme: "dark",
+ windowAdapter: webWindowAdapter,
+ uiOptions: FUND_WALLET_UI_OPTIONS.ethDefault,
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onDone: { action: "success screen closed" },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const DefaultLight: Story = {
+ args: {
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const OnrampPayment: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleOnrampQuote,
+ completedStatuses: mockOnrampCompletedStatuses,
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Success screen for onramp payments showing payment ID that can be copied to clipboard.",
+ },
+ },
+ },
+};
+
+export const OnrampPaymentLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleOnrampQuote,
+ completedStatuses: mockOnrampCompletedStatuses,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const ComplexPayment: Story = {
+ args: {
+ theme: "dark",
+ preparedQuote: simpleOnrampQuote,
+ completedStatuses: [
+ ...mockOnrampCompletedStatuses,
+ ...mockBuyCompletedStatuses,
+ ],
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Success screen for onramp payments showing payment ID that can be copied to clipboard.",
+ },
+ },
+ },
+};
+
+export const ComplexPaymentLight: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleOnrampQuote,
+ completedStatuses: [
+ ...mockOnrampCompletedStatuses,
+ ...mockBuyCompletedStatuses,
+ ],
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const TransactionPayment: Story = {
+ args: {
+ theme: "light",
+ preparedQuote: simpleBuyQuote,
+ completedStatuses: mockBuyCompletedStatuses,
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx b/packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx
new file mode 100644
index 00000000000..0a8deb13b92
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/TransactionPayment.stories.tsx
@@ -0,0 +1,170 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+ TransactionPayment,
+ type TransactionPaymentProps,
+} from "../../react/web/ui/Bridge/TransactionPayment.js";
+import { ModalThemeWrapper, storyClient } from "../utils.js";
+import { TRANSACTION_UI_OPTIONS } from "./fixtures.js";
+
+// Props interface for the wrapper component
+interface TransactionPaymentWithThemeProps extends TransactionPaymentProps {
+ theme: "light" | "dark";
+}
+
+// Wrapper component to provide theme context
+const TransactionPaymentWithTheme = (
+ props: TransactionPaymentWithThemeProps,
+) => {
+ const { theme, ...componentProps } = props;
+
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/TransactionPayment",
+ component: TransactionPaymentWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Transaction payment component that displays detailed transaction information including contract details, function names, transaction costs, and network fees.\n\n" +
+ "## Features\n" +
+ "- **Contract Information**: Shows contract name and clickable address\n" +
+ "- **Function Detection**: Extracts function names from transaction data using ABI\n" +
+ "- **Cost Calculation**: Displays transaction value and USD equivalent\n" +
+ "- **Network Fees**: Shows estimated gas costs with token amounts\n" +
+ "- **Chain Details**: Network name and logo with proper formatting\n" +
+ "- **Skeleton Loading**: Comprehensive loading states matching final layout\n\n" +
+ "This component now accepts uiOptions directly to configure the transaction and metadata. Supports both native token and ERC20 token transactions with proper function name extraction.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.ethTransfer,
+ client: storyClient,
+ onContinue: (_amount, _token, _receiverAddress) => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onContinue: {
+ action: "continue clicked",
+ description: "Called when user continues with the transaction",
+ },
+ uiOptions: {
+ description:
+ "UI configuration for transaction mode including prepared transaction",
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const EthereumTransfer: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.ethTransfer,
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Simple ETH transfer transaction showing native token value and network fees with USD conversion. Demonstrates function name extraction from contract ABI.",
+ },
+ },
+ },
+};
+
+export const EthereumTransferLight: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.ethTransfer,
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Simple ETH transfer transaction in light theme with skeleton loading support.",
+ },
+ },
+ },
+};
+
+export const ERC20TokenTransfer: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.erc20Transfer,
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "ERC20 token transaction showing token amount, USD value, and proper formatting using real token data. Displays transfer function details.",
+ },
+ },
+ },
+};
+
+export const ERC20TokenTransferLight: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.erc20Transfer,
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "ERC20 token transaction in light theme with enhanced formatting.",
+ },
+ },
+ },
+};
+
+export const ContractInteraction: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Complex contract interaction showing function name extraction from ABI (claimTo), cost calculation, and network details with proper currency formatting.",
+ },
+ },
+ },
+};
+
+export const ContractInteractionLight: Story = {
+ args: {
+ uiOptions: TRANSACTION_UI_OPTIONS.contractInteraction,
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Contract interaction transaction in light theme with enhanced UX and skeleton loading.",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/UnsupportedTokenScreen.stories.tsx b/packages/thirdweb/src/stories/Bridge/UnsupportedTokenScreen.stories.tsx
new file mode 100644
index 00000000000..71dc490b325
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/UnsupportedTokenScreen.stories.tsx
@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { defineChain } from "../../chains/utils.js";
+import type { Theme } from "../../react/core/design-system/index.js";
+import {
+ UnsupportedTokenScreen,
+ type UnsupportedTokenScreenProps,
+} from "../../react/web/ui/Bridge/UnsupportedTokenScreen.js";
+import { ModalThemeWrapper } from "../utils.js";
+
+// Props interface for the wrapper component
+interface UnsupportedTokenScreenWithThemeProps
+ extends UnsupportedTokenScreenProps {
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const UnsupportedTokenScreenWithTheme = (
+ props: UnsupportedTokenScreenWithThemeProps,
+) => {
+ const { theme, ...componentProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/UnsupportedTokenScreen",
+ component: UnsupportedTokenScreenWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "Screen displayed when a token is being indexed or when using an unsupported testnet. Shows loading state for indexing tokens or error state for testnets.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ chain: defineChain(1), // Ethereum mainnet
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const TokenNotSupported: Story = {
+ args: {
+ theme: "dark",
+ chain: defineChain(1), // Ethereum mainnet - will show indexing spinner
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Shows the loading state when a token is being indexed by the Universal Bridge on a mainnet chain.",
+ },
+ },
+ },
+};
+
+export const TokenNotSupportedLight: Story = {
+ args: {
+ theme: "light",
+ chain: defineChain(1), // Ethereum mainnet - will show indexing spinner
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Shows the loading state when a token is being indexed by the Universal Bridge on a mainnet chain (light theme).",
+ },
+ },
+ },
+};
+
+export const TestnetNotSupported: Story = {
+ args: {
+ theme: "dark",
+ chain: defineChain(11155111), // Sepolia testnet - will show error state
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ docs: {
+ description: {
+ story:
+ "Shows the error state when trying to use the Universal Bridge on a testnet chain (Sepolia in this example).",
+ },
+ },
+ },
+};
+
+export const TestnetNotSupportedLight: Story = {
+ args: {
+ theme: "light",
+ chain: defineChain(11155111), // Sepolia testnet - will show error state
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ docs: {
+ description: {
+ story:
+ "Shows the error state when trying to use the Universal Bridge on a testnet chain (Sepolia in this example, light theme).",
+ },
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/Bridge/fixtures.ts b/packages/thirdweb/src/stories/Bridge/fixtures.ts
new file mode 100644
index 00000000000..0b3f8cae16a
--- /dev/null
+++ b/packages/thirdweb/src/stories/Bridge/fixtures.ts
@@ -0,0 +1,802 @@
+import { stringify } from "viem";
+import type { Token } from "../../bridge/index.js";
+import { baseSepolia } from "../../chains/chain-definitions/base-sepolia.js";
+import { base } from "../../chains/chain-definitions/base.js";
+import { polygon } from "../../chains/chain-definitions/polygon.js";
+import { defineChain } from "../../chains/utils.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../constants/addresses.js";
+import { getContract } from "../../contract/contract.js";
+import { claimTo } from "../../extensions/erc20/drops/write/claimTo.js";
+import { transfer } from "../../extensions/erc20/write/transfer.js";
+import type { BridgePrepareResult } from "../../react/core/hooks/useBridgePrepare.js";
+import type { BridgePrepareRequest } from "../../react/core/hooks/useBridgePrepare.js";
+import { getDefaultToken } from "../../react/core/utils/defaultTokens.js";
+import type { UIOptions } from "../../react/web/ui/Bridge/BridgeOrchestrator.js";
+import { prepareTransaction } from "../../transaction/prepare-transaction.js";
+import { toWei } from "../../utils/units.js";
+import type { Account, Wallet } from "../../wallets/interfaces/wallet.js";
+import { storyClient } from "../utils.js";
+
+export const ETH: Token = {
+ address: NATIVE_TOKEN_ADDRESS,
+ name: "Ethereum",
+ symbol: "ETH",
+ chainId: 10,
+ decimals: 18,
+ priceUsd: 1000,
+ iconUri:
+ "https://coin-images.coingecko.com/coins/images/279/large/ethereum.png",
+};
+
+export const USDC: Token = {
+ address: getDefaultToken(base, "USDC")?.address ?? "",
+ name: "USD Coin",
+ symbol: "USDC",
+ chainId: base.id,
+ decimals: 6,
+ priceUsd: 1,
+ iconUri:
+ "https://coin-images.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+};
+
+export const UNI: Token = {
+ address: "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
+ name: "Uniswap",
+ symbol: "UNI",
+ chainId: 10,
+ decimals: 18,
+ priceUsd: 1000,
+ iconUri:
+ "https://coin-images.coingecko.com/coins/images/12504/large/uniswap-uni.png",
+};
+
+const createStoryMockWallet = (): Wallet => {
+ const mockAccount: Account = {
+ address: "0x1234567890123456789012345678901234567890" as `0x${string}`,
+ sendTransaction: async () => ({
+ transactionHash: "0xmockhash123" as `0x${string}`,
+ chain: defineChain(1),
+ client: storyClient,
+ }),
+ signMessage: async () => "0xsignature" as `0x${string}`,
+ signTypedData: async () => "0xsignature" as `0x${string}`,
+ };
+
+ // Simple mock wallet implementation for storybook display only
+ return {
+ id: "inApp",
+ getAccount: () => mockAccount,
+ getChain: async () => defineChain(1),
+ autoConnect: async () => mockAccount,
+ connect: async () => mockAccount,
+ disconnect: async () => {},
+ switchChain: async () => {},
+ subscribe: () => () => {},
+ getConfig: () => ({}),
+ } as unknown as Wallet;
+};
+
+export const STORY_MOCK_WALLET = createStoryMockWallet();
+
+// Simple onramp quote with no extra steps
+export const simpleOnrampQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "onramp",
+ id: "onramp-simple-123",
+ link: "https://stripe.com/session/simple",
+ currency: "USD",
+ currencyAmount: 50.0,
+ destinationAmount: 50000000n, // 50 USDC
+ destinationToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ timestamp: Date.now(),
+ steps: [], // No additional steps needed
+ intent: {
+ onramp: "stripe",
+ chainId: 137,
+ tokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ amount: 50000000n,
+ },
+ }),
+);
+
+// Onramp quote with 2 extra swap steps
+export const onrampWithSwapsQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "onramp",
+ id: "onramp-swaps-456",
+ link: "https://stripe.com/session/swaps",
+ currency: "EUR",
+ currencyAmount: 100.0,
+ destinationAmount: 1000000000000000000n, // 1 ETH
+ destinationToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ },
+ timestamp: Date.now(),
+ steps: [
+ {
+ originToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 137,
+ address: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ name: "Wrapped Ether",
+ symbol: "WETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ },
+ originAmount: 110000000n, // 110 USDC
+ destinationAmount: 44000000000000000n, // 0.044 WETH
+ estimatedExecutionTimeMs: 30000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0x1a2b3c",
+ to: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+ data: "0x095ea7b3",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ {
+ action: "buy",
+ id: "0x4d5e6f",
+ to: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+ data: "0x472b43f3",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ ],
+ },
+ {
+ originToken: {
+ chainId: 137,
+ address: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ name: "Wrapped Ether",
+ symbol: "WETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ },
+ destinationToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ },
+ originAmount: 44000000000000000n, // 0.044 WETH
+ destinationAmount: 1000000000000000000n, // 1 ETH
+ estimatedExecutionTimeMs: 180000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0x7g8h9i",
+ to: "0x3fc91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
+ data: "0x095ea7b3",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ {
+ action: "transfer",
+ id: "0xj1k2l3",
+ to: "0x3fc91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
+ data: "0x3593564c",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ ],
+ },
+ ],
+ intent: {
+ onramp: "stripe",
+ chainId: 1,
+ tokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ amount: 1000000000000000000n,
+ },
+ }),
+);
+
+// Simple buy quote with single step (no approval needed)
+export const simpleBuyQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "buy",
+ originAmount: 1000000000000000000n, // 1 ETH
+ destinationAmount: 100000000n, // 100 USDC
+ timestamp: Date.now(),
+ estimatedExecutionTimeMs: 60000,
+ steps: [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ name: "USD Coin",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ originAmount: 1000000000000000000n,
+ destinationAmount: 100000000n,
+ estimatedExecutionTimeMs: 60000,
+ transactions: [
+ {
+ action: "buy",
+ id: "0xsingle123",
+ to: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+ data: "0x472b43f3",
+ value: 1000000000000000000n,
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ ],
+ intent: {
+ originChainId: 1,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ destinationChainId: 1,
+ destinationTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ amount: 100000000n,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0x2247d5d238d0f9d37184d8332aE0289d1aD9991b",
+ },
+ }),
+);
+
+export const longTextBuyQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "buy",
+ originAmount: 1000000000000000000n, // 1 ETH
+ destinationAmount: 1000394284092830482309n,
+ timestamp: Date.now(),
+ estimatedExecutionTimeMs: 60000,
+ steps: [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 42793,
+ address: "0x796Ea11Fa2dD751eD01b53C372fFDB4AAa8f00F9",
+ name: "USD Coin (USDC.e on Etherlink)",
+ symbol: "USDC.e",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ originAmount: 1000000000000000000n,
+ destinationAmount: 1000394284092830482309n,
+ estimatedExecutionTimeMs: 60000,
+ transactions: [
+ {
+ action: "buy",
+ id: "0xsingle123",
+ to: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+ data: "0x472b43f3",
+ value: 1000000000000000000n,
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ ],
+ intent: {
+ originChainId: 1,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ destinationChainId: 1,
+ destinationTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ amount: 100000000n,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ },
+ }),
+);
+
+// Buy quote with approval + buy in single step
+export const buyWithApprovalQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "buy",
+ originAmount: 100000000n, // 100 USDC
+ destinationAmount: 100000000n, // 100 USDC on different chain
+ timestamp: Date.now(),
+ estimatedExecutionTimeMs: 120000,
+ steps: [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ name: "USD Coin",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ originAmount: 100000000n,
+ destinationAmount: 100000000n,
+ estimatedExecutionTimeMs: 120000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0xapproval789",
+ to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ data: "0x095ea7b3",
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ {
+ action: "buy",
+ id: "0xbuy456",
+ to: "0x3fc91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
+ data: "0x3593564c",
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ ],
+ intent: {
+ originChainId: 1,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 100000000n,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ },
+ }),
+);
+
+// Complex buy quote with 3 steps, each with approval + buy
+export const complexBuyQuote: BridgePrepareResult = JSON.parse(
+ stringify({
+ type: "buy",
+ originAmount: 1000000000000000000n, // 1 ETH
+ destinationAmount: 1000000000000000000n, // 1 ETH on final chain
+ timestamp: Date.now(),
+ estimatedExecutionTimeMs: 300000,
+ steps: [
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ name: "Ethereum",
+ symbol: "ETH",
+ decimals: 18,
+ priceUsd: 2500.0,
+ },
+ destinationToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ name: "USD Coin",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ originAmount: 1000000000000000000n,
+ destinationAmount: 2500000000n, // 2500 USDC
+ estimatedExecutionTimeMs: 60000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0xstep1approval",
+ to: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
+ data: "0x095ea7b3",
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ {
+ action: "buy",
+ id: "0xstep1buy",
+ to: "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
+ data: "0x7ff36ab5",
+ value: 1000000000000000000n,
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ {
+ originToken: {
+ chainId: 1,
+ address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ name: "USD Coin",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ originAmount: 2500000000n,
+ destinationAmount: 2495000000n, // 2495 USDC (after bridge fees)
+ estimatedExecutionTimeMs: 180000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0xstep2approval",
+ to: "0x3fc91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
+ data: "0x095ea7b3",
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ {
+ action: "transfer",
+ id: "0xstep2bridge",
+ to: "0x3fc91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
+ data: "0x3593564c",
+ chainId: 1,
+ client: storyClient,
+ chain: defineChain(1),
+ },
+ ],
+ },
+ {
+ originToken: {
+ chainId: 137,
+ address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ name: "USD Coin (PoS)",
+ symbol: "USDC",
+ decimals: 6,
+ priceUsd: 1.0,
+ iconUri:
+ "https://assets.coingecko.com/coins/images/6319/large/USD_Coin_icon.png",
+ },
+ destinationToken: {
+ chainId: 43114,
+ address: "0x62D0A8458eD7719FDAF978fe5929C6D342B0bFcE",
+ symbol: "BEAM",
+ name: "Beam",
+ decimals: 18,
+ priceUsd: 0.00642458,
+ iconUri:
+ "https://coin-images.coingecko.com/coins/images/32417/small/cgicon.png?1747892021",
+ },
+ originAmount: 2495000000n,
+ destinationAmount: 1000000000000000000n, // 1 BEAM
+ estimatedExecutionTimeMs: 60000,
+ transactions: [
+ {
+ action: "approval",
+ id: "0xstep3approval",
+ to: "0x1111111254fb6c44bAC0beD2854e76F90643097d",
+ data: "0x095ea7b3",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ {
+ action: "buy",
+ id: "0xstep3buy",
+ to: "0x1111111254fb6c44bAC0beD2854e76F90643097d",
+ data: "0x12aa3caf",
+ chainId: 137,
+ client: storyClient,
+ chain: defineChain(137),
+ },
+ ],
+ },
+ ],
+ intent: {
+ originChainId: 1,
+ originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ destinationChainId: 42161,
+ destinationTokenAddress: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+ amount: 1000000000000000000n,
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ },
+ }),
+);
+export const simpleBuyRequest: BridgePrepareRequest = {
+ type: "buy",
+ originChainId: 1,
+ originTokenAddress: NATIVE_TOKEN_ADDRESS,
+ destinationChainId: 10,
+ destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
+ amount: toWei("0.01"),
+ sender: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ receiver: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD",
+ client: storyClient,
+};
+
+// ========== PREPARED TRANSACTIONS FOR TRANSACTION PAYMENT ========== //
+
+// mintTo raw transaction
+const ethTransferTransaction = prepareTransaction({
+ to: "0x87C52295891f208459F334975a3beE198fE75244",
+ data: "0x449a52f80000000000000000000000008447c7a30d18e9adf2abe362689fc994cc6a340d00000000000000000000000000000000000000000000000000038d7ea4c68000",
+ chain: baseSepolia,
+ client: storyClient,
+});
+
+// ERC20 token transaction with value
+const erc20Transaction = transfer({
+ contract: getContract({
+ client: storyClient,
+ address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+ chain: base,
+ }),
+ to: "0x2247d5d238d0f9d37184d8332aE0289d1aD9991b",
+ amount: 100,
+});
+
+// claimTo on Polygon
+const contractInteractionTransaction = claimTo({
+ contract: getContract({
+ client: storyClient,
+ address: "0x683f91F407301b90e501492F8A26A3498D8d9638",
+ chain: polygon,
+ }),
+ to: "0x2247d5d238d0f9d37184d8332aE0289d1aD9991b",
+ quantity: "10",
+});
+
+// ========== COMMON DUMMY DATA FOR STORYBOOK ========== //
+
+// Common receiver addresses for testing
+export const RECEIVER_ADDRESSES = {
+ primary: "0x2247d5d238d0f9d37184d8332aE0289d1aD9991b" as const,
+ secondary: "0xa3841994009B4fEabb01ebcC62062F9E56F701CD" as const,
+ seller: "0x1234567890123456789012345678901234567890" as const,
+ subscription: "0x9876543210987654321098765432109876543210" as const,
+ physical: "0x5555666677778888999900001111222233334444" as const,
+};
+
+// Product metadata for direct payments
+const PRODUCT_METADATA = {
+ digitalArt: {
+ name: "Premium Digital Art NFT",
+ image:
+ "https://images.unsplash.com/photo-1465101046530-73398c7f28ca?w=500&h=300&fit=crop",
+ description: "This is a premium digital art by a famous artist",
+ },
+ concertTicket: {
+ name: "Concert Ticket - The Midnight Live",
+ image:
+ "https://images.unsplash.com/photo-1501281668745-f7f57925c3b4?w=500&h=300&fit=crop",
+ description: "Concert ticket for the upcoming show",
+ },
+ subscription: {
+ name: "Premium Streaming Service - Monthly",
+ image:
+ "https://images.unsplash.com/photo-1611162617474-5b21e879e113?w=500&h=300&fit=crop",
+ description:
+ "Get unlimited access to our premium streaming service with this monthly subscription. Enjoy ad-free viewing, exclusive content, and the ability to download shows for offline viewing.",
+ },
+ sneakers: {
+ name: "Limited Edition Sneakers",
+ image:
+ "https://images.unsplash.com/photo-1549298916-b41d501d3772?w=500&h=300&fit=crop",
+ },
+ credits: {
+ name: "Thirdweb Credits",
+ description:
+ "Add credits to your account for future billing cycles. Credits are non-refundable and do not expire.",
+ },
+};
+
+// Type aliases for better type safety
+type FundWalletUIOptions = Extract;
+type DirectPaymentUIOptions = Extract;
+type TransactionUIOptions = Extract;
+
+// UI Options for FundWallet mode
+export const FUND_WALLET_UI_OPTIONS: Record<
+ "ethDefault" | "ethWithAmount" | "usdcDefault" | "uniLarge",
+ FundWalletUIOptions
+> = {
+ ethDefault: {
+ mode: "fund_wallet" as const,
+ destinationToken: ETH,
+ metadata: {
+ title: "Fund Wallet",
+ description: "Add funds to your wallet",
+ },
+ },
+ ethWithAmount: {
+ mode: "fund_wallet" as const,
+ destinationToken: ETH,
+ initialAmount: "0.001",
+ metadata: {
+ title: "Fund Wallet",
+ description: "Add funds to your wallet",
+ },
+ },
+ usdcDefault: {
+ mode: "fund_wallet" as const,
+ destinationToken: USDC,
+ initialAmount: "5",
+ },
+ uniLarge: {
+ mode: "fund_wallet" as const,
+ destinationToken: UNI,
+ initialAmount: "150000",
+ metadata: {
+ title: "Fund Wallet",
+ description: "Add UNI tokens to your wallet",
+ },
+ },
+};
+
+// UI Options for DirectPayment mode
+export const DIRECT_PAYMENT_UI_OPTIONS: Record<
+ "digitalArt" | "concertTicket" | "subscription" | "sneakers" | "credits",
+ DirectPaymentUIOptions
+> = {
+ digitalArt: {
+ mode: "direct_payment" as const,
+ paymentInfo: {
+ sellerAddress: RECEIVER_ADDRESSES.seller,
+ token: ETH,
+ amount: "0.1",
+ feePayer: "sender" as const,
+ },
+ metadata: {
+ title: "Purchase Digital Art",
+ description: "Buy premium digital art NFT",
+ image: PRODUCT_METADATA.digitalArt.image,
+ },
+ },
+ concertTicket: {
+ mode: "direct_payment" as const,
+ paymentInfo: {
+ sellerAddress: RECEIVER_ADDRESSES.primary,
+ token: USDC,
+ amount: "25.00",
+ feePayer: "receiver" as const,
+ },
+ metadata: {
+ title: "Buy Concert Ticket",
+ description: "Get your ticket for The Midnight Live",
+ image: PRODUCT_METADATA.concertTicket.image,
+ },
+ },
+ subscription: {
+ mode: "direct_payment" as const,
+ paymentInfo: {
+ sellerAddress: RECEIVER_ADDRESSES.subscription,
+ token: USDC,
+ amount: "9.99",
+ feePayer: "sender" as const,
+ },
+ metadata: {
+ title: "Subscribe to Premium",
+ description: PRODUCT_METADATA.subscription.description,
+ image: PRODUCT_METADATA.subscription.image,
+ },
+ },
+ sneakers: {
+ mode: "direct_payment" as const,
+ paymentInfo: {
+ sellerAddress: RECEIVER_ADDRESSES.physical,
+ token: ETH,
+ amount: "0.05",
+ feePayer: "receiver" as const,
+ },
+ metadata: {
+ title: "Buy Sneakers",
+ description: "Limited edition sneakers",
+ image: PRODUCT_METADATA.sneakers.image,
+ },
+ },
+ credits: {
+ mode: "direct_payment" as const,
+ paymentInfo: {
+ sellerAddress: RECEIVER_ADDRESSES.physical,
+ token: USDC,
+ amount: "25",
+ feePayer: "receiver" as const,
+ },
+ metadata: {
+ title: "Add Credits",
+ description: PRODUCT_METADATA.credits.description,
+ },
+ },
+};
+
+// UI Options for Transaction mode
+export const TRANSACTION_UI_OPTIONS: Record<
+ "ethTransfer" | "erc20Transfer" | "contractInteraction",
+ TransactionUIOptions
+> = {
+ ethTransfer: {
+ mode: "transaction" as const,
+ transaction: ethTransferTransaction,
+ metadata: {
+ title: "Execute Transaction",
+ description: "Review and execute transaction",
+ },
+ },
+ erc20Transfer: {
+ mode: "transaction" as const,
+ transaction: erc20Transaction,
+ metadata: {
+ title: "Token Transfer",
+ description: "Transfer ERC20 tokens",
+ },
+ },
+ contractInteraction: {
+ mode: "transaction" as const,
+ transaction: contractInteractionTransaction,
+ metadata: {
+ title: "Contract Interaction",
+ description: "Interact with smart contract",
+ },
+ },
+};
diff --git a/packages/thirdweb/src/stories/TokenBalanceRow.stories.tsx b/packages/thirdweb/src/stories/TokenBalanceRow.stories.tsx
new file mode 100644
index 00000000000..dc9e46e5b70
--- /dev/null
+++ b/packages/thirdweb/src/stories/TokenBalanceRow.stories.tsx
@@ -0,0 +1,169 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { Token } from "../bridge/index.js";
+import { ethereum } from "../chains/chain-definitions/ethereum.js";
+import type { Chain } from "../chains/types.js";
+import type { ThirdwebClient } from "../client/client.js";
+import { CustomThemeProvider } from "../react/core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../react/core/design-system/index.js";
+import { TokenBalanceRow } from "../react/web/ui/Bridge/common/TokenBalanceRow.js";
+import { ETH, UNI, USDC } from "./Bridge/fixtures.js";
+import { storyClient } from "./utils.js";
+
+// Props interface for the wrapper component
+interface TokenBalanceRowWithThemeProps {
+ client: ThirdwebClient;
+ token: Token;
+ chain: Chain;
+ amount: string;
+ onClick: (token: Token) => void;
+ style?: React.CSSProperties;
+ theme: "light" | "dark" | Theme;
+}
+
+const dummyBalanceETH: string = "1.2345";
+
+const dummyBalanceUSDC: string = "1234.56";
+
+const dummyBalanceLowUNI: string = "0.0012";
+
+// Wrapper component to provide theme context
+const TokenBalanceRowWithTheme = (props: TokenBalanceRowWithThemeProps) => {
+ const { theme, ...tokenBalanceRowProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Bridge/TokenBalanceRow",
+ component: TokenBalanceRowWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "A row component that displays token balance information including token icon, symbol, chain, balance amount and fiat value. Used in bridge interfaces for token selection.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ client: storyClient,
+ token: ETH,
+ chain: ethereum,
+ amount: dummyBalanceETH,
+ onClick: (_token: Token) => {},
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ onClick: {
+ action: "clicked",
+ description: "Callback function when token row is clicked",
+ },
+ },
+} satisfies Meta;
+
+type Story = StoryObj;
+
+export const TokenList: Story = {
+ render: (args) => (
+
+
+ ),
+ args: {
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const DarkTokenList: Story = {
+ render: (args) => (
+
+
+ ),
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export default meta;
diff --git a/packages/thirdweb/src/stories/WalletRow.stories.tsx b/packages/thirdweb/src/stories/WalletRow.stories.tsx
new file mode 100644
index 00000000000..ebe21bb060d
--- /dev/null
+++ b/packages/thirdweb/src/stories/WalletRow.stories.tsx
@@ -0,0 +1,166 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { ThirdwebClient } from "../client/client.js";
+import { CustomThemeProvider } from "../react/core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../react/core/design-system/index.js";
+import { WalletRow } from "../react/web/ui/ConnectWallet/screens/Buy/swap/WalletRow.js";
+import { storyClient } from "./utils.js";
+
+// Props interface for the wrapper component
+interface WalletRowWithThemeProps {
+ client: ThirdwebClient;
+ address: string;
+ iconSize?: "xs" | "sm" | "md" | "lg" | "xl";
+ textSize?: "xs" | "sm" | "md" | "lg" | "xl";
+ label?: string;
+ theme: "light" | "dark" | Theme;
+}
+
+// Wrapper component to provide theme context
+const WalletRowWithTheme = (props: WalletRowWithThemeProps) => {
+ const { theme, ...walletRowProps } = props;
+ return (
+
+
+ );
+};
+
+const meta = {
+ title: "Connect/WalletRow",
+ component: WalletRowWithTheme,
+ parameters: {
+ layout: "centered",
+ docs: {
+ description: {
+ component:
+ "A reusable component that displays wallet information including address, wallet type, and optional ENS name or email.",
+ },
+ },
+ },
+ tags: ["autodocs"],
+ args: {
+ client: storyClient,
+ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", // Vitalik's address for ENS demo
+ theme: "dark",
+ },
+ argTypes: {
+ theme: {
+ control: "select",
+ options: ["light", "dark"],
+ description: "Theme for the component",
+ },
+ iconSize: {
+ control: "select",
+ options: ["xs", "sm", "md", "lg", "xl"],
+ description: "Size of the wallet icon",
+ },
+ textSize: {
+ control: "select",
+ options: ["xs", "sm", "md", "lg", "xl"],
+ description: "Size of the main address text",
+ },
+ label: {
+ control: "text",
+ description: "Optional label to display above the address",
+ },
+ address: {
+ control: "text",
+ description: "Wallet address to display",
+ },
+ },
+} satisfies Meta;
+
+type Story = StoryObj;
+
+export const Light: Story = {
+ args: {
+ theme: "light",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const Dark: Story = {
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const WithLabel: Story = {
+ args: {
+ theme: "dark",
+ label: "Recipient Wallet",
+ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const LargeSize: Story = {
+ args: {
+ theme: "light",
+ iconSize: "lg",
+ textSize: "md",
+ label: "Primary Wallet",
+ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+ },
+ parameters: {
+ backgrounds: { default: "light" },
+ },
+};
+
+export const SmallSize: Story = {
+ args: {
+ theme: "dark",
+ iconSize: "sm",
+ textSize: "xs",
+ address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export const DifferentAddresses: Story = {
+ render: (args) => (
+
+
+ ),
+ args: {
+ theme: "dark",
+ },
+ parameters: {
+ backgrounds: { default: "dark" },
+ },
+};
+
+export default meta;
diff --git a/packages/thirdweb/src/stories/utils.tsx b/packages/thirdweb/src/stories/utils.tsx
index 45502b9fc3b..28d8d004339 100644
--- a/packages/thirdweb/src/stories/utils.tsx
+++ b/packages/thirdweb/src/stories/utils.tsx
@@ -1,4 +1,10 @@
import { createThirdwebClient } from "../client/client.js";
+import {
+ CustomThemeProvider,
+ useCustomTheme,
+} from "../react/core/design-system/CustomThemeProvider.js";
+import type { Theme } from "../react/core/design-system/index.js";
+import { radius } from "../react/native/design-system/index.js";
const clientId = process.env.STORYBOOK_CLIENT_ID;
@@ -9,3 +15,32 @@ if (!clientId) {
export const storyClient = createThirdwebClient({
clientId: clientId,
});
+
+export const ModalThemeWrapper = (props: {
+ children: React.ReactNode;
+ theme: "light" | "dark" | Theme;
+}) => {
+ const { theme } = props;
+ return (
+
+ {props.children}
+
+ );
+};
+
+const ModalWrapper = (props: { children: React.ReactNode }) => {
+ const theme = useCustomTheme();
+ return (
+
-
- );
-}
diff --git a/apps/playground-web/src/components/pay/transaction-button.tsx b/apps/playground-web/src/components/pay/transaction-button.tsx
index f34df14ee83..3d4fd7e3b53 100644
--- a/apps/playground-web/src/components/pay/transaction-button.tsx
+++ b/apps/playground-web/src/components/pay/transaction-button.tsx
@@ -1,14 +1,13 @@
"use client";
import { useTheme } from "next-themes";
-import { getContract } from "thirdweb";
-import { prepareTransaction } from "thirdweb";
+import { getContract, prepareTransaction } from "thirdweb";
import { base, baseSepolia, polygon } from "thirdweb/chains";
import { transfer } from "thirdweb/extensions/erc20";
import { claimTo, getNFT } from "thirdweb/extensions/erc1155";
import {
- PayEmbed,
TransactionButton,
+ TransactionWidget,
getDefaultToken,
useActiveAccount,
useReadContract,
@@ -45,20 +44,18 @@ export function PayTransactionPreview() {
+
+
+ );
+}
diff --git a/packages/thirdweb/package.json b/packages/thirdweb/package.json
index 921c7ed9996..f45e1a944a4 100644
--- a/packages/thirdweb/package.json
+++ b/packages/thirdweb/package.json
@@ -147,66 +147,26 @@
},
"typesVersions": {
"*": {
- "adapters/*": [
- "./dist/types/exports/adapters/*.d.ts"
- ],
- "auth": [
- "./dist/types/exports/auth.d.ts"
- ],
- "chains": [
- "./dist/types/exports/chains.d.ts"
- ],
- "contract": [
- "./dist/types/exports/contract.d.ts"
- ],
- "deploys": [
- "./dist/types/exports/deploys.d.ts"
- ],
- "event": [
- "./dist/types/exports/event.d.ts"
- ],
- "extensions/*": [
- "./dist/types/exports/extensions/*.d.ts"
- ],
- "pay": [
- "./dist/types/exports/pay.d.ts"
- ],
- "react": [
- "./dist/types/exports/react.d.ts"
- ],
- "react-native": [
- "./dist/types/exports/react.native.d.ts"
- ],
- "rpc": [
- "./dist/types/exports/rpc.d.ts"
- ],
- "storage": [
- "./dist/types/exports/storage.d.ts"
- ],
- "transaction": [
- "./dist/types/exports/transaction.d.ts"
- ],
- "utils": [
- "./dist/types/exports/utils.d.ts"
- ],
- "wallets": [
- "./dist/types/exports/wallets.d.ts"
- ],
- "wallets/*": [
- "./dist/types/exports/wallets/*.d.ts"
- ],
- "modules": [
- "./dist/types/exports/modules.d.ts"
- ],
- "social": [
- "./dist/types/exports/social.d.ts"
- ],
- "ai": [
- "./dist/types/exports/ai.d.ts"
- ],
- "bridge": [
- "./dist/types/exports/bridge.d.ts"
- ]
+ "adapters/*": ["./dist/types/exports/adapters/*.d.ts"],
+ "auth": ["./dist/types/exports/auth.d.ts"],
+ "chains": ["./dist/types/exports/chains.d.ts"],
+ "contract": ["./dist/types/exports/contract.d.ts"],
+ "deploys": ["./dist/types/exports/deploys.d.ts"],
+ "event": ["./dist/types/exports/event.d.ts"],
+ "extensions/*": ["./dist/types/exports/extensions/*.d.ts"],
+ "pay": ["./dist/types/exports/pay.d.ts"],
+ "react": ["./dist/types/exports/react.d.ts"],
+ "react-native": ["./dist/types/exports/react.native.d.ts"],
+ "rpc": ["./dist/types/exports/rpc.d.ts"],
+ "storage": ["./dist/types/exports/storage.d.ts"],
+ "transaction": ["./dist/types/exports/transaction.d.ts"],
+ "utils": ["./dist/types/exports/utils.d.ts"],
+ "wallets": ["./dist/types/exports/wallets.d.ts"],
+ "wallets/*": ["./dist/types/exports/wallets/*.d.ts"],
+ "modules": ["./dist/types/exports/modules.d.ts"],
+ "social": ["./dist/types/exports/social.d.ts"],
+ "ai": ["./dist/types/exports/ai.d.ts"],
+ "bridge": ["./dist/types/exports/bridge.d.ts"]
}
},
"browser": {
@@ -235,6 +195,7 @@
"@radix-ui/react-focus-scope": "1.1.7",
"@radix-ui/react-icons": "1.3.2",
"@radix-ui/react-tooltip": "1.2.7",
+ "@storybook/react": "9.0.8",
"@tanstack/react-query": "5.80.7",
"@thirdweb-dev/engine": "workspace:*",
"@thirdweb-dev/insight": "workspace:*",
diff --git a/packages/thirdweb/src/bridge/Routes.ts b/packages/thirdweb/src/bridge/Routes.ts
index d023c7d7e95..012a9fb42fc 100644
--- a/packages/thirdweb/src/bridge/Routes.ts
+++ b/packages/thirdweb/src/bridge/Routes.ts
@@ -131,6 +131,7 @@ export async function routes(options: routes.Options): Promise
+ *
+ * );
+ * }
+ * ```
+ */
+export function useBridgeError(
+ params: UseBridgeErrorParams,
+): UseBridgeErrorResult {
+ const { error } = params;
+
+ // No error case
+ if (!error) {
+ return {
+ mappedError: null,
+ isRetryable: false,
+ userMessage: "",
+ errorCode: null,
+ statusCode: null,
+ isClientError: false,
+ isServerError: false,
+ };
+ }
+
+ // Convert to ApiError if it's not already
+ let apiError: ApiError;
+ if (error instanceof ApiError) {
+ apiError = mapBridgeError(error);
+ } else {
+ // Create ApiError from generic Error
+ apiError = new ApiError({
+ code: "UNKNOWN_ERROR",
+ message: error.message || "An unknown error occurred",
+ statusCode: 500, // Default for generic errors
+ });
+ }
+
+ const statusCode = apiError.statusCode || null;
+ const isClientError =
+ statusCode !== null && statusCode >= 400 && statusCode < 500;
+ const isServerError = statusCode !== null && statusCode >= 500;
+
+ // Generate user-friendly message based on error code
+ const userMessage = getUserFriendlyMessage(apiError);
+
+ return {
+ mappedError: apiError,
+ isRetryable: isRetryable(apiError.code),
+ userMessage,
+ errorCode: apiError.code,
+ statusCode,
+ isClientError,
+ isServerError,
+ };
+}
+
+/**
+ * Converts technical error codes to user-friendly messages
+ */
+function getUserFriendlyMessage(error: ApiError): string {
+ switch (error.code) {
+ case "INVALID_INPUT":
+ return "Invalid input provided. Please check your parameters and try again.";
+ case "ROUTE_NOT_FOUND":
+ return "No route found for this transaction. Please try a different token pair or amount.";
+ case "AMOUNT_TOO_LOW":
+ return "The amount is too low for this transaction. Please increase the amount.";
+ case "AMOUNT_TOO_HIGH":
+ return "The amount is too high for this transaction. Please decrease the amount.";
+ case "INTERNAL_SERVER_ERROR":
+ return "A temporary error occurred. Please try again in a moment.";
+ default:
+ // Fallback to the original error message if available
+ return error.message || "An unexpected error occurred. Please try again.";
+ }
+}
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgePrepare.test.ts b/packages/thirdweb/src/react/core/hooks/useBridgePrepare.test.ts
new file mode 100644
index 00000000000..5293e528879
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgePrepare.test.ts
@@ -0,0 +1,161 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ThirdwebClient } from "../../../client/client.js";
+import type {
+ BridgePrepareRequest,
+ UseBridgePrepareParams,
+} from "./useBridgePrepare.js";
+
+// Mock client
+const mockClient = { clientId: "test" } as ThirdwebClient;
+
+describe("useBridgePrepare", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it("should have correct type structure for buy prepare request", () => {
+ const buyRequest: BridgePrepareRequest = {
+ type: "buy",
+ client: mockClient,
+ originChainId: 1,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ };
+
+ expect(buyRequest.type).toBe("buy");
+ expect(buyRequest.amount).toBe(1000000n);
+ expect(buyRequest.client).toBe(mockClient);
+ });
+
+ it("should have correct type structure for transfer prepare request", () => {
+ const transferRequest: BridgePrepareRequest = {
+ type: "transfer",
+ client: mockClient,
+ chainId: 1,
+ tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ };
+
+ expect(transferRequest.type).toBe("transfer");
+ expect(transferRequest.amount).toBe(1000000n);
+ expect(transferRequest.client).toBe(mockClient);
+ });
+
+ it("should have correct type structure for sell prepare request", () => {
+ const sellRequest: BridgePrepareRequest = {
+ type: "sell",
+ client: mockClient,
+ originChainId: 1,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ };
+
+ expect(sellRequest.type).toBe("sell");
+ expect(sellRequest.amount).toBe(1000000n);
+ expect(sellRequest.client).toBe(mockClient);
+ });
+
+ it("should have correct type structure for onramp prepare request", () => {
+ const onrampRequest: BridgePrepareRequest = {
+ type: "onramp",
+ client: mockClient,
+ onramp: "stripe",
+ chainId: 137,
+ tokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ receiver: "0x1234567890123456789012345678901234567890",
+ amount: 1000000n,
+ };
+
+ expect(onrampRequest.type).toBe("onramp");
+ expect(onrampRequest.amount).toBe(1000000n);
+ expect(onrampRequest.client).toBe(mockClient);
+ });
+
+ it("should handle UseBridgePrepareParams with enabled option", () => {
+ const params: UseBridgePrepareParams = {
+ type: "buy",
+ client: mockClient,
+ originChainId: 1,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ enabled: false,
+ };
+
+ expect(params.enabled).toBe(false);
+ expect(params.type).toBe("buy");
+ });
+
+ it("should have optional enabled parameter", () => {
+ const paramsWithoutEnabled: UseBridgePrepareParams = {
+ type: "transfer",
+ client: mockClient,
+ chainId: 1,
+ tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ };
+
+ expect(paramsWithoutEnabled.enabled).toBeUndefined(); // Should be optional
+ expect(paramsWithoutEnabled.type).toBe("transfer");
+ });
+
+ it("should correctly discriminate between different prepare request types", () => {
+ const buyRequest: BridgePrepareRequest = {
+ type: "buy",
+ client: mockClient,
+ originChainId: 1,
+ originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ destinationChainId: 137,
+ destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ amount: 1000000n,
+ sender: "0x1234567890123456789012345678901234567890",
+ receiver: "0x1234567890123456789012345678901234567890",
+ };
+
+ // Type narrowing should work
+ if (buyRequest.type === "buy") {
+ expect(buyRequest.sender).toBe(
+ "0x1234567890123456789012345678901234567890",
+ );
+ expect(buyRequest.receiver).toBe(
+ "0x1234567890123456789012345678901234567890",
+ );
+ }
+
+ const onrampRequest: BridgePrepareRequest = {
+ type: "onramp",
+ client: mockClient,
+ onramp: "stripe",
+ chainId: 137,
+ tokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ receiver: "0x1234567890123456789012345678901234567890",
+ amount: 1000000n,
+ };
+
+ // Type narrowing should work for onramp
+ if (onrampRequest.type === "onramp") {
+ expect(onrampRequest.receiver).toBe(
+ "0x1234567890123456789012345678901234567890",
+ );
+ expect(onrampRequest.tokenAddress).toBe(
+ "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ );
+ expect(onrampRequest.onramp).toBe("stripe");
+ }
+ });
+});
diff --git a/packages/thirdweb/src/react/core/hooks/useBridgePrepare.ts b/packages/thirdweb/src/react/core/hooks/useBridgePrepare.ts
new file mode 100644
index 00000000000..8ee3c592871
--- /dev/null
+++ b/packages/thirdweb/src/react/core/hooks/useBridgePrepare.ts
@@ -0,0 +1,133 @@
+import { useQuery } from "@tanstack/react-query";
+import type { prepare as BuyPrepare } from "../../../bridge/Buy.js";
+import type { prepare as OnrampPrepare } from "../../../bridge/Onramp.js";
+import type { prepare as SellPrepare } from "../../../bridge/Sell.js";
+import type { prepare as TransferPrepare } from "../../../bridge/Transfer.js";
+import * as Bridge from "../../../bridge/index.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { stringify } from "../../../utils/json.js";
+import { mapBridgeError } from "../errors/mapBridgeError.js";
+
+/**
+ * Union type for different Bridge prepare request types
+ */
+export type BridgePrepareRequest =
+ | ({ type: "buy" } & BuyPrepare.Options)
+ | ({ type: "sell" } & SellPrepare.Options)
+ | ({ type: "transfer" } & TransferPrepare.Options)
+ | ({ type: "onramp" } & OnrampPrepare.Options);
+
+/**
+ * Union type for different Bridge prepare result types
+ */
+export type BridgePrepareResult =
+ | ({ type: "buy" } & BuyPrepare.Result)
+ | ({ type: "sell" } & SellPrepare.Result)
+ | ({ type: "transfer" } & TransferPrepare.Result)
+ | ({ type: "onramp" } & OnrampPrepare.Result);
+
+/**
+ * Parameters for the useBridgePrepare hook
+ */
+export type UseBridgePrepareParams = BridgePrepareRequest & {
+ /**
+ * Whether to enable the query. Useful for conditional fetching.
+ * @default true
+ */
+ enabled?: boolean;
+};
+
+/**
+ * Hook that prepares bridge transactions with caching and retry logic
+ *
+ * @param params - Parameters for preparing bridge transactions including type and specific options
+ * @returns React Query result with prepared transaction data, loading state, and error handling
+ *
+ * @example
+ * ```tsx
+ * // Buy preparation
+ * const { data: preparedBuy, isLoading, error } = useBridgePrepare({
+ * type: "buy",
+ * client: thirdwebClient,
+ * originChainId: 1,
+ * originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ * destinationChainId: 137,
+ * destinationTokenAddress: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ * amount: parseEther("1"),
+ * sender: "0x...",
+ * receiver: "0x..."
+ * });
+ *
+ * // Transfer preparation
+ * const { data: preparedTransfer } = useBridgePrepare({
+ * type: "transfer",
+ * client: thirdwebClient,
+ * originChainId: 1,
+ * originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ * destinationChainId: 137,
+ * destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ * amount: 1000000n,
+ * sender: "0x...",
+ * receiver: "0x..."
+ * });
+ * ```
+ */
+export function useBridgePrepare(params: UseBridgePrepareParams) {
+ const { enabled = true, type, ...prepareParams } = params;
+
+ return useQuery({
+ queryKey: ["bridge-prepare", type, stringify(prepareParams)],
+ queryFn: async (): Promise{userMessage}
+ * {isRetryable && } + *
+
+ );
+ } else if (bridgeDataQuery.data?.type === "unsupported_token") {
+ // Show unsupported token screen
+ content =
+
+ );
+ } else if (bridgeDataQuery.data?.type === "unsupported_token") {
+ // Show unsupported token screen
+ content = ) => {
+ if (e.key === "Enter" || e.key === " ") {
+ e.preventDefault();
+ focusInput();
+ }
+ }}
+ role="button"
+ tabIndex={0}
+ >
+
+ {
+ // put cursor at the end of the input
+ if (amount === "") {
+ e.currentTarget.setSelectionRange(
+ e.currentTarget.value.length,
+ e.currentTarget.value.length,
+ );
+ }
+ }}
+ onChange={(e) => {
+ handleAmountChange(e.target.value);
+ }}
+ style={{
+ fontSize: getAmountFontSize(),
+ fontWeight: 600,
+ textAlign: "right",
+ padding: "0",
+ border: "none",
+ boxShadow: "none",
+ }}
+ />
+
+
+
+ {/* Fiat Value */}
+ transactions are complete. +
+
+ );
+ } else if (bridgeDataQuery.data?.type === "unsupported_token") {
+ // Show unsupported token screen
+ content =
+
+
+
+
+
+
+
+
+ {props.children}
+
+ );
+};
diff --git a/packages/thirdweb/src/wallets/connection/autoConnectCore.test.ts b/packages/thirdweb/src/wallets/connection/autoConnectCore.test.ts
index 395472fc108..0819fe1b448 100644
--- a/packages/thirdweb/src/wallets/connection/autoConnectCore.test.ts
+++ b/packages/thirdweb/src/wallets/connection/autoConnectCore.test.ts
@@ -90,59 +90,6 @@ describe("useAutoConnectCore", () => {
).toBe(false);
});
- it("should call onTimeout on ... timeout", async () => {
- vi.mocked(getUrlToken).mockReturnValue({});
-
- const wallet = createWalletAdapter({
- adaptedAccount: TEST_ACCOUNT_A,
- client: TEST_CLIENT,
- chain: ethereum,
- onDisconnect: () => {},
- switchChain: () => {},
- });
- mockStorage.setItem("thirdweb:active-wallet-id", wallet.id);
- const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
- const infoSpy = vi.spyOn(console, "info").mockImplementation(() => {});
- // Purposefully mock the wallet.autoConnect method to test the timeout logic
- wallet.autoConnect = () =>
- new Promise((resolve) => {
- setTimeout(() => {
- // @ts-ignore Mock purpose
- resolve("Connection successful");
- }, 2100);
- });
-
- await autoConnectCore({
- force: true,
- storage: mockStorage,
- props: {
- wallets: [wallet],
- client: TEST_CLIENT,
- onTimeout: () => console.info("TIMEOUTTED"),
- timeout: 0,
- },
- createWalletFn: (id: WalletId) =>
- createWalletAdapter({
- adaptedAccount: TEST_ACCOUNT_A,
- client: TEST_CLIENT,
- chain: ethereum,
- onDisconnect: () => {
- console.warn(id);
- },
- switchChain: () => {},
- }),
- manager,
- });
-
- expect(warnSpy).toHaveBeenCalled();
- expect(warnSpy).toHaveBeenCalledWith(
- "AutoConnect timeout: 0ms limit exceeded.",
- );
- expect(infoSpy).toHaveBeenCalled();
- expect(infoSpy).toHaveBeenCalledWith("TIMEOUTTED");
- warnSpy.mockRestore();
- });
-
it("should handle auth cookie storage correctly", async () => {
const mockAuthCookie = "mock-auth-cookie";
const wallet = createWalletAdapter({
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9aaff733e53..1fc1f87cba9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1065,7 +1065,7 @@ importers:
version: 22.14.1
'@vitest/coverage-v8':
specifier: 3.2.3
- version: 3.2.3(vitest@3.2.3(@types/debug@4.1.12)(@types/node@22.14.1)(@vitest/ui@3.2.3)(happy-dom@18.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.10.2(@types/node@22.14.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))
+ version: 3.2.3(vitest@3.2.3)
typescript:
specifier: 5.8.3
version: 5.8.3
@@ -1105,6 +1105,9 @@ importers:
'@radix-ui/react-tooltip':
specifier: 1.2.7
version: 1.2.7(@types/react-dom@19.1.6(@types/react@19.1.8))(@types/react@19.1.8)(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
+ '@storybook/react':
+ specifier: 9.0.8
+ version: 9.0.8(react-dom@19.1.0(react@19.1.0))(react@19.1.0)(storybook@9.0.8(@testing-library/dom@10.4.0)(bufferutil@4.0.9)(prettier@3.5.3)(utf-8-validate@5.0.10))(typescript@5.8.3)
'@tanstack/react-query':
specifier: 5.80.7
version: 5.80.7(react@19.1.0)
@@ -1180,7 +1183,7 @@ importers:
version: 4.0.0(storybook@9.0.8(@testing-library/dom@10.4.0)(bufferutil@4.0.9)(prettier@3.5.3)(utf-8-validate@5.0.10))
'@codspeed/vitest-plugin':
specifier: 4.0.1
- version: 4.0.1(vite@6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))(vitest@3.2.3(@types/debug@4.1.12)(@types/node@24.0.1)(@vitest/ui@3.2.3)(happy-dom@17.4.4)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.7.5(@types/node@24.0.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))
+ version: 4.0.1(vite@6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))(vitest@3.2.3)
'@coinbase/wallet-mobile-sdk':
specifier: 1.1.2
version: 1.1.2(expo@53.0.11(@babel/core@7.27.4)(bufferutil@4.0.9)(graphql@16.11.0)(react-native@0.78.1(@babel/core@7.27.4)(@babel/preset-env@7.27.2(@babel/core@7.27.4))(@types/react@19.1.8)(bufferutil@4.0.9)(react@19.1.0)(utf-8-validate@5.0.10))(react@19.1.0)(utf-8-validate@5.0.10))(react-native@0.78.1(@babel/core@7.27.4)(@babel/preset-env@7.27.2(@babel/core@7.27.4))(@types/react@19.1.8)(bufferutil@4.0.9)(react@19.1.0)(utf-8-validate@5.0.10))(react@19.1.0)
@@ -1231,7 +1234,7 @@ importers:
version: 4.5.2(vite@6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))
'@vitest/coverage-v8':
specifier: 3.2.3
- version: 3.2.3(vitest@3.2.3(@types/debug@4.1.12)(@types/node@24.0.1)(@vitest/ui@3.2.3)(happy-dom@17.4.4)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.7.5(@types/node@24.0.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))
+ version: 3.2.3(vitest@3.2.3)
'@vitest/ui':
specifier: 3.2.3
version: 3.2.3(vitest@3.2.3)
@@ -18240,7 +18243,7 @@ snapshots:
transitivePeerDependencies:
- debug
- '@codspeed/vitest-plugin@4.0.1(vite@6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))(vitest@3.2.3(@types/debug@4.1.12)(@types/node@24.0.1)(@vitest/ui@3.2.3)(happy-dom@17.4.4)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.7.5(@types/node@24.0.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))':
+ '@codspeed/vitest-plugin@4.0.1(vite@6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))(vitest@3.2.3)':
dependencies:
'@codspeed/core': 4.0.1
vite: 6.3.5(@types/node@24.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0)
@@ -25267,7 +25270,7 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@vitest/coverage-v8@3.2.3(vitest@3.2.3(@types/debug@4.1.12)(@types/node@22.14.1)(@vitest/ui@3.2.3)(happy-dom@18.0.1)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.10.2(@types/node@22.14.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))':
+ '@vitest/coverage-v8@3.2.3(vitest@3.2.3)':
dependencies:
'@ampproject/remapping': 2.3.0
'@bcoe/v8-coverage': 1.0.2
@@ -25286,25 +25289,6 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@vitest/coverage-v8@3.2.3(vitest@3.2.3(@types/debug@4.1.12)(@types/node@24.0.1)(@vitest/ui@3.2.3)(happy-dom@17.4.4)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.7.5(@types/node@24.0.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0))':
- dependencies:
- '@ampproject/remapping': 2.3.0
- '@bcoe/v8-coverage': 1.0.2
- ast-v8-to-istanbul: 0.3.3
- debug: 4.4.1(supports-color@8.1.1)
- istanbul-lib-coverage: 3.2.2
- istanbul-lib-report: 3.0.1
- istanbul-lib-source-maps: 5.0.6
- istanbul-reports: 3.1.7
- magic-string: 0.30.17
- magicast: 0.3.5
- std-env: 3.9.0
- test-exclude: 7.0.1
- tinyrainbow: 2.0.0
- vitest: 3.2.3(@types/debug@4.1.12)(@types/node@24.0.1)(@vitest/ui@3.2.3)(happy-dom@17.4.4)(jiti@2.4.2)(lightningcss@1.30.1)(msw@2.7.5(@types/node@24.0.1)(typescript@5.8.3))(terser@5.42.0)(tsx@4.20.1)(yaml@2.8.0)
- transitivePeerDependencies:
- - supports-color
-
'@vitest/expect@3.0.9':
dependencies:
'@vitest/spy': 3.0.9
@@ -29052,7 +29036,7 @@ snapshots:
- bluebird
- supports-color
- eslint-module-utils@2.12.0(@typescript-eslint/parser@7.14.1(eslint@8.57.0)(typescript@5.8.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.31.0)(eslint@8.57.0))(eslint@8.57.0):
+ eslint-module-utils@2.12.0(@typescript-eslint/parser@7.14.1(eslint@8.57.0)(typescript@5.8.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.0):
dependencies:
debug: 3.2.7
optionalDependencies:
@@ -29085,7 +29069,7 @@ snapshots:
doctrine: 2.1.0
eslint: 8.57.0
eslint-import-resolver-node: 0.3.9
- eslint-module-utils: 2.12.0(@typescript-eslint/parser@7.14.1(eslint@8.57.0)(typescript@5.8.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1(eslint-plugin-import@2.31.0)(eslint@8.57.0))(eslint@8.57.0)
+ eslint-module-utils: 2.12.0(@typescript-eslint/parser@7.14.1(eslint@8.57.0)(typescript@5.8.3))(eslint-import-resolver-node@0.3.9)(eslint-import-resolver-typescript@3.10.1)(eslint@8.57.0)
hasown: 2.0.2
is-core-module: 2.16.1
is-glob: 4.0.3