> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Token Balances

> [card] Recommended: JavaScript SDK for React Native
>
> While this SDK is still supported, we recommend using newer [JavaScript SDK](https://docs.dynamic.xyz/docs/javascript/reference/react-native-quickstart.md), which is optimized for React Native, but also comes with a host of other benefits.

> [!NOTE]
>
> 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

```typescript theme={"system"}
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`:

```tsx theme={"system"}
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 |

> [!NOTE]
>
> 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:

```json theme={"system"}
[
  {
    "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..."
  }
]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.