0xtrails 0.13.0 → 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 "./prices.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

@@ -3,7 +3,6 @@
  * This is a leaf module — NO React imports, NO queryClient, NO balanceKeys.
  */
 import type {
-  IndexerGateway as IndexerGatewayTypes,
   NativeTokenBalance,
   Page,
   SequenceIndexerGateway,
@@ -11,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 { getTokenPrices } from "../prices.js"
-import { getChainInfo } from "../chains.js"
+import { erc20Abi, parseUnits, zeroAddress } from "viem"
+import { getTokenPrices } from "./price.queries.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"
@@ -74,6 +76,10 @@ export type GetTokenBalancesWithPriceReturn = {
   balances: Token[]
 }
 
+type TokenBalancesSummary = Awaited<
+  ReturnType<SequenceIndexerGateway["getTokenBalancesSummary"]>
+>
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -234,6 +240,28 @@ export function convertNativeTokenBalanceToToken(
   return result
 }
 
+type BalanceEntry = TokenBalance | NativeTokenBalance
+
+function convertBalanceToTokenOrNull(
+  token: BalanceEntry,
+  priceData?: TokenPrice,
+): Token | null {
+  try {
+    if (isNativeToken(token)) {
+      return convertNativeTokenBalanceToToken(token, priceData)
+    }
+
+    return convertTokenBalanceToToken(token, priceData)
+  } catch (err) {
+    logger.console.warn(
+      "[trails-sdk] Skipping malformed token balance:",
+      token,
+      err,
+    )
+    return null
+  }
+}
+
 // Default empty page info for query fallback
 export const defaultPage = { page: 1, pageSize: 10, more: false }
 
@@ -260,10 +288,10 @@ function createEmptyMultiAccountResult(
   return result
 }
 
-function mapChainEntryResults<T extends { accountAddress?: string }>(
+function mapChainEntryResults<T extends BalanceEntry>(
   entries: Array<{ chainId: number; results?: T[] }>,
   result: GetTokenBalancesForMultipleAccountsReturn,
-  toToken: (entry: T) => Token,
+  toToken: (entry: T) => Token | null,
   bucket: "erc20Tokens" | "nativeTokens",
 ): void {
   for (const chainEntry of entries) {
@@ -280,6 +308,8 @@ function mapChainEntryResults<T extends { accountAddress?: string }>(
       if (!accountEntry) continue
 
       const token = toToken(entry)
+      if (!token) continue
+
       accountEntry[bucket].push(token)
       accountEntry.tokens.push(token)
     }
@@ -291,7 +321,7 @@ function toTokenPriceKey(chainId: number, tokenAddress?: string): string {
 }
 
 function createTokenMapFromGatewaySummary(
-  summary: IndexerGatewayTypes.GetTokenBalancesSummaryResponse,
+  summary: TokenBalancesSummary,
 ): Map<string, TokenBalance | NativeTokenBalance> {
   const tokenMap = new Map<string, TokenBalance | NativeTokenBalance>()
 
@@ -389,7 +419,7 @@ export async function fetchTokenBalancesSummary({
   indexerGatewayClient,
   page,
   pageSize,
-}: GetTokenBalancesParams): Promise<IndexerGatewayTypes.GetTokenBalancesSummaryResponse> {
+}: GetTokenBalancesParams): Promise<TokenBalancesSummary> {
   if (!account || !indexerGatewayClient) {
     throw new Error("Account address and indexer client are required")
   }
@@ -467,14 +497,14 @@ export async function fetchMultiAccountBalances({
     mapChainEntryResults(
       summaryFromGateway.balances,
       result,
-      convertTokenBalanceToToken,
+      convertBalanceToTokenOrNull,
       "erc20Tokens",
     )
 
     mapChainEntryResults(
       summaryFromGateway.nativeBalances,
       result,
-      convertNativeTokenBalanceToToken,
+      convertBalanceToTokenOrNull,
       "nativeTokens",
     )
 
@@ -551,17 +581,15 @@ export async function fetchBalancesWithPrices({
     )
   }
 
-  const balancesWithPrices: Token[] = tokens.map((b) => {
+  const balancesWithPrices: Token[] = tokens.flatMap((b) => {
     const priceData = tokenPriceMap.get(
       toTokenPriceKey(
         b.chainId,
         isNativeToken(b) ? zeroAddress : b.contractAddress,
       ),
     )
-    if (isNativeToken(b)) {
-      return convertNativeTokenBalanceToToken(b, priceData)
-    }
-    return convertTokenBalanceToToken(b, priceData)
+    const token = convertBalanceToTokenOrNull(b, priceData)
+    return token ? [token] : []
   })
 
   return {
@@ -569,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

@@ -53,7 +53,7 @@ export function useTokenBalances(
   isLoadingSortedTokens: boolean
   balanceError: Error | null
   sortedTokens: Token[]
-  refetch: () => void
+  refetch: () => Promise<void>
 } {
   const indexerClient = useIndexerGatewayClient()
   const trailsClient = useTrailsClient()
@@ -120,7 +120,9 @@ export function useTokenBalances(
     isLoadingSortedTokens: isLoading,
     balanceError,
     sortedTokens,
-    refetch,
+    refetch: async () => {
+      await refetch()
+    },
   }
 }
 
@@ -138,7 +140,7 @@ export type UseTokenBalancesForMultipleAccountsReturn = {
   /** Combined error - first error encountered */
   error: Error | null
   /** Refetch function to manually trigger balance updates */
-  refetch: () => void
+  refetch: () => Promise<void>
 }
 
 /**
@@ -199,7 +201,9 @@ export function useTokenBalancesForMultipleAccounts(
     balancesByAccount,
     isLoading,
     error,
-    refetch,
+    refetch: async () => {
+      await refetch()
+    },
   }
 }
 
@@ -211,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,
@@ -281,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"