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.