Recommended: MirrorNodeAccountBalanceQuery
MirrorNodeAccountBalanceQuery is the SDK-native replacement for the deprecated AccountBalanceQuery. 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 (MirrorNodeContractCallQuery, MirrorNodeContractEstimateQuery).
Key properties:
- Free: No query payment and no operator key signing.
- Automatic retries: Transient mirror node errors (5xx) and network timeouts are retried with exponential backoff using your existing client configuration.
- Flexible account references:
setAccountIdacceptsshard.realm.num, an EVM address (0x...), an account alias, or a contract ID. There is no separatesetContractId; all formats resolve throughsetAccountId.
MirrorNodeAccountBalance with a single hbars field. Token balances are not returned (see Token balances).
Basic usage
Querying by EVM address or account alias
The mirror node resolves EVM addresses and account aliases natively, with no additional resolution step:Behavioral differences from AccountBalanceQuery
The HBAR balance result is equivalent, but the behavior in edge cases differs. The first three points are the migration essentials; the last two come from the SDK implementation and matter for high-balance accounts and custom retry logic.
SDK Versions
MirrorNodeAccountBalanceQuery is available in:
- JavaScript (
@hiero-ledger/sdk): v2.87.0+ - Java: coming soon
- Go: coming soon
- Rust: not available
Token balances
MirrorNodeAccountBalanceQuery returns HBAR only. To read an account’s token balances, see Get account token balance.
Deprecated: AccountBalanceQuery
AccountBalanceQuery returns the balance from a single consensus node. It requires the client operator private key to sign the query. See the transaction and query fees table for the base fee, and the Hedera fee estimator to estimate the cost.
In Services release 0.50, returning token balance from the consensus node was deprecated with HIP-367. This query returns token information by requesting it from the Hedera Mirror Node APIs; token symbol is not returned in the response.