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",
  "start_timestamp": "2025-04-01T00:00:00Z"
}'
{
  "items": [
    {
      "timestamp": "2023-11-07T05:31:56Z",
      "usd_amount": 123
    }
  ],
  "cursor": "<string>"
}
This endpoint provides historical USD value of holdings for specified wallet addresses. It returns aggregated data at regular intervals based on your requested time range and granularity. At every timestamp, the endpoint calculates holdings by 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: The beginning of the time range (inclusive)
  • end_timestamp: The 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
  • 15s: 15-second intervals
Important notes and error handling
  • 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 time range exceeds the retention period for the selected granularity, an error will be returned
  • If a wallet has no holdings or does not exist, the endpoint will interpolate the aggregated holdings to be 0
Supported Chains and Holdings
ChainGranularityRetentionAsset Types
Bitcoin1d, 1h, 5m, 15sall, all, 72h, 72hbitcoin
Solana (Beta)1d, 1h, 5m, 15sall, all, 30d, 1hsol, spl tokens
Performance Metrics The endpoint returns up to 5000 aggregated holdings per request and provides a cursor to paginate through additional responses.
Performance MetricsValue
PaginationUp to 5000 aggregated holdings
Chain CoverageBitcoin, Solana (Beta)

Authorizations

​
X-API-KEY
string
header
required

Query Parameters

​
cursor
string

Body

application/json
​
granularity
enum<string>
required
Available options:
15s,
5m,
1h,
1d
​
start_timestamp
string<date-time>
required
​
end_timestamp
string<date-time>
required
​
addresses
PayloadAddress · object[]
required

Response

Successful Response

​
items
AggregatedHoldings · object[]
required
​
cursor
string | null