Get account balance

Get an account’s HBAR balance for free with MirrorNodeAccountBalanceQuery, the replacement for AccountBalanceQuery that accepts EVM addresses and aliases.

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.

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: 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).

Method	Type	Requirement
setAccountId(<accountId>)	AccountId | string	Required

Basic usage

JavaScript

//Create the mirror node account balance query
const balance = await new MirrorNodeAccountBalanceQuery()
    .setAccountId(accountId)
    .execute(client);

//Print the balance of hbars
console.log(balance.hbars.toString());

//v2.87.0

Querying by EVM address or account alias

The mirror node resolves EVM addresses and account aliases natively, with no additional resolution step:

JavaScript

//By EVM address
const balanceByEvm = await new MirrorNodeAccountBalanceQuery()
    .setAccountId("0x0000000000000000000000000000000000bc614e")
    .execute(client);

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

//By account alias
const balanceByAlias = await new MirrorNodeAccountBalanceQuery()
    .setAccountId("0.0.302a300506032b6570032100e0c8ec2758a5879ffac226a13c0c516b799e72e35141a905d7822d6526b870d")
    .execute(client);
console.log(balanceByAlias.hbars.toString());

//v2.87.0

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 accounts fail with INVALID_ACCOUNT_ID. The mirror node returns an empty array (HTTP 200) for an account it does not know, and each SDK reports that as INVALID_ACCOUNT_ID, matching the old AccountBalanceQuery:
  • JavaScript (v2.88.0+) throws a MirrorNodeStatusError whose status is INVALID_ACCOUNT_ID. Match on error.status, not on the error class. v2.87.0 returned hbars = 0 instead, which looks the same as a real account holding zero HBAR, so upgrade if you rely on this check.
  • Java throws a PrecheckStatusException with INVALID_ACCOUNT_ID.
  • Go returns an ErrHederaPreCheckStatus with INVALID_ACCOUNT_ID (see detecting a missing account).
• No setContractId: Pass contract IDs, EVM addresses, and account aliases through setAccountId.
• Precision (JavaScript before v2.89.0): JavaScript SDK v2.87.0 and v2.88.0 rounded balances above Number.MAX_SAFE_INTEGER tinybars. v2.89.0 fixed this. 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, do not retry a 4xx other than 408 and 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:

balance, err := hiero.NewMirrorNodeAccountBalanceQuery().
    SetAccountID(id).
    Execute(client)

// errors is the standard library package.
var pre hiero.ErrHederaPreCheckStatus
if errors.As(err, &pre) && pre.Status == hiero.StatusInvalidAccountID {
    // No such account on the mirror node.
}

Retry behavior by SDK

Each SDK retries transient failures automatically; the retried set differs slightly. In every SDK, a 4xx other than 408 and 429 is treated as a bad request and is not retried. The table reflects JavaScript v2.89.0+, Java v2.77.0+, and Go v2.85.0+.

Failure	JavaScript	Java	Go
Network timeout	Retried	Retried	Retried
408 (request timeout), 429 (rate limit)	Retried	Retried	Retried
500, 502, 503, 504	Retried	Retried	Retried
Other 5xx (for example 501, 505)	Not retried	Retried	Not retried
Other 4xx	Not retried	Not retried	Not retried

SDK Versions

MirrorNodeAccountBalanceQuery is available in:

• JavaScript (@hiero-ledger/sdk): v2.87.0+
• Java (com.hedera.hashgraph:sdk): v2.77.0+
• Go (github.com/hiero-ledger/hiero-sdk-go/v2): v2.84.0+
• Rust: not available

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 no longer works. It read the consensus node’s cryptoGetBalance query, which consensus node release v0.77 removed (testnet on September 15, 2026, mainnet on September 29, 2026). Current SDKs (JavaScript v2.89.0+, Java v2.78.0+, Go v2.85.1+) fail the call immediately with a deprecation error and never contact a node. Older SDK versions, and the Rust SDK, still send the query, and the network answers BUSY until the SDK runs out of retries.

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.

Method	Type	Description
setAccountId(<accountId>)	AccountID	The account ID to return the current balance for.
setContractId(<contractId>)	ContractID	The contract ID to return the current balance for.

Java

//Create the account balance query
AccountBalanceQuery query = new AccountBalanceQuery()
     .setAccountId(accountId);

//Sign with client operator private key and submit the query to a Hedera network
AccountBalance accountBalance = query.execute(client);

//Print the balance of hbars
System.out.println("The hbar account balance for this account is " +accountBalance.hbars);

//v2.0.0