# Token balances

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

---

### GET /v1/data/token/balances

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

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`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `chainId` | query | string | yes | Chain ID to fetch balances on See the `ChainId` schema for the full set of supported chains. |
| `account` | query | string | yes | EVM account address (0x-prefixed, 40 hex chars) |
| `assets` | query | string | yes | Comma-separated token addresses to fetch balances for |

**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 `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.