Hedera Migrates HBAR Balance Reads to Mirror Nodes

Hedera has launched MirrorNodeAccountBalanceQuery, a new SDK-native tool that replaces AccountBalanceQuery. This update allows developers to read HBAR balances directly from Mirror Nodes without needing custom REST calls. The feature is available in JavaScript, Java, and Go, and it supports multiple account ID formats, including shard.realm.num, EVM addresses, public-key aliases, and contract IDs. Unlike its predecessor, MirrorNodeAccountBalanceQuery does not require HBAR payment and includes automatic retries for transient errors.

The migration to MirrorNodeAccountBalanceQuery is mandatory for applications using AccountBalanceQuery, as the consensus-node endpoint for the older query is throttled to zero on both testnet and mainnet starting from software release v0.77. Hedera emphasizes that the new query integrates seamlessly into existing workflows, reducing the need for custom REST or retry logic. Developers can migrate by replacing the AccountBalanceQuery import with MirrorNodeAccountBalanceQuery, maintaining the same execution pattern.

Hedera also notes that Mirror Nodes receive data from consensus nodes after a propagation delay, which can take several seconds. To address this, developers are advised to add a short retry or polling step when reading a balance immediately after a transaction or to rely on the transaction receipt. Testing the new method against a testnet account before deployment is recommended.