Skip to main content

Parse token balances

POST 
/v1/data/token/balances/parse

Accepts the raw hex RPC response obtained by executing the call from /token/balances/rpc-call and decodes it into structured token balance data with USD values.

Workflow:

  1. Call /token/balances/rpc-call to get prepared RPC calls and a rpcCallId
  2. Execute the RPC call against your own node
  3. Send rpcCallId + rawResponses to this endpoint for parsing

The rpcCallId ties the response back to the cached preparation context (valid for 5 minutes). After successful parsing the cached context is deleted.

Multi-chain mode (when the rpc-call was made with chains): rawResponses entries are { chainId, result } (result = hex string or full JSON-RPC envelope), and the response is { account, chains: [{ chainId, count, items }], missingChains? } — chains whose response was not submitted appear in missingChains.

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
Plain-text reference — POST /v1/data/token/balances/parse

Request body

FieldTypeRequiredDescription
rpcCallIdstringyesThe rpcCallId returned by /token/balances/rpc-call.
rawResponsesstring[]yesArray containing the raw hex-encoded result from the eth_call. Typically a single-element array.

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