Balances API Documentation
This section covers how to fetch balance-related data on Ethereum via Bitquery GraphQL APIs and Streams.
To get started, signup with Bitquery and get your Access Token by following these steps.
If you need help getting balance data, reach out to support.
Modes Supported
- GraphQL API
- GraphQL Stream
- Kafka Stream
Primary APIs
| API | Documentation | Description |
|---|---|---|
| Balances | Address Balance API | Current and historical token balances for wallet addresses (EVM.Balances). |
| Holders | Token Holders API | Top holders, holder counts, and holder activity (EVM.Holders). |
| TransactionBalances | Transaction Balance Tracker | Per-transaction balance updates with supply, market cap, reason codes, and streams (EVM.TransactionBalances). |
What is the Balance API?
On Ethereum, use the Balances cube for address-level balances and the Holders cube for token holder lists and counts. Both support dataset: combined (realtime + archive) and dataset: archive (historical and inactive addresses).
See the Address Balance API, Token Holders API, and Transaction Balance Tracker for queries and IDE examples.
The Transaction Balance Tracker section also covers validator, miner, MEV, gas, NFT, and self-destruct balance tracking.
When to Use Which API or Stream?
| Use Case | API/Stream | Description |
|---|---|---|
| Latest wallet balances | Balances API | Token balances for an address (dataset: combined; use Amount(selectWhere: { gt: "0" }) for non-zero). |
| Balance on a date | Balances API | Point-in-time snapshot with Block.Date.till (dataset: archive). |
| Wallet balance for one token on a date | Balances API | Block.Date, limit: 1, orderBy: Block_Date. |
| Balance history over time | Balances API | Snapshots ordered by Block_Date. |
| Top token holders | Holders API | orderBy: Balance_Amount, limit. |
| Token holder count | Holders API | uniq(of: Holder_Address) with dataset: combined. |
| Holders above a threshold | Holders API | uniq with if: { Balance: { Amount: { gt: "..." } } } }. |
| Token balance with supply and market cap | Transaction Balance Tracker | EVM.TransactionBalances — post balance, supply, USD value per transaction. |
| Real-time balance change streams | Transaction Balance Tracker | Subscribe to balance updates with reason codes. |
| Validator / miner / MEV balance tracking | Transaction Balance Tracker | Specialized trackers for rewards and MEV. |