Skip to main content
A query that returns an account’s HBAR balance. Requesting a balance is free of charge and does not change account state or require network consensus. 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: setAccountId accepts shard.realm.num, an EVM address (0x...), an account alias, or a contract ID. There is no separate setContractId; all formats resolve through setAccountId.
It returns a 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.
  • Eventual consistency. The mirror node ingests blocks asynchronously a few seconds after consensus, so a balance read immediately after getReceipt() may still show the pre-transaction value. Poll until the balance changes, or rely on the transaction receipt for confirmation rather than a balance read. (The SDK source describes the result as not read-after-write consistent.)
  • Non-existent account returns hbars = 0, not a thrown INVALID_ACCOUNT_ID error. The mirror node returns an empty array for unknown accounts rather than a 404. If your code catches that error to detect a missing account, check for a zero balance instead.
  • No setContractId. Pass contract IDs, EVM addresses, and account aliases through setAccountId.
  • Precision. In the JavaScript SDK, balances above Number.MAX_SAFE_INTEGER lose precision silently. Account for this on very high-balance accounts.
  • Error handling asymmetry. 5xx responses and network timeouts are retried with exponential backoff, but 4xx responses throw immediately. If you wrap this query in your own retry logic, do not retry on 4xx.

SDK Versions

MirrorNodeAccountBalanceQuery is available in: For Rust, and for Java and Go until those ship, read HBAR balances from the Mirror Node REST API directly.

Token balances

MirrorNodeAccountBalanceQuery returns HBAR only. To read an account’s token balances, see Get account token balance.

Deprecated: AccountBalanceQuery

AccountBalanceQuery reads the consensus node’s cryptoGetBalance query, which is being throttled to zero as part of its deprecation. It has been throttled to zero on testnet (August 13, 2026) and is scheduled for mainnet on September 9, 2026 (consensus node release 0.77, an estimate subject to change). After removal, AccountBalanceQuery will no longer function. Migrate to MirrorNodeAccountBalanceQuery (above) or the Mirror Node REST API.📚 For the full migration guide, read: Migrating from AccountBalanceQuery: What You Need to Know
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.