Balance & Assets

Hooks for native balances, fiat conversion, ERC-20 token balances, and asset tracking.

embarkAI provides a set of hooks for reading balances and asset data. The primary useBalance hook returns the native token balance with fiat conversion, while useAssets, useTokenInfo, and useTokenBalance give you access to individual ERC-20 tokens.

Import


import {
  useBalance,
  useAssets,
  useTokenInfo,
  useTokenBalance,
  useBlockscoutAssets,
} from '@embarkai/ui-kit'

useBalance

Returns the native token balance for the connected wallet along with fiat conversion data.


import { useBalance } from '@embarkai/ui-kit'
 
function BalanceCard() {
  const { walletBalance, fiatBalance, cryptoRate, fiatSymbol, cryptoSymbol } = useBalance()
 
  return (
    <div>
      <p>{walletBalance.formatted} {walletBalance.symbol}</p>
      <p>{fiatSymbol}{fiatBalance.toFixed(2)}</p>
      <p className="text-sm">Rate: {fiatSymbol}{cryptoRate}</p>
    </div>
  )
}

Return Values

Property	Type	Description
`walletBalance`	`{ formatted: string; symbol: string; value: bigint; decimals: number }`	Native token balance. `formatted` is human-readable (e.g. `'1.5'`), `value` is in wei.
`fiatBalance`	`number`	Balance converted to fiat currency.
`cryptoRate`	`number`	Current exchange rate for the native token.
`fiatSymbol`	`string`	Fiat currency symbol (e.g. `'$'`).
`cryptoSymbol`	`string`	Native token symbol (e.g. `'LUMIA'`).

useAssets

Returns the native balance and the tracked ERC-20 assets for the connected wallet (or for address, if passed). Tracked tokens are configured via the watchTokens option in the Provider.


import { useAssets } from '@embarkai/ui-kit'
 
function AssetList() {
  const { assets, nativeBalance, isLoading, refreshBalances } = useAssets()
 
  if (isLoading) return <p>Loading assets...</p>
 
  return (
    <div>
      <p>{nativeBalance.symbol}: {nativeBalance.value.toString()} wei</p>
      <ul>
        {assets.map((asset) => (
          <li key={asset.address ?? asset.symbol}>
            {asset.symbol}: {asset.formattedBalance}
          </li>
        ))}
      </ul>
      <button onClick={refreshBalances}>Refresh</button>
    </div>
  )
}

Return Value

Property	Type	Description
`nativeBalance`	`{ value: bigint; symbol: string; decimals: number }`	Native token balance.
`assets`	`Asset[]`	Tracked tokens with `symbol`, `name`, `balance`, `formattedBalance`, `address?`, `decimals?`, `logo?`.
`getTokenBalance(tokenAddress)`	`(address) => { balance, formattedBalance, symbol, … }`	Look up one tracked token.
`refreshBalances`	`() => Promise<void>`	Refetch all balances.
`isLoading` / `isConnected`	`boolean`	Query state / whether a wallet is connected.

useTokenInfo

Returns { isLoading, tokenInfo } for a token contract address, where tokenInfo is { name, symbol, decimals, address } once loaded.


import { useTokenInfo } from '@embarkai/ui-kit'
 
function TokenDetails({ address }: { address: `0x${string}` }) {
  const { tokenInfo, isLoading } = useTokenInfo(address)
 
  if (isLoading || !tokenInfo) return <p>Loading token info...</p>
 
  return (
    <div>
      <p>{tokenInfo.name} ({tokenInfo.symbol})</p>
      <p>Decimals: {tokenInfo.decimals}</p>
    </div>
  )
}

useTokenBalance

useTokenBalance(tokenAddress, userAddress?) returns { balance: bigint, formattedBalance: string, tokenInfo, isLoading, refetch } for an ERC-20 token. userAddress defaults to the connected wallet.


import { useTokenBalance } from '@embarkai/ui-kit'
 
function TokenBalance({ address }: { address: `0x${string}` }) {
  const { formattedBalance, balance, isLoading, refetch } = useTokenBalance(address)
 
  if (isLoading) return <p>Loading...</p>
 
  return (
    <p>
      Balance: {formattedBalance} ({balance.toString()} raw)
      <button onClick={() => refetch()}>↻</button>
    </p>
  )
}

Formatting Example

Combine hooks to build a complete balance display:


import { useBalance, useAssets } from '@embarkai/ui-kit'
 
function Portfolio() {
  const { walletBalance, fiatBalance, fiatSymbol } = useBalance()
  const { assets } = useAssets()
 
  return (
    <div>
      <h2>Portfolio</h2>
      <div className="native-balance">
        <span>{walletBalance.formatted} {walletBalance.symbol}</span>
        <span className="text-muted">{fiatSymbol}{fiatBalance.toFixed(2)}</span>
      </div>
 
      <h3>Tokens</h3>
      {assets.map((asset) => (
        <div key={asset.address ?? asset.symbol} className="token-row">
          <span>{asset.symbol}</span>
          <span>{asset.formattedBalance}</span>
        </div>
      ))}
    </div>
  )
}

useBlockscoutAssets

Fetches the full token portfolio (native + ERC-20 + NFTs) from a Blockscout-compatible API. Returns richer data than useAssets because it queries the indexer rather than on-chain multicall — useful when you need NFT metadata or a complete token list without manual configuration.


import { useBlockscoutAssets } from '@embarkai/ui-kit'
 
function Portfolio({ address }: { address: `0x${string}` }) {
  const {
    nativeBalance,
    assets,
    isLoading,
    isBlockscoutAvailable,
    error,
  } = useBlockscoutAssets({ address })
 
  if (isLoading) return <p>Loading...</p>
  if (!isBlockscoutAvailable) return <p>Blockscout unavailable — falling back to on-chain data.</p>
 
  return (
    <ul>
      {nativeBalance && (
        <li>{nativeBalance.symbol}: {nativeBalance.formatted}</li>
      )}
      {assets.map((a) => (
        <li key={a.address ?? a.symbol}>{a.symbol}: {a.formattedBalance}</li>
      ))}
    </ul>
  )
}

Options

Prop	Type	Default	Description
`address`	`Address \| undefined`	—	Wallet address to query.
`enabled`	`boolean`	`true`	Disable the query (e.g. while address is unknown).
`detectSecurityTokens`	`boolean`	`true`	Auto-detect ERC-3643 security tokens.

Return Value

Property	Type	Description
`nativeBalance`	`{ value, formatted, symbol } \| null`	Native-token balance (always via RPC).
`assets`	`Asset[]`	All discovered assets: native + tokens + NFTs.
`isLoading`	`boolean`	Any query in progress.
`isInitialLoading`	`boolean`	First load only.
`error`	`AssetListError \| null`	Blockscout error (null if native balance is available).
`isBlockscoutAvailable`	`boolean`	Whether the indexer responded.

Next Steps

useSendTransaction — send tokens from the wallet
Components — display transactions and addresses with built-in components
useSession — check connection state before reading balances