Get account token balance

Get an account’s token balances on Hedera for free with MirrorNodeTokenBalanceQuery or the Mirror Node REST API. AccountBalanceQuery stopped working with consensus node release v0.77.

A query that returns the balance an account holds in a token. Token balances are read from a mirror node, either through MirrorNodeTokenBalanceQuery in the SDK or directly from the Mirror Node REST API. Both are free and do not need an operator account.

Recommended: MirrorNodeTokenBalanceQuery

MirrorNodeTokenBalanceQuery reads an account’s token relationships from the Mirror Node REST API (GET /api/v1/accounts/{id}/tokens) through the SDK’s query interface. It is the SDK replacement for the token balances that AccountBalanceQuery used to return. For HBAR balances, use MirrorNodeAccountBalanceQuery.

• Free: No query payment and no operator key signing.
• Smallest unit: For fungible tokens, balance is in the token’s smallest denomination. Divide by 10^decimals to get the display amount: a balance of 1234 with decimals of 2 is 12.34 tokens. For NFT collections, balance is the number of NFTs the account holds.
• Flexible account references: setAccountId accepts 0.0.<num>, an EVM address (0x...), or a contract ID. The mirror node resolves all of them.

Method	Type	Requirement
setAccountId(<accountId>)	AccountId	Required
setTokenId(<tokenId>)	TokenId	Required in JavaScript and Java. Optional in Go: leave it unset to list every token the account holds.
SetNextPage(<next>)	string	Go only. Optional. The Next cursor from the previous page. Cannot be combined with SetAccountID or SetTokenID.

Basic usage

JavaScript

//Create the mirror node token balance query
const tokenBalance = await new MirrorNodeTokenBalanceQuery()
    .setAccountId(accountId)
    .setTokenId(tokenId)
    .execute(client);

//Print the balance in the token's smallest unit and the token's decimals
console.log(`${tokenBalance.tokenId}: ${tokenBalance.balance} (decimals: ${tokenBalance.decimals})`);

//v2.89.0

List every token an account holds (Go)

In Go, leave SetTokenID unset to read all of the account’s token relationships, up to 100 per page. Follow the Next cursor until it is empty:

page, err := hiero.NewMirrorNodeTokenBalanceQuery().
    SetAccountID(accountId).
    Execute(client)
for err == nil {
    for _, token := range page.Tokens {
        fmt.Printf("%v: %d (decimals: %d, KYC: %s, freeze: %s)\n",
            token.TokenID, token.Balance, token.Decimals, token.KycStatus, token.FreezeStatus)
    }
    if page.Next == "" {
        break
    }
    page, err = hiero.NewMirrorNodeTokenBalanceQuery().
        SetNextPage(page.Next).
        Execute(client)
}
if err != nil {
    panic(err)
}

//v2.85.0

The JavaScript and Java SDKs return one token per query. To list every token an account holds in those SDKs, call the Mirror Node REST API directly.

In the JavaScript SDK, MirrorNodeTokenBalanceQuery shipped as a single-token query before the cross-SDK design (sdk-collaboration-hub#281) was final. That design is still under review, and the SDK notes that the query’s shape may change once it is accepted, so check the release notes when you upgrade.

Behavior by SDK

The three SDKs report a missing token relationship and an unknown account differently:

Case	JavaScript	Java	Go
Account holds the token	balance and decimals	balance, decimals, and isAssociated() returns true	One entry in Tokens
Account is not associated with the token	balance is 0 and decimals is 0	balance is 0, decimals is null, and isAssociated() returns false	Tokens is empty
Mirror node does not know the account	Throws MirrorNodeStatusError with status INVALID_ACCOUNT_ID	No error: balance is 0 and isAssociated() returns false	Returns ErrHederaPreCheckStatus with status INVALID_ACCOUNT_ID

• Eventual consistency: The mirror node ingests blocks a few seconds after consensus. A balance read right after a transfer, or a query for a newly created account, can return the pre-transaction state. Poll until the balance changes, or rely on the transaction receipt for confirmation.
• Java and unknown accounts: In Java, a mistyped or not-yet-ingested account ID reads as “not associated” instead of failing. Do not treat isAssociated() == false as proof that the account exists.
• JavaScript decimals: When the account is not associated, decimals is 0 because the mirror node response does not include it. Read decimals from the token itself if you need them in that case.

Mirror Node REST API

The SDK query calls this endpoint, and you can call it directly from any language, including Rust. Add token.id to return a single token, or leave it out to list every token the account holds:

curl "https://testnet.mirrornode.hedera.com/api/v1/accounts/0.0.1234/tokens?token.id=0.0.5678"

{
  "tokens": [
    {
      "automatic_association": false,
      "balance": 1250,
      "created_timestamp": "1791993803.714558718",
      "decimals": 2,
      "token_id": "0.0.5678",
      "freeze_status": "NOT_APPLICABLE",
      "kyc_status": "NOT_APPLICABLE"
    }
  ],
  "links": {
    "next": null
  }
}

• The response lists only tokens the account is associated with. An unassociated token returns an empty tokens array.
• An unknown account returns HTTP 404.
• When listing every token, follow links.next until it is null.

See the Get token relationships info for an account reference for every parameter.

SDK versions

MirrorNodeTokenBalanceQuery is available in:

• JavaScript (@hiero-ledger/sdk): v2.89.0+
• Java (com.hedera.hashgraph:sdk): v2.78.0+
• Go (github.com/hiero-ledger/hiero-sdk-go/v2): v2.85.0+
• Rust: not available. Use the Mirror Node REST API.

HBAR balances

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

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

For token balances, use MirrorNodeTokenBalanceQuery (above) or the Mirror Node REST API.

📚 For the full migration guide, read: Migrating from AccountBalanceQuery: What You Need to Know