0xtrails 0.6.6 → 0.7.0

package/src/widget/hooks/useTokenList.ts

@@ -1,29 +1,26 @@
-import { ResourceStatus } from "@0xsequence/indexer"
 import { Address } from "ox"
 import { useEffect, useMemo, useState } from "react"
-import { isAddressEqual, zeroAddress } from "viem"
+import { isAddress, isAddressEqual, zeroAddress } from "viem"
 import { useAccount } from "wagmi"
+import { useQuery } from "@tanstack/react-query"
 import { getChainInfo, useSupportedChains } from "../../chains.js"
-import type {
-  TokenBalanceExtended,
-  TokenBalanceWithPrice,
-  NativeTokenBalanceWithPrice,
-} from "../../tokenBalances.js"
+import type { Token } from "../../tokens.js"
+import { isNativeToken as isNativeTokenUtil } from "../../utils.js"
 import {
-  formatRawAmount,
   useAccountTotalBalanceUsd,
   useHasSufficientBalanceUsd,
   useTokenBalances,
+  formatPriceFields,
 } from "../../tokenBalances.js"
-import {
-  getFormatttedTokenName,
-  useSupportedTokens,
-  useGetTokenImageUrl,
-} from "../../tokens.js"
+import { useSupportedTokens, useGetTokenImageUrl } from "../../tokens.js"
 import { useIndexerGatewayClient } from "../../indexerClient.js"
 import { useTrailsClient } from "../../trailsClient.js"
 import { useTokenPrices } from "../../prices.js"
 import { logger } from "../../logger.js"
+import { useTrails } from "../providers/TrailsProvider.js"
+import { useCustomTokenFetch } from "./useCustomTokenFetch.js"
+import { useChainFilter } from "./useChainFilter.js"
+import { useDebounce } from "./useDebounce.js"
 
 // Standard tokens for QR code and exchange modes
 const STANDARD_TOKENS = [
@@ -36,6 +33,79 @@ const STANDARD_TOKENS = [
   "WETH",
 ] as const
 
+// Type for API token info from getTokenList endpoint
+type ApiTokenInfo = {
+  chainId: number
+  address: string
+  name: string
+  symbol: string
+  decimals: number
+  supportsBridging?: boolean
+  logoUri?: string
+}
+
+// Helper function to validate and clamp decimals (1-18)
+function validateDecimals(decimals: number): number {
+  return Math.max(1, Math.min(18, Math.floor(decimals || 18)))
+}
+
+// Helper function to check if token is native
+function isNativeToken(token: Token | ApiTokenInfo): boolean {
+  // Token has isNativeToken property
+  if ("isNativeToken" in token && typeof token.isNativeToken === "boolean") {
+    return token.isNativeToken
+  }
+  // ApiTokenInfo uses "address" field (intermediate type before conversion to Token)
+  if ("address" in token) {
+    return isNativeTokenUtil(token.address)
+  }
+  return false
+}
+
+// Helper function to get token key for mapping
+function getTokenKey(chainId: number, contractAddress: string): string {
+  return `${chainId}:${contractAddress.toLowerCase()}`
+}
+
+// Helper function to convert API token info to Token
+function convertApiTokenToToken(
+  tokenInfo: ApiTokenInfo,
+  getTokenImageUrl: (params: {
+    chainId: number
+    contractAddress: string
+    symbol: string
+  }) => string,
+): Token {
+  const chainInfo = getChainInfo(tokenInfo.chainId)
+  const isNative = isNativeToken(tokenInfo)
+  const validatedDecimals = validateDecimals(tokenInfo.decimals)
+
+  return {
+    symbol: isNative
+      ? chainInfo?.nativeCurrency.symbol || "ETH"
+      : tokenInfo.symbol,
+    name: isNative
+      ? chainInfo?.nativeCurrency.name || "Native Token"
+      : tokenInfo.name,
+    decimals: isNative
+      ? chainInfo?.nativeCurrency.decimals || 18
+      : validatedDecimals,
+    contractAddress: isNative ? zeroAddress : tokenInfo.address,
+    chainId: tokenInfo.chainId,
+    chainName: chainInfo?.name || `Chain ${tokenInfo.chainId}`,
+    imageUrl:
+      tokenInfo.logoUri ||
+      getTokenImageUrl({
+        chainId: tokenInfo.chainId,
+        contractAddress: isNative ? zeroAddress : tokenInfo.address,
+        symbol: isNative
+          ? chainInfo?.nativeCurrency.symbol || "ETH"
+          : tokenInfo.symbol,
+      }),
+    isNativeToken: isNative,
+  }
+}
+
 // Helper function to calculate search relevance score
 function calculateSearchRelevanceScore(
   tokenSymbol: string,
@@ -74,35 +144,6 @@ function calculateSearchRelevanceScore(
   return score
 }
 
-export interface Token {
-  id: number
-  name: string
-  symbol: string
-  balance: string
-  imageUrl: string
-  chainId: number
-  contractAddress: string
-  balanceUsdFormatted: string
-  tokenPriceUsd: number
-  contractInfo?: {
-    decimals: number
-    symbol: string
-    name: string
-  }
-}
-
-export type TokenFormatted = Token &
-  TokenBalanceExtended & {
-    balanceFormatted: string
-    tokenPriceUsd: number
-    balanceUsdFormatted: string
-    isNative: boolean
-    tokenName: string
-    priceUsd: number
-    isSufficientBalance: boolean
-    chainName: string
-  }
-
 export type UseTokenListProps = {
   onContinue: (selectedToken: Token) => void
   targetAmountUsd?: number | null
@@ -114,14 +155,16 @@ export type UseTokenListProps = {
 export type UseTokenListReturn = {
   selectedToken: Token | null
   searchQuery: string
-  handleTokenSelect: (token: TokenFormatted) => void
-  filteredTokens: TokenBalanceExtended[]
+  handleTokenSelect: (token: Token) => void
+  filteredTokens: Token[]
   isLoadingSortedTokens: boolean
+  isLoadingSearchTokens?: boolean
+  isSearching: boolean // True when search is in progress (typing or fetching)
   balanceError: Error | null
   showContinueButton: boolean
-  isTokenSelected: (token: TokenBalanceExtended) => boolean
+  isTokenSelected: (token: Token) => boolean
   setSearchQuery: (query: string) => void
-  filteredTokensFormatted: TokenFormatted[]
+  filteredTokensFormatted: Token[]
   totalBalanceUsd: number
   totalBalanceUsdFormatted: string
   isLoadingTotalBalanceUsd: boolean
@@ -152,6 +195,145 @@ export function useTokenList({
   const { supportedTokens, isLoadingTokens: isLoadingSupportedTokens } =
     useSupportedTokens()
 
+  // Get trails config for API calls
+  const trailsConfig = useTrails()
+
+  // Get supported chains for getTokenList API
+  const { supportedChains } = useSupportedChains()
+
+  // Get chain filter for destination token list
+  const { selectedChainId: filterByChainId } = useChainFilter()
+
+  // Only use API search for exchange/qr-code modes or when allSupportedTokens is true
+  // (where we show all tokens, not just user balances)
+  // For other modes, we only filter user's token balances locally
+  const shouldUseApiSearch =
+    fundMethod === "exchange" || fundMethod === "qr-code" || allSupportedTokens
+
+  // Memoize chain IDs to avoid recalculating
+  const apiSearchChainIds = useMemo(
+    () => supportedChains.map((chain) => chain.id),
+    [supportedChains],
+  )
+
+  // Check if search query is an address
+  const trimmedSearchQuery = useMemo(() => searchQuery.trim(), [searchQuery])
+  // Debounce the search query to avoid excessive API calls (300ms delay)
+  const debouncedSearchQuery = useDebounce(trimmedSearchQuery, 300)
+  const isSearchQueryAddress = useMemo(
+    () => (debouncedSearchQuery ? isAddress(debouncedSearchQuery) : false),
+    [debouncedSearchQuery],
+  )
+
+  // Track if user is actively typing (search query changed but debounce hasn't fired yet)
+  const isSearchPending = trimmedSearchQuery !== debouncedSearchQuery
+
+  // Call getTokenList API when there's a search query
+  const { data: searchTokensResult, isLoading: isLoadingSearchTokens } =
+    useQuery({
+      queryKey: [
+        "getTokenList",
+        debouncedSearchQuery,
+        apiSearchChainIds,
+        trailsConfig.trailsApiUrl,
+        trailsConfig.trailsApiKey,
+      ],
+      queryFn: async () => {
+        if (
+          !debouncedSearchQuery ||
+          !trailsClient ||
+          !trailsConfig.trailsApiKey
+        ) {
+          return { tokens: [] }
+        }
+
+        try {
+          const response = await trailsClient.getTokenList({
+            searchQuery: debouncedSearchQuery,
+            chainIds: apiSearchChainIds,
+            includeAllListed: true,
+          })
+          return response
+        } catch (error) {
+          logger.console.warn("[trails-sdk] Error searching tokens:", error)
+          return { tokens: [] }
+        }
+      },
+      enabled:
+        shouldUseApiSearch &&
+        debouncedSearchQuery.length > 0 &&
+        !!trailsClient &&
+        !!trailsConfig.trailsApiKey,
+      staleTime: 30 * 1000, // 30 seconds
+      gcTime: 5 * 60 * 1000, // 5 minutes
+    })
+
+  // Fetch custom token info if searching by address and getTokenList returned no results
+  const hasNoSearchResults = searchTokensResult?.tokens?.length === 0
+  const shouldFetchCustomToken =
+    shouldUseApiSearch &&
+    isSearchQueryAddress &&
+    hasNoSearchResults &&
+    !isLoadingSearchTokens &&
+    trimmedSearchQuery.length > 0
+  const customTokenChainId = supportedChains[0]?.id ?? null
+
+  const { tokenInfo: customTokenInfo, isLoading: isLoadingCustomToken } =
+    useCustomTokenFetch({
+      address: shouldFetchCustomToken ? trimmedSearchQuery : null,
+      chainId: customTokenChainId,
+      enabled: shouldFetchCustomToken,
+    })
+
+  // Fetch tokens from getTokenList when a chain is selected (for destination token list only)
+  // This fetches all available tokens from that chain, not just filtering existing tokens
+  const {
+    data: chainFilteredTokenList,
+    isLoading: isLoadingChainFilteredTokens,
+  } = useQuery({
+    queryKey: [
+      "getTokenList",
+      filterByChainId,
+      trailsConfig.trailsApiUrl,
+      trailsConfig.trailsApiKey,
+    ],
+    queryFn: async () => {
+      if (
+        !filterByChainId ||
+        !trailsClient ||
+        !trailsConfig.trailsApiKey ||
+        !shouldUseApiSearch
+      ) {
+        return { tokens: [] }
+      }
+
+      try {
+        // Fetch tokens from the selected chain with limit of 100 for single chain
+        const response = await trailsClient.getTokenList({
+          chainIds: [filterByChainId],
+          includeAllListed: true,
+          limit: 100,
+        })
+        return response
+      } catch (error) {
+        logger.console.warn(
+          "[trails-sdk] Error fetching tokens for chain filter:",
+          error,
+        )
+        return { tokens: [] }
+      }
+    },
+    enabled:
+      shouldUseApiSearch &&
+      filterByChainId !== null &&
+      !!trailsClient &&
+      !!trailsConfig.trailsApiKey,
+    staleTime: 60 * 60 * 1000, // 1 hour - tokens rarely change
+    gcTime: 24 * 60 * 60 * 1000, // 24 hours
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+  })
+
   // Fetch prices for supported tokens when allSupportedTokens is true OR for qr-code/exchange modes
   const supportedTokensForPricing = useMemo(() => {
     if (fundMethod === "qr-code" || fundMethod === "exchange") {
@@ -187,11 +369,16 @@ export function useTokenList({
   // Determine loading state based on fund method and allSupportedTokens
   const isLoadingTokens =
     fundMethod === "qr-code" || fundMethod === "exchange"
-      ? isLoadingSupportedTokens || isLoadingSupportedTokenPrices
+      ? isLoadingSupportedTokens ||
+        isLoadingSupportedTokenPrices ||
+        isLoadingSearchTokens ||
+        isLoadingCustomToken ||
+        isLoadingChainFilteredTokens
       : allSupportedTokens
         ? isLoadingSortedTokens ||
           isLoadingSupportedTokens ||
-          isLoadingSupportedTokenPrices
+          isLoadingSupportedTokenPrices ||
+          isLoadingChainFilteredTokens
         : isLoadingSortedTokens
 
   const {
@@ -213,90 +400,194 @@ export function useTokenList({
     return new Set(supportedToChains.map((c) => c.id))
   }, [supportedToChains])
 
-  const sortedTokens = useMemo<Array<TokenBalanceExtended>>(() => {
+  // Map chain-filtered token list results to Token format
+  // Used when a chain is selected for destination token list
+  const chainFilteredApiTokens = useMemo(() => {
+    if (
+      !shouldUseApiSearch ||
+      !chainFilteredTokenList?.tokens?.length ||
+      filterByChainId === null
+    ) {
+      return []
+    }
+
+    return chainFilteredTokenList.tokens
+      .filter((tokenInfo: ApiTokenInfo) => {
+        // Validate decimals - must be between 1 and 18
+        const decimals = tokenInfo.decimals
+        if (!Number.isInteger(decimals) || decimals < 1 || decimals > 18) {
+          logger.console.warn(
+            "[trails-sdk] Skipping token with invalid decimals:",
+            {
+              symbol: tokenInfo.symbol,
+              address: tokenInfo.address,
+              decimals: tokenInfo.decimals,
+            },
+          )
+          return false
+        }
+        return true
+      })
+      .map((tokenInfo: ApiTokenInfo) =>
+        convertApiTokenToToken(tokenInfo, getTokenImageUrl),
+      )
+  }, [
+    chainFilteredTokenList,
+    getTokenImageUrl,
+    shouldUseApiSearch,
+    filterByChainId,
+  ])
+
+  const sortedTokens = useMemo<Array<Token>>(() => {
     // If fundMethod is "qr-code" or "exchange", use filtered supported tokens
     if (fundMethod === "qr-code" || fundMethod === "exchange") {
+      // If chain filter is active and we have chain-filtered tokens, use those
+      if (
+        shouldUseApiSearch &&
+        filterByChainId !== null &&
+        chainFilteredApiTokens.length > 0
+      ) {
+        // Merge chain-filtered tokens with local tokens (prefer local tokens with balances)
+        const localTokensMap = new Map<string, Token>()
+        for (const tokenItem of allSortedTokens) {
+          const contractAddress = tokenItem.contractAddress || zeroAddress
+          const key = getTokenKey(tokenItem.chainId || 0, contractAddress)
+          localTokensMap.set(key, tokenItem)
+        }
+
+        const mergedTokens: Token[] = chainFilteredApiTokens.map(
+          (apiToken: Token) => {
+            const contractAddress = apiToken.contractAddress || zeroAddress
+            const key = getTokenKey(apiToken.chainId || 0, contractAddress)
+            const localToken = localTokensMap.get(key)
+
+            // If local token exists and has balance, use it; otherwise use API token
+            return localToken && (localToken.balanceUsd || 0) > 0
+              ? localToken
+              : apiToken
+          },
+        )
+
+        // Add any local tokens that weren't in API results
+        const apiTokenKeys = new Set(
+          mergedTokens.map((token) =>
+            getTokenKey(
+              token.chainId || 0,
+              token.contractAddress || zeroAddress,
+            ),
+          ),
+        )
+        for (const localToken of allSortedTokens) {
+          const key = getTokenKey(
+            localToken.chainId || 0,
+            localToken.contractAddress || zeroAddress,
+          )
+          if (
+            !apiTokenKeys.has(key) &&
+            (localToken.chainId || 0) === filterByChainId
+          ) {
+            mergedTokens.push(localToken)
+          }
+        }
+
+        return mergedTokens
+      }
+
       // Filter to only show specific tokens for QR code and exchange modes
       const filteredTokens = supportedTokens.filter((token: any) => {
         const symbol = token.symbol.toUpperCase()
         return STANDARD_TOKENS.includes(symbol as any)
       })
 
-      // Convert SupportedToken to TokenBalanceExtended format and add price data
-      const tokensWithPrices = filteredTokens.map((token: any) => {
-        // Find price data for this token
-        const priceData = supportedTokenPrices?.find(
-          (p: any) =>
-            p.token.tokenAddress?.toLowerCase() ===
-              (token.contractAddress || zeroAddress).toLowerCase() &&
-            p.token.chainId === token.chainId,
-        )
+      // Convert SupportedToken to Token format and add price data
+      const tokensWithPrices: Token[] = filteredTokens.map(
+        (token: Token): Token => {
+          // Find price data for this token
+          const priceData = supportedTokenPrices?.find(
+            (p: any) =>
+              p.token.tokenAddress?.toLowerCase() ===
+                (token.contractAddress || zeroAddress).toLowerCase() &&
+              p.token.chainId === token.chainId,
+          )
 
-        // Check if it's a native token (like ETH)
-        if (
-          token.contractAddress === "0x0000000000000000000000000000000000000000"
-        ) {
-          // Native token format
-          return {
-            chainId: token.chainId,
-            balance: "0", // No balance info for QR code and exchange modes
-            balanceUsd: 0,
-            balanceUsdFormatted: "0",
-            price:
-              priceData?.priceUsd !== undefined
-                ? { value: priceData.priceUsd, currency: "USD" }
-                : { value: 0, currency: "USD" },
-            price24hVol: 0, // Volume data not available in new API
-            imageUrl: token.imageUrl,
-            symbol: token.symbol,
-            isSufficientBalance: true, // Always true for QR code and exchange modes
-            accountAddress: address as Address.Address,
-          } as NativeTokenBalanceWithPrice
-        } else {
-          // ERC20 token format
+          const priceUsd = priceData?.priceUsd
+
+          // Format price fields if price exists
+          const priceFields = priceUsd ? formatPriceFields(priceUsd) : undefined
+
+          // Return Token with price data
           return {
-            chainId: token.chainId,
-            contractAddress: token.contractAddress,
-            balance: "0", // No balance info for QR code and exchange modes
-            balanceUsd: 0,
-            balanceUsdFormatted: "0",
-            price:
-              priceData?.priceUsd !== undefined
-                ? { value: priceData.priceUsd, currency: "USD" }
-                : { value: 0, currency: "USD" },
-            price24hVol: 0, // Volume data not available in new API
-            imageUrl: token.imageUrl,
-            contractInfo: {
-              decimals: token.decimals,
-              symbol: token.symbol,
-              name: token.name,
-            },
+            ...token,
+            // No balance info for QR code and exchange modes
+            ...(priceFields && {
+              priceUsd: priceFields.priceUsd,
+              priceUsdFormatted: priceFields.priceUsdFormatted,
+              priceUsdDisplay: priceFields.priceUsdDisplay,
+            }),
             isSufficientBalance: true, // Always true for QR code and exchange modes
-            // Add required properties for TokenBalanceWithPrice
-            contractType: "ERC20",
-            accountAddress: address as Address.Address,
-            blockHash: "",
-            blockNumber: 0,
-            logIndex: 0,
-            transactionHash: "",
-            transactionIndex: 0,
-            uniqueCollectibles: "0",
-            isSummary: false,
-          } as any
-        }
+          }
+        },
+      )
+
+      // Sort by price (highest first) since volume is not available
+      return tokensWithPrices.sort((a, b) => {
+        return (b.priceUsd || 0) - (a.priceUsd || 0)
       })
+    }
+
+    // If allSupportedTokens is true and chain filter is active, use chain-filtered tokens
+    if (
+      allSupportedTokens &&
+      shouldUseApiSearch &&
+      filterByChainId !== null &&
+      chainFilteredApiTokens.length > 0
+    ) {
+      // Merge chain-filtered tokens with local tokens (prefer local tokens with balances)
+      const localTokensMap = new Map<string, Token>()
+      for (const tokenItem of allSortedTokens) {
+        const contractAddress = tokenItem.contractAddress || zeroAddress
+        const key = getTokenKey(tokenItem.chainId || 0, contractAddress)
+        localTokensMap.set(key, tokenItem)
+      }
+
+      const mergedTokens: Token[] = chainFilteredApiTokens.map(
+        (apiToken: Token) => {
+          const contractAddress = apiToken.contractAddress || zeroAddress
+          const key = getTokenKey(apiToken.chainId || 0, contractAddress)
+          const localToken = localTokensMap.get(key)
+
+          // If local token exists and has balance, use it; otherwise use API token
+          return localToken && (localToken.balanceUsd || 0) > 0
+            ? localToken
+            : apiToken
+        },
+      )
 
-      // Sort by 24h volume (highest first)
-      return tokensWithPrices.sort((a: any, b: any) => {
-        const aVolume = Number(a?.price24hVol || 0)
-        const bVolume = Number(b?.price24hVol || 0)
-        return bVolume - aVolume
-      }) as unknown as TokenBalanceExtended[]
+      // Add any local tokens that weren't in API results
+      const apiTokenKeys = new Set(
+        mergedTokens.map((token) =>
+          getTokenKey(token.chainId || 0, token.contractAddress || zeroAddress),
+        ),
+      )
+      for (const localToken of allSortedTokens) {
+        const key = getTokenKey(
+          localToken.chainId || 0,
+          localToken.contractAddress || zeroAddress,
+        )
+        if (
+          !apiTokenKeys.has(key) &&
+          (localToken.chainId || 0) === filterByChainId
+        ) {
+          mergedTokens.push(localToken)
+        }
+      }
+
+      return mergedTokens
     }
 
-    // Default behavior: use account-specific tokens
-    return allSortedTokens.filter((token: TokenBalanceExtended) => {
-      if (!supportedChainIds.has(token.chainId)) {
+    // Default behavior: use account-specific tokens (already Token[])
+    return allSortedTokens.filter((token: Token) => {
+      if (!supportedChainIds.has(token.chainId || 0)) {
         return false
       }
       return true
@@ -306,8 +597,11 @@ export function useTokenList({
     supportedChainIds,
     fundMethod,
     supportedTokens,
-    address,
     supportedTokenPrices,
+    shouldUseApiSearch,
+    filterByChainId,
+    chainFilteredApiTokens,
+    allSupportedTokens,
   ])
 
   useEffect(() => {
@@ -316,17 +610,14 @@ export function useTokenList({
     }
   }, [balanceError, onError])
 
-  const handleTokenSelect = (token: TokenFormatted) => {
-    const isNative =
-      !("contractAddress" in token) || token.contractAddress === zeroAddress
-    const chainInfo = getChainInfo(token.chainId)
-    const imageUrl = token.imageUrl
-    const decimals = isNative ? 18 : token.contractInfo?.decimals
+  const handleTokenSelect = (token: Token) => {
+    const isNative = token.isNativeToken ?? false
+    const decimals = token.decimals
     if (!decimals) {
       logger.console.warn(
         "[trails-sdk] [useTokenList] Missing decimals for token:",
         {
-          token: token.contractInfo,
+          token: token,
           chainId: token.chainId,
           isNative,
         },
@@ -335,71 +626,32 @@ export function useTokenList({
       return
     }
 
-    let formattedToken: Token
-    if (isNative) {
-      formattedToken = {
-        id: (token as TokenBalanceExtended).chainId,
-        name: chainInfo?.nativeCurrency.name || "Native Token",
-        symbol: chainInfo?.nativeCurrency.symbol || "ETH",
-        balance: (token as TokenBalanceExtended).balance,
-        imageUrl,
-        chainId: (token as TokenBalanceExtended).chainId,
-        contractAddress: zeroAddress,
-        balanceUsdFormatted:
-          (token as TokenBalanceExtended).balanceUsdFormatted ?? "",
-        tokenPriceUsd: (token as TokenBalanceExtended).price?.value ?? 0,
-        contractInfo: {
-          decimals,
-          symbol: chainInfo?.nativeCurrency.symbol || "ETH",
-          name: chainInfo?.nativeCurrency.name || "Native Token",
-        },
-      }
-    } else {
-      formattedToken = {
-        id: token.chainId,
-        name: token.contractInfo?.name || "Unknown Token",
-        symbol: token.contractInfo?.symbol || "???",
-        balance: token.balance,
-        imageUrl,
-        chainId: token.chainId,
-        contractAddress: token.contractAddress,
-        contractInfo: {
-          ...token.contractInfo,
-          name: token.contractInfo?.name ?? "Unknown Token",
-          symbol: token.contractInfo?.symbol ?? "???",
-          decimals,
-        },
-        balanceUsdFormatted: token.balanceUsdFormatted ?? "",
-        tokenPriceUsd: token.price?.value ?? 0,
-      }
-    }
-
-    setSelectedToken(formattedToken)
+    setSelectedToken(token)
     const canContinue =
       (!targetAmountUsd || (targetAmountUsd && hasSufficientBalanceUsd)) &&
-      token.isSufficientBalance
+      (token.isSufficientBalance ?? true)
 
     if (!canContinue) {
       logger.console.warn("[trails-sdk] Cannot continue with token selection", {
-        token: formattedToken,
+        token: token,
         targetAmountUsd,
         hasSufficientBalanceUsd,
         isSufficientBalance: token.isSufficientBalance,
       })
     }
 
-    onContinue(formattedToken)
+    onContinue(token)
   }
 
-  const isTokenSelected = (token: TokenBalanceExtended): boolean => {
+  const isTokenSelected = (token: Token): boolean => {
     if (!selectedToken) return false
 
-    const isNative =
-      !("contractAddress" in token) || token.contractAddress === zeroAddress
+    const isNative = token.isNativeToken ?? false
+    const selectedIsNative = selectedToken.isNativeToken ?? false
     return (
-      selectedToken.chainId === token.chainId &&
+      (selectedToken.chainId || 0) === (token.chainId || 0) &&
       (isNative
-        ? selectedToken.contractAddress === zeroAddress
+        ? selectedIsNative
         : isAddressEqual(
             Address.from(selectedToken.contractAddress),
             Address.from(token.contractAddress),
@@ -407,105 +659,182 @@ export function useTokenList({
     )
   }
 
+  // Map API search results to Token format
+  // Only used for exchange/qr-code modes
+  const apiSearchTokens = useMemo(() => {
+    if (!shouldUseApiSearch || !searchTokensResult?.tokens?.length) {
+      return []
+    }
+
+    return searchTokensResult.tokens
+      .filter((tokenInfo: ApiTokenInfo) => {
+        // Validate decimals - must be between 1 and 18 (formatRawAmount requires 1-18)
+        const decimals = tokenInfo.decimals
+        if (!Number.isInteger(decimals) || decimals < 1 || decimals > 18) {
+          logger.console.warn(
+            "[trails-sdk] Skipping token with invalid decimals:",
+            {
+              symbol: tokenInfo.symbol,
+              address: tokenInfo.address,
+              decimals: tokenInfo.decimals,
+            },
+          )
+          return false
+        }
+        return true
+      })
+      .map((tokenInfo: ApiTokenInfo) =>
+        convertApiTokenToToken(tokenInfo, getTokenImageUrl),
+      )
+  }, [searchTokensResult, getTokenImageUrl, shouldUseApiSearch])
+
+  // Convert custom token info to Token format
+  const customTokenAsTokenBalance = useMemo(() => {
+    if (!customTokenInfo || !customTokenChainId) return null
+
+    const chainInfo = getChainInfo(customTokenChainId)
+    const validatedDecimals = validateDecimals(customTokenInfo.decimals)
+
+    return {
+      symbol: customTokenInfo.symbol,
+      name: customTokenInfo.name,
+      decimals: validatedDecimals,
+      contractAddress: customTokenInfo.contractAddress,
+      chainId: customTokenChainId,
+      chainName: chainInfo?.name || `Chain ${customTokenChainId}`,
+      imageUrl: getTokenImageUrl({
+        chainId: customTokenChainId,
+        contractAddress: customTokenInfo.contractAddress,
+        symbol: customTokenInfo.symbol,
+      }),
+      isCustomToken: true,
+    } as Token
+  }, [customTokenInfo, customTokenChainId, getTokenImageUrl])
+
   const filteredTokens = useMemo(() => {
-    if (!searchQuery.trim()) {
-      return sortedTokens
+    // If searching by address and getTokenList returned no results, return custom token if available
+    if (
+      shouldUseApiSearch &&
+      isSearchQueryAddress &&
+      hasNoSearchResults &&
+      customTokenAsTokenBalance
+    ) {
+      return [customTokenAsTokenBalance]
     }
 
-    const query = searchQuery.trim().toLowerCase()
-    const queryParts = query.split(/\s+/).filter((part) => part.length > 0)
+    // sortedTokens is already Token[] from useTokenBalances
+    // Only use API search results for exchange/qr-code modes
+    if (
+      shouldUseApiSearch &&
+      trimmedSearchQuery &&
+      apiSearchTokens.length > 0
+    ) {
+      // Create a map of local tokens by chainId and contractAddress for quick lookup
+      const localTokensMap = new Map<string, Token>()
+      for (const tokenItem of sortedTokens) {
+        const contractAddress = tokenItem.contractAddress || zeroAddress
+        const key = getTokenKey(tokenItem.chainId || 0, contractAddress)
+        localTokensMap.set(key, tokenItem)
+      }
 
-    const matchingTokens = sortedTokens.filter(
-      (token: TokenBalanceExtended) => {
-        const isNative =
-          !("contractAddress" in token) || token.contractAddress === zeroAddress
-        const chainInfo = getChainInfo(token.chainId)
-        const chainName = chainInfo?.name || ""
-        const chainNameLower = chainName.toLowerCase()
+      // Merge API results with local tokens (prefer local tokens with balances)
+      const mergedTokens: Token[] = apiSearchTokens.map((apiToken: Token) => {
+        const contractAddress = apiToken.contractAddress || zeroAddress
+        const key = getTokenKey(apiToken.chainId || 0, contractAddress)
+        const localToken = localTokensMap.get(key)
 
-        if (isNative) {
-          const nativeSymbol = chainInfo?.nativeCurrency.symbol || "ETH"
-          const nativeName = chainInfo?.nativeCurrency.name || "Native Token"
-          const nativeSymbolLower = nativeSymbol.toLowerCase()
-          const nativeNameLower = nativeName.toLowerCase()
+        // If local token exists and has balance, use it; otherwise use API token
+        return localToken && (localToken.balanceUsd || 0) > 0
+          ? localToken
+          : apiToken
+      })
 
-          // If multiple query parts, check if they match chain + token combination
-          if (queryParts.length > 1) {
-            const matchesChain = queryParts.some((part) =>
-              chainNameLower.includes(part),
-            )
-            const matchesToken = queryParts.some(
-              (part) =>
-                nativeSymbolLower.includes(part) ||
-                nativeNameLower.includes(part),
-            )
-            return matchesChain && matchesToken
-          }
+      // Add any local tokens that weren't in API results but match the search
+      const apiTokenKeys = new Set(
+        mergedTokens.map((token) => {
+          const contractAddress = token.contractAddress || zeroAddress
+          return getTokenKey(token.chainId || 0, contractAddress)
+        }),
+      )
 
-          // Single query part - match against any field
-          return queryParts.some(
-            (part) =>
-              nativeSymbolLower.includes(part) ||
-              nativeNameLower.includes(part) ||
-              chainNameLower.includes(part),
-          )
+      const queryLower = trimmedSearchQuery.toLowerCase()
+      for (const tokenItem of sortedTokens) {
+        const contractAddress = tokenItem.contractAddress || zeroAddress
+        const key = getTokenKey(tokenItem.chainId || 0, contractAddress)
+
+        if (!apiTokenKeys.has(key)) {
+          // Check if token matches search query locally
+          const tokenSymbol = (tokenItem.symbol || "").toLowerCase()
+          const tokenName = (tokenItem.name || "").toLowerCase()
+
+          if (
+            tokenSymbol.includes(queryLower) ||
+            tokenName.includes(queryLower) ||
+            contractAddress.toLowerCase().includes(queryLower)
+          ) {
+            mergedTokens.push(tokenItem)
+          }
         }
+      }
 
-        const tokenSymbol = token.contractInfo?.symbol || "???"
-        const tokenName = token.contractInfo?.name || "Unknown Token"
-        const contractAddress = token.contractAddress || ""
-        const tokenSymbolLower = tokenSymbol.toLowerCase()
-        const tokenNameLower = tokenName.toLowerCase()
-        const contractAddressLower = contractAddress.toLowerCase()
-
-        // If multiple query parts, check if they match chain + token combination
-        if (queryParts.length > 1) {
-          const matchesChain = queryParts.some((part) =>
-            chainNameLower.includes(part),
-          )
-          const matchesToken = queryParts.some(
-            (part) =>
-              tokenSymbolLower.includes(part) ||
-              tokenNameLower.includes(part) ||
-              contractAddressLower.includes(part),
-          )
-          return matchesChain && matchesToken
-        }
+      return mergedTokens
+    }
+
+    // Fallback to local filtering if no API results or not using API search
+    if (!trimmedSearchQuery) {
+      return sortedTokens
+    }
+
+    const queryLower = trimmedSearchQuery.toLowerCase()
+    const queryParts = queryLower.split(/\s+/).filter((part) => part.length > 0)
+
+    const matchingTokens = sortedTokens.filter((token: Token) => {
+      const chainInfo = getChainInfo(token.chainId || 0)
+      const chainName = chainInfo?.name || ""
+      const chainNameLower = chainName.toLowerCase()
 
-        // Single query part - match against any field
-        return queryParts.some(
+      const tokenSymbol = (token.symbol || "???").toLowerCase()
+      const tokenName = (token.name || "Unknown Token").toLowerCase()
+      const contractAddress = (
+        token.contractAddress || zeroAddress
+      ).toLowerCase()
+
+      // If multiple query parts, check if they match chain + token combination
+      if (queryParts.length > 1) {
+        const matchesChain = queryParts.some((part) =>
+          chainNameLower.includes(part),
+        )
+        const matchesToken = queryParts.some(
           (part) =>
-            tokenSymbolLower.includes(part) ||
-            tokenNameLower.includes(part) ||
-            chainNameLower.includes(part) ||
-            contractAddressLower.includes(part),
+            tokenSymbol.includes(part) ||
+            tokenName.includes(part) ||
+            contractAddress.includes(part),
         )
-      },
-    )
+        return matchesChain && matchesToken
+      }
 
-    // Sort by relevance for balance tokens too
-    return matchingTokens.sort((a, b) => {
-      const isANative = !("contractAddress" in a)
-      const isBNative = !("contractAddress" in b)
+      // Single query part - match against any field
+      return queryParts.some(
+        (part) =>
+          tokenSymbol.includes(part) ||
+          tokenName.includes(part) ||
+          chainNameLower.includes(part) ||
+          contractAddress.includes(part),
+      )
+    })
 
-      const aChainInfo = getChainInfo(a.chainId)
-      const bChainInfo = getChainInfo(b.chainId)
+    // Sort by relevance for balance tokens too
+    return matchingTokens.sort((a: Token, b: Token) => {
+      const aChainInfo = getChainInfo(a.chainId || 0)
+      const bChainInfo = getChainInfo(b.chainId || 0)
       const aChainName = aChainInfo?.name?.toLowerCase() || ""
       const bChainName = bChainInfo?.name?.toLowerCase() || ""
 
-      const aTokenSymbol = isANative
-        ? (aChainInfo?.nativeCurrency.symbol || "ETH").toLowerCase()
-        : (a.contractInfo?.symbol || "").toLowerCase()
-      const bTokenSymbol = isBNative
-        ? (bChainInfo?.nativeCurrency.symbol || "ETH").toLowerCase()
-        : (b.contractInfo?.symbol || "").toLowerCase()
+      const aTokenSymbol = (a.symbol || "???").toLowerCase()
+      const bTokenSymbol = (b.symbol || "???").toLowerCase()
 
-      const aTokenName = isANative
-        ? (aChainInfo?.nativeCurrency.name || "Native Token").toLowerCase()
-        : (a.contractInfo?.name || "").toLowerCase()
-      const bTokenName = isBNative
-        ? (bChainInfo?.nativeCurrency.name || "Native Token").toLowerCase()
-        : (b.contractInfo?.name || "").toLowerCase()
+      const aTokenName = (a.name || "Unknown Token").toLowerCase()
+      const bTokenName = (b.name || "Unknown Token").toLowerCase()
 
       // Calculate relevance scores using helper function
       const aScore = calculateSearchRelevanceScore(
@@ -523,118 +852,63 @@ export function useTokenList({
 
       return bScore - aScore // Higher score first
     })
-  }, [sortedTokens, searchQuery])
+  }, [
+    sortedTokens,
+    trimmedSearchQuery,
+    apiSearchTokens,
+    shouldUseApiSearch,
+    isSearchQueryAddress,
+    hasNoSearchResults,
+    customTokenAsTokenBalance,
+  ])
 
   const filteredTokensFormatted = useMemo(() => {
-    // Get base formatted tokens
+    // Get base formatted tokens - filteredTokens is already Token[]
     const baseFormattedTokens = filteredTokens
-      .map((token: TokenBalanceExtended): TokenFormatted | null => {
-        const isNative =
-          !("contractAddress" in token) || token.contractAddress === zeroAddress
-        const chainInfo = getChainInfo(token.chainId)
-        const nativeSymbol = chainInfo?.nativeCurrency.symbol || "ETH"
-        const tokenSymbol = isNative
-          ? nativeSymbol
-          : token.contractInfo?.symbol || "???"
-        const contractAddress = isNative ? zeroAddress : token.contractAddress
-        let imageContractAddress = contractAddress
-        if (tokenSymbol === "WETH") {
-          imageContractAddress = zeroAddress
-        }
-        const fallbackImageUrl =
-          (token as TokenBalanceWithPrice).contractInfo?.logoURI || ""
-        const imageUrl = getTokenImageUrl({
-          chainId: token.chainId,
-          contractAddress: imageContractAddress,
-          symbol: tokenSymbol,
-          fallbackImageUrl: fallbackImageUrl || undefined,
-        })
-        const currentTokenName =
-          (token as TokenBalanceWithPrice).contractInfo?.name || ""
-        const tokenName = getFormatttedTokenName(
-          currentTokenName,
-          tokenSymbol,
-          token.chainId,
-        )
-        const decimals = isNative ? 18 : token.contractInfo?.decimals
+      .map((token: Token): Token | null => {
+        const isNative = token.isNativeToken ?? false
+        const chainInfo = getChainInfo(token.chainId || 0)
+        const decimals = token.decimals
         if (!decimals) {
           logger.console.warn(
             "[trails-sdk] Missing decimals for token, skipping:",
             {
-              token: isNative ? token : token.contractInfo,
+              token: token,
               chainId: token.chainId,
               isNative,
             },
           )
           return null // Return null to filter out tokens without decimals
         }
-        const formattedBalance = formatRawAmount(token.balance, decimals)
-        const priceUsd = Number(token.price?.value) ?? 0
-        const balanceUsdFormatted = token.balanceUsdFormatted ?? ""
 
-        let isSufficientBalance = true
+        let isSufficientBalance = token.isSufficientBalance ?? true
         if (targetAmountUsd) {
           isSufficientBalance = (token.balanceUsd ?? 0) >= targetAmountUsd
         }
-        const chainName = chainInfo?.name || ""
+        const chainName = token.chainName || chainInfo?.name || ""
 
+        // Format price fields if not already formatted
+        const priceFields = token.priceUsdFormatted
+          ? undefined
+          : token.priceUsd
+            ? formatPriceFields(token.priceUsd)
+            : undefined
+
+        // Return Token with all formatting fields set
         return {
           ...token,
-          id: token.chainId,
-          contractInfo: {
-            ...(token as TokenBalanceWithPrice).contractInfo,
-            chainId: Number(token.chainId),
-            source: (token as TokenBalanceWithPrice).contractInfo?.source || "",
-            type: (token as TokenBalanceWithPrice).contractInfo?.type || "",
-            logoURI:
-              (token as TokenBalanceWithPrice).contractInfo?.logoURI || "",
-            deployed:
-              (token as TokenBalanceWithPrice).contractInfo?.deployed || false,
-            bytecodeHash:
-              (token as TokenBalanceWithPrice).contractInfo?.bytecodeHash || "",
-            updatedAt:
-              (token as TokenBalanceWithPrice).contractInfo?.updatedAt || "",
-            queuedAt:
-              (token as TokenBalanceWithPrice).contractInfo?.queuedAt || "",
-            extensions: (token as TokenBalanceWithPrice).contractInfo
-              ?.extensions || {
-              link: "",
-              description: "",
-              categories: [],
-              ogImage: "",
-              ogName: "",
-              originChainId: 0,
-              originAddress: "",
-              blacklist: false,
-              verified: false,
-              featureIndex: 0,
-              verifiedBy: "",
-              featured: false,
-            },
-            status:
-              (token as TokenBalanceWithPrice).contractInfo?.status ||
-              ResourceStatus.NOT_AVAILABLE,
-            address: contractAddress,
-            name: tokenName,
-            symbol: tokenSymbol,
-            decimals: decimals,
-          },
-          name: tokenName,
-          symbol: tokenSymbol,
-          balanceFormatted: formattedBalance,
-          imageUrl,
-          chainId: token.chainId,
-          contractAddress: contractAddress,
-          balanceUsdFormatted,
-          tokenPriceUsd: priceUsd,
-          isNative: isNative,
-          tokenName: tokenName,
-          priceUsd: priceUsd,
+          balanceDisplay: token.balanceDisplay || token.balanceFormatted,
+          priceUsdFormatted:
+            token.priceUsdFormatted || priceFields?.priceUsdFormatted,
+          priceUsdDisplay:
+            token.priceUsdDisplay || priceFields?.priceUsdDisplay,
+          balanceUsdDisplay:
+            token.balanceUsdDisplay || token.balanceUsdFormatted,
           isSufficientBalance,
           chainName,
         }
       })
-      .filter(Boolean) as TokenFormatted[] // Filter out null values for tokens without decimals
+      .filter(Boolean) as Token[] // Filter out null values for tokens without decimals
 
     // If allSupportedTokens is true, combine with supported tokens
     if (allSupportedTokens) {
@@ -646,19 +920,15 @@ export function useTokenList({
       )
 
       // Add supported tokens that don't exist in the base list
-      const additionalSupportedTokens = supportedTokens
+      const additionalSupportedTokens: Token[] = supportedTokens
         .filter((supportedToken) => {
-          const key = `${supportedToken.chainId}-${supportedToken.contractAddress.toLowerCase()}`
+          const key = `${supportedToken.chainId || 0}-${supportedToken.contractAddress.toLowerCase()}`
           return !existingTokenKeys.has(key)
         })
-        .map((supportedToken) => {
-          const chainInfo = getChainInfo(supportedToken.chainId)
-          const chainName = chainInfo?.name || `Chain ${supportedToken.chainId}`
-          const tokenName = getFormatttedTokenName(
-            supportedToken.name,
-            supportedToken.symbol,
-            supportedToken.chainId,
-          )
+        .map((supportedToken): Token => {
+          const chainInfo = getChainInfo(supportedToken.chainId || 0)
+          const chainName =
+            chainInfo?.name || `Chain ${supportedToken.chainId || 0}`
 
           // Find price data for this supported token
           const priceData = supportedTokenPrices?.find(
@@ -668,30 +938,30 @@ export function useTokenList({
               p.token.chainId === supportedToken.chainId,
           )
 
+          // Format price fields if price exists
+          const priceFields = priceData?.priceUsd
+            ? formatPriceFields(priceData.priceUsd)
+            : undefined
+
           return {
-            ...supportedToken,
-            tokenName: tokenName,
+            symbol: supportedToken.symbol,
+            name: supportedToken.name,
+            decimals: supportedToken.decimals,
+            contractAddress: supportedToken.contractAddress,
+            chainId: supportedToken.chainId,
             chainName: chainName,
-            contractInfo: {
-              decimals: supportedToken.decimals,
-              symbol: supportedToken.symbol,
-              name: supportedToken.name,
-            },
-            // Add minimal required properties to make it work
-            balance: "",
-            balanceFormatted: "",
-            balanceUsdFormatted: "",
-            priceUsd: priceData?.priceUsd || 0,
-            price24hVol: 0, // Volume data not available in new API
+            imageUrl: supportedToken.imageUrl || "",
+            ...(priceFields && {
+              priceUsd: priceFields.priceUsd,
+              priceUsdFormatted: priceFields.priceUsdFormatted,
+              priceUsdDisplay: priceFields.priceUsdDisplay,
+            }),
             isSufficientBalance: true,
-            // Use any type to bypass strict type checking for now
-          } as any
+          }
         })
-        .sort((a: any, b: any) => {
-          // Sort supported tokens by 24h volume (highest first)
-          const aVolume = Number(a?.price24hVol || 0)
-          const bVolume = Number(b?.price24hVol || 0)
-          return bVolume - aVolume
+        .sort((a, b) => {
+          // Sort supported tokens by price (highest first) since volume is not available
+          return (b.priceUsd || 0) - (a.priceUsd || 0)
         })
 
       // Combine lists with base tokens taking precedence
@@ -705,37 +975,35 @@ export function useTokenList({
         const query = searchQuery.toLowerCase().trim()
         const queryParts = query.split(/\s+/).filter((part) => part.length > 0)
 
-        const filteredTokens = combinedTokens.filter(
-          (token: TokenFormatted) => {
-            const chainName = token.chainName?.toLowerCase() || ""
-            const tokenSymbol = token.symbol?.toLowerCase() || ""
-            const tokenName = token.name?.toLowerCase() || ""
-            const contractAddress = token.contractAddress?.toLowerCase() || ""
-
-            // If multiple query parts, check if they match chain + token combination
-            if (queryParts.length > 1) {
-              const matchesChain = queryParts.some((part) =>
-                chainName.includes(part),
-              )
-              const matchesToken = queryParts.some(
-                (part) =>
-                  tokenSymbol.includes(part) ||
-                  tokenName.includes(part) ||
-                  contractAddress.includes(part),
-              )
-              return matchesChain && matchesToken
-            }
-
-            // Single query part - match against any field
-            return queryParts.some(
+        const filteredTokens = combinedTokens.filter((token: Token) => {
+          const chainName = token.chainName?.toLowerCase() || ""
+          const tokenSymbol = token.symbol?.toLowerCase() || ""
+          const tokenName = token.name?.toLowerCase() || ""
+          const contractAddress = token.contractAddress?.toLowerCase() || ""
+
+          // If multiple query parts, check if they match chain + token combination
+          if (queryParts.length > 1) {
+            const matchesChain = queryParts.some((part) =>
+              chainName.includes(part),
+            )
+            const matchesToken = queryParts.some(
               (part) =>
                 tokenSymbol.includes(part) ||
                 tokenName.includes(part) ||
-                chainName.includes(part) ||
                 contractAddress.includes(part),
             )
-          },
-        )
+            return matchesChain && matchesToken
+          }
+
+          // Single query part - match against any field
+          return queryParts.some(
+            (part) =>
+              tokenSymbol.includes(part) ||
+              tokenName.includes(part) ||
+              chainName.includes(part) ||
+              contractAddress.includes(part),
+          )
+        })
 
         // Sort filtered tokens by relevance
         return filteredTokens.sort((a, b) => {
@@ -783,7 +1051,6 @@ export function useTokenList({
     supportedTokens,
     supportedTokenPrices,
     searchQuery,
-    getTokenImageUrl,
   ])
 
   const showInsufficientBalance = useMemo(() => {
@@ -805,12 +1072,17 @@ export function useTokenList({
     totalBalanceUsd,
   ])
 
+  // isSearching: true when user is typing (debounce pending) or API is fetching
+  const isSearching = isSearchPending || isLoadingSearchTokens
+
   return {
     selectedToken,
     searchQuery,
     handleTokenSelect,
     filteredTokens,
-    isLoadingSortedTokens,
+    isLoadingSortedTokens: isLoadingSortedTokens || isLoadingSearchTokens,
+    isLoadingSearchTokens,
+    isSearching,
     balanceError,
     showContinueButton,
     isTokenSelected,