Skip to main content
POST
/
api
/
v1
/
developer
/
wallet
/
holdings
/
history
Get Holdings History
curl --request POST \
  --url https://api.allium.so/api/v1/developer/wallet/holdings/history \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "addresses": [
    {
      "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp",
      "chain": "solana"
    }
  ],
  "end_timestamp": "2025-04-10T00:00:00Z",
  "granularity": "1h",
  "include_token_breakdown": false,
  "start_timestamp": "2025-04-01T00:00:00Z"
}
'
{
  "items": [
    {
      "address": "0x8e0e6fbaf18f209916bb7c5960a70d6bb5760938",
      "amount": {
        "amount": 297231.67,
        "currency": "USD"
      },
      "chain": "ethereum",
      "timestamp": "2026-04-12T00:00:00Z"
    },
    {
      "address": "0x8e0e6fbaf18f209916bb7c5960a70d6bb5760938",
      "amount": {
        "amount": 305582.84,
        "currency": "USD"
      },
      "chain": "ethereum",
      "timestamp": "2026-04-11T00:00:00Z"
    },
    {
      "address": "0x8e0e6fbaf18f209916bb7c5960a70d6bb5760938",
      "amount": {
        "amount": 310573.28,
        "currency": "USD"
      },
      "chain": "ethereum",
      "timestamp": "2026-04-10T00:00:00Z"
    }
  ]
}
This endpoint provides historical USD value of holdings for wallet addresses, returning aggregated data at regular intervals based on your requested time range and granularity. At every timestamp, holdings are calculated using the most recent balance and USD price for each asset. Results are sorted by timestamp in descending order (newest first).

​
Time Range Parameters

  • start_timestamp - Beginning of the time range (inclusive)
  • end_timestamp - End of the time range (exclusive)
  • Both timestamps are assumed to be in UTC if no timezone is specified
  • All returned data is in UTC

​
Granularity Options

  • 1d - Daily intervals
  • 1h - Hourly intervals
  • 5m - 5-minute intervals
  • 1m - 1-minute intervals
  • 15s - 15-second intervals

​
Granularity Constraints

The allowed granularity depends on the requested time range:
Time RangeFinest Granularity Allowed
0 - 24 hours15s
1 - 7 days5m
1 week - 1 year1h
Over 1 year1d
Additionally, 15s granularity data is only retained for 7 days — the start timestamp cannot be more than 7 days in the past when using 15s.

​
Request Parameters

  • addresses - List of wallet chain+address pairs (1 to 15 per request)
  • include_token_breakdown - If true, includes per-token USD breakdown in each interval (default: false)
  • min_liquidity - Optional minimum USD liquidity threshold to filter out low-liquidity tokens
  • cursor - Pagination cursor for fetching additional results

​
Important Notes

  • Value errors are returned for invalid address, chain, or time range payloads
  • If end_timestamp is earlier than start_timestamp, an error will be returned
  • If end_timestamp is in the future, it will be adjusted to the current time
  • If the requested granularity is too fine for the time range, an error will be returned (see constraints above)
  • If a wallet has no holdings or does not exist, the endpoint will interpolate the aggregated holdings to be 0
  • Timestamps are snapped to the nearest granularity boundary (e.g., 5-minute marks for 5m, 15-second marks for 15s)

​
Supported Chains

​
Performance

The endpoint returns up to 800 records per page and provides a cursor to paginate through additional results. When querying multiple addresses, timestamps are divided across addresses (e.g., 2 addresses yield ~400 timestamps each).

Authorizations

​
X-API-KEY
string
header
required

Query Parameters

​
cursor
string
​
min_liquidity
number

Minimum USD liquidity threshold to include a token

Body

application/json
​
start_timestamp
string<date-time>
required

Start of time range (UTC ISO 8601)

​
end_timestamp
string<date-time>
required

End of time range (UTC ISO 8601)

​
granularity
enum<string>
required

Time interval granularity (15s, 1m, 5m, 1h, 1d)

Available options:
15s,
1m,
5m,
1h,
1d
​
addresses
PayloadAddress · object[]
required

List of wallet chain+address pairs

Required array length: 1 - 15 elements
​
include_token_breakdown
boolean
default:false

If true, includes per-token breakdown in each interval

Response

Successful Response

​
items
AggregatedHoldings · object[]
required

Holdings snapshots, one per time interval

​
cursor
string | null

Pagination cursor for next page