@spacesops/wdk-react-native-core 1.0.0-beta.67 → 1.0.0-beta.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spacesops/wdk-react-native-core",
-  "version": "1.0.0-beta.67",
+  "version": "1.0.0-beta.69",
   "description": "Core functionality for React Native wallets - wallet management, balance fetching, and worklet operations",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/services/transactionService.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for TransactionService
+ */
+
+import { setIndexerConfig } from '../../store/indexerConfigStore'
+import { TransactionService } from '../../services/transactionService'
+
+const mockFetch = jest.fn()
+global.fetch = mockFetch as typeof fetch
+
+describe('TransactionService', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    setIndexerConfig({
+      baseUrl: 'https://wdk-api.tether.io',
+      apiKey: 'test-api-key',
+    })
+  })
+
+  afterEach(() => {
+    setIndexerConfig(null)
+  })
+
+  it('fetches and parses token transfers', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        transfers: [
+          {
+            blockchain: 'ethereum',
+            transactionHash: '0xabc',
+            token: 'xaut',
+            amount: '1.5',
+            timestamp: 1700000000,
+            from: '0xfrom',
+            to: '0xto',
+          },
+        ],
+      }),
+    })
+
+    const transfers = await TransactionService.fetchTokenTransfers(
+      'ethereum',
+      'xaut',
+      '0xWallet'
+    )
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://wdk-api.tether.io/api/v1/ethereum/xaut/0xWallet/token-transfers',
+      expect.objectContaining({
+        method: 'GET',
+        headers: expect.objectContaining({
+          'x-api-key': 'test-api-key',
+        }),
+      })
+    )
+    expect(transfers).toHaveLength(1)
+    expect(transfers[0].token).toBe('xaut')
+    expect(transfers[0].amount).toBe('1.5')
+  })
+
+  it('returns empty list on 404', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 404,
+      text: async () => 'not found',
+    })
+
+    const transfers = await TransactionService.fetchTokenTransfers(
+      'ethereum',
+      'usdt',
+      '0xWallet'
+    )
+    expect(transfers).toEqual([])
+  })
+
+  it('aggregates transfers across networks and dedupes', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({ transfers: [] }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          transfers: [
+            {
+              blockchain: 'ethereum',
+              transactionHash: '0x1',
+              token: 'usdt',
+              amount: '10',
+              timestamp: 100,
+              from: '0xa',
+              to: '0xb',
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          transfers: [
+            {
+              blockchain: 'ethereum',
+              transactionHash: '0x2',
+              token: 'xaut',
+              amount: '0.5',
+              timestamp: 200,
+              from: '0xc',
+              to: '0xd',
+            },
+          ],
+        }),
+      })
+
+    const tokenConfigs = {
+      ethereum: {
+        native: { address: null, symbol: 'ETH', name: 'Ethereum', decimals: 18 },
+        tokens: [
+          {
+            address: '0xusdt',
+            symbol: 'USDT',
+            name: 'Tether USD',
+            decimals: 6,
+          },
+          {
+            address: '0xxaut',
+            symbol: 'XAUT',
+            name: 'Tether Gold',
+            decimals: 6,
+          },
+        ],
+      },
+    }
+
+    const list = await TransactionService.fetchWalletTransactions({
+      addresses: { ethereum: { 0: '0xWallet' } },
+      accountIndex: 0,
+      tokenConfigs,
+    })
+
+    expect(list).toHaveLength(2)
+    expect(list[0].transactionHash).toBe('0x2')
+    expect(list[1].transactionHash).toBe('0x1')
+  })
+
+  it('resolveWalletTransactions returns empty when indexer not configured', async () => {
+    setIndexerConfig(null)
+    const list = await TransactionService.resolveWalletTransactions({
+      addresses: { ethereum: { 0: '0xWallet' } },
+      accountIndex: 0,
+      tokenConfigs: {
+        ethereum: {
+          native: { address: null, symbol: 'ETH', name: 'Ethereum', decimals: 18 },
+          tokens: [],
+        },
+      },
+    })
+    expect(list).toEqual([])
+    expect(mockFetch).not.toHaveBeenCalled()
+  })
+})

package/src/__tests__/utils/retryUtils.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Tests for retry utilities
+ */
+
+import {
+  delay,
+  isTransientBlockchainError,
+  withTransientRetry,
+} from '../../utils/retryUtils'
+
+describe('retryUtils', () => {
+  describe('isTransientBlockchainError', () => {
+    it('detects 429 rate limit errors', () => {
+      expect(isTransientBlockchainError(new Error('HTTP 429 Too Many Requests'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('rate limit exceeded'))).toBe(true)
+    })
+
+    it('detects 5xx server errors', () => {
+      expect(isTransientBlockchainError(new Error('upstream returned 502 Bad Gateway'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('status 503'))).toBe(true)
+    })
+
+    it('detects network and timeout errors', () => {
+      expect(isTransientBlockchainError(new Error('network request failed'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('ETIMEDOUT'))).toBe(true)
+      expect(isTransientBlockchainError(new Error('408 Request Timeout'))).toBe(true)
+    })
+
+    it('does not treat client errors as transient', () => {
+      expect(isTransientBlockchainError(new Error('Invalid balance format: abc'))).toBe(false)
+      expect(isTransientBlockchainError(new Error('HTTP 400 Bad Request'))).toBe(false)
+      expect(isTransientBlockchainError(new Error('HTTP 404 Not Found'))).toBe(false)
+    })
+  })
+
+  describe('withTransientRetry', () => {
+    beforeEach(() => {
+      jest.useFakeTimers()
+    })
+
+    afterEach(() => {
+      jest.useRealTimers()
+    })
+
+    it('returns immediately on success', async () => {
+      const fn = jest.fn().mockResolvedValue('ok')
+      await expect(withTransientRetry(fn)).resolves.toBe('ok')
+      expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('retries transient errors with exponential backoff', async () => {
+      const fn = jest
+        .fn()
+        .mockRejectedValueOnce(new Error('HTTP 429 Too Many Requests'))
+        .mockRejectedValueOnce(new Error('HTTP 429 Too Many Requests'))
+        .mockResolvedValue('ok')
+
+      const promise = withTransientRetry(fn, { label: 'test' })
+
+      await jest.advanceTimersByTimeAsync(1000)
+      await jest.advanceTimersByTimeAsync(2000)
+
+      await expect(promise).resolves.toBe('ok')
+      expect(fn).toHaveBeenCalledTimes(3)
+    })
+
+    it('does not retry non-transient errors', async () => {
+      const fn = jest.fn().mockRejectedValue(new Error('Invalid balance format'))
+      await expect(withTransientRetry(fn)).rejects.toThrow('Invalid balance format')
+      expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('throws after exhausting retries', async () => {
+      const fn = jest.fn().mockRejectedValue(new Error('HTTP 429'))
+      const promise = withTransientRetry(fn, { maxAttempts: 3, initialBackoffMs: 100 })
+
+      await jest.advanceTimersByTimeAsync(100)
+      await jest.advanceTimersByTimeAsync(200)
+
+      await expect(promise).rejects.toThrow('HTTP 429')
+      expect(fn).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  describe('delay', () => {
+    beforeEach(() => {
+      jest.useFakeTimers()
+    })
+
+    afterEach(() => {
+      jest.useRealTimers()
+    })
+
+    it('resolves after the specified duration', async () => {
+      const promise = delay(500)
+      jest.advanceTimersByTime(500)
+      await expect(promise).resolves.toBeUndefined()
+    })
+  })
+})

package/src/hooks/useBalance.ts

@@ -54,8 +54,11 @@ import {
   NATIVE_TOKEN_KEY,
   DEFAULT_QUERY_STALE_TIME_MS,
   DEFAULT_QUERY_GC_TIME_MS,
+  BALANCE_FETCH_STAGGER_MS,
+  BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS,
 } from '../utils/constants'
 import { logError } from '../utils/logger'
+import { delay, withTransientRetry } from '../utils/retryUtils'
 import { validateWalletParams } from '../utils/validation'
 import type { BalanceFetchResult, TokenConfigProvider } from '../types'
 
@@ -203,11 +206,17 @@ async function fetchBalance(
     const methodName = isNative ? ACCOUNT_METHOD_GET_BALANCE : ACCOUNT_METHOD_GET_TOKEN_BALANCE
     const methodArg = isNative ? null : tokenAddress
 
-    const balanceResult = await AccountService.callAccountMethod<string>(
-      network,
-      accountIndex,
-      methodName,
-      methodArg
+    const balanceResult = await withTransientRetry(
+      () =>
+        AccountService.callAccountMethod<string>(
+          network,
+          accountIndex,
+          methodName,
+          methodArg
+        ),
+      {
+        label: `${network} ${methodName}`,
+      }
     )
 
     // Convert to string (handles BigInt values)
@@ -335,23 +344,73 @@ function buildBalanceQueryKeys(
 }
 
 /**
- * Fetch balances for all query keys
+ * Group balance query keys by network, preserving first-seen network order.
+ */
+function groupQueryKeysByNetwork(
+  queryKeys: ReturnType<typeof balanceQueryKeys.byToken>[]
+): ReturnType<typeof balanceQueryKeys.byToken>[][] {
+  const networkOrder: string[] = []
+  const byNetwork = new Map<string, ReturnType<typeof balanceQueryKeys.byToken>[]>()
+
+  for (const queryKey of queryKeys) {
+    const { network } = validateQueryKeyStructure(queryKey)
+    if (!byNetwork.has(network)) {
+      networkOrder.push(network)
+      byNetwork.set(network, [])
+    }
+    byNetwork.get(network)!.push(queryKey)
+  }
+
+  return networkOrder.map((network) => byNetwork.get(network)!)
+}
+
+function balanceQueryKeyId(queryKey: ReturnType<typeof balanceQueryKeys.byToken>): string {
+  return queryKey.join('\0')
+}
+
+/**
+ * Fetch balances for all query keys, staggering per-network to avoid RPC bursts.
  */
 async function fetchBalancesForQueryKeys(
   queryKeys: ReturnType<typeof balanceQueryKeys.byToken>[],
   walletId: string
 ): Promise<BalanceFetchResult[]> {
-  return Promise.all(
-    queryKeys.map(async (queryKey) => {
+  if (queryKeys.length === 0) {
+    return []
+  }
+
+  const networkGroups = groupQueryKeysByNetwork(queryKeys)
+  const results = new Map<string, BalanceFetchResult>()
+  let isFirstNetwork = true
+
+  for (const keys of networkGroups) {
+    if (!isFirstNetwork) {
+      await delay(BALANCE_FETCH_STAGGER_MS)
+    }
+    isFirstNetwork = false
+
+    const networkResults: Array<{ id: string; result: BalanceFetchResult }> = []
+    for (let i = 0; i < keys.length; i++) {
+      if (i > 0) {
+        await delay(BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS)
+      }
+      const queryKey = keys[i]
       const validated = validateQueryKeyStructure(queryKey)
-      return fetchBalance(
+      const result = await fetchBalance(
         validated.network,
         validated.accountIndex,
         validated.tokenAddress,
         walletId
       )
-    })
-  )
+      networkResults.push({ id: balanceQueryKeyId(queryKey), result })
+    }
+
+    for (const { id, result } of networkResults) {
+      results.set(id, result)
+    }
+  }
+
+  return queryKeys.map((queryKey) => results.get(balanceQueryKeyId(queryKey))!)
 }
 
 /**

package/src/hooks/useTransactions.ts

@@ -0,0 +1,98 @@
+/**
+ * Transaction hooks with TanStack Query
+ *
+ * Fetches wallet activity from the WDK Indexer (token-transfers per network/token/address).
+ * Requires indexerConfig on WdkAppProvider (typically from EXPO_PUBLIC_WDK_INDEXER_* in the app).
+ */
+
+import { useQuery } from '@tanstack/react-query'
+import { useShallow } from 'zustand/react/shallow'
+
+import { TransactionService } from '../services/transactionService'
+import { getWalletStore } from '../store/walletStore'
+import { getWorkletStore } from '../store/workletStore'
+import { isIndexerConfigured } from '../store/indexerConfigStore'
+import { resolveWalletId } from '../utils/storeHelpers'
+import {
+  DEFAULT_QUERY_GC_TIME_MS,
+  DEFAULT_QUERY_STALE_TIME_MS,
+} from '../utils/constants'
+import type { TokenConfigProvider, WalletTransaction } from '../types'
+
+export interface WalletTransactionsQueryOptions {
+  enabled?: boolean
+  staleTime?: number
+  refetchInterval?: number | false
+  walletId?: string
+}
+
+export const transactionQueryKeys = {
+  all: ['transactions'] as const,
+  byWallet: (walletId: string, accountIndex: number) =>
+    ['transactions', 'wallet', walletId, accountIndex] as const,
+}
+
+function resolveTokenConfigs(tokenConfigs: TokenConfigProvider) {
+  return typeof tokenConfigs === 'function' ? tokenConfigs() : tokenConfigs
+}
+
+function addressesFingerprint(
+  addresses: Record<string, Record<number, string>>,
+  accountIndex: number
+): string {
+  const parts: string[] = []
+  for (const network of Object.keys(addresses).sort()) {
+    const address = addresses[network]?.[accountIndex]
+    if (address) {
+      parts.push(`${network}:${address.toLowerCase()}`)
+    }
+  }
+  return parts.join('|')
+}
+
+async function fetchWalletTransactionsForAccount(
+  walletId: string,
+  accountIndex: number,
+  tokenConfigs: TokenConfigProvider
+): Promise<WalletTransaction[]> {
+  const walletStore = getWalletStore()
+  const addresses = walletStore.getState().addresses[walletId] ?? {}
+
+  return TransactionService.resolveWalletTransactions({
+    addresses,
+    accountIndex,
+    tokenConfigs: resolveTokenConfigs(tokenConfigs),
+  })
+}
+
+/**
+ * Fetch aggregated wallet transactions from the WDK Indexer.
+ */
+export function useWalletTransactions(
+  accountIndex: number,
+  tokenConfigs: TokenConfigProvider,
+  options?: WalletTransactionsQueryOptions
+) {
+  const workletStore = getWorkletStore()
+  const walletStore = getWalletStore()
+  const isInitialized = workletStore.getState().isInitialized
+  const walletId = resolveWalletId(options?.walletId)
+  const addresses = walletStore(
+    useShallow((state) => state.addresses[walletId] ?? {})
+  )
+  const addressKey = addressesFingerprint(addresses, accountIndex)
+  const indexerReady = isIndexerConfigured()
+
+  return useQuery({
+    queryKey: [...transactionQueryKeys.byWallet(walletId, accountIndex), addressKey],
+    queryFn: () => fetchWalletTransactionsForAccount(walletId, accountIndex, tokenConfigs),
+    enabled:
+      (options?.enabled !== false) &&
+      isInitialized &&
+      indexerReady &&
+      addressKey.length > 0,
+    staleTime: options?.staleTime ?? DEFAULT_QUERY_STALE_TIME_MS,
+    gcTime: DEFAULT_QUERY_GC_TIME_MS,
+    refetchInterval: options?.refetchInterval,
+  })
+}

package/src/index.ts

@@ -20,6 +20,9 @@ export type {
   TokenConfigProvider,
   TokenHelpers,
   WalletStore,
+  IndexerConfig,
+  WalletTransaction,
+  IndexerTokenTransfersResponse,
 } from './types'
 
 // HRPC Type Extensions (for extending HRPC functionality)
@@ -38,6 +41,8 @@ export { useWdkApp } from './hooks/useWdkApp'
 export { useWalletManager } from './hooks/useWalletManager'
 export type { UseWalletManagerResult, WalletInfo } from './hooks/useWalletManager'
 export { useBalance, useBalancesForWallet, useBalancesForWallets, useRefreshBalance, balanceQueryKeys } from './hooks/useBalance'
+export { useWalletTransactions, transactionQueryKeys } from './hooks/useTransactions'
+export type { WalletTransactionsQueryOptions } from './hooks/useTransactions'
 export type { AccountInfo } from './store/walletStore'
 
 // Validation Utilities (for validating configs before use)
@@ -84,6 +89,7 @@ export { WorkletLifecycleService } from './services/workletLifecycleService'
 export { AddressService } from './services/addressService'
 export { AccountService } from './services/accountService'
 export { BalanceService } from './services/balanceService'
+export { TransactionService } from './services/transactionService'
 export { WalletSetupService } from './services/walletSetupService'
 export { WalletSwitchingService } from './services/walletSwitchingService'
 

package/src/provider/WdkAppProvider.tsx

@@ -48,7 +48,8 @@ import { log, logError } from '../utils/logger'
 import { validateNetworkConfigs, validateTokenConfigs } from '../utils/validation'
 import { DEFAULT_QUERY_STALE_TIME_MS, DEFAULT_QUERY_GC_TIME_MS } from '../utils/constants'
 import { InitializationStatus, AppStatus, isAppReadyStatus, isAppInProgressStatus, getCombinedStatus, getWorkletStatus } from '../utils/initializationState'
-import type { NetworkConfigs, TokenConfigs } from '../types'
+import type { IndexerConfig, NetworkConfigs, TokenConfigs } from '../types'
+import { setIndexerConfig } from '../store/indexerConfigStore'
 
 
 
@@ -134,6 +135,11 @@ export interface WdkAppProviderProps {
   networkConfigs: NetworkConfigs
   /** Token configurations for balance fetching */
   tokenConfigs: TokenConfigs
+  /**
+   * WDK Indexer configuration for transaction history.
+   * Apps typically pass EXPO_PUBLIC_WDK_INDEXER_BASE_URL and EXPO_PUBLIC_WDK_INDEXER_API_KEY.
+   */
+  indexerConfig?: IndexerConfig
   /** Enable automatic wallet initialization on app restart (default: true) */
   enableAutoInitialization?: boolean
   /**
@@ -190,6 +196,7 @@ const deepEqualityFn = (a: any, b: any) => {
 export function WdkAppProvider({
   networkConfigs,
   tokenConfigs,
+  indexerConfig,
   enableAutoInitialization = true,
   currentUserId,
   children,
@@ -267,6 +274,11 @@ export function WdkAppProvider({
     }
   }, [networkConfigs, tokenConfigs])
 
+  useEffect(() => {
+    setIndexerConfig(indexerConfig ?? null)
+    return () => setIndexerConfig(null)
+  }, [indexerConfig])
+
   // Worklet state - read from workletStore via hook
   const workletHookState = useWorklet()
   const {

package/src/services/transactionService.ts

@@ -0,0 +1,194 @@
+/**
+ * Transaction Service
+ *
+ * Fetches wallet transaction history from the WDK Indexer API.
+ * Endpoint: GET /api/v1/{network}/{token}/{address}/token-transfers
+ */
+
+import { getIndexerConfig } from '../store/indexerConfigStore'
+import { BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS, BALANCE_FETCH_STAGGER_MS } from '../utils/constants'
+import { logError, logWarn } from '../utils/logger'
+import { delay, withTransientRetry } from '../utils/retryUtils'
+import type { IndexerTokenTransfersResponse, TokenConfigs, WalletTransaction } from '../types'
+
+export interface FetchWalletTransactionsParams {
+  addresses: Record<string, Record<number, string>>
+  accountIndex: number
+  tokenConfigs: TokenConfigs
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/$/, '')
+}
+
+function tokenSlugFromConfig(symbol: string): string {
+  return symbol.toLowerCase()
+}
+
+function transactionDedupeKey(tx: WalletTransaction): string {
+  return [
+    tx.blockchain,
+    tx.transactionHash,
+    tx.token,
+    tx.transferIndex ?? '',
+    tx.logIndex ?? '',
+    tx.from,
+    tx.to,
+    tx.amount,
+  ].join('|')
+}
+
+function parseIndexerTransfers(payload: unknown): WalletTransaction[] {
+  if (!payload || typeof payload !== 'object') {
+    return []
+  }
+  const transfers = (payload as IndexerTokenTransfersResponse).transfers
+  if (!Array.isArray(transfers)) {
+    return []
+  }
+
+  const parsed: WalletTransaction[] = []
+  for (const item of transfers) {
+    if (!item || typeof item !== 'object') continue
+    const tx = item as Partial<WalletTransaction>
+    if (
+      typeof tx.transactionHash !== 'string' ||
+      typeof tx.token !== 'string' ||
+      typeof tx.amount !== 'string' ||
+      typeof tx.timestamp !== 'number' ||
+      typeof tx.from !== 'string' ||
+      typeof tx.to !== 'string'
+    ) {
+      continue
+    }
+    parsed.push({
+      blockchain: typeof tx.blockchain === 'string' ? tx.blockchain : '',
+      blockNumber: typeof tx.blockNumber === 'number' ? tx.blockNumber : undefined,
+      transactionHash: tx.transactionHash,
+      transferIndex: typeof tx.transferIndex === 'number' ? tx.transferIndex : undefined,
+      token: tx.token.toLowerCase(),
+      amount: tx.amount,
+      timestamp: tx.timestamp,
+      transactionIndex: typeof tx.transactionIndex === 'number' ? tx.transactionIndex : undefined,
+      logIndex: typeof tx.logIndex === 'number' ? tx.logIndex : undefined,
+      from: tx.from,
+      to: tx.to,
+      label: typeof tx.label === 'string' ? tx.label : undefined,
+    })
+  }
+  return parsed
+}
+
+export class TransactionService {
+  /**
+   * Fetch token transfers for one network/token/address from the indexer.
+   */
+  static async fetchTokenTransfers(
+    network: string,
+    tokenSlug: string,
+    address: string
+  ): Promise<WalletTransaction[]> {
+    const config = getIndexerConfig()
+    if (!config?.baseUrl || !config.apiKey) {
+      throw new Error('WDK Indexer is not configured')
+    }
+
+    const url = `${normalizeBaseUrl(config.baseUrl)}/api/v1/${encodeURIComponent(network)}/${encodeURIComponent(tokenSlug)}/${encodeURIComponent(address)}/token-transfers`
+
+    const response = await withTransientRetry(
+      async () => {
+        const res = await fetch(url, {
+          method: 'GET',
+          headers: {
+            'x-api-key': config.apiKey,
+            Accept: 'application/json',
+          },
+        })
+
+        if (res.status === 404) {
+          return { ok: true as const, transfers: [] as WalletTransaction[] }
+        }
+
+        if (!res.ok) {
+          const text = await res.text().catch(() => '')
+          throw new Error(
+            `Indexer token-transfers failed (${res.status}) for ${network}/${tokenSlug}: ${text.slice(0, 200)}`
+          )
+        }
+
+        const json: unknown = await res.json()
+        return { ok: true as const, transfers: parseIndexerTransfers(json) }
+      },
+      { label: `${network}/${tokenSlug} token-transfers` }
+    )
+
+    return response.transfers
+  }
+
+  /**
+   * Fetch transfers for all configured networks/tokens for one account index.
+   */
+  static async fetchWalletTransactions(
+    params: FetchWalletTransactionsParams
+  ): Promise<WalletTransaction[]> {
+    const { addresses, accountIndex, tokenConfigs } = params
+    const networks = Object.keys(tokenConfigs)
+    const deduped = new Map<string, WalletTransaction>()
+    let isFirstNetwork = true
+
+    for (const network of networks) {
+      const address = addresses[network]?.[accountIndex]
+      if (!address) {
+        continue
+      }
+
+      if (!isFirstNetwork) {
+        await delay(BALANCE_FETCH_STAGGER_MS)
+      }
+      isFirstNetwork = false
+
+      const networkTokens = tokenConfigs[network]
+      if (!networkTokens) continue
+
+      const tokens = [networkTokens.native, ...networkTokens.tokens]
+      for (let i = 0; i < tokens.length; i++) {
+        if (i > 0) {
+          await delay(BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS)
+        }
+
+        const token = tokens[i]
+        const tokenSlug = tokenSlugFromConfig(token.symbol)
+        try {
+          const transfers = await this.fetchTokenTransfers(network, tokenSlug, address)
+          for (const tx of transfers) {
+            const withBlockchain = tx.blockchain
+              ? tx
+              : { ...tx, blockchain: network }
+            deduped.set(transactionDedupeKey(withBlockchain), withBlockchain)
+          }
+        } catch (error) {
+          logError(
+            `Failed to fetch token transfers for ${network}/${tokenSlug}:`,
+            error
+          )
+        }
+      }
+    }
+
+    return Array.from(deduped.values()).sort((a, b) => b.timestamp - a.timestamp)
+  }
+
+  /**
+   * Resolve wallet transactions (alias for fetchWalletTransactions).
+   * Matches the legacy resolveWalletTransactions name used by consuming apps.
+   */
+  static async resolveWalletTransactions(
+    params: FetchWalletTransactionsParams
+  ): Promise<WalletTransaction[]> {
+    if (!getIndexerConfig()) {
+      logWarn('[TransactionService] Indexer not configured — returning empty transaction list')
+      return []
+    }
+    return this.fetchWalletTransactions(params)
+  }
+}

package/src/store/indexerConfigStore.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime WDK Indexer configuration (set by WdkAppProvider from app env).
+ */
+
+import type { IndexerConfig } from '../types'
+
+let indexerConfig: IndexerConfig | null = null
+
+export function setIndexerConfig(config: IndexerConfig | null): void {
+  indexerConfig = config
+}
+
+export function getIndexerConfig(): IndexerConfig | null {
+  return indexerConfig
+}
+
+export function isIndexerConfigured(): boolean {
+  return Boolean(indexerConfig?.baseUrl && indexerConfig?.apiKey)
+}

package/src/types.ts

@@ -157,6 +157,42 @@ export interface BalanceFetchResult {
  */
 export type TokenConfigProvider = TokenConfigs | (() => TokenConfigs)
 
+/**
+ * WDK Indexer API configuration (balance/transaction history).
+ */
+export interface IndexerConfig {
+  /** Base URL, e.g. https://wdk-api.tether.io */
+  baseUrl: string
+  /** API key sent as x-api-key header */
+  apiKey: string
+}
+
+/**
+ * Token transfer from the WDK Indexer token-transfers endpoint.
+ */
+export interface WalletTransaction {
+  blockchain: string
+  blockNumber?: number
+  transactionHash: string
+  transferIndex?: number
+  token: string
+  amount: string
+  /** Unix timestamp in seconds (indexer convention) */
+  timestamp: number
+  transactionIndex?: number
+  logIndex?: number
+  from: string
+  to: string
+  label?: string
+}
+
+/**
+ * Raw indexer response for token-transfers.
+ */
+export interface IndexerTokenTransfersResponse {
+  transfers?: WalletTransaction[]
+}
+
 /**
  * Token Helpers
  * 

package/src/utils/constants.ts

@@ -67,6 +67,28 @@ export const DEFAULT_QUERY_STALE_TIME_MS = 30 * 1000
  */
 export const DEFAULT_QUERY_GC_TIME_MS = 5 * 60 * 1000
 
+/**
+ * Delay between per-network balance fetches on wallet load (ms).
+ * Spreads RPC load across chains instead of firing every network at once.
+ */
+export const BALANCE_FETCH_STAGGER_MS = 400
+
+/**
+ * Delay between token balance fetches within the same network (ms).
+ * TON jetton balances issue multiple RPC calls each; serializing avoids 429 bursts.
+ */
+export const BALANCE_FETCH_INTRA_NETWORK_STAGGER_MS = 300
+
+/**
+ * Max attempts for transient blockchain/RPC errors (429, 5xx, network timeouts).
+ */
+export const TRANSIENT_ERROR_MAX_ATTEMPTS = 3
+
+/**
+ * Initial backoff for transient error retries (ms); doubled on each attempt.
+ */
+export const TRANSIENT_ERROR_INITIAL_BACKOFF_MS = 1000
+
 /**
  * Allowed account methods whitelist
  * Only these methods can be called through AccountService for security

package/src/utils/retryUtils.ts

@@ -0,0 +1,77 @@
+/**
+ * Retry helpers for transient blockchain/RPC failures (429, 5xx, network errors).
+ */
+
+import {
+  TRANSIENT_ERROR_INITIAL_BACKOFF_MS,
+  TRANSIENT_ERROR_MAX_ATTEMPTS,
+} from './constants'
+import { getErrorMessage } from './errorUtils'
+import { log } from './logger'
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Whether an error is likely transient and worth retrying with backoff.
+ * Matches Spaces API retry rules: 429, 408, 5xx, and common network failures.
+ */
+export function isTransientBlockchainError(error: unknown): boolean {
+  const message = getErrorMessage(error).toLowerCase()
+
+  if (
+    message.includes('429') ||
+    message.includes('too many requests') ||
+    message.includes('rate limit') ||
+    message.includes('408') ||
+    message.includes('request timeout') ||
+    message.includes('etimedout') ||
+    message.includes('econnreset') ||
+    message.includes('econnrefused') ||
+    message.includes('network request failed') ||
+    message.includes('network error') ||
+    message.includes('socket hang up')
+  ) {
+    return true
+  }
+
+  return /\b5\d{2}\b/.test(message)
+}
+
+export interface WithTransientRetryOptions {
+  maxAttempts?: number
+  initialBackoffMs?: number
+  /** Label for retry log messages */
+  label?: string
+}
+
+/**
+ * Run an async function with exponential backoff on transient errors.
+ */
+export async function withTransientRetry<T>(
+  fn: () => Promise<T>,
+  options: WithTransientRetryOptions = {}
+): Promise<T> {
+  const maxAttempts = options.maxAttempts ?? TRANSIENT_ERROR_MAX_ATTEMPTS
+  const initialBackoffMs = options.initialBackoffMs ?? TRANSIENT_ERROR_INITIAL_BACKOFF_MS
+  const label = options.label ?? 'operation'
+
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (!isTransientBlockchainError(error) || attempt >= maxAttempts) {
+        throw error
+      }
+      const backoffMs = initialBackoffMs * (1 << (attempt - 1))
+      log(`[Balance] ${label}: retry in ${backoffMs}ms (${attempt}/${maxAttempts})`)
+      await delay(backoffMs)
+    }
+  }
+
+  throw lastError
+}