Portfolio history

GET /api/portfolio-history/ gives you a time series of total USD value for one account, sampled at fixed intervals. Drop it straight into a chart.

Endpoint

Parameter	Required	Notes
`account_address`	yes	Wallet address
`start_time`	yes	ISO-8601 timestamp
`end_time`	no	ISO-8601, defaults to now
`interval`	no	One of `1 hour`, `1 day` (default), `1 week`, `1 month`
`fill_gaps`	no	`false` to skip empty buckets; default `true`

Example

Response

Code

json

1{
2  "success": true,
3  "data": [
4    {
5      "bucket": "2026-01-20T00:00:00Z",
6      "total_usd": 10495300.460964,
7      "tracked_total_usd": 10495300.460964,
8      "holdings_count": 44,
9      "untracked_count": 42
10    },
11    {
12      "bucket": "2026-01-21T00:00:00Z",
13      "total_usd": 10495300.460964,
14      "tracked_total_usd": 10495300.460964,
15      "holdings_count": 44,
16      "untracked_count": 42
17    }
18  ],
19  "count": 6,
20  "interval": "1 day",
21  "fill_gaps": true,
22  "start_time": "2026-01-20T00:00:00+00:00",
23  "end_time":   "2026-01-25T00:00:00+00:00"
24}

How buckets work

Each bucket is the start of its interval (midnight UTC for daily, top of the hour for hourly). The total_usd is the value at the end of that bucket, after every transfer that landed inside it.

If the account had no activity in a bucket, the previous bucket's value carries forward. With fill_gaps=true (the default), every bucket boundary shows up so your charting library doesn't have to interpolate.

A note on cost

The more tokens a wallet holds, the more work the API does. Rough idea:

Tokens	Days	Roughly
1 (e.g. STRK)	30	~0.5 s
10 (small wallet)	30	~2 s
44 (active wallet)	5	~8 s
100+ (whale)	30	tens of seconds

Tip

For dashboards that load portfolio history on every page view, cache the response in your app keyed by (account, start, end, interval). Past buckets never change, so the cache TTL on historical ranges can basically be forever.