Skip to content

/wallet/getaccountbalance

Query an account's TRX balance at a specific block (block-anchored).

  • Source: framework/src/main/java/org/tron/core/services/http/GetAccountBalanceServlet.java
  • Method: POST
  • Request: protocol.AccountBalanceRequest (balance_contract.proto)
  • Response: protocol.AccountBalanceResponse (balance_contract.proto)

Request parameters

Field Type Required Description
account_identifier.address string Yes Account address
block_identifier.hash string Yes Block hash
block_identifier.number int64 No Block number; omitted defaults to 0. It may be omitted only for the genesis block; for other blocks it must match block_identifier.hash
visible bool No Address format

Example:

curl --request POST \
     --url https://nile.trongrid.io/wallet/getaccountbalance \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_identifier": { "address": "41dd791d6b49e190062d650e6a23c575510d35f2f9" },
  "block_identifier": {
    "hash": "0000000003fe262d52bfa4b2814f816fd2e57af5b98a33d60d8630a03a908e0e",
    "number": 66987565
  }
}
'

Response

Field Type Description
balance int64 Latest recorded account balance at or before the requested block (sun); accuracy depends on the node's history coverage
block_identifier object Hash/number of the returned balance record, or the requested block when no record is found

Response example (Nile returns block_identifier as the most recent block in which the node tracked this account's balance, which may differ from the anchor in the request):

{
  "balance": 1793227200,
  "block_identifier": {
    "hash": "0000000003fe25c69a3321cd009c484efe62b11abf0f8966fc81c1ff4a917cad",
    "number": 66987462
  }
}

Accurate results require the node to have recorded the relevant balance history. storage.balance.history.lookup = true (equivalent to the --history-balance-lookup startup flag) enables recording; the query itself reads existing records regardless of the current setting. Disabling recording leaves earlier records queryable and can produce a stale balance for a later requested block. Enabling or re-enabling it does not backfill missing history. When no record is found at or before the requested block, the response echoes the request's block_identifier and returns balance: 0; this does not prove that the account actually had a zero balance.

Error responses

Trigger Response
Request body exceeds node.http.maxMessageSize Usually HTTP 413 Payload Too Large when rejected by SizeLimitHandler
Request body is not valid JSON / field type mismatch {"Error": "class org.tron.json.JSONException : <parser info>"} or {"Error": "class org.tron.core.services.http.JsonFormat$ParseException : <decoder info>"}
account_identifier missing {"Error": "class java.lang.IllegalArgumentException : account_identifier is null"}
account_identifier.address missing {"Error": "class java.lang.IllegalArgumentException : account_identifier address is null"}
block_identifier missing {"Error": "class java.lang.IllegalArgumentException : block_identifier null"}
block_identifier.number < 0 {"Error": "class java.lang.IllegalArgumentException : block_identifier number less than 0"}
block_identifier.hash is not 32 bytes {"Error": "class java.lang.IllegalArgumentException : block_identifier hash length not equals 32"}
block_identifier's number and hash do not match {"Error": "class java.lang.IllegalArgumentException : number and hash do not match"}
Block number does not exist {"Error": "class org.tron.core.exception.ItemNotFoundException : number: <N> is not found!"}
Other exceptions {"Error": "<exceptionClass> : <message>"}