---
title: "Get Holdings History"
method: POST
path: "/api/v1/developer/wallet/holdings/history"
tags: ["HOLDINGS", "DEVELOPER", "WALLET"]
---

# Get Holdings History

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

## Query parameters

- `cursor` string
- `min_liquidity` number — Minimum USD liquidity threshold to include a token

## Request body

- PayloadHistoricalHoldings
  - `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` '15s' | '1m' | '5m' | '1h' | '1d', required
  - `addresses` PayloadAddress[], required — List of wallet chain+address pairs
    - `chain` string, required — Lowercase chain name
    - `address` string, required — Wallet address
  - `include_token_breakdown` boolean — If true, includes per-token breakdown in each interval

## Response `200`

Successful Response

- ApiServerAppServicesHoldingsCommonModelsEnvelope
  - `items` AggregatedHoldings[], required — Holdings snapshots, one per time interval
    - `chain` string — Lowercase chain name
    - `address` string — Wallet address
    - `timestamp` string, date-time, required — Interval start time (UTC)
    - `amount` NotionalAmount, required
      - `currency` 'USD', required
      - `amount` number, required — Value in the specified currency
    - `token_breakdown` TokenHolding[], nullable — Per-token breakdown (included when include_token_breakdown=true)
      - `token_address` string, required — Token contract address
      - `amount` NotionalAmount, required
        - `currency` 'USD', required
        - `amount` number, required — Value in the specified currency
      - `liquidity` LiquidityResults, required
        - `amount` number, nullable — Liquidity amount (USD)
        - `details` string, nullable — Status when amount unavailable (e.g. LIQUIDITY_TOO_HIGH)
  - `cursor` string, nullable — Pagination cursor for next page

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/allium/apis/allium-account-api.md) · [All operations](https://skmtc.net/allium/apis/allium-account-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/allium/allium-account-api/versions/6c79c032c85d/schema)