---
title: "Get token balance(s)"
method: GET
path: "/tokens"
tags: ["Chain State"]
---

# Get token balance(s)

`GET /tokens`

Retrieve token balance(s) for one or more addresses at given block(s). Corresponds to the <a href="/chifra/chainstate/#chifra-tokens">chifra tokens</a> command line.

## Query parameters

- `addrs` string[], required
- `blocks` string[]
- `approvals` boolean
- `parts` string[]
- `byAcct` boolean
- `changes` boolean
- `noZero` boolean
- `chain` string
- `noHeader` boolean
- `cache` boolean
- `decache` boolean
- `fmt` string

## Response `200`

returns the requested data

- object
  - `data` union[] — Produces <a href="/data-model/accounts/#approval">Approval</a> or <a href="/data-model/chainstate/#token">Token</a> data. Corresponds to the <a href="/chifra/chainstate/#chifra-tokens">chifra tokens</a> command line.
    - union
      - Approval — an ERC-20 token approval granting spending permission from owner to spender
        - `allowance` string, wei — the amount of tokens approved for spending
        - `blockNumber` number — the current block number when the report was generated
        - `timestamp` number — the current timestamp when the report was generated
        - `date` string, datetime — the timestamp as a date (calculated)
        - `owner` string, address — the address of the owner of the token (the approver)
        - `spender` string, address — the address being granted approval to spend tokens
        - `token` string, address — the address of the ERC-20 token being approved
        - `lastAppBlock` number — the block number of the last approval event
        - `lastAppTs` number — the timestamp of the last approval event
        - `lastAppTxID` number — the transaction index of the last approval event
        - `lastAppLogID` number — the log index of the last approval event
      - Token — on-chain token-related data such as totalSupply, symbol, decimals, and individual balances for a given address at a given block
        - `blockNumber` number — the block at which the report is made
        - `transactionIndex` number — the transaction index (if applicable) at which the report is made
        - `timestamp` number — the timestamp of the block
        - `date` string, datetime — the timestamp as a date (calculated)
        - `totalSupply` string, int256 — the total supply of the token contract
        - `address` string, address — the address of the token contract
        - `holder` string, address — the holder address for which we are reporting
        - `priorBalance` string, int256 — the holder's asset balance at its prior appearance
        - `balance` string, int256 — the holder's asset balance at the given block height
        - `balanceDec` number, float — the holder's asset balance (in Ether) at the given block height (calculated)
        - `diff` string, int256 — the difference, if any, between the prior and current balance (calculated)
        - `name` string, string — the name of the token contract, if available
        - `symbol` string, string — the symbol of the token contract
        - `decimals` number — the number of decimals for the token contract
        - `type` object — the type of token (ERC20 or ERC721) or none

## Other responses

- `400` — bad input parameter

## Changes

- **2025-09-28** `4811465a7c75` — 5 warning, 6 info
  - removed the optional property `data/items/oneOf[#/components/schemas/approval]/address` from the response with the `200` status
  - removed the optional property `data/items/oneOf[#/components/schemas/approval]/addressName` from the response with the `200` status
  - removed the optional property `data/items/oneOf[#/components/schemas/approval]/amount` from the response with the `200` status
  - removed the optional property `data/items/oneOf[#/components/schemas/approval]/spenderName` from the response with the `200` status
  - …7 more
- **2025-09-26** `bfab37f3cd3f` — 2 breaking, 15 warning, 1 info
  - added `#/components/schemas/approval, #/components/schemas/token` to the `data/items/` response property `oneOf` list for the response status `200`
  - the `data/items/` response's property type/format changed from `object`/`` to ``/`` for status `200`
  - removed the optional property `data/items/address` from the response with the `200` status
  - removed the optional property `data/items/balance` from the response with the `200` status
  - …14 more
- **2025-03-27** `2f9b4968d332` — 1 breaking
  - the `data/items/balanceDec` response's property type/format changed from `number`/`float64` to `number`/`float` for status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/trueblocks/apis/trueblocks-api/changes/tokens/get.md)

---

[API](https://skmtc.dev/trueblocks/apis/trueblocks-api.md) · [All operations](https://skmtc.dev/trueblocks/apis/trueblocks-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trueblocks/trueblocks-api/revisions/2a176f1485a9/schema)