> ## 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 token price history

> Get the price history for the given token and the given time granularity.

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 returns the price and OHLC for a list of tokens/chains in a given time window. Prices are calculated as a volume-weighted average and OHLC values are aggregated over DEX trades within the window specified by `time_window`.

**Max number of tokens per request:** 50

## Supported Windows

The following are the supported time windows and their associated retention periods:

| Window | Retention |
| :----- | :-------- |
| 15s    | 5 days    |
| 1m     | All       |
| 5m     | All       |
| 1h     | All       |
| 1d     | All       |

## Supported Chains

<SupportedChainsList product_name="token_price_history" />

## Edge Cases

### Forward-filled prices

If a token has **no trading activity** in a requested time window, we will **forward fill** the price and OHLC from the **most recent prior window** with data (i.e., carry forward the last known values) so your time series is more consistent/dense.

Notes:

* If there is **no prior datapoint** to forward fill from before the start of the requested time window (e.g. if the token was not created yet), that window will still have **no data**.

### Incomplete Time Windows

This endpoint returns price data for the current time window, even if it's incomplete. For example:

* If the API is called at **10:30**, the latest hourly datapoint for 10:00 is based on trades from 10:00 to 10:30
* If called at **11:00**, the 10:00 datapoint will be finalized, reflecting a full hour of trades (i.e., 10:00 to 11:00)

Users should account for this when handling near-realtime data.


## OpenAPI

````yaml /_openapi/prices-api.json POST /api/v1/developer/prices/history
openapi: 3.1.0
info:
  title: Allium API
  version: 0.1.0
servers:
  - url: https://api.allium.so
security: []
paths:
  /api/v1/developer/prices/history:
    post:
      tags:
        - PRICES
        - DEVELOPER
      summary: Token Prices History
      description: >-
        Get a list of historical token prices by chain and token address for a
        given time range and granularity.
      operationId: get_historical_prices_api_v1_developer_prices_history_post
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            title: Cursor
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/PayloadPriceHistorical'
                - $ref: '#/components/schemas/PayloadPriceHistoricalLegacy'
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Envelope_Union_TokenPriceHistorical__TokenPrice__
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyBearer: []
components:
  schemas:
    PayloadPriceHistorical:
      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)
        addresses:
          items:
            $ref: '#/components/schemas/PayloadTokenAddress'
          type: array
          title: Addresses
          description: List of token address+chain pairs
        time_granularity:
          $ref: >-
            #/components/schemas/api_server__app__services__prices__models__Granularity
          description: Candle granularity (15s, 1m, 5m, 1h, 1d)
      type: object
      required:
        - start_timestamp
        - end_timestamp
        - addresses
        - time_granularity
      title: PayloadPriceHistorical
      example:
        addresses:
          - chain: string
            token_address: string
          - chain: string
            token_address: string
        end_timestamp: '2025-03-07T01:00:00Z'
        start_timestamp: '2025-03-07T00:00:00Z'
        time_granularity: 5m
    PayloadPriceHistoricalLegacy:
      properties:
        chain:
          type: string
          title: Chain
        token_address:
          type: string
          title: Token Address
        time_granularity:
          $ref: >-
            #/components/schemas/api_server__app__services__prices__models__Granularity
        start_timestamp:
          type: string
          format: date-time
          title: Start Timestamp
        end_timestamp:
          type: string
          format: date-time
          title: End Timestamp
      type: object
      required:
        - chain
        - token_address
        - time_granularity
        - start_timestamp
        - end_timestamp
      title: PayloadPriceHistoricalLegacy
      example:
        chain: string
        end_timestamp: '2025-03-07T01:00:00Z'
        start_timestamp: '2025-03-07T00:00:00Z'
        time_granularity: 5m
        token_address: string
    Envelope_Union_TokenPriceHistorical__TokenPrice__:
      properties:
        items:
          items:
            anyOf:
              - $ref: '#/components/schemas/TokenPriceHistorical'
              - $ref: '#/components/schemas/TokenPrice'
          type: array
          title: Items
          description: Response items
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Pagination cursor for next page
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Informational message (e.g. partial results)
      type: object
      required:
        - items
      title: Envelope[Union[TokenPriceHistorical, TokenPrice]]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PayloadTokenAddress:
      properties:
        token_address:
          type: string
          title: Token Address
          description: Token contract address
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
      type: object
      required:
        - token_address
        - chain
      title: PayloadTokenAddress
      example:
        chain: ethereum
        token_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    api_server__app__services__prices__models__Granularity:
      type: string
      enum:
        - 15s
        - 1m
        - 5m
        - 1h
        - 1d
      title: Granularity
    TokenPriceHistorical:
      properties:
        mint:
          type: string
          title: Mint
          description: Token contract address
        chain:
          type: string
          title: Chain
          description: Lowercase chain name
        decimals:
          anyOf:
            - type: integer
            - type: 'null'
          title: Decimals
          description: Token decimal places
        prices:
          items:
            $ref: '#/components/schemas/TokenPriceHistoricalItem'
          type: array
          title: Prices
          description: OHLCV candle array, one entry per time interval
      type: object
      required:
        - mint
        - chain
        - prices
      title: TokenPriceHistorical
    TokenPrice:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        chain:
          type: string
          title: Chain
        mint:
          type: string
          title: Mint
        decimals:
          anyOf:
            - type: integer
            - type: 'null'
          title: Decimals
        price:
          type: number
          title: Price
        open:
          type: number
          title: Open
        high:
          type: number
          title: High
        close:
          type: number
          title: Close
        low:
          type: number
          title: Low
        volume_24h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 24H
        volume_1h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 1H
        trade_count_24h:
          anyOf:
            - type: integer
            - type: 'null'
          title: Trade Count 24H
        trade_count_1h:
          anyOf:
            - type: integer
            - type: 'null'
          title: Trade Count 1H
      type: object
      required:
        - timestamp
        - chain
        - mint
        - price
        - open
        - high
        - close
        - low
      title: TokenPrice
    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
    TokenPriceHistoricalItem:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: ISO 8601 UTC candle start time
        price:
          type: number
          title: Price
          description: Volume-weighted average price (USD) over the interval
        open:
          type: number
          title: Open
          description: Opening price (USD) at the start of the interval
        high:
          type: number
          title: High
          description: Highest price (USD) during the interval
        close:
          type: number
          title: Close
          description: Closing price (USD) at the end of the interval
        low:
          type: number
          title: Low
          description: Lowest price (USD) during the interval
      type: object
      required:
        - timestamp
        - price
        - open
        - high
        - close
        - low
      title: TokenPriceHistoricalItem
  securitySchemes:
    APIKeyBearer:
      type: apiKey
      in: header
      name: X-API-KEY

````