Balances

Overview

The Balances endpoints in the Hedera Mirror Node REST API allows developers to query account balances on the Hedera network. These endpoints provides real-time and historical balance data, essential for wallets, explorers, and financial applications.

Endpoints

The following endpoint is available for the Balances object:

Endpoint	Description
GET /api/v1/balances	Retrieves a list of account balances.

Balances

The balance object represents the balance of accounts on the Hedera network. You can retrieve this to view the most recent balance of all the accounts on the network at that given time. The balances object returns the account ID and the balance in HBAR. Balances are checked on a periodic basis and thus return the most recent snapshot of time captured prior to the request.

The balance object represents the balance of accounts on the Hedera network. It allows you to retrieve the most recent snapshot of all account balances on the network at a given time. Since balances are updated periodically, the returned values reflect the latest recorded state before the request.

Each balance object includes:

• Account ID – The Hedera account being queried.

• Balance (in HBAR) – The most recent balance available.

• Token Balances (if applicable) – Associated token balances for the account.

Note

Balance information returned by this API has a 15 minute granularity when using the timestamp query parameter, as it's generated by an asynchronous balance snapshot process. When not using the timestamp parameter, the API returns real-time balance data.

List account balances

get

Returns a list of account and token balances on the network. Balance information returned by this API has a 15 minute granularity as it's generated by an asynchronous balance snapshot process. This information is limited to at most 50 token balances per account as outlined in HIP-367. As such, it's not recommended for general use and we instead recommend using either /api/v1/accounts/{id}/tokens or /api/v1/tokens/{id}/balances to obtain the current token balance information and /api/v1/accounts/{id} to return the current account balance.

Query parameters

account.idstringOptional

Account id or account alias with no shard realm or evm address with no shard realm

Example: {"value":"HIQQEXWKW53RKN4W6XXC4Q232SYNZ3SZANVZZSUME5B5PRGXL663UAQA"}Pattern: ^(\d{1,10}\.){0,2}(\d{1,10}|(0x)?[A-Fa-f0-9]{40}|(?:[A-Z2-7]{8})*(?:[A-Z2-7]{2}|[A-Z2-7]{4,5}|[A-Z2-7]{7,8}))$

account.balancestringOptional

The optional balance value to compare against

Example: {"summary":"--","value":""}Pattern: ^((gte?|lte?|eq|ne)\:)?\d{1,10}$

account.publickeystringOptional

The account's public key to compare against

Example: 3c3d546321ff6f63d701d2ec5c277095874e19f4a235bee1e6bb19258bf362be

limitinteger · int32 · min: 1 · max: 100Optional

The maximum number of items to return

Default: 25Example: 2

orderundefined · enumOptional

The order in which items are listed

Default: descExample: ascPossible values:

timestampstring[]Optional

The consensus timestamp as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See unixtimestamp.com for a simple way to convert a date to the 'seconds' part of the Unix time.

Example: {"summary":"--","value":""}

Responses

200

OK

application/json

400

Invalid parameter

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/balances HTTP/1.1
Host: 
Accept: */*

{
  "timestamp": "1586567700.453054000",
  "balances": [
    {
      "account": "0.15.10",
      "balance": 80,
      "tokens": [
        {
          "token_id": "0.0.200001",
          "balance": 8
        }
      ]
    }
  ],
  "links": {
    "next": null
  }
}

Response Details

Response Item	Description
timestamp	The seconds.nanoseconds of the timestamp at which the list of balances for each account are returned
balances	List of balances for each account
account	The ID of the account
balance	The balance of the account
tokens	The tokens that are associated to this account
tokens.token_id	The ID of the token associated to this account
tokens.balance	The token balance for the specified token associated to this account
links.next	Hyperlink to the next page of results

Optional Filtering

Operator	Example	Description
lt (less than)	/api/v1/balances?account.id=lt:0.0.1000	Returns the balances of account IDs less than 1,000
lte (less than or equal to)	/api/v1/balances?account.id=lte:0.0.1000	Returns the balances account IDs less than or equal to 1,000
gt (greater than)	/api/v1/balances?account.id=gt:0.0.1000	Returns the balances of account IDs greater than to 1,000
gte (greater than or equal to)	/api/v1/balances?account.id=gte:0.0.1000	Returns the balances of account IDs greater than or equal to 1,000
order (order asc or desc values)	/api/v1/balances?order=asc ​ /api/v1/balances?order=desc	Lists balances in ascending order ​ Lists balances in descending order

Additional Examples

Example Requests	Description
/api/v1/balances?account.id=0.0.1000	Returns balance for account ID 1,000
/api/v1/balances?account.balance=gt:1000	Returns all account IDs that have a balance greater than 1000 tinybars
/api/v1/balances?timestamp=1566562500.040961001	Returns all account balances referencing the latest snapshot that occurred prior to 1566562500 seconds and 040961001 nanoseconds
/api/v1/balances?account.publickey=2b60955bcbf0cf5e9ea880b52e5b6 3f664b08edf6ed15e301049517438d61864	Returns balance information for 2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed 15e301049517438d61864 public key