# A verified pool's fee history

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

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

`GET /dex/fees/history` for any verified pool. Collected for verified pools only, each other than ERG:LIT from the height it joined the verified list, `stats.collectedFrom`.

## Parameters

| Name | In | Type | Required | Description |

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

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

| `from` | query | integer · int32 | no | First height |

| `to` | query | integer · int32 | no | Last height |

| `bucket` | query | integer · int32 | no | Bucket size in blocks, default 720 |

## Responses

### 200: Fee series

`LDFeeHistory`

- `history` (LDFeeHistoryPoint[], required)
  - `height` (integer · int32, required): Block height at the end of this bucket
  - `timestamp` (integer · int64): Unix milliseconds at the end of this bucket. Absent if unresolved.
  - `periodX` (string, required): nanoERG fees taken during this bucket. Decimal string.
  - `periodY` (string, required)
  - `cumulativeX` (string, required): nanoERG fees taken from the start of the range to here. Decimal string.
  - `cumulativeY` (string, required)
- `partial` (boolean, required): True when the history scan could not cover the requested window or the snapshot is stale. Values are derived from accumulator differences with integer rounding, not payment receipts. 
- `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: Heights outside the collected window, or 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}/fees/history"
```

## Example response

```json
{
  "history": [
    {
      "height": 1312460,
      "timestamp": 1765432100000,
      "periodX": "210000000",
      "periodY": "6350000",
      "cumulativeX": "8420000000",
      "cumulativeY": "254300000"
    }
  ],
  "partial": false,
  "stats": {
    "status": "disabled",
    "updatedAt": 0,
    "sourceHeight": 0,
    "sourceBlockId": "string",
    "windowStartHeight": 0,
    "coverageStartHeight": 0,
    "historyComplete": true,
    "refreshing": true,
    "restored": true,
    "error": "string",
    "collectedFrom": 0
  }
}
```