Hedera AccountBalanceQuery Deprecation: The Critical Developer Migration Guide
Global, May 2025: The Hedera Governing Council has confirmed a significant network evolution: the AccountBalanceQuery is officially deprecated and will be fully removed in the July 2026 Consensus Node release (version 0.75). This decisive move pushes the Hedera developer ecosystem toward its modern data infrastructure, the Mirror Node REST API, with a structured, multi-phase transition beginning in May 2026. For developers building on one of the enterprise-grade public ledgers, understanding this timeline and its technical implications is now essential.
Hedera AccountBalanceQuery Deprecation: Understanding the Core Change
For years, the AccountBalanceQuery served as a primary method for applications to retrieve real-time account balance information directly from Hedera consensus nodes. This gRPC-based query was integral to wallets, explorers, and DeFi protocols. However, its design placed a direct computational load on the consensus layer, which is optimized for transaction ordering and validation, not high-volume data retrieval. The deprecation signals Hedera’s commitment to a more scalable and performant architecture by separating consensus duties from data querying. The network is directing all balance and historical data queries to the dedicated Mirror Node network, a layer specifically built for high-efficiency data serving.
The Official Timeline and Throttle Step-Down Schedule
Hedera has outlined a clear, developer-friendly transition period to prevent service disruption. The process is not an immediate shutdown but a gradual migration.
- May 2026: The first phase begins. Throttles (rate limits) on the AccountBalanceQuery will start to step down from consensus nodes. Developers will begin to experience reduced performance and reliability if they continue using the old query, serving as an early warning to complete migrations.
- July 2026: The final phase arrives with the release of Consensus Node software version 0.75. This release will completely remove support for the AccountBalanceQuery from the core network nodes. Any application still relying on it will fail to retrieve balance data, potentially causing broken functionality for end-users.
This 14-month lead time provides ample opportunity for development teams to audit their codebases, plan the migration, and implement changes. Proactive action is strongly advised to avoid a last-minute scramble.
Technical Implications for DApp and Service Architecture
This shift is more than a simple endpoint change; it represents a fundamental architectural migration. The Mirror Node REST API offers a different interaction model (RESTful HTTP vs. gRPC) and often returns data in a different structure. Developers must update their SDK implementations, error handling, and data parsing logic. Furthermore, while consensus nodes provide a single source of real-time truth, mirror nodes offer redundant, globally distributed endpoints with built-in historical data, enabling more robust and feature-rich applications. The move encourages developers to leverage the full historical query capabilities that were not possible with the simple AccountBalanceQuery.
Migrating to the Mirror Node REST API: A Practical Overview
The Mirror Node REST API is not a new service but a mature and capable replacement. It provides all the functionality of AccountBalanceQuery and significantly more. The primary endpoint for balance information shifts from a direct node query to a REST API call. For example, instead of calling a consensus node, an application will query a mirror node REST endpoint. This offers advantages like JSON responses, built-in pagination for accounts with many tokens, and seamless integration with historical balance data. Major Hedera SDKs, including the JavaScript and Java SDKs, are already updated or are being updated to facilitate this transition, abstracting much of the complexity for developers.
| Feature | AccountBalanceQuery (Legacy) | Mirror Node REST API (New) |
|---|---|---|
| Protocol | gRPC | REST (HTTP/HTTPS) |
| Data Source | Consensus Node | Mirror Node Network |
| Primary Use | Real-time balance only | Real-time & historical balances, transactions, states |
| Scalability | Limited by consensus node resources | Highly scalable, dedicated data layer |
| Network Impact | Adds load to consensus processing | Offloads query load, improves consensus efficiency |
Why This Change Matters for Hedera’s Long-Term Vision
This deprecation is a strategic step within Hedera’s broader roadmap to enhance network performance, stability, and enterprise readiness. By offloading query traffic to mirror nodes, the consensus layer can focus solely on achieving fast, fair, and secure transaction ordering—its core competency. This separation of concerns is a hallmark of scalable web2 architecture now being applied to public ledger technology. It paves the way for higher transaction throughput (TPS) and more predictable performance for core settlement, even as the number of data-intensive applications on the network grows exponentially.
Actionable Steps for Developers and Project Teams
Development teams should begin their migration process immediately. The recommended steps are:
- Inventory & Audit: Identify all instances where your application code, smart contracts (via precompiled calls), or services use the AccountBalanceQuery.
- Review Documentation: Study the official Hedera Mirror Node REST API documentation to understand the new endpoints, request formats, and response schemas.
- Update SDKs: Ensure you are using the latest version of your preferred Hedera SDK, which should include helper functions for the new API calls.
- Implement & Test: Replace the old query logic with calls to the Mirror Node API in a development or testnet environment. Hedera’s testnet mirror nodes are available for this purpose.
- Monitor & Deploy: After thorough testing, deploy the changes to production well ahead of the May 2026 throttle step-down.
Ignoring this timeline risks application failure and poor user experience. The Hedera community and foundation are providing resources, but the onus is on individual projects to execute the update.
Conclusion
The deprecation of the Hedera AccountBalanceQuery is a calculated and necessary evolution, not an endpoint removal in isolation. It underscores the network’s maturation from a foundational ledger to a scalable data platform. By migrating to the Mirror Node REST API, developers gain access to a more powerful, scalable, and feature-rich data layer while contributing to the overall efficiency and robustness of the Hedera network. With the July 2026 deadline firmly set, proactive migration is the only path forward for maintaining seamless and reliable application performance on one of the world’s leading enterprise DLT platforms.
FAQs
Q1: What exactly is being deprecated on Hedera?
A1: Hedera is deprecating and removing the specific gRPC query called “AccountBalanceQuery” from its consensus nodes. This is the method applications used to ask a node directly for an account’s HBAR and token balances.
Q2: What should developers use instead?
A2: Developers must migrate to using the Hedera Mirror Node REST API. This separate network layer is specifically designed for querying account balances, transaction history, and other blockchain data, offloading that work from the main consensus nodes.
Q3: When will the old query stop working completely?
A3: The AccountBalanceQuery will be fully removed from the network with the release of Consensus Node version 0.75, scheduled for July 2026. Its performance will begin degrading in May 2026 as rate limits are reduced.
Q4: Will this affect the speed of checking balances?
A4: The Mirror Node API is designed for high-performance data retrieval. While the network hop may differ, for most applications, the performance will be comparable or better, especially for queries involving historical data or pagination.
Q5: Is my existing Hedera wallet at risk?
A5: No, end-user wallets are not directly at risk. However, the wallet application or service you use must update its backend code to use the new Mirror Node API before the July 2026 deadline. Reputable wallet providers are already managing this transition.
Related News
- Aave Wants to Launch a Rival to MakerDAO’s DAI Stablecoin
- Binance Wallet TGE: Exclusive Opportunity for SGC Token Launch on June 13
- South Korean Crypto Exchange Fund: A Bold Regulatory Proposal for Market Reform
Related: Cardano Price Prediction: Analyzing ADA's Trajectory Amid Evolving Tech and Policy
Related: Nexo's Remarkable 52% Repeat Borrower Rate Signals Crypto Lending Surge
Related: Nigeria's 2026 Tax Laws: Bitcoin Holders Face Stiff 25% Capital Gains Levy
