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. Eventual consistency and unknown-account handling are the migration essentials; the precision and retry notes 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.
  • Unknown-account handling differs by SDK. The mirror node returns an empty array (HTTP 200) for an account it does not know, and each SDK maps that differently:
    • JavaScript returns hbars = 0, which is indistinguishable from a real account that holds zero HBAR. Do not use a zero balance to infer that an account is missing.
    • Java throws INVALID_ACCOUNT_ID, matching the deprecated AccountBalanceQuery.
    • Go returns an INVALID_ACCOUNT_ID error, matching the deprecated AccountBalanceQuery (see detecting a missing account).
  • No setContractId: Pass contract IDs, EVM addresses, and account aliases through setAccountId.
  • Precision (JavaScript only): In the JavaScript SDK, balances above Number.MAX_SAFE_INTEGER lose precision silently. The Java (Hbar/long) and Go (Hbar/int64) SDKs are not affected.
  • Retry behavior: Transient failures are retried automatically with exponential backoff, so a wrapper retry loop is usually unnecessary. The exact retried set differs by SDK (see Retry behavior by SDK). In your own retry logic, never retry a 4xx other than 429: a 4xx means the request itself is invalid (for example, a malformed account ID) and will fail again.

Detecting a missing account in Go

The Go error is the same precheck-status error the deprecated AccountBalanceQuery returned, so you branch on its status:

Retry behavior by SDK

Each SDK retries transient failures automatically; the retried set differs. In every SDK, a plain 4xx (other than 429) is treated as a bad request and is not retried.

SDK Versions

MirrorNodeAccountBalanceQuery is available in: For Rust, 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.