Skip to main content

Token balances

GET 
/v1/data/token/balances

Fetches token balances for a given account on a specific chain, including USD values.

Features:

  • Automatically includes native token balance (ETH, BNB, etc.)
  • Fetches current prices for USD conversion
  • Returns both raw and formatted balance values

Response Structure:

  • items: Array of balance entries for each token
  • count: Total number of balance entries

Balance Entry includes:

  • address: Token contract address (zeroAddress for native)
  • symbol: Token symbol
  • name: Token name
  • decimals: Token decimals
  • balanceRaw: Raw balance as string (wei/smallest unit)
  • balance: Formatted balance as decimal string
  • balanceUSD: Balance value in USD

Note: The native token balance is always included with address 0x0000000000000000000000000000000000000000.

Plain-text reference — GET /v1/data/token/balances

Parameters

ParameterInTypeRequiredDescription
chainIdquerystringyesChain ID to fetch balances on See the ChainId schema for the full set of supported chains.
accountquerystringyesEVM account address (0x-prefixed, 40 hex chars)
assetsquerystringyesComma-separated token addresses to fetch balances for

Response 200

FieldTypeDescription
successTrue
dataobject
data.chainIdstringEVM chain id, as a decimal string. See the ChainId schema.
data.accountstringLowercase account address
data.countintegerNumber of balance entries
data.itemsobject[]The result set for this response.
data.items[].addressstringToken contract address (zeroAddress for native)
data.items[].symbolstringToken symbol, e.g. WETH.
data.items[].namestringHuman-readable display name.
data.items[].decimalsintegerToken decimals — divide raw amounts by 10 ** decimals.
data.items[].balanceRawstringRaw balance in smallest unit (wei)
data.items[].balancestringFormatted balance as decimal string
data.items[].priceUSDnumberPer-unit USD price of the token
data.items[].balanceUSDnumberBalance value in USD
actionsnull

Example response

{
  "success": true,
  "data": {
    "chainId": "1",
    "account": "0xbada9c382165b31419f4cc0edf0fa84f80a3c8e5",
    "count": 1,
    "items": [
      {
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "balanceRaw": "1000000",
        "balance": "1.0",
        "priceUSD": 1,
        "balanceUSD": 1
      }
    ]
  }
}

Request​

Responses​

Token balances with USD values