0xtrails 0.13.1 → 0.13.2

package/src/prepareSend.ts

@@ -3,7 +3,7 @@ import { trackPaymentError, trackPaymentStarted } from "./analytics.js"
 import { getSlippageToleranceValue } from "./widget/components/SlippageToleranceSettings.js"
 import { addressEqual, isNativeToken, isZeroAccount } from "./utils/address.js"
 import { getERC20TransferData } from "./utils.js"
-import { getTokenPrice } from "./query/price.queries.js"
+import { getTokenPrices } from "./query/price.queries.js"
 import {
   calldataHasPlaceholder,
   replacePlaceholderInCalldata,
@@ -221,22 +221,28 @@ export async function prepareSend(
     )
   }
 
-  let intentProtocolVersion = IntentProtocolVersion.v1 // Default to v1
+  let intentProtocol = IntentProtocolVersion.v1 // Default to v1
 
   // Only fetch supported versions when using dev trails API environments for now
-  const shouldFetchVersions = getShouldFetchVersions()
+  const shouldFetchVersions = getShouldFetchVersions(trailsApiUrl)
 
   if (shouldFetchVersions) {
     try {
-      const supportedIntentProtocolVersions =
-        await trailsClient.getSupportedIntentProtocolVersions()
-      intentProtocolVersion =
-        supportedIntentProtocolVersions.versions[0] ?? IntentProtocolVersion.v1
+      const normalizeIntentProtocolVersion = (
+        version?: string,
+      ): IntentProtocolVersion => {
+        if (version === "v1.5" || version === "v1_5") {
+          return IntentProtocolVersion.v1_5
+        }
+        return IntentProtocolVersion.v1
+      }
+
+      const response = await trailsClient.getDefaultIntentProtocol()
+      intentProtocol = normalizeIntentProtocolVersion(response.version)
       logger.console.log(
-        "[trails-sdk] [intent-protocol] Fetched supported protocol versions from API",
+        "[trails-sdk] [intent-protocol] Fetched default protocol version from API",
         {
-          supportedVersions: supportedIntentProtocolVersions.versions,
-          selectedVersion: intentProtocolVersion,
+          intentProtocol,
         },
       )
     } catch (_error) {
@@ -254,9 +260,9 @@ export async function prepareSend(
   logger.console.log(
     "[trails-sdk] [intent-protocol] === Protocol Version Selected ===",
     {
-      intentProtocolVersion,
-      isV1: intentProtocolVersion === IntentProtocolVersion.v1,
-      isV1_5: intentProtocolVersion === IntentProtocolVersion.v1_5,
+      intentProtocol,
+      isV1: intentProtocol === IntentProtocolVersion.v1,
+      isV1_5: intentProtocol === IntentProtocolVersion.v1_5,
     },
   )
 
@@ -264,15 +270,15 @@ export async function prepareSend(
     logger.console.log(
       "[trails-sdk] [intent-protocol] Calldata wrapping required for custom calldata",
       {
-        intentProtocolVersion,
+        intentProtocol,
         wrapperType:
-          intentProtocolVersion === "v1"
+          intentProtocol === IntentProtocolVersion.v1
             ? "TrailsRouter"
             : "TrailsUtils (Hydrate)",
       },
     )
 
-    if (intentProtocolVersion === "v1") {
+    if (intentProtocol === IntentProtocolVersion.v1) {
       // @deprecated - v1 only
 
       logger.console.log(
@@ -378,36 +384,31 @@ export async function prepareSend(
     }
   }
 
-  // Fallback price fetching if prices are 0
-  if (!sourceTokenPriceUsd) {
-    try {
-      const price = await getTokenPrice(trailsClient, {
-        tokenSymbol: originTokenAddress,
-        tokenAddress: originTokenAddress,
-        chainId: originChainId,
-      })
-      sourceTokenPriceUsd = price?.priceUsd ?? 0
-    } catch (error) {
-      logger.console.error(
-        "[trails-sdk] Error getting source token price:",
-        error,
-      )
-    }
-  }
-
-  if (!destinationTokenPriceUsd) {
+  // Fallback price fetching if any prices are missing
+  if (!sourceTokenPriceUsd || !destinationTokenPriceUsd) {
     try {
-      const price = await getTokenPrice(trailsClient, {
-        tokenSymbol: destinationTokenAddress,
-        tokenAddress: destinationTokenAddress,
-        chainId: destinationChainId,
-      })
-      destinationTokenPriceUsd = price?.priceUsd ?? 0
+      const prices = await getTokenPrices(trailsClient, [
+        {
+          tokenSymbol: originTokenSymbol,
+          tokenAddress: originTokenAddress,
+          chainId: originChainId,
+        },
+        {
+          tokenSymbol: destinationTokenSymbol,
+          tokenAddress: destinationTokenAddress,
+          chainId: destinationChainId,
+        },
+      ])
+      sourceTokenPriceUsd =
+        prices.find((p) =>
+          addressEqual(p.token.tokenAddress, originTokenAddress),
+        )?.priceUsd ?? 0
+      destinationTokenPriceUsd =
+        prices.find((p) =>
+          addressEqual(p.token.tokenAddress, destinationTokenAddress),
+        )?.priceUsd ?? 0
     } catch (error) {
-      logger.console.error(
-        "[trails-sdk] Error getting destination token price:",
-        error,
-      )
+      logger.console.error("[trails-sdk] Error getting token prices:", error)
     }
   }
 

package/src/query/balance.fetchers.ts

@@ -10,19 +10,22 @@ import type {
 } from "@0xsequence/indexer"
 import { ContractVerificationStatus } from "@0xsequence/indexer"
 import type { TokenPrice } from "@0xtrails/api"
-import { parseUnits, zeroAddress } from "viem"
+import { erc20Abi, parseUnits, zeroAddress } from "viem"
 import { getTokenPrices } from "./price.queries.js"
-import { getChainInfo } from "../chains.js"
+import { getChainInfo, getChainRpcClient } from "../chains.js"
 import { getTokenImageUrl, type Token } from "../tokens.js"
 import type { TrailsClient } from "../trailsClient.js"
-
 import { logger } from "../logger.js"
-import { addressEqual } from "../utils/address.js"
+import {
+  addressEqual,
+  isNativeToken as isNativeTokenAddress,
+} from "../utils/address.js"
 import {
   formatBalanceFields,
   formatPriceFields,
   formatUsdFields,
   getTokenBalanceUsd,
+  rawAmountToNumber,
   type Price,
 } from "../utils/format.js"
 import { isNetworkError } from "./helpers.js"
@@ -594,6 +597,133 @@ export async function fetchBalancesWithPrices({
   }
 }
 
+// ============================================================================
+// On-chain Balance Fetcher — bypasses the indexer entirely
+// ============================================================================
+
+export type FetchTokenBalanceOnchainParams = {
+  token: Token
+  accountAddress: string
+}
+
+export type FetchTokenBalanceOnchainWithPricesParams = {
+  token: Token
+  accountAddress: string
+  trailsClient: TrailsClient
+}
+
+export type FetchTokenBalanceOnchainReturn = {
+  token: Token
+}
+
+/**
+ * Reads the on-chain balance for a single token via RPC.
+ * Fast path — only a single RPC call, no price API.
+ *
+ * Returns a Token with fresh balance fields (balance, balanceFormatted,
+ * balanceDisplay, balanceLocaleDisplay).
+ */
+export async function fetchTokenBalanceOnchain({
+  token,
+  accountAddress,
+}: FetchTokenBalanceOnchainParams): Promise<FetchTokenBalanceOnchainReturn> {
+  const chainId = token.chainId
+  if (!chainId) {
+    throw new Error("Token must have a chainId")
+  }
+
+  const publicClient = getChainRpcClient(chainId)
+  const isNative = isNativeTokenAddress(token.contractAddress)
+
+  let rawBalance: bigint
+  if (isNative) {
+    rawBalance = await publicClient.getBalance({
+      address: accountAddress as `0x${string}`,
+    })
+  } else {
+    rawBalance = (await publicClient.readContract({
+      address: token.contractAddress as `0x${string}`,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [accountAddress as `0x${string}`],
+    })) as bigint
+  }
+
+  const balanceFields = formatBalanceFields(
+    rawBalance.toString(),
+    token.decimals,
+  )
+
+  return {
+    token: {
+      ...token,
+      ...balanceFields,
+      isSufficientBalance: true,
+    },
+  }
+}
+
+/**
+ * Reads the on-chain balance via RPC, then enriches it with price and USD
+ * data from the Trails price API.
+ *
+ * Use this variant only when the caller needs balanceUsd / priceUsd fields.
+ */
+export async function fetchTokenBalanceOnchainWithPrices({
+  token,
+  accountAddress,
+  trailsClient,
+}: FetchTokenBalanceOnchainWithPricesParams): Promise<FetchTokenBalanceOnchainReturn> {
+  const { token: tokenWithBalance } = await fetchTokenBalanceOnchain({
+    token,
+    accountAddress,
+  })
+
+  const chainId = token.chainId!
+  const isNative = isNativeTokenAddress(token.contractAddress)
+
+  let priceUsd: number | undefined
+  try {
+    const tokenPrices = await getTokenPrices(trailsClient, [
+      {
+        chainId,
+        tokenAddress: isNative ? zeroAddress : token.contractAddress,
+        tokenSymbol: isNative ? "" : token.symbol,
+      },
+    ])
+    if (tokenPrices.length > 0 && tokenPrices[0]?.priceUsd !== undefined) {
+      priceUsd = tokenPrices[0].priceUsd
+    }
+  } catch (err) {
+    logger.console.warn(
+      "[trails-sdk] Price fetch failed, returning balance without prices:",
+      err,
+    )
+  }
+
+  const priceFields = priceUsd !== undefined ? formatPriceFields(priceUsd) : {}
+
+  let usdFields: ReturnType<typeof formatUsdFields> = {}
+  if (priceUsd !== undefined && tokenWithBalance.balance) {
+    const balanceNum = rawAmountToNumber(
+      tokenWithBalance.balance,
+      token.decimals,
+    )
+    const balanceUsdValue = balanceNum * priceUsd
+    if (Number.isFinite(balanceUsdValue)) {
+      usdFields = formatUsdFields(balanceUsdValue)
+    }
+  }
+
+  return {
+    token: {
+      ...tokenWithBalance,
+      ...priceFields,
+      ...usdFields,
+    },
+  }
+}
+
 // ============================================================================
 // Pure Sufficiency Check
 // ============================================================================

package/src/query/balance.hooks.ts

@@ -215,6 +215,67 @@ export type UseAccountTokenBalanceParams = {
   trailsClient?: TrailsClient | null
 }
 
+/**
+ * Fetches a single token's on-chain balance via RPC.
+ *
+ * Pass `withPrices: true` to additionally fetch USD price data from the
+ * Trails price API (uses a separate query key so balance-only consumers
+ * are not blocked by the price call).
+ *
+ * Auto-disables when `accountAddress` or `token` is nullish.
+ */
+export function useAccountTokenBalanceOnchain(
+  token: Token | null | undefined,
+  accountAddress: string | null | undefined,
+  options?: {
+    refetchInterval?: number | false
+    disabled?: boolean
+    withPrices?: boolean
+  },
+): {
+  token: Token | null | undefined
+  isLoadingBalance: boolean
+  error: Error | null
+  refetch: () => void
+} {
+  const trailsClient = useTrailsClient()
+  const { isUserActive } = useUserActivityContext()
+
+  const isDisabled = options?.disabled || !accountAddress || !token
+  const effectiveToken = isDisabled ? null : token
+  const effectiveAddress = isDisabled ? null : accountAddress
+
+  const refetchInterval = isUserActive
+    ? clampRefetchInterval(options?.refetchInterval)
+    : false
+
+  const queryOpts = options?.withPrices
+    ? balanceQueries.onchainWithPrices(
+        effectiveToken,
+        effectiveAddress,
+        trailsClient,
+      )
+    : balanceQueries.onchain(effectiveToken, effectiveAddress)
+
+  const { data, isLoading, error, refetch } = useQuery({
+    ...queryOpts,
+    refetchInterval,
+    refetchIntervalInBackground: false,
+    refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
+    refetchOnMount: true,
+  })
+
+  const enrichedToken = data?.token ?? token ?? null
+
+  return {
+    token: isDisabled ? token : enrichedToken,
+    isLoadingBalance: isLoading,
+    error,
+    refetch,
+  }
+}
+
 export function useAccountTokenBalance({
   account,
   token,
@@ -285,13 +346,11 @@ export function useHasSufficientBalanceUsd(
 export function useAccountTotalBalanceUsd(account: string | null) {
   const indexerGatewayClient = useIndexerGatewayClient()
   const trailsClient = useTrailsClient()
-  const { isUserActive } = useUserActivityContext()
 
   return useQuery({
     ...balanceQueries.totalUsd(account, indexerGatewayClient, trailsClient),
     refetchOnWindowFocus: false,
     refetchOnReconnect: true,
-    refetchInterval: isUserActive ? WIDGET_REFRESH_INTERVAL : false,
     refetchIntervalInBackground: false,
     refetchOnMount: true,
   })

package/src/query/balance.queries.ts

@@ -10,10 +10,14 @@ import { createRetry, retryDelay } from "./helpers.js"
 import {
   fetchMultiAccountBalances,
   fetchBalancesWithPrices,
+  fetchTokenBalanceOnchain,
+  fetchTokenBalanceOnchainWithPrices,
   checkSufficientToken,
   type GetTokenBalancesForMultipleAccountsReturn,
   type GetTokenBalancesWithPriceReturn,
+  type FetchTokenBalanceOnchainReturn,
 } from "./balance.fetchers.js"
+import type { Token } from "../tokens.js"
 import { queryClient as defaultQueryClient } from "./client.js"
 import { logger } from "../logger.js"
 
@@ -143,6 +147,65 @@ export const balanceQueries = {
         Number(targetAmountUsd),
     })
   },
+
+  // single-token on-chain balance (RPC only, no price API)
+  onchain: (
+    token: Token | null | undefined,
+    accountAddress: string | null | undefined,
+  ) => {
+    const canFetch = !!token && !!token.chainId && !!accountAddress
+    return queryOptions<FetchTokenBalanceOnchainReturn>({
+      queryKey: [
+        ...balanceQueries.all,
+        "onchain",
+        accountAddress ?? null,
+        token?.contractAddress ?? null,
+        token?.chainId ?? null,
+      ] as const,
+      queryFn: canFetch
+        ? () =>
+            fetchTokenBalanceOnchain({
+              token,
+              accountAddress,
+            })
+        : skipToken,
+      staleTime: BALANCE_STALE_MS,
+      gcTime: BALANCE_GC_MS,
+      retry: createRetry(2),
+      retryDelay,
+    })
+  },
+
+  // single-token on-chain balance + price/USD enrichment (RPC + price API)
+  onchainWithPrices: (
+    token: Token | null | undefined,
+    accountAddress: string | null | undefined,
+    trailsClient: TrailsClient | null | undefined,
+  ) => {
+    const canFetch =
+      !!token && !!token.chainId && !!accountAddress && !!trailsClient
+    return queryOptions<FetchTokenBalanceOnchainReturn>({
+      queryKey: [
+        ...balanceQueries.all,
+        "onchainWithPrices",
+        accountAddress ?? null,
+        token?.contractAddress ?? null,
+        token?.chainId ?? null,
+      ] as const,
+      queryFn: canFetch
+        ? () =>
+            fetchTokenBalanceOnchainWithPrices({
+              token,
+              accountAddress,
+              trailsClient,
+            })
+        : skipToken,
+      staleTime: BALANCE_STALE_MS,
+      gcTime: BALANCE_GC_MS,
+      retry: createRetry(2),
+      retryDelay,
+    })
+  },
 }
 
 // ============================================================================

package/src/query/chains.queries.ts

@@ -8,12 +8,7 @@ export const chainQueries = {
 
   supported: (config?: { trailsApiUrl?: string; trailsApiKey?: string }) =>
     queryOptions<Chain[]>({
-      queryKey: [
-        ...chainQueries.all,
-        "supported",
-        config?.trailsApiUrl || "default",
-        config?.trailsApiKey || "",
-      ] as const,
+      queryKey: [...chainQueries.all, "supported"] as const,
       queryFn: () => getSupportedChains(config),
       staleTime: HOUR_MS,
       gcTime: DAY_MS,

package/src/query/meld.fetchers.ts

@@ -11,7 +11,7 @@ import type {
   MeldCryptoCurrency,
   MeldCountryDefault,
   MeldTransaction,
-} from "../onramp-client/trails-onramp.gen.js"
+} from "@0xtrails/api/onramp"
 import { normalizeAddress } from "../utils/address.js"
 
 export interface MeldCountryDefaults {

package/src/query/meld.hooks.ts

@@ -1,6 +1,6 @@
 import { useQuery } from "@tanstack/react-query"
 import { useOnrampClient } from "../onrampClient.js"
-import type { GetMeldServiceProvidersRequest } from "../onramp-client/trails-onramp.gen.js"
+import type { GetMeldServiceProvidersRequest } from "@0xtrails/api/onramp"
 import { meldQueries } from "./meld.queries.js"
 
 export function useMeldPaymentMethods(fiatCurrency?: string) {

package/src/query/meld.queries.ts

@@ -3,7 +3,7 @@ import type { TrailsOnramp } from "../onrampClient.js"
 import type {
   GetMeldServiceProvidersRequest,
   MeldServiceProvider,
-} from "../onramp-client/trails-onramp.gen.js"
+} from "@0xtrails/api/onramp"
 import { DAY_MS, MINUTE_MS } from "../utils/time.js"
 import { createRetry, retryDelay, STATIC_QUERY_OPTIONS } from "./helpers.js"
 import { queryPersister } from "./persister.js"

package/src/query/tokenList.queries.ts

@@ -0,0 +1,118 @@
+import { queryOptions, skipToken } from "@tanstack/react-query"
+import type { TrailsClient } from "../trailsClient.js"
+import { DAY_MS, MINUTE_MS, SECOND_MS } from "../utils/time.js"
+import { createRetry, retryDelay, STATIC_QUERY_OPTIONS } from "./helpers.js"
+
+type TokenListResult = {
+  tokens: unknown[]
+}
+
+const EMPTY_RESULT: TokenListResult = { tokens: [] }
+
+export const tokenListQueries = {
+  all: ["tokenList"] as const,
+
+  catalog: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { chainIds: number[]; includeAllListed?: boolean; limit?: number },
+  ) => {
+    const hasChains = params.chainIds.length > 0
+    const canFetch = !!trailsClient && !!config.trailsApiKey && hasChains
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "catalog",
+        [...params.chainIds].sort((a, b) => a - b).join(","),
+        params.includeAllListed ?? true,
+        params.limit ?? null,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              chainIds: params.chainIds,
+              includeAllListed: params.includeAllListed ?? true,
+              limit: params.limit,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: DAY_MS,
+      gcTime: DAY_MS,
+      retry: createRetry(2),
+      retryDelay,
+      ...STATIC_QUERY_OPTIONS,
+    })
+  },
+
+  search: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { searchQuery: string; chainIds: number[]; limit?: number },
+  ) => {
+    const searchQuery = params.searchQuery.trim()
+    const canFetch =
+      !!trailsClient &&
+      !!config.trailsApiKey &&
+      searchQuery.length > 0 &&
+      params.chainIds.length > 0
+
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "search",
+        searchQuery,
+        [...params.chainIds].sort((a, b) => a - b).join(","),
+        params.limit ?? 30,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              searchQuery,
+              chainIds: params.chainIds,
+              includeAllListed: true,
+              limit: params.limit ?? 30,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: 30 * SECOND_MS,
+      gcTime: 5 * MINUTE_MS,
+      retry: createRetry(1),
+      retryDelay,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+    })
+  },
+
+  byChain: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { chainId: number | null; limit?: number },
+  ) => {
+    const canFetch =
+      !!trailsClient && !!config.trailsApiKey && params.chainId != null
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "byChain",
+        params.chainId,
+        params.limit ?? 100,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              chainIds: [params.chainId as number],
+              includeAllListed: true,
+              limit: params.limit ?? 100,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: DAY_MS,
+      gcTime: DAY_MS,
+      retry: createRetry(2),
+      retryDelay,
+      ...STATIC_QUERY_OPTIONS,
+    })
+  },
+
+  empty: EMPTY_RESULT,
+}