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

# Midprice History

> Returns sampled midprice history for a pool over a time range.

## Path Parameters

<ParamField path="address" type="string" required>
  The pool config PDA address.
</ParamField>

## Query Parameters

<ParamField query="timeframe" type="string" default="1h">
  Sample interval. One of: `1m`, `5m`, `30m`, `1h`, `2h`, `4h`, `12h`, `24h`, `raw`.

  When set to `raw`, every recorded midprice point is returned without bucketing/sampling. Results are paginated via `cursor`.
</ParamField>

<ParamField query="start_time" type="integer">
  Start of the time range as a Unix timestamp in seconds (inclusive). Defaults to `end_time - 86400` (24 hours ago).
</ParamField>

<ParamField query="end_time" type="integer">
  End of the time range as a Unix timestamp in seconds (inclusive). Defaults to current time.
</ParamField>

<ParamField query="limit" type="integer" default="200">
  Number of records per page (1–1000). Only applicable when `timeframe=raw`.
</ParamField>

<ParamField query="cursor" type="integer">
  Unix timestamp in seconds. Fetch records **before** this timestamp (newest first). Use the `next_cursor` value from a previous response to paginate backwards through history. Only applicable when `timeframe=raw`.
</ParamField>

<ParamField query="cluster" type="string" default="mainnet-beta">
  Solana cluster — `mainnet-beta` or `devnet`.
</ParamField>

## Response

<ResponseField name="start_time" type="integer">
  Start of the requested range (Unix seconds).
</ResponseField>

<ResponseField name="end_time" type="integer">
  End of the requested range (Unix seconds).
</ResponseField>

<ResponseField name="timeframe" type="string">
  The sample interval used.
</ResponseField>

<ResponseField name="next_cursor" type="integer | null">
  Timestamp of the oldest record in the current page (Unix seconds). Pass as `cursor` to fetch the next (older) page. `null` when there are no more records. Only present when `timeframe=raw`.
</ResponseField>

<ResponseField name="data" type="array">
  Array of midprice samples. One entry per time bucket that contains data (sampled modes), or every recorded point (`raw` mode).

  <Expandable title="Midprice sample">
    <ResponseField name="timestamp" type="integer">
      Sample timestamp (Unix seconds).
    </ResponseField>

    <ResponseField name="slot" type="integer">
      Solana slot number when this midprice update was confirmed on-chain.
    </ResponseField>

    <ResponseField name="midprice" type="number">
      Raw midprice value. This is the on-chain Q32-decoded midprice representing `token_y per token_x` in raw units. To get a human-readable price, multiply by `10^(decimals_x - decimals_y)`.
    </ResponseField>

    <ResponseField name="base_spread_factor" type="number">
      Base spread factor (Q32-decoded). A value near `1.0` means minimal spread. The spread in basis points is `(1 - base_spread_factor) * 10000`.
    </ResponseField>

    <ResponseField name="signature" type="string | null">
      Base58 transaction signature of the `UpdateMidprice` or `UpdateMidpriceAndSpreadFactor` instruction that produced this update. `null` for historical records ingested before signature tracking was added.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Sampled (1h) theme={null}
  {
    "start_time": 1773164464,
    "end_time": 1773250864,
    "timeframe": "1h",
    "data": [
      {
        "timestamp": 1773164464,
        "slot": 410333466,
        "midprice": 0.08771598688326776,
        "base_spread_factor": 0.9994999999180436,
        "signature": "E6cGjfbdRs4ShbmZc1AHeLZg7vN79PYHFWe4..."
      },
      {
        "timestamp": 1773168065,
        "slot": 410342211,
        "midprice": 0.08653769129887223,
        "base_spread_factor": 0.9994999999180436,
        "signature": "3Ni7GhiHoPmnUxcgpPMYW61qPkxUunj4WwB9..."
      }
    ]
  }
  ```

  ```json Raw (paginated) theme={null}
  {
    "start_time": 1710000000,
    "end_time": 1710086400,
    "timeframe": "raw",
    "next_cursor": 1710003600,
    "data": [
      {
        "timestamp": 1710000000,
        "slot": 409267135,
        "midprice": 145.23,
        "base_spread_factor": 0.9997,
        "signature": "44txvmp2QQJa9XLkG8Gj2zHnBScRkXxL5dHd..."
      },
      {
        "timestamp": 1710000400,
        "slot": 409268012,
        "midprice": 145.45,
        "base_spread_factor": 0.9997,
        "signature": "5AUySbnZ8qjk1Zr7VqTW8tPKJ9Gm3CfWgJ7x..."
      },
      {
        "timestamp": 1710003600,
        "slot": 409275890,
        "midprice": 145.12,
        "base_spread_factor": 0.9995,
        "signature": null
      }
    ]
  }
  ```
</ResponseExample>

## Errors

| Status | Message                                                            |
| ------ | ------------------------------------------------------------------ |
| `400`  | `Invalid timeframe`                                                |
| `400`  | `start_time and end_time must be valid unix timestamps in seconds` |
| `400`  | `cursor must be a valid unix timestamp in seconds`                 |