Fetch Token Balances

Recommended: JavaScript SDK for React Native

While this SDK is still supported, we recommend using newer JavaScript SDK, which is optimized for React Native, but also comes with a host of other benefits.

Token balances are provided by Zerion and supported across 35+ EVM networks (including Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Avalanche, zkSync Era, Linea, Scroll, Gnosis, Apechain, Lens Chain, Soneium, Abstract, and Ink) plus Solana.

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/legacy-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

For BTC (served separately from Zerion), pass a single network ID matching the network the address belongs to: 1 for mainnet, 2 for testnet, or 3 for signet. Only the first network ID is used for a BTC balance lookup, and a mismatch returns an empty balance set. Testnet and signet share the same address format, so pass the ID for the network you intend to query.

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..."
  }
]