Fetch holdings history

Get historical aggregated USD holdings for an address.

POST /api/v1/developer/wallet/holdings/history

Get Holdings History

cURL

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"
}
'

200

{
  "items": [
    {
      "timestamp": "2023-11-07T05:31:56Z",
      "amount": {
        "currency": "USD",
        "amount": 123
      },
      "chain": "",
      "address": "",
      "token_breakdown": [
        {
          "token_address": "<string>",
          "amount": {
            "currency": "USD",
            "amount": 123
          },
          "liquidity": {
            "amount": 123,
            "details": "<string>"
          }
        }
      ]
    }
  ],
  "cursor": "<string>"
}

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
• 15s - 15-second intervals

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 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

Chain	Granularity	Retention	Asset Types
Bitcoin	1d, 1h, 5m, 15s	all, all, 72h, 72h	bitcoin
Solana (Beta)	1d, 1h, 5m, 15s	all, all, 30d, 1h	sol, spl tokens

Performance

The endpoint returns up to 5,000 aggregated holdings per request and provides a cursor to paginate through additional results.

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

Show child attributes

include_token_breakdown · boolean · default: false

If true, includes per-token breakdown in each interval

Response

200

application/json

Successful Response

items · AggregatedHoldings · object[] · required

Holdings snapshots, one per time interval

Show child attributes

cursor · string | null

Pagination cursor for next page