Migrating from AccountBalanceQuery: What You Need to Know

The AccountBalanceQuery in the Hiero SDKs (and Hedera API) will be entirely removed in Consensus Node release v0.77. A gradual throttle reduction begins in June 2026 with v0.74 to give developers time to transition. This post covers the rationale, timeline, and migration paths available today.

Why This Change?

Usage patterns over time have revealed scalability challenges with AccountBalanceQuery. Each call places a load directly on consensus nodes, pulling them away from their core job of processing transactions and reaching consensus. As the network grows, that trade-off becomes harder to justify.

Better alternatives already exist. Mirror Nodes and the upcoming Block Nodes are purpose-built for data queries, offering improved performance, lower costs, and no impact on consensus. This deprecation aligns with a broader architectural principle: consensus nodes handle consensus, and specialized infrastructure handles data access.

Deprecation Timeline

The throttle will be reduced gradually over six months:

This timeline applies equally to mainnet, testnet, and previewnet.

Migration Paths

Option 1: MirrorNodeAccountBalanceQuery in the SDKs (Available Now)

MirrorNodeAccountBalanceQuery is the SDK-native replacement for the deprecated query. It reads an account’s HBAR balance from the Mirror Node REST API (GET /api/v1/balances?account.id={id}) while keeping the familiar SDK query interface, and it follows the same convention already established for mirror node queries in the SDK.

Option 2: Mirror Node REST API (Available Now)

The Mirror Node REST API is production-ready and provides cost-effective access to account balances without burdening consensus nodes. Queries are free on the Hedera-hosted mirror node (subject to throttles), and commercial providers offer paid plans for higher volumes.

Endpoint:

GET https://mainnet.mirrornode.hedera.com/api/v1/balances?account.id={accountId}

Before (AccountBalanceQuery):

const query = new AccountBalanceQuery()
    .setAccountId(accountId);
const balance = await query.execute(client);

After (Mirror Node REST API):

const response = await fetch(
    `https://mainnet.mirrornode.hedera.com/api/v1/balances?account.id=${accountId}`
);
const data = await response.json();
const balanceInTinybars = data.balances[0].balance;

Mirror Nodes also support token balance queries via the /api/v1/accounts/{accountId}/tokens endpoint.

Option 3: Block Nodes and Block Streams (Coming Soon)

For applications that require real-time balance updates, Block Streams offers an event-driven alternative. Based on HIP-1056 and HIP-1081, Block Streams unify Hedera’s event, record, and sidecar streams into a single, efficient, verifiable data stream. Developers will be able to subscribe and filter for only the changes they care about.

Block Nodes are actively under development. In the meantime, the Mirror Node REST API is the recommended path forward.

How to Migrate

1. Audit your codebase. Search for AccountBalanceQuery and .getAccountBalance() to identify every call site.

2. Choose a migration path. The alternatives above provide parity and help you cover the vast majority of use cases today.

3. Test in testnet. Try the MirrorNodeAccountBalanceQuery in the SDKs. Similarly, the Mirror Node testnet endpoint is available at https://testnet.mirrornode.hedera.com/api/v1/balances?account.id={accountId}.

4. Deploy before June 2026. Completing the migration before the first throttle reduction reduces the risk of rate limiting.

5. Remove deprecated references. Clean up all AccountBalanceQuery usage once the new integration is confirmed.

Get Support & Start Today

Experts and contributors across the ecosystem are available to help throughout this transition. The following resources are available to support you:

Documentation & Articles:

• Get account balances
• Mirror Node REST API Reference
• Balance Endpoints
• Querying Data on Hedera: SDK vs Mirror Node REST API

Discord: Ask migration questions in the developer channels

Hedera Developer Playground: Try this example and see how to query account balances with the Mirror Node REST API.

Start planning your migration today. For the latest updates, visit docs.hedera.com.

FAQs

Can applications still use AccountBalanceQuery today?

Yes. It remains fully functional through June 2026 at the 40,000 rps throttle. However, starting migration early is strongly recommended.

What happens if migration is not completed by June?

Applications exceeding the reduced throttle limits will experience rate limiting. After v0.77, all AccountBalanceQuery requests will fail.

Will Mirror Nodes have the same throttle limitations?

No. Mirror Nodes are designed for high-throughput query workloads. The Hedera-hosted mirror node offers free queries with specific throttles, and commercial providers offer higher limits through paid plans.

Is there a cost difference?

AccountBalanceQuery is currently free but burdens consensus nodes. Mirror Node REST API queries are also free (with throttles) on the Hedera-hosted mirror node and have no impact on consensus.

.elementor-5381 .elementor-element.elementor-element-18f2aab > figure {margin-top: 20px;margin-bottom:20px;}