# A verified pool's price history

`GET /dex/pools/{poolNft}/price/history` · Lithos client API · Lithos Dex

Source: https://lithosprotocol.org/docs/api/get-ld-pool-price-history

`GET /dex/price/history` for any verified pool: Y per X at display decimals, from a background snapshot. Collected for verified pools only. A pool other than ERG:LIT is collected from the height it joined the verified list, `stats.collectedFrom`; a range reaching earlier is `partial`.

## Parameters

| Name | In | Type | Required | Description |

|---|---|---|---|---|

| `poolNft` | path | string | yes | The pool's NFT id, 64 hex characters |

| `range` | query | string | no | How far back to go |

| `bucket` | query | integer · int32 | no | Positive bucket size in blocks. At most 500 points including range boundaries. |

## Responses

### 200: Price series for the requested range

`LDPriceHistory`

- `range` (string, required): The range served, echoed back
- `changePct` (number · double, required): Signed fraction across the range; 0.018 is +1.8%
- `partial` (boolean, required): True when the series does not span the whole range or the snapshot is stale.
- `history` (LDPricePoint[], required)
  - `height` (integer · int32, required)
  - `timestamp` (integer · int64): Unix milliseconds. Absent if unresolved.
  - `price` (number · double, required): Token per ERG with the token's decimals applied. A display value — recompute from the reserves if you need it exact. 
  - `reservesX` (string, required): nanoERG the AMM traded with at this point. Decimal string.
  - `reservesY` (string, required): Raw token units the AMM traded with at this point. Decimal string.
- `stats` (DexStatsView)
  - `status` (string, required, one of disabled, loading, ready, stale, unavailable): Freshness only. Coverage is a separate question — read `historyComplete` and a graph's `partial`.
  - `updatedAt` (integer · int64): When the last successful refresh began, in Unix milliseconds, before it read the node.
  - `sourceHeight` (integer · int32)
  - `sourceBlockId` (string): The chain tip checked before and after the read. Current price and activity can also include the mempool.
  - `windowStartHeight` (integer · int32): Earliest height you can ask for, max(0, `sourceHeight` - 21600).
  - `coverageStartHeight` (integer · int32): Oldest retained pool snapshot, including a predecessor where one exists.
  - `historyComplete` (boolean): Whether the history read reached the start of the index, or a predecessor, before the requested window.
  - `refreshing` (boolean, required)
  - `restored` (boolean, required): Loaded from disk. Stale until a node read succeeds, and never overwrites newer live data.
  - `error` (string): Short refresh failure message. Details stay in the client log.
  - `collectedFrom` (integer · int32): The height a verified pool other than ERG:LIT joined the verified list. Nothing before it is collected, so a graph covering earlier heights shows that range as not collected. Absent for ERG:LIT, whose whole life is collected. 

### 400: Unknown `range`, or a `bucket` that would return too many points.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 404: Not a verified pool, so nothing is collected for it.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 503: No snapshot yet, or the pool index is still building. Retry-After is 5 seconds.

`DexStatsUnavailable`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description
- `stats` (DexStatsView, required)
  - `status` (string, required, one of disabled, loading, ready, stale, unavailable): Freshness only. Coverage is a separate question — read `historyComplete` and a graph's `partial`.
  - `updatedAt` (integer · int64): When the last successful refresh began, in Unix milliseconds, before it read the node.
  - `sourceHeight` (integer · int32)
  - `sourceBlockId` (string): The chain tip checked before and after the read. Current price and activity can also include the mempool.
  - `windowStartHeight` (integer · int32): Earliest height you can ask for, max(0, `sourceHeight` - 21600).
  - `coverageStartHeight` (integer · int32): Oldest retained pool snapshot, including a predecessor where one exists.
  - `historyComplete` (boolean): Whether the history read reached the start of the index, or a predecessor, before the requested window.
  - `refreshing` (boolean, required)
  - `restored` (boolean, required): Loaded from disk. Stale until a node read succeeds, and never overwrites newer live data.
  - `error` (string): Short refresh failure message. Details stay in the client log.
  - `collectedFrom` (integer · int32): The height a verified pool other than ERG:LIT joined the verified list. Nothing before it is collected, so a graph covering earlier heights shows that range as not collected. Absent for ERG:LIT, whose whole life is collected. 

### default: Error

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

## Example request

```bash
curl -X GET "http://localhost:9000/dex/pools/{poolNft}/price/history"
```

## Example response

```json
{
  "range": "24H",
  "changePct": 0.018,
  "partial": false,
  "history": [
    {
      "height": 484719,
      "timestamp": 1765432100000,
      "price": 35.6285,
      "reservesX": "1133460000000",
      "reservesY": "403834600000"
    }
  ],
  "stats": {
    "status": "disabled",
    "updatedAt": 0,
    "sourceHeight": 0,
    "sourceBlockId": "string",
    "windowStartHeight": 0,
    "coverageStartHeight": 0,
    "historyComplete": true,
    "refreshing": true,
    "restored": true,
    "error": "string",
    "collectedFrom": 0
  }
}
```