---
title: "Get balances by time of addresses"
method: GET
path: "/v4/data/wallet/balance/time"
tags: ["Wallet API"]
---

# Get balances by time of addresses

`GET /v4/data/wallet/balance/time`

/v4/data/wallet/balance/time

**100 credits per API call**

Get native balances for a specific wallet addresses by time on the following blockchains:

*   Ethereum - ethereum-mainnet
*   Bitcoin - bitcoin-mainnet
*   Base - base-mainnet
*   Arbitrum - arb-one-mainnet
*   BSC - bsc-mainnet
*   Polygon - polygon-mainnet
*   Optimism - optimism-mainnet
*   Berachain - berachain-mainnet
*   Unichain - unichain-mainnet
*   Celo - celo-mainnet
*   Avalanche - avax-mainnet
*   Gnosis - gno-mainnet
*   zkSync - zksync-mainnet
*   Rootstock - rsk-mainnet
*   Ethereum Classic - ethereum-classic-mainnet
*   Lisk - lisk-mainnet
*   XDC - xdc-mainnet
*   Sonic - sonic-mainnet

To get started, provide a chain name, comma-separated list of addresses and specify one of the filters listed below (combination of the filters is not allowed):

*   block number
*   time
*   unix

If you pass a block number that is in the future (beyond the current latest block), the system will return the balance for the latest block.

If you pass a time or Unix timestamp that is in the future, the system will also return the balance for the latest block.

If you pass a time or Unix timestamp in the past (dating back to or earlier than the blockchain's genesis block), the system will return the balance for the first block (genesis block).

## Query parameters

- `chain` 'ethereum-mainnet' | 'bitcoin-mainnet' | 'base-mainnet' | 'arb-one-mainnet' | 'bsc-mainnet' | 'polygon-mainnet' | 'optimism-mainnet' | 'berachain-mainnet' | 'unichain-mainnet' | 'celo-mainnet' | 'avax-mainnet' | 'gno-mainnet' | 'zksync-mainnet' | 'rsk-mainnet' | 'ethereum-classic-mainnet' | 'lisk-mainnet' | 'xdc-mainnet' | 'sonic-mainnet', required
- `addresses` string, required — Wallet address
- `blockNumber` number
- `time` string
- `unix` number

## Response `200`

OK

- object
  - `result` NativeTokenBalance[] — List of all balances for all selected tokens.
    - `chain` string, required — Name of the chain.
    - `type` 'native' | 'fungible' | 'nft' | 'multitoken', required — Enum representing the type of token.
    - `address` string, required
    - `balance` string, required
    - `denominatedBalance` string, required
    - `decimals` number, required
  - `prevPage` string — Cursor pagination, used to get previous page of results (work in progress, not used right now).
  - `nextPage` string — Cursor pagination, used to get next page of results (work in progress, not used right now).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/revisions/8622ee4b8fae/schema)