Skip to content

Balance dynamics for one token

GET
/balances/{address}/history

Returns the balance of one token over time, with the change on each point. Only days on which the balance actually moved are returned, so a quiet address gives a short array rather than a row per day.
Pass days for a trailing window, or date_from together with date_to for an explicit period. The two date parameters only switch the mode when both are present; supplying one of them is rejected.

Authorizations

ApiKeyAuth

API key from the dashboard. Some Host Mode endpoints also accept the key as an api_key field in the request body — this is stated in the schema of the particular operation.

Type
API Key (header: X-API-KEY)

Parameters

Header Parameters

X-Real-IP*

An IP address from the key's whitelist. A request from an address outside the whitelist is rejected with 401.

Type
string
Required
Example"203.0.113.10"
Format
"ipv4"

Path Parameters

address*

TRON address in base58, exactly 34 characters.

Type
string
Required
Example"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Min Length
34
Max Length
34

Query Parameters

token_id

TRX, a TRC20 contract address, or a numeric TRC10 id.

Type
string
Default
"TRX"
days

Trailing window in days. Ignored when both dates are given.

Type
integer
Minimum
7
Maximum
1825
Default
90
date_from

Start of the period, UTC. Must be sent together with date_to.

Type
string
Format
"date"
date_to

End of the period, UTC, inclusive. Must be sent together with date_from.

Type
string
Format
"date"

Responses

Points at which the balance changed.

application/json
JSON
{
  
"status": "success",
  
"code": 0,
  
"msg": "",
  
"data": {
  
  
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  
  
"token_id": "TRX",
  
  
"days": 90,
  
  
"opening_balance": "148067.807102",
  
  
"has_usd": true,
  
  
"points": [
  
  
  
{
  
  
  
  
"date": "2026-09-01",
  
  
  
  
"balance": "1141.899000",
  
  
  
  
"delta": "-75352.041406",
  
  
  
  
"price_usd": "0.322386",
  
  
  
  
"balance_usd": "368.13"
  
  
  
}
  
  
]
  
}
}

Playground

Authorization
Headers
Variables
Key
Value

Samples

Powered by VitePress OpenAPI