Getting Multichain Token Balances

Recommended default. getMultichainTokenBalances is the most general balance fetcher — it batches token balances across any combination of chains, networks, and addresses in a single API call. Use it unless you specifically only need one chain (getTokenBalances) or the native gas balance (getNativeBalance).

You can get token balances across multiple chains and networks by calling the getMultichainTokenBalances function. This fetches cryptocurrency and token balances for wallet addresses across different chains, networks, and addresses specified in the request.

Usage

JavaScript
React

import { getMultichainTokenBalances } from '@dynamic-labs-sdk/client';

const chainBalances = await getMultichainTokenBalances({
  balanceRequest: {
    filterSpamTokens: true,
    balanceRequests: [
      {
        address: '0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0',
        chain: 'EVM',
        networkIds: [1, 137, 56], // Ethereum, Polygon, BNB
        whitelistedContracts: ['0x...'], // Optional: contracts to not filter out
      },
      {
        address: 'CKEAuq1E7hUcrjDcu1xP6nax3YBvEhhq7qaCzDUkPNer',
        chain: 'SOL',
        networkIds: [101], // Solana mainnet
      },
    ],
  },
});

import { getMultichainTokenBalances } from '@dynamic-labs-sdk/client';
import { useEffect, useState } from 'react';

function MultichainBalances({ evmAddress, solanaAddress }) {
  const [chainBalances, setChainBalances] = useState([]);

  useEffect(() => {
    if (!evmAddress) return;

    getMultichainTokenBalances({
      balanceRequest: {
        filterSpamTokens: true,
        balanceRequests: [
          { address: evmAddress, chain: 'EVM', networkIds: [1, 137] },
          ...(solanaAddress
            ? [{ address: solanaAddress, chain: 'SOL', networkIds: [101] }]
            : []),
        ],
      },
    }).then(setChainBalances);
  }, [evmAddress, solanaAddress]);

  return <pre>{JSON.stringify(chainBalances, null, 2)}</pre>;
}

Parameters

Parameter	Type	Description
`balanceRequest`	`MultichainAccountBalancesRequest`	The balance request configuration
`client`	`DynamicClient`	Optional. Only required when using multiple Dynamic clients

MultichainAccountBalancesRequest

Parameter	Type	Required	Description
`filterSpamTokens`	Boolean	No	Filter out spam tokens (default: `true`)
`balanceRequests`	Array	Yes	Array of balance request objects

Balance Request Object

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
`whitelistedContracts`	Array<String>	No	Contract addresses to not filter out

Response

Returns Promise<MultichainAccountBalanceResponse['chainBalances']> — an array of chain balance objects organized by chain and network.

[
  {
    "chain": "EVM",
    "networks": [
      {
        "networkId": 1,
        "balances": [
          {
            "address": "0x9de16c805a3227b9b92e39a446f9d56cf59fe640",
            "balance": 7877386.999999999,
            "decimals": 18,
            "id": null,
            "isNative": false,
            "liquidityPoolSizeUsd": 35339.28,
            "logoURI": "https://...",
            "marketValue": 0.05,
            "name": "TokenName",
            "networkId": 1,
            "price": 6.83e-9,
            "rawBalance": 7.877387e+24,
            "rawBalanceString": "7877387000000000000000000",
            "symbol": "TKN"
          }
        ]
      }
    ],
    "walletAddress": "0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0"
  }
]

Getting Token Balances - Single-network token balance variant
Getting Native Balance - Native gas balance only, via RPC
Getting Wallet Accounts
Getting Active Network

Documentation Index

​Usage

​Parameters

​MultichainAccountBalancesRequest

​Balance Request Object

​Response

​Related functions

Usage

Parameters

MultichainAccountBalancesRequest

Balance Request Object

Response

Related functions