useTokenUsdValues()

function useTokenUsdValues(entries): UseTokenUsdValuesResult;

Fetches the USD-equivalent value of each entry’s balance through one SDK batch read. Only entries with a positive balance are priced — zero-balance entries return 0n without a Hermes request. Only fresh display outcomes produce a value: tokens whose price lookup fails (no feed, network error, or invalid data) or whose price is outside oracleConfig.maxPriceAgeSeconds come back as undefined so callers can sort them after entries with known values. data stays undefined until the first read settles.

This hook reads the provider through useAnvilSDKOptional, so it does not throw outside an <AnvilProvider>; without one it issues no read and returns only the zero-balance entries. Read failures surface on error, never as a throw.

Parameters

Parameter	Type	Description
entries	| UseTokenUsdValuesEntry[] | undefined	Tokens to price and the balances to price them at. undefined, an empty array, or entries whose balances are all zero issue no request.

Returns

UseTokenUsdValuesResult

The read envelope. data maps every supplied address to its USD-cent value, undefined per address where the price is unknown, and is itself undefined until the first batch read settles.

Example

export function WalletValue({ balances }: { balances: Token[] }) {
  const { data: valuesByToken } = useTokenUsdValues(
    balances.map(token => ({ address: token.address, balance: 1n }))
  );

  return (
    <ul>
      {balances.map(token => {
        const cents = valuesByToken?.[token.address];
        return (
          <li key={token.address}>
            {/* `undefined` means unknown (no feed, stale, or failed) --
                sort those last rather than treating them as zero. */}
            {token.symbol}: {cents === undefined ? '—' : `${cents}¢`}
          </li>
        );
      })}
    </ul>
  );
}