Module com.hedera.hashgraph.sdk

Package com.hedera.hashgraph.sdk

Class MirrorNodeAccountBalanceQuery

java.lang.Object

com.hedera.hashgraph.sdk.MirrorNodeAccountBalanceQuery

public final class MirrorNodeAccountBalanceQuery
extends Object

Get the HBAR balance of an account from the mirror node REST API (GET /api/v1/balances?account.id=...).

This is the replacement for AccountBalanceQuery, which relies on the consensus node CryptoService/cryptoGetBalance endpoint that the network is retiring.

The account may be identified by shard.realm.num, by an EVM address, or by a public key alias — the mirror node resolves all three. Contract IDs are also accepted; pass them through setAccountId(AccountId), as the balances endpoint supports them directly and no separate setter is needed.

Only the HBAR balance is returned. Token balances are not covered by this query.

An account the mirror node does not know fails with a PrecheckStatusException carrying Status.INVALID_ACCOUNT_ID, the same error AccountBalanceQuery reported. Note that the balances endpoint answers with an empty result rather than a 404, so this is the SDK's mapping of that empty result — not a status the mirror node itself returned.

Eventual consistency: the mirror node reflects network state with a small lag, typically a few seconds. Applications that need an immediate post-transaction balance must allow for it. The lag applies to the account's existence as well as to its balance: a freshly created account can transiently fail with Status.INVALID_ACCOUNT_ID until the mirror node has ingested it, so code that queries an account right after creating it should retry rather than treat the first failure as final.

This query is free.

Constructor Summary

Constructors

Constructor	Description
MirrorNodeAccountBalanceQuery()	Constructor.

Method Summary

Modifier and Type	Method	Description
MirrorNodeAccountBalance	execute(Client client)	Executes the query with the user supplied client.
MirrorNodeAccountBalance	execute(Client client, Duration timeout)	Executes the query with the user supplied client and timeout.
CompletableFuture<MirrorNodeAccountBalance>	executeAsync(Client client)	Executes the query asynchronously with the user supplied client.
CompletableFuture<MirrorNodeAccountBalance>	executeAsync(Client client, Duration timeout)	Executes the query asynchronously with the user supplied client and timeout.
AccountId	getAccountId()	Return the account's id.
int	getMaxAttempts()	Extract the maximum number of attempts.
Duration	getMaxBackoff()	Extract the maximum backoff duration.
MirrorNodeAccountBalanceQuery	setAccountId(AccountId accountId)	The ID of the account for which the balance is being requested.
MirrorNodeAccountBalanceQuery	setMaxAttempts(int maxAttempts)	Set the maximum number of attempts for the query.
MirrorNodeAccountBalanceQuery	setMaxBackoff(Duration maxBackoff)	Set the maximum backoff duration for retry attempts.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

MirrorNodeAccountBalanceQuery

public MirrorNodeAccountBalanceQuery()

Constructor.

Method Details

getAccountId

@Nullable
public AccountId getAccountId()

Return the account's id.

Returns:

accountId

setAccountId

public MirrorNodeAccountBalanceQuery setAccountId(AccountId accountId)

The ID of the account for which the balance is being requested.

Accepts shard.realm.num, an EVM address, or a public key alias. Contract IDs are also accepted — the balances endpoint resolves them, so no separate setter is needed; convert with new AccountId(contractId.shard, contractId.realm, contractId.num).

Parameters:

accountId - the account id to set

Returns:

this

getMaxAttempts

public int getMaxAttempts()

Extract the maximum number of attempts.

Returns:

the maximum number of attempts

setMaxAttempts

public MirrorNodeAccountBalanceQuery setMaxAttempts(int maxAttempts)

Set the maximum number of attempts for the query.

Parameters:

maxAttempts - the maximum number of attempts

Returns:

this

getMaxBackoff

public Duration getMaxBackoff()

Extract the maximum backoff duration.

Returns:

the maximum backoff duration

setMaxBackoff

public MirrorNodeAccountBalanceQuery setMaxBackoff(Duration maxBackoff)

Set the maximum backoff duration for retry attempts.

Parameters:

maxBackoff - the maximum backoff duration

Returns:

this

execute

public MirrorNodeAccountBalance execute(Client client)
                                 throws PrecheckStatusException,
ExecutionException,
InterruptedException

Executes the query with the user supplied client.

Parameters:

client - the client with which this will be executed

Returns:

the retrieved MirrorNodeAccountBalance

Throws:

PrecheckStatusException - with Status.INVALID_ACCOUNT_ID if the mirror node knows no such account

ExecutionException - if the query fails

InterruptedException - if the thread is interrupted

execute

public MirrorNodeAccountBalance execute(Client client,
 Duration timeout)
                                 throws PrecheckStatusException,
ExecutionException,
InterruptedException

Executes the query with the user supplied client and timeout.

Parameters:

client - the client with which this will be executed

timeout - the maximum duration for each individual HTTP request

Returns:

the retrieved MirrorNodeAccountBalance

Throws:

PrecheckStatusException - with Status.INVALID_ACCOUNT_ID if the mirror node knows no such account

ExecutionException - if the query fails

InterruptedException - if the thread is interrupted

executeAsync

public CompletableFuture<MirrorNodeAccountBalance> executeAsync(Client client)

Executes the query asynchronously with the user supplied client.

If the mirror node knows no such account the future completes exceptionally with a PrecheckStatusException carrying Status.INVALID_ACCOUNT_ID — surfaced as the cause of a CompletionException from join(), or of an ExecutionException from get().

Parameters:

client - the client with which this will be executed

Returns:

a future representing the retrieved MirrorNodeAccountBalance

executeAsync

public CompletableFuture<MirrorNodeAccountBalance> executeAsync(Client client,
 Duration timeout)

Executes the query asynchronously with the user supplied client and timeout.

If the mirror node knows no such account the future completes exceptionally with a PrecheckStatusException carrying Status.INVALID_ACCOUNT_ID — surfaced as the cause of a CompletionException from join(), or of an ExecutionException from get().

Parameters:

client - the client with which this will be executed

timeout - the maximum duration for each individual HTTP request

Returns:

a future representing the retrieved MirrorNodeAccountBalance

toString

public String toString()

Overrides:

toString in class Object