@xswap-link/sdk 0.14.0 → 0.15.0

package/src/context/SwapProvider.tsx

@@ -1,5 +1,7 @@
 import { TxConfigFormPayload } from "@src/components";
 import {
+  DEFAULT_BRIDGE_DESTINATION_CHAIN_ID,
+  DEFAULT_BRIDGE_SOURCE_CHAIN_ID,
   DEFAULT_DESTINATION_CHAIN_ID,
   DEFAULT_REQUEST_ABORT_MSG,
   DEFAULT_SOURCE_CHAIN_ID,
@@ -28,10 +30,11 @@ import {
   getPrices,
   getRoute,
   getSolanaRoute,
+  getTokenBalance,
 } from "@src/services";
+import { getCustomTokenRefs } from "@src/utils/tokens";
 import {
   deepMergeObjects,
-  getBalanceOf,
   humanReadableToWei,
   isServer,
   resolveTokenAddress,
@@ -129,6 +132,10 @@ type SwapContext = {
     chainId: string | undefined,
     token: TokenOption,
   ) => void;
+  // Which side's token/network picker is open. The picker renders in place
+  // of the swap view (desktop) or as a bottom sheet (mobile).
+  activePicker: "source" | "destination" | null;
+  setActivePicker: Dispatch<SetStateAction<"source" | "destination" | null>>;
 };
 
 const functionNotImplemented = () => {
@@ -142,6 +149,8 @@ const init: SwapContext = {
   tab: "Swap",
   overlay: false,
   error: "",
+  activePicker: null,
+  setActivePicker: functionNotImplemented,
   feeToken: undefined,
   srcChain: undefined,
   srcChainTokensOptions: [],
@@ -224,6 +233,7 @@ export const SwapProvider = ({
   // Settings
   const [tab, setTab] = useState(init.tab);
   const [error, setError] = useState(init.error);
+  const [activePicker, setActivePicker] = useState(init.activePicker);
   const [expressDelivery, setExpressDelivery] = useState(init.expressDelivery);
   const [slippage, setSlippage] = useState(init.slippage);
   const [infiniteApproval, setInfiniteApproval] = useState(
@@ -240,6 +250,9 @@ export const SwapProvider = ({
   const [tokenBalances, setTokenBalances] = useState<
     Record<string, Record<string, string>>
   >({});
+  // bumped when the user imports a token, so the supported tokens mapping and
+  // the balances list get rebuilt with the new custom token included
+  const [customTokensVersion, setCustomTokensVersion] = useState(0);
   const [bridgeTokens, setBridgeTokens] = useState<BridgeToken[]>([]);
   // Values
   const [srcValue, setSrcValue] = useState(init.srcValue);
@@ -280,6 +293,19 @@ export const SwapProvider = ({
   const routeAbortController = useRef<AbortController | null>(null);
   const refreshSelectedTokenBalanceNonce = useRef(crypto.randomUUID());
   const prevWalletAddresses = useRef<string | undefined>(undefined);
+  // last wallet chain id seen by the follow-the-wallet effect below
+  const prevFollowedWalletChainId = useRef<string | undefined>(undefined);
+  // True between the bridgeUI-change reset and the re-init that follows it.
+  // Effects in the reset's commit still close over the pre-reset state (with
+  // the new bridgeUI), so acting on that mix would remap the old mode's route
+  // as the new mode's — this ref lets them bail out synchronously.
+  const initPending = useRef(false);
+  // True while a bridgeUI-change re-init is pending. The web-component
+  // wrapper delivers attribute updates one by one, so at re-init time the
+  // route config may still hold the previous mode's values (there is no way
+  // to tell them apart from intentional ones) — the re-init therefore
+  // ignores route config entirely and starts from the new mode's defaults.
+  const modeSwitchReinit = useRef(false);
 
   // =============================================================================
   // Memoized Values
@@ -334,8 +360,9 @@ export const SwapProvider = ({
       });
     });
     return deepMergeObjects(chainIdToTokenAddressToData, customTokens);
+    // customTokensVersion re-reads localStorage after an in-session import
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [supportedChains]);
+  }, [supportedChains, customTokensVersion]);
 
   // useMemo: creates a mapping from each chain ID to available token options sorted by token priority.
   const chainToTokenOptionsMap = useMemo(() => {
@@ -679,6 +706,12 @@ export const SwapProvider = ({
         !srcToken ||
         !srcToken?.address
       ) {
+        // Nothing to read a balance for — drop the previous selection's
+        // balance (and invalidate any in-flight read) so the MAX button
+        // never acts on a stale value.
+        refreshSelectedTokenBalanceNonce.current = crypto.randomUUID();
+        setSrcTokenBalanceWei("");
+        setIsFetchingBalance(false);
         return;
       }
 
@@ -686,68 +719,70 @@ export const SwapProvider = ({
       refreshSelectedTokenBalanceNonce.current = nonce;
       setIsFetchingBalance(true);
       let balance = "0";
-      if (srcChain?.ecosystem === Ecosystem.EVM && evmAddress) {
-        const balanceFromBackend =
-          tokenBalances[srcChain?.chainId]?.[srcToken.address];
-        if (options?.forceRpc || balanceFromBackend === undefined) {
-          const balanceUI = await getBalanceOf(
-            evmAddress,
-            srcToken.address,
-            srcChain?.publicRpcUrls[0],
-          );
-          balance = humanReadableToWei({
-            amount: balanceUI,
-            decimals: srcToken.decimals,
-          });
-          if (options?.forceRpc && balanceFromBackend !== undefined) {
-            // keep the backend cache in sync so token pickers and future
-            // non-forced refreshes see the fresh value
-            const chainId = srcChain.chainId;
-            const tokenAddress = srcToken.address;
-            const freshBalance = balance;
-            setTokenBalances((prev) => ({
-              ...prev,
-              [chainId]: {
-                ...prev[chainId],
-                [tokenAddress]: freshBalance,
-              },
+      try {
+        if (srcChain?.ecosystem === Ecosystem.EVM && evmAddress) {
+          const balanceFromBackend =
+            tokenBalances[srcChain?.chainId]?.[srcToken.address];
+          if (options?.forceRpc || balanceFromBackend === undefined) {
+            // single-token read resolved server-side through private RPCs
+            ({ balance } = await getTokenBalance({
+              chainId: srcChain.chainId,
+              tokenAddress: srcToken.address,
+              walletAddress: evmAddress,
             }));
+            if (options?.forceRpc && balanceFromBackend !== undefined) {
+              // keep the backend cache in sync so token pickers and future
+              // non-forced refreshes see the fresh value
+              const chainId = srcChain.chainId;
+              const tokenAddress = srcToken.address;
+              const freshBalance = balance;
+              setTokenBalances((prev) => ({
+                ...prev,
+                [chainId]: {
+                  ...prev[chainId],
+                  [tokenAddress]: freshBalance,
+                },
+              }));
+            }
+          } else {
+            balance = balanceFromBackend;
           }
-        } else {
-          balance = balanceFromBackend;
-        }
-      } else if (srcChain?.ecosystem === Ecosystem.SOLANA && solanaAddress) {
-        const solanaPublicKey = new PublicKey(solanaAddress);
-        const connection = new Connection(srcChain.publicRpcUrls[0]!);
-        if (srcToken.address === SOLANA_NATIVE_TOKEN_ADDRESS.toBase58()) {
-          balance = new BigNumberJS(
-            await connection.getBalance(solanaPublicKey),
-          ).toString();
-        } else {
-          const tokenAccounts = await connection.getParsedTokenAccountsByOwner(
-            solanaPublicKey,
-            {
-              programId: SOLANA_TOKEN_PROGRAM_ID,
-            },
-          );
-          const token2022Accounts =
-            await connection.getParsedTokenAccountsByOwner(solanaPublicKey, {
-              programId: SOLANA_TOKEN_2022_PROGRAM_ID,
-            });
-          const allTokenAccount = [
-            ...tokenAccounts.value,
-            ...token2022Accounts.value,
-          ];
-          const tokenAccount = allTokenAccount.find(
-            (account) =>
-              account.account.data.parsed.info.mint === srcToken.address,
-          );
-          if (!tokenAccount) {
-            balance = "0";
+        } else if (srcChain?.ecosystem === Ecosystem.SOLANA && solanaAddress) {
+          const solanaPublicKey = new PublicKey(solanaAddress);
+          const connection = new Connection(srcChain.publicRpcUrls[0]!);
+          if (srcToken.address === SOLANA_NATIVE_TOKEN_ADDRESS.toBase58()) {
+            balance = new BigNumberJS(
+              await connection.getBalance(solanaPublicKey),
+            ).toString();
           } else {
-            balance = tokenAccount.account.data.parsed.info.tokenAmount.amount;
+            const tokenAccounts =
+              await connection.getParsedTokenAccountsByOwner(solanaPublicKey, {
+                programId: SOLANA_TOKEN_PROGRAM_ID,
+              });
+            const token2022Accounts =
+              await connection.getParsedTokenAccountsByOwner(solanaPublicKey, {
+                programId: SOLANA_TOKEN_2022_PROGRAM_ID,
+              });
+            const allTokenAccount = [
+              ...tokenAccounts.value,
+              ...token2022Accounts.value,
+            ];
+            const tokenAccount = allTokenAccount.find(
+              (account) =>
+                account.account.data.parsed.info.mint === srcToken.address,
+            );
+            if (!tokenAccount) {
+              balance = "0";
+            } else {
+              balance =
+                tokenAccount.account.data.parsed.info.tokenAmount.amount;
+            }
           }
         }
+      } catch (_) {
+        // failed read — keep the loader on: the balance must be loaded before
+        // a swap is allowed, so we never show a stale value as loaded
+        return;
       }
       if (nonce !== refreshSelectedTokenBalanceNonce.current) {
         return;
@@ -790,6 +825,10 @@ export const SwapProvider = ({
         ? chain
         : { ...chain, tokens: [...chain.tokens, token] };
 
+      if (!tokenExists) {
+        setCustomTokensVersion((version) => version + 1);
+      }
+
       setSrcChain(updated);
       setSrcToken(token);
     },
@@ -821,8 +860,9 @@ export const SwapProvider = ({
     quoteRoute();
   }, [quoteRoute]);
   // calls refreshBalance to update source token balance on mount or when refreshBalance changes.
-  // when the connected wallet changed, force an RPC read — the cached backend
-  // balances still belong to the previous wallet until getBalances resolves.
+  // when the connected wallet changed, force a fresh single-token read — the
+  // cached balances list still belongs to the previous wallet until
+  // getBalances resolves.
   useEffect(() => {
     const walletAddresses = `${evmAddress ?? ""}:${solanaAddress ?? ""}`;
     const walletChanged =
@@ -832,6 +872,8 @@ export const SwapProvider = ({
     refreshBalance(walletChanged ? { forceRpc: true } : undefined);
   }, [refreshBalance, evmAddress, solanaAddress]);
   // fetches user all token balances when a wallet address is available and supported chains are loaded.
+  // imported tokens from localStorage are passed along so their balances get
+  // resolved server-side too.
   useEffect(() => {
     let isCancelled = false;
     if ((evmAddress || solanaAddress) && supportedChains.length > 0) {
@@ -839,6 +881,7 @@ export const SwapProvider = ({
       getBalances({
         walletAddress: evmAddress,
         solanaWalletAddress: solanaAddress,
+        customTokens: getCustomTokenRefs(),
       }).then((balances) => {
         if (!isCancelled) {
           setTokenBalances(balances);
@@ -850,7 +893,7 @@ export const SwapProvider = ({
     return () => {
       isCancelled = true; // prevent state update from stale async call
     };
-  }, [evmAddress, solanaAddress, supportedChains.length]);
+  }, [evmAddress, solanaAddress, supportedChains.length, customTokensVersion]);
   // sets the fee token from the source chain's tokens by selecting the native token (AddressZero).
   useEffect(() => {
     if (srcChain?.chainId === "mainnet-beta") {
@@ -1055,9 +1098,23 @@ export const SwapProvider = ({
   // useEffects responsible for state updates and validations
   // =============================================================================
 
-  // sets the initial source chain based on the wallet's chain ID if not already initialized.
+  // Follows a real in-session wallet network switch with the source chain.
+  // Only a defined -> defined change counts: the chain id first appearing
+  // during reconnect is ignored, since wagmi restores a persisted (possibly
+  // stale) chain id before the connector reports the actual one. Bridge keeps
+  // its fixed default route instead of following the wallet chain.
   useEffect(() => {
-    if (!walletChainId || !isInitialStateSet || integrationConfig?.srcChainId) {
+    const prevWalletChainId = prevFollowedWalletChainId.current;
+    prevFollowedWalletChainId.current = walletChainId;
+
+    if (
+      !walletChainId ||
+      !prevWalletChainId ||
+      prevWalletChainId === walletChainId ||
+      !isInitialStateSet ||
+      integrationConfig?.srcChainId ||
+      bridgeUI
+    ) {
       return;
     }
     const initSrcChain = supportedChains.find(
@@ -1071,18 +1128,29 @@ export const SwapProvider = ({
     isInitialStateSet,
     supportedChains,
     integrationConfig?.srcChainId,
+    bridgeUI,
   ]);
 
-  // resets source and destination tokens and chains when bridgeUI changes and initial state is not yet set.
+  // resets the widget state when bridgeUI changes at runtime: back to the
+  // main view (leaving Settings/History), cleared selection and amount, and
+  // re-arms the init effect below so the new mode gets its default route
+  // (config -> wallet chain -> mode defaults) applied again.
   useEffect(() => {
     if (!isInitialStateSet) {
       return;
     }
 
+    initPending.current = true;
+    modeSwitchReinit.current = true;
+    setTab(init.tab);
+    setActivePicker(null);
+    setError(init.error);
+    setSrcValue(init.srcValue);
     setSrcToken(undefined);
     setDstToken(undefined);
     setSrcChain(undefined);
     setDstChain(undefined);
+    setIsInitialStateSet(false);
 
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [bridgeUI]);
@@ -1098,21 +1166,51 @@ export const SwapProvider = ({
       return;
     }
 
+    // During a bridgeUI-change re-init the route config may still hold the
+    // previous mode's values (web-component attribute updates arrive one by
+    // one), so it is ignored — the new mode starts from its own defaults.
+    // Route config still seeds the very first init (deep links, integrator
+    // presets).
+    const ignoreRouteConfig = modeSwitchReinit.current;
+    const cfgSrcChainId = ignoreRouteConfig
+      ? undefined
+      : integrationConfig?.srcChainId;
+    const cfgDstChainId = ignoreRouteConfig
+      ? undefined
+      : integrationConfig?.dstChainId;
+    const cfgSrcTokenAddr = ignoreRouteConfig
+      ? undefined
+      : integrationConfig?.srcTokenAddr;
+    const cfgDstTokenAddr = ignoreRouteConfig
+      ? undefined
+      : integrationConfig?.dstTokenAddr;
+
     // find chains
+    // Default routes are fixed (swap: ETH -> ETH, bridge: ETH -> Base) and do
+    // not follow the wallet's chain — on load wagmi can still report a stale,
+    // persisted chain id, so it can't be trusted here. Integrator config
+    // still takes precedence, and a real in-session network switch is
+    // followed by the effect below.
     const searchedSrcChainId =
-      srcChain ||
-      integrationConfig?.srcChainId ||
-      (walletChainId ? `${walletChainId}` : undefined) ||
-      (bridgeUI ? undefined : DEFAULT_SOURCE_CHAIN_ID);
+      srcChain?.chainId ||
+      cfgSrcChainId ||
+      (bridgeUI ? DEFAULT_BRIDGE_SOURCE_CHAIN_ID : DEFAULT_SOURCE_CHAIN_ID);
 
     const initSrcChain = supportedChains.find(
       ({ chainId }) => chainId === searchedSrcChainId,
     );
 
+    // Bridge can't route within one chain, so when the source already sits on
+    // the default bridge destination, fall back to the reversed default route.
+    const bridgeDefaultDstChainId =
+      initSrcChain?.chainId === DEFAULT_BRIDGE_DESTINATION_CHAIN_ID
+        ? DEFAULT_BRIDGE_SOURCE_CHAIN_ID
+        : DEFAULT_BRIDGE_DESTINATION_CHAIN_ID;
+
     const searchedDstChainId =
-      dstChain ||
-      integrationConfig?.dstChainId ||
-      (bridgeUI ? undefined : DEFAULT_DESTINATION_CHAIN_ID);
+      dstChain?.chainId ||
+      cfgDstChainId ||
+      (bridgeUI ? bridgeDefaultDstChainId : DEFAULT_DESTINATION_CHAIN_ID);
 
     const initDstChain = supportedChains.find(
       ({ chainId }) => chainId === searchedDstChainId,
@@ -1123,13 +1221,13 @@ export const SwapProvider = ({
     let initSrcToken: Token | undefined;
 
     const srcTokenAddress = resolveTokenAddress(
-      integrationConfig.srcTokenAddr,
-      integrationConfig?.srcChainId,
+      cfgSrcTokenAddr,
+      cfgSrcChainId,
       supportedChains,
     );
     const dstTokenAddress = resolveTokenAddress(
-      integrationConfig.dstTokenAddr,
-      integrationConfig?.dstChainId,
+      cfgDstTokenAddr,
+      cfgDstChainId,
       supportedChains,
     );
 
@@ -1159,6 +1257,8 @@ export const SwapProvider = ({
     setSrcToken(source.token);
     setDstToken(target.token);
     // Mark initial state as set
+    modeSwitchReinit.current = false;
+    initPending.current = false;
     setIsInitialStateSet(true);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
@@ -1177,7 +1277,11 @@ export const SwapProvider = ({
     if (
       !bridgeTokensDictionary ||
       supportedChains.length === 0 ||
-      !isInitialStateSet
+      !isInitialStateSet ||
+      // A bridgeUI-change reset is in flight: this closure still holds the
+      // previous mode's route, so mapping it against the new mode would
+      // resurrect it. The re-init applies the new mode's defaults instead.
+      initPending.current
     ) {
       return;
     }
@@ -1218,9 +1322,15 @@ export const SwapProvider = ({
     bridgeTokensDictionary,
     isInitialStateSet,
   ]);
+  // Notify effects below also re-run whenever the integrator recreates the
+  // callback props (inline arrows give them a new identity every render).
+  // During a bridgeUI-change reset their closures still hold the previous
+  // mode's route, and re-emitting it would feed it back to the integrator as
+  // config — the initPending guard keeps them quiet until the re-init lands.
+
   // notifies integration or global callback when the destination chain changes.
   useEffect(() => {
-    if (!isInitialStateSet) {
+    if (!isInitialStateSet || initPending.current) {
       return;
     }
     if (integrationConfig.onDstChainChange) {
@@ -1232,7 +1342,7 @@ export const SwapProvider = ({
   }, [integrationConfig.onDstChainChange, dstChain]);
   // notifies integration or global callback when the destination token changes.
   useEffect(() => {
-    if (!isInitialStateSet) {
+    if (!isInitialStateSet || initPending.current) {
       return;
     }
     const token = dstToken
@@ -1248,7 +1358,7 @@ export const SwapProvider = ({
   }, [integrationConfig.onDstTokenChange, dstToken]);
   // notifies integration or global callback when the source chain changes.
   useEffect(() => {
-    if (!isInitialStateSet) {
+    if (!isInitialStateSet || initPending.current) {
       return;
     }
     if (integrationConfig.onSrcChainChange) {
@@ -1260,7 +1370,7 @@ export const SwapProvider = ({
   }, [integrationConfig.onSrcChainChange, srcChain]);
   // notifies integration or global callback when the source token changes.
   useEffect(() => {
-    if (!isInitialStateSet) {
+    if (!isInitialStateSet || initPending.current) {
       return;
     }
     const token = srcToken
@@ -1337,6 +1447,8 @@ export const SwapProvider = ({
         onConnectWallet,
         hasOnConnectWalletCallback,
         addTokenToChainIfNotExists,
+        activePicker,
+        setActivePicker,
       }}
     >
       {children}

package/src/context/TxUIWrapper.tsx

@@ -113,7 +113,7 @@ export const TxUIWrapper = ({ children }: Props) => {
                     </Button>
 
                     <div
-                      className="fill-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
+                      className="fill-t_text_primary text-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
                       onClick={() => closeSnackbar(snackbarKey)}
                     >
                       <CloseIcon />
@@ -225,7 +225,7 @@ export const TxUIWrapper = ({ children }: Props) => {
                     View
                   </Button>
                   <div
-                    className="fill-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
+                    className="fill-t_text_primary text-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
                     onClick={() => closeSnackbar(snackbarKey)}
                   >
                     <CloseIcon />
@@ -321,7 +321,7 @@ export const TxUIWrapper = ({ children }: Props) => {
                   </Button>
 
                   <div
-                    className="fill-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
+                    className="fill-t_text_primary text-t_text_primary w-[14px] h-[14px] cursor-pointer p-[14px] leading-[0px]"
                     onClick={() => closeSnackbar(snackbarKey)}
                   >
                     <CloseIcon />

package/src/hooks/useEvmContractApi.ts

@@ -2,6 +2,14 @@ import { GAS_LIMIT_MULTIPLIER } from "@src/constants";
 import { ethers } from "ethers";
 import { useMemo } from "react";
 
+// RPC nodes behind a load balancer can lag right after a tx is mined (e.g. the
+// swap's gas estimation not seeing the allowance from a just-confirmed
+// approval), so retry the estimation with increasing delays before giving up.
+const GAS_ESTIMATION_RETRY_DELAYS_MS = [500, 1000, 2000];
+
+const wait = (ms: number) =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
 export const useEvmContractApi = () =>
   useMemo(
     () => ({
@@ -59,11 +67,27 @@ export const useEvmContractApi = () =>
           throw new Error(decodedError?.name);
         }
       },
-      executeCalldata: async (signer, transaction) => {
+      executeCalldata: async (
+        signer,
+        transaction,
+        { retryGasEstimation = false } = {},
+      ) => {
         try {
-          const gasEstimation = await signer.estimateGas({
-            ...transaction,
-          });
+          let gasEstimation;
+          for (let attempt = 0; ; attempt++) {
+            try {
+              gasEstimation = await signer.estimateGas({
+                ...transaction,
+              });
+              break;
+            } catch (estimationErr) {
+              const delayMs = GAS_ESTIMATION_RETRY_DELAYS_MS[attempt];
+              if (!retryGasEstimation || delayMs === undefined) {
+                throw estimationErr;
+              }
+              await wait(delayMs);
+            }
+          }
           return await signer.sendTransaction({
             ...transaction,
             gasLimit: Math.floor(

package/src/models/payloads/GetBalancesPayload.ts

@@ -1,4 +1,5 @@
 export type GetTokenBalancesPayload = {
   walletAddress?: string;
   solanaWalletAddress?: string;
+  customTokens?: { chainId: string; tokenAddress: string }[];
 };

package/src/services/api.ts

@@ -7,6 +7,7 @@ import {
   GetRoutePayload,
   GetSolanaRoutePayload,
   GetTokenBalancesPayload,
+  ImportedTokenData,
   EVMRoute,
   SolanaRoute,
   Token,
@@ -169,3 +170,39 @@ export async function getLeaderboardChange(
 export async function getBridgeTokens(): Promise<BridgeToken[]> {
   return _sendRequest<BridgeToken[]>(`/bridgeTokens`);
 }
+
+/**
+ * GET a single token balance (in wei) resolved server-side through private
+ * RPCs. Native balance when tokenAddress is the zero address.
+ * @param payload required
+ * @param abortSignal
+ */
+export async function getTokenBalance(
+  payload: { chainId: string; tokenAddress: string; walletAddress: string },
+  abortSignal?: AbortSignal,
+): Promise<{ balance: string }> {
+  return _sendRequest<{ balance: string }>(
+    `/tokenBalance?${new URLSearchParams({
+      data: JSON.stringify(payload),
+    })}`,
+    { signal: abortSignal },
+  );
+}
+
+/**
+ * GET ERC20 token metadata (name, symbol, decimals) resolved server-side
+ * through private RPCs.
+ * @param payload required
+ * @param abortSignal
+ */
+export async function getTokenMetadata(
+  payload: { chainId: string; tokenAddress: string },
+  abortSignal?: AbortSignal,
+): Promise<ImportedTokenData> {
+  return _sendRequest<ImportedTokenData>(
+    `/tokenMetadata?${new URLSearchParams({
+      data: JSON.stringify(payload),
+    })}`,
+    { signal: abortSignal },
+  );
+}

package/src/utils/index.ts

@@ -3,7 +3,7 @@ export * from "./numbers";
 export * from "./parseWeb3Error";
 export * from "./strings";
 
-import { Chain } from "@src/models";
+import { BridgeTokensDictionary, Chain, Ecosystem } from "@src/models";
 import { format } from "date-fns";
 import { ethers } from "ethers";
 
@@ -98,6 +98,32 @@ export const isChainConnectionSupported = (
   return !!supportedDst?.includes(dstChainId);
 };
 
+// Chain-level support (supportedDstForBridge) is not enough for bridging —
+// the specific token must have a route to the destination chain in the
+// bridge tokens dictionary.
+export const isBridgeTokenConnectionSupported = ({
+  token,
+  tokenChain,
+  dstChainId,
+  bridgeTokensDictionary,
+}: {
+  token: { address: string };
+  tokenChain: Chain | undefined;
+  dstChainId: string | undefined;
+  bridgeTokensDictionary: BridgeTokensDictionary | null;
+}): boolean => {
+  if (!tokenChain || !dstChainId || !bridgeTokensDictionary) {
+    return true;
+  }
+  const tokenAddress =
+    tokenChain.ecosystem === Ecosystem.SOLANA
+      ? token.address
+      : token.address.toLowerCase();
+  return !!bridgeTokensDictionary[tokenChain.chainId]?.[tokenAddress]?.[
+    dstChainId
+  ];
+};
+
 export const sortChains = (chains: Chain[], disabledChainIds: string[]) =>
   [...chains]
 

package/src/utils/tokens.ts

@@ -1,11 +1,30 @@
 import { Chain, Token } from "@src/models";
-import { isServer } from "@src/utils";
+import { isETHAddressValid, isServer } from "@src/utils";
 
 /**
  * Retrieves custom tokens from localStorage and adds them to the provided chains
  * @param chains - The original chains to which custom tokens should be added
  * @returns A new array of chains with custom tokens added
  */
+/**
+ * Lists tokens imported by the user (kept in localStorage) as chainId+address
+ * pairs, EVM only — the shape the balances endpoint accepts.
+ */
+export const getCustomTokenRefs = (): {
+  chainId: string;
+  tokenAddress: string;
+}[] => {
+  const customTokensObj = !isServer
+    ? JSON.parse(localStorage.getItem("custom-tokens") || "{}")
+    : {};
+
+  return Object.entries(customTokensObj).flatMap(([chainId, tokensObj]) =>
+    Object.keys(tokensObj as Record<string, Token>)
+      .filter((tokenAddress) => isETHAddressValid(tokenAddress))
+      .map((tokenAddress) => ({ chainId, tokenAddress })),
+  );
+};
+
 export const addCustomTokensToChains = (chains: Chain[]): Chain[] => {
   const customTokensObj = !isServer
     ? JSON.parse(localStorage.getItem("custom-tokens") || "{}")