> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allium.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch holdings history

> Get historical aggregated USD holdings for one or more addresses.

export const SupportedChainsList = props => {
  const [data, setData] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch("https://api.allium.so/api/v1/supported-chains/realtime-apis", {
          method: "GET"
        });
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const responseData = await response.json();
        const filteredData = responseData.filter(entry => {
          const product = entry.endpoints[props.product_name];
          return product !== null;
        });
        setData(filteredData);
        setIsLoading(false);
      } catch (error) {
        setIsLoading(false);
      }
    };
    fetchData();
  }, []);
  if (isLoading) {
    return <div>Loading chain information...</div>;
  }
  if (!data) {
    return <div>No data available</div>;
  }
  const isCustomSQL = props.product_name === "custom_sql";
  return <div>
            {data.length > 0 && <table className="w-full">
                    <thead>
                        <tr>
                            <th>Chain</th>
                            <th>Chain ID</th>
                            <th>Status</th>
                            {isCustomSQL && <th>Tables</th>}
                        </tr>
                    </thead>
                    <tbody>
                        {data.map(chain => {
    const endpoint = chain.endpoints[props.product_name];
    return <tr key={chain.id}>
                                    <td style={{
      padding: '12px'
    }}>{chain.label}</td>
                                    <td style={{
      padding: '12px'
    }}><code>{chain.id}</code></td>
                                    <td style={{
      padding: '12px'
    }}>{endpoint ? endpoint.availability === "beta" ? "🌱 Beta" : "✅ Supported" : "❌ Not Supported"}</td>
                                    {isCustomSQL && <td style={{
      padding: '12px'
    }}>
                                            {endpoint && endpoint.tables ? endpoint.tables.map(t => t.name).join(", ") : "-"}
                                        </td>}
                                </tr>;
  })}
                    </tbody>
                </table>}
        </div>;
};

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 Range      | Finest Granularity Allowed |
| :-------------- | :------------------------- |
| 0 - 24 hours    | `15s`                      |
| 1 - 7 days      | `5m`                       |
| 1 week - 1 year | `1h`                       |
| Over 1 year     | `1d`                       |

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

<SupportedChainsList product_name="holdings_history" />

## 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).


## OpenAPI

````yaml /_openapi/holdings-api.json POST /api/v1/developer/wallet/holdings/history
openapi: 3.1.0
info:
  title: Allium API
  version: 0.1.0
servers:
  - url: https://api.allium.so
security: []
paths:
  /api/v1/developer/wallet/holdings/history:
    post:
      tags:
        - HOLDINGS
        - DEVELOPER
        - WALLET
      summary: Get Holdings History
      operationId: get_holdings_history_api_v1_developer_wallet_holdings_history_post
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            title: Cursor
            type: string
        - name: min_liquidity
          in: query
          required: false
          schema:
            description: Minimum USD liquidity threshold to include a token
            title: Min Liquidity
            type: number
          description: Minimum USD liquidity threshold to include a token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayloadHistoricalHoldings'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/api_server__app__services__holdings__common__models__Envelope
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyBearer: []
components:
  schemas:
    PayloadHistoricalHoldings:
      properties:
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
          description: Start of time range (UTC ISO 8601)
        end_timestamp:
          type: string
          format: date-time
          title: End Timestamp
          description: End of time range (UTC ISO 8601)
        granularity:
          $ref: >-
            #/components/schemas/api_server__app__services__prices__models__Granularity
          description: Time interval granularity (15s, 1m, 5m, 1h, 1d)
        addresses:
          items:
            $ref: '#/components/schemas/PayloadAddress'
          type: array
          maxItems: 15
          minItems: 1
          title: Addresses
          description: List of wallet chain+address pairs
        include_token_breakdown:
          type: boolean
          title: Include Token Breakdown
          description: If true, includes per-token breakdown in each interval
          default: false
      type: object
      required:
        - start_timestamp
        - end_timestamp
        - granularity
        - addresses
      title: PayloadHistoricalHoldings
      example:
        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'
    api_server__app__services__holdings__common__models__Envelope:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AggregatedHoldings'
          type: array
          title: Items
          description: Holdings snapshots, one per time interval
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Pagination cursor for next page
      type: object
      required:
        - items
      title: Envelope
      example:
        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'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    api_server__app__services__prices__models__Granularity:
      type: string
      enum:
        - 15s
        - 1m
        - 5m
        - 1h
        - 1d
      title: Granularity
    PayloadAddress:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        address:
          type: string
          title: Address
          description: Wallet address
      type: object
      required:
        - chain
        - address
      title: PayloadAddress
      examples:
        - address: '0xab16781a13fe343a275f4bb5c883a64ceda52917'
          chain: ethereum
        - address: 125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp
          chain: solana
    AggregatedHoldings:
      properties:
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
          default: ''
        address:
          type: string
          title: Address
          description: Wallet address
          default: ''
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Interval start time (UTC)
        amount:
          $ref: '#/components/schemas/NotionalAmount'
          description: Total USD value of all holdings at this timestamp
        token_breakdown:
          anyOf:
            - items:
                $ref: '#/components/schemas/TokenHolding'
              type: array
            - type: 'null'
          title: Token Breakdown
          description: Per-token breakdown (included when include_token_breakdown=true)
      type: object
      required:
        - timestamp
        - amount
      title: AggregatedHoldings
      example:
        address: '0x8e0e6fbaf18f209916bb7c5960a70d6bb5760938'
        amount:
          amount: 297231.67
          currency: USD
        chain: ethereum
        timestamp: '2026-04-12T00:00:00Z'
        token_breakdown:
          - amount:
              amount: 79905.56
              currency: USD
            liquidity:
              details: LIQUIDITY_TOO_HIGH
            token_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
          - amount:
              amount: 622.15
              currency: USD
            liquidity:
              amount: 2427432.99
            token_address: '0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    NotionalAmount:
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
          description: Currency code
        amount:
          type: number
          title: Amount
          description: Value in the specified currency
      type: object
      required:
        - currency
        - amount
      title: NotionalAmount
    TokenHolding:
      properties:
        token_address:
          type: string
          title: Token Address
          description: Token contract address
        amount:
          $ref: '#/components/schemas/NotionalAmount'
          description: Token value (USD)
        liquidity:
          anyOf:
            - $ref: '#/components/schemas/LiquidityResults'
            - type: 'null'
          description: Token liquidity info
      type: object
      required:
        - token_address
        - amount
        - liquidity
      title: TokenHolding
    Currency:
      type: string
      enum:
        - USD
      title: Currency
    LiquidityResults:
      properties:
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
          description: Liquidity amount (USD)
        details:
          anyOf:
            - type: string
            - type: 'null'
          title: Details
          description: Status when amount unavailable (e.g. LIQUIDITY_TOO_HIGH)
      type: object
      title: LiquidityResults
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````