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} {cryptoSymbol}</p>
      <p>{fiatSymbol}{fiatBalance}</p>
      <p className="text-sm">Rate: {fiatSymbol}{cryptoRate}</p>
    </div>
  )
}

Return Values

Property	Type	Description
`walletBalance`	`string`	Native token balance (e.g., `'1.5'`).
`fiatBalance`	`string`	Balance converted to fiat currency.
`cryptoRate`	`string`	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 full list of tracked token assets for the connected wallet. Tracked tokens are configured via the watchTokens option in the Provider.


import { useAssets } from '@embarkai/ui-kit'
 
function AssetList() {
  const assets = useAssets()
 
  return (
    <ul>
      {assets?.map((asset) => (
        <li key={asset.address}>
          {asset.symbol}: {asset.balance}
        </li>
      ))}
    </ul>
  )
}

useTokenInfo

Returns metadata for a specific token by its contract address.


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

useTokenBalance

Returns the balance for a specific ERC-20 token by its contract address.


import { useTokenBalance } from '@embarkai/ui-kit'
 
function TokenBalance({ address }: { address: `0x${string}` }) {
  const balance = useTokenBalance(address)
 
  return <p>Balance: {balance ?? '0'}</p>
}

Formatting Example

Combine hooks to build a complete balance display:


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