Migrating from AccountBalanceQuery: What You Need to Know

The AccountBalanceQuery in the Hiero SDKs (and Hedera API) will be entirely removed in July 2026. A gradual throttle reduction begins in May 2026 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: 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}

Copy

Before (AccountBalanceQuery):

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

Copy

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;

Copy

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

Option 2: 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. Mirror Node REST API covers the vast majority of use cases today.

3. Test in testnet. The Mirror Node testnet endpoint is available at https://testnet.mirrornode.hedera.com/api/v1/balances?account.id={accountId}.

4. Deploy before May 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:

• 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

Office Hours: Monthly community calls and weekly Q&As

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 April 2026 at the current 40,000 rps throttle. However, starting migration early is strongly recommended.

What happens if migration is not completed by May?

Applications exceeding the reduced throttle limits will experience rate limiting. After July 2026, 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.