Introducing MirrorNodeAccountBalanceQuery: The SDK-Native Migration Path for AccountBalanceQuery

This post supplements Migrating from AccountBalanceQuery: What You Need to Know, which covers the full deprecation timeline and migration rationale. Read that first for background.

MirrorNodeAccountBalanceQuery is available now in the JavaScript, Java, and Go Hiero SDKs, giving developers a native way to read an account’s HBAR balance from the Mirror Node REST API without leaving the SDK’s familiar query interface. The new method replaces AccountBalanceQuery, giving developers a first-class SDK method to read balances from the mirror node without hand-rolling REST calls or retry logic themselves. Adopting requires no new dependencies or client configuration changes.

Motivation

Mirror nodes have always exposed account balance data through their REST API, and SDK clients already hold a connection to a mirror network. MirrorNodeAccountBalanceQuery extends the SDK’s native query interface to that data, using the same fluent, typed pattern developers use for every other SDK query. It follows the same convention already established for mirror node queries in the SDK, including MirrorNodeContractCallQuery and MirrorNodeContractEstimateQuery.

What MirrorNodeAccountBalanceQuery Does

MirrorNodeAccountBalanceQuery fetches an account’s HBAR balance from the mirror node’s GET /api/v1/balances endpoint and returns it through the same AccountBalance-style result developers already expect. 

Key properties:

• Free. No query payment and no HBAR required to execute it.
• Automatic retries. Transient mirror node errors (5xx responses and network failures) are retried with exponential backoff, using the client’s existing timeout and retry configuration.
• Flexible ID formats. Accepts shard.realm.num, an EVM address, a public key alias, or a contract ID, all through the same setAccountId method. The mirror node resolves every format natively, extending that same flexibility to account lookups made through the SDK.

Migrating in 60 Seconds

For the JavaScript SDK, the change is two lines:

// Before
import { AccountBalanceQuery } from "@hiero-ledger/sdk";

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

console.log(balance.hbars.toString());

// After
import { MirrorNodeAccountBalanceQuery } from "@hiero-ledger/sdk";

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

console.log(balance.hbars.toString());

The same pattern applies in Java and Go, using each SDK’s equivalent import. Java developers reading a contract’s balance pass the contract’s shard, realm, and number through AccountId directly, since MirrorNodeAccountBalanceQuery does not expose a separate contract setter:

// Go
balance, err := hiero.NewMirrorNodeAccountBalanceQuery().
    SetAccountID(accountID).
    Execute(client)

Rust, Swift, and C++ developers can read the same data by calling the mirror node’s GET /api/v1/balances endpoint directly through the client’s mirror network configuration.

Action Required

AccountBalanceQuery’s consensus node endpoint is throttled to zero on testnet and mainnet as of release v0.77 of Consensus Node software, as covered in the companion migration guide linked above, so this migration is not optional for applications that depend on it. Developers currently calling AccountBalanceQuery in the JavaScript, Java, or Go SDKs need to migrate to MirrorNodeAccountBalanceQuery:

1. Update to a recent SDK release: @hiero-ledger/sdk for JavaScript/TypeScript, or the equivalent Java and Go SDK packages.
2. Replace AccountBalanceQuery with MirrorNodeAccountBalanceQuery and remove any separate contract-ID setter call, passing contract IDs through setAccountId instead.
3. Add a short retry or poll, or rely on the transaction receipt, anywhere the application reads a balance immediately after submitting a transaction, since propagation from the Consensus nodes to the Mirror nodes requires a few seconds.

Applications that are not currently calling AccountBalanceQuery are not affected.

SDK Availability

AccountBalanceQuery is deprecated in favor of MirrorNodeAccountBalanceQuery and the mirror node REST API, as outlined in the companion migration guide linked above.

Next Steps

Update to the latest SDK release for the language in use and try MirrorNodeAccountBalanceQuery against a testnet account to confirm it fits the application’s balance-reading logic before rolling it out more broadly.

• SDK reference: MirrorNodeAccountBalanceQuery
• Mirror Node REST API: List Account Balances
• Migrating from AccountBalanceQuery: What You Need to Know
• @hiero-ledger/sdk on npm