# Parse token balances

Endpoint reference for the 1delta API. Index: https://docs.1delta.io/llms.txt · every endpoint: https://docs.1delta.io/llms-full.txt

---

### POST /v1/data/token/balances/parse

- operationId: `parse-token-balances`
- docs: https://docs.1delta.io/1delta-api/parse-token-balances/
- markdown: https://docs.1delta.io/1delta-api/parse-token-balances.md
- tags: Token

Parse token balances

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

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rpcCallId` | string | yes | The rpcCallId returned by /token/balances/rpc-call. |
| `rawResponses` | string[] | yes | Array containing the raw hex-encoded result from the eth_call. Typically a single-element array. |

**Example request body**

```json
{
  "rpcCallId": "string",
  "rawResponses": [
    "string"
  ]
}
```

**Response `200`** — Token balances with USD values

| Field | Type | Description |
| --- | --- | --- |
| `success` | true |  |
| `data` | object |  |
| `data.chainId` | string | EVM chain id, as a decimal string. See the `ChainId` schema. |
| `data.account` | string | Lowercase account address |
| `data.count` | integer | Number of balance entries |
| `data.items` | object[] | The result set for this response. |
| `data.items[].address` | string | Token contract address (zeroAddress for native) |
| `data.items[].symbol` | string | Token symbol, e.g. `WETH`. |
| `data.items[].name` | string | Human-readable display name. |
| `data.items[].decimals` | integer | Token decimals — divide raw amounts by `10 ** decimals`. |
| `data.items[].balanceRaw` | string | Raw balance in smallest unit (wei) |
| `data.items[].balance` | string | Formatted balance as decimal string |
| `data.items[].priceUSD` | number | Per-unit USD price of the token |
| `data.items[].balanceUSD` | number | Balance value in USD |
| `actions` | null |  |

**Example response**

```json
{
  "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
      }
    ]
  }
}
```

**Response `400`** — Validation error

**Response `404`** — RPC call context not found or expired (older than 5 minutes). Call `/token/balances/rpc-call` again.

**Response `429`** — Rate limited. Unauthenticated callers share a per-IP budget; send an `x-api-key` header to lift it. Retry with exponential backoff.

**Response `500`** — Unexpected server error. Safe to retry with backoff.

**Response `502`** — An upstream data source or protocol origin failed (`error.code` is `ORIGIN_FAILED`). `error.details` carries the per-origin status. This is also what a missing or malformed required parameter currently returns, rather than a 400.