Historical Balances
Understanding how wallet balances have changed over time is essential for tax reporting, auditing, and portfolio tracking.
Tatum’s Get Historical Wallet Balances endpoint lets you fetch the native token balance of one or more addresses at a specific block or timestamp.
Get Historical Balances (Popular🔥)
GET /v4/data/wallet/balance/time
Retrieve historical wallet balances at a specific timestamp.
Explore Docs →
Example cURL Request to get historical balances
curl --request GET \
--url 'https://api.tatum.io/v4/data/wallet/balance/time?chain=ethereum-mainnet&addresses=0x80d8bac9a6901698b3749fe336bbd1385c1f98f2%2C0xAe680Ed83baF08a8028118Bd19859F8a0E744cc6' \
--header 'accept: application/json' \
--header 'x-api-key: YOUR_API_KEY'
const options = {
method: 'GET',
headers: {
accept: 'application/json',
'x-api-key': 'YOUR_API_KEY'
}
};
fetch('https://api.tatum.io/v4/data/wallet/balance/time?chain=ethereum-mainnet', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
Sample Response
{
"result": [
{
"chain": "ethereum-mainnet",
"address": "0x80d8bac9a6901698b3749fe336bbd1385c1f98f2",
"balance": "0",
"lastUpdatedBlockNumber": 16499510,
"type": "native"
},
{
"chain": "ethereum-mainnet",
"address": "0xAe680Ed83baF08a8028118Bd19859F8a0E744cc6",
"balance": "0.036638040392209662",
"lastUpdatedBlockNumber": 16499510,
"type": "native"
}
],
"prevPage": "",
"nextPage": ""
}
Historical Balances - FAQs
What does the Historical Balances API do?
The Historical Balances endpoint lets you fetch a wallet’s native coin balance at a specific past date or block height. This is critical for tax reporting, portfolio performance tracking, reconciliation of old records, and audits that require end-of-period snapshots.
Which blockchains are supported for historical balances?
Tatum supports historical balance queries on all chains that maintain account or UTXO-based ledgers in our indexer — including Ethereum, Bitcoin, Polygon, BSC, Solana, Tron, Litecoin, and others. For each, you can query by timestamp or block number back to its genesis block.
Can I get historical balances for tokens or NFTs as well?
The historical balance API focuses on native assets (like ETH, BTC, MATIC). To reconstruct historical token or NFT balances, pair this endpoint with Transaction History to replay token transfers up to the target date. This combination is often used in capital-gains tax reports.
How do I request a balance at a specific point in time?
Pass either a timestamp (UTC) or a blockHeight
along with the wallet address to the endpoint.
For example, to get an end-of-fiscal-year snapshot, use
timestamp=2024-12-31T23:59:59Z.
The response shows the wallet’s native balance at that moment.
How accurate is the timestamp-based query compared to block-based?
Timestamp queries resolve to the closest block mined before or at that timestamp,
so they are block-level accurate.
If you need precise reconciliation with a known block height (e.g. after a specific transaction),
use the blockHeight parameter directly.
How do I convert historical balances to fiat value for reports?
Use the Exchange Rate API to fetch crypto-to-fiat rates for the relevant date (if available), or use archived price data from your own store. Multiply the historical crypto balance by the corresponding fiat rate to produce capital-gains or end-of-period portfolio valuations.
What are best practices for historical balance queries?
- Use block-based queries for precise reconciliation.
- Batch multiple addresses in one call when possible.
- Cache repeated snapshots for performance and cost savings.
- Pair with Transaction History to explain balance changes.
Practical Use Cases
-
Track Historical Portfolio Value
Determine wallet balances at any point in time to calculate asset growth or historical holdings. -
Audit & Compliance
Verify that balances at specific blocks match reported transactions for auditing purposes. -
Tax Reporting
Accurately compute capital gains or losses by fetching balances at key dates or block numbers.
By integrating this endpoint, you can reconstruct wallet balances over time, enabling precise auditing, compliance, and portfolio analysis workflows.
Updated 17 days ago