Balance history

GET /api/balance-history/ gives you a snapshot for every transfer that touched a given (account, token) pair inside a time range. Each row carries the running balance right after that event, plus its USD value if we have a price for the token.

Info

You're getting an exact answer for every event in the window, not a sample. The current balance acts as the anchor and the API works backwards through the transfer log to figure out what came before.

Endpoint

Parameter	Required	Notes
`account_address`	yes	Wallet address
`token_address`	yes	Token contract
`start_time`	yes	ISO-8601 timestamp, inclusive
`end_time`	no	ISO-8601 timestamp, defaults to now

Example

Response

Code

json

1{
2  "success": true,
3  "data": [
4    {
5      "time": "2026-01-24T23:03:20Z",
6      "block_number": 6000181,
7      "event_index": 0,
8      "balance": "5445567935812",
9      "token_price_usd": 1.0,
10      "balance_usd": 5445567.935812
11    },
12    {
13      "time": "2026-01-24T23:07:18Z",
14      "block_number": 6000296,
15      "event_index": 13,
16      "balance": "5445844685351",
17      "token_price_usd": 1.0,
18      "balance_usd": 5445844.685351
19    }
20  ],
21  "count": 55,
22  "account_address": "0x...",
23  "token_address": "0x053c91253...",
24  "start_time": "2026-01-20T00:00:00Z",
25  "end_time":   "2026-01-25T00:00:00Z"
26}

Tip

For very active accounts (10K+ transfers in the window), responses can get big fast. Tighten your time range or page through it in narrower chunks.

Tokens we don't price

If token_price_usd is null, we don't have a price feed for this token at the requested time. The balance is still right; balance_usd will be null instead of a misleading 0.

Documentation

Balance history

Endpoint

Example

Response

Tokens we don't price

See also