OptionalrequestTimeout: numbertotal timeout for the whole
operation in milliseconds, every retry included; defaults to the
retry policy's totalDeadline, which in turn defaults to
client.requestTimeout
Set the account whose token balance to read.
Set the token to read the balance of. Required.
Mirror-node REST query for a single token balance held by an account.
AccountBalanceQueryused to return every token balance alongside the HBAR balance, andAccountInfoQuery.tokenRelationshipsis deprecated as of HIP-367 (and truncated at 1000 relationships), so this is the supported way to read a token balance.Reads
GET /api/v1/accounts/{id}/tokens?token.id={tokenId}through the client's shared HTTP transport: a single request, scoped to one token, so there is no pagination to walk. Pure HTTP: no query payment, no node rotation, no gRPC, so this class deliberately does not extendQuery. Retry, backoff and timeouts follow the client'sMirrorNodeHttpRetryPolicy(seeClient.setMirrorNodeHttpConfig).Both
setAccountIdandsetTokenIdare required.NOTE ON STABILITY: the cross-SDK proposal for this query (hiero-ledger/sdk-collaboration-hub#281) is still under review, and its current draft returns a page with a cursor and an optional token filter rather than a single balance. This single-token form is shipping now to meet the consensus node release 0.77 cutoff, so this API may change once that proposal is finalized.
An account the mirror node does not know throws a MirrorNodeStatusError carrying Status.InvalidAccountId, matching
MirrorNodeAccountBalanceQuery. An account that exists but holds no relationship with the token returns a zero balance with zero decimals, since the decimals are not knowable from that response.NOTE ON CONSISTENCY: the mirror node ingests consensus state asynchronously and typically lags the network by a few seconds. Results are therefore NOT read-after-write consistent: a balance read immediately after a transfer may still show the pre-transfer value.