Balances

Load token balances for connected wallets (walletId). Amounts are human-readable crypto; fiat (currently USD) is filled when an exchange rate is available.

getBalances() returns API balances first, then enriches rates. Subscribe to wallets:balancesUpdated for the rate-enriched snapshot. getCachedBalances() is the last snapshot (used by getConnections({ sort: 'balanceDesc' })).

Balances do not prove the wallet is still live. They use addresses from connection state, including last-known addresses after restore.

Methods

Method	Returns
getBalances({ forceRefetch? })	WalletBalancesForWallet[] - one group per walletId
getWalletBalance(walletId, { forceRefetch? })	WalletBalance[] for one instance
getCachedBalances()	Last snapshot

getBalances() is every connected wallet (one group per walletId). getWalletBalance(walletId) is one instance. React: useAllWalletBalances / useWalletBalances.

forceRefetch: true bypasses the balances cache (wallets.balancesCacheTtlMs on the client, default 10 minutes).

const groups = await client.wallets.getBalances()

const tokens = await client.wallets.getWalletBalance(walletId, {
  forceRefetch: true,
})

client.on('wallets:balancesUpdated', ({ balances }) => {
  // same shape as getBalances(), after rate enrichment
})

WalletBalance

Field	Meaning
symbol / name / decimals	Token
balance	Raw amount in base units. Native SOL is spendable (rent + fee buffer already subtracted)
displayBalance	Human-readable crypto (spendable for native SOL)
network	Network
walletAddress	Address this balance belongs to
tokenAddress	Contract, or null for native
logo / thumbnail	Images
exchangeRate	Fiat price per 1 token, or null
fiatValue	Fiat value of this balance, or null
supported	A deposit route exists (session wallet match, or swap / bridge)
balanceTooLow	Spendable amount is zero, below display dust, or below the session / destination min
eligible	supported && !balanceTooLow - safe to take into amount / submit
ineligibleReason?	'unsupported' | 'zero_balance' | 'below_min'
formatted.balance	Display-ready crypto string
formatted.fiatValue	Display-ready fiat string (empty when unknown)

for (const group of groups) {
  for (const token of group.balances) {
    token.formatted.balance
    token.formatted.fiatValue
    token.eligible
    token.ineligibleReason
  }
}

Eligibility

Decide in this order. Still list ineligible rows - map ineligibleReason to copy.

1. Supported - a deposit route exists (supported). If not → 'unsupported'
2. Has balance - spendable amount is above dust. If not → 'zero_balance'
3. Meets min - spendable meets the session / destination minimum. If not → 'below_min'
4. Eligible - supported && !balanceTooLow

sortWalletTokens(tokens, 'balanceDesc') sorts eligible tokens first, then higher fiatValue. Tokens without a rate stay after rated ones. balanceTooLow rows sink.