Fetch Token Balances

Token balance are currently supported on: Ethereum, Worldchain, Shape, Zksync, Optimism, Polygon, Geist, Arbitrum, Blast, Linea, Base, Scroll, Gnosis, BNB, Avalanche, Apechain, Lens, Soneium, Rootstock, Abstract, Settlus, Ink, Solana, and SUI.

Dynamic supports fetching the top 3000 tokens by market cap.

You can fetch token balances across multiple blockchain networks using the getMultichainBalances method on the Dynamic client. This returns balances for all tokens held at the specified addresses, including prices and metadata.

Usage

import { dynamicClient } from '<path to client file>';
import { ChainEnum } from '@dynamic-labs/sdk-api-core';

const wallet = dynamicClient.wallets.primary;

if (wallet) {
  const chainBalances = await dynamicClient.wallets.getMultichainBalances({
    balanceRequest: {
      filterSpamTokens: true,
      balanceRequests: [
        {
          address: wallet.address,
          chain: wallet.chain as ChainEnum,
          networkIds: [1], // e.g. Ethereum mainnet
        },
      ],
    },
  });
}

Full example with React Query

This example shows how to fetch and display token balances for a wallet using @tanstack/react-query:

import { FC } from 'react';
import { Text, View, Image } from 'react-native';
import { useQuery } from '@tanstack/react-query';
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
import { Wallet } from '@dynamic-labs/client';

import { dynamicClient } from '<path to client file>';

type WalletTokenBalancesProps = {
  wallet: Wallet;
  network: number;
};

export const WalletTokenBalances: FC<WalletTokenBalancesProps> = ({
  wallet,
  network,
}) => {
  const { data: balances } = useQuery({
    queryKey: ['wallets', wallet.address, 'networks', network, 'getMultichainBalances'],
    enabled: !!network,
    queryFn: () =>
      dynamicClient.wallets.getMultichainBalances({
        balanceRequest: {
          balanceRequests: [
            {
              address: wallet.address,
              chain: wallet.chain as ChainEnum,
              networkIds: [network],
            },
          ],
        },
      }),
    retry: false,
    refetchOnWindowFocus: false,
  });

  const tokenBalances = (balances ?? [])
    .flatMap((chain) => chain.networks ?? [])
    .flatMap((net) => net.balances ?? []);

  return (
    <View>
      {tokenBalances.map((token) => (
        <View key={`${token?.networkId}-${token?.address}`}>
          {!!token?.logoURI && (
            <Image
              source={{ uri: token.logoURI }}
              style={{ width: 24, height: 24, borderRadius: 12 }}
            />
          )}
          <Text>{token?.name ?? token?.symbol ?? 'Token'}</Text>
          <Text>{token?.balance} {token?.symbol}</Text>
        </View>
      ))}
    </View>
  );
};

Parameters

Parameter	Type	Required	Description
address	String	Yes	The wallet address
chain	ChainEnum	Yes	Chain type (Evm, Sol, Btc, etc.)
networkIds	Array<Number>	Yes	Array of network IDs to query
filterSpamTokens	Boolean	No	Filter out spam tokens (default: true)
whitelistedContracts	Array<String>	No	Contract addresses to not filter out

Response

Returns an array of chain balance objects. Each object contains the chain, wallet address, and an array of networks with their token balances:

[
  {
    "chain": "EVM",
    "networks": [
      {
        "networkId": 1,
        "balances": [
          {
            "address": "0x...",
            "balance": 1.5,
            "decimals": 18,
            "isNative": true,
            "logoURI": "https://...",
            "marketValue": 3750.00,
            "name": "Ether",
            "networkId": 1,
            "price": 2500.00,
            "symbol": "ETH"
          }
        ]
      }
    ],
    "walletAddress": "0x..."
  }
]