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

# Pools Reserves Overview

> Access normalized pool reserve snapshots for on-chain liquidity analytics and time-series analysis.

## Overview

The Pools Reserves endpoints provide time-series snapshots of AMM pool liquidity states. Reserve data is normalized across pool types (constant-product, concentrated liquidity, weighted, bin-based) to enable consistent analytics regardless of the underlying AMM. Each snapshot includes lineage metadata linking back to on-chain state changes.

### Endpoint Matrix

| Endpoint                                                                                             | Summary                                                          | Dataset ID | Typical Latency |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------- | --------------- |
| [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves)                                      | Normalized reserve snapshots with decimals-adjusted amounts      | `0301`     | \< 250 ms       |
| [`POST /v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) | Per-tick liquidity distribution for concentrated liquidity pools | `0301`     | \< 400 ms       |

### Parameter Conventions

<ParamField body="from_block" type="number">
  Starting block height (inclusive) for reserve snapshots.
</ParamField>

<ParamField body="to_block" type="number">
  Ending block height (inclusive) for reserve snapshots.
</ParamField>

<ParamField body="from_timestamp" type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField body="to_timestamp" type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField body="pool_uids" type="string[]">
  BlockDB pool identifiers for direct lookups.
</ParamField>

<ParamField body="pool_addresses" type="string[]">
  Pool contract addresses to scope reserve data.
</ParamField>

<ParamField body="pool_ids" type="string[]">
  Provider-specific pool identifiers when applicable.
</ParamField>

<ParamField body="exchange_ids" type="number[]">
  Exchange identifiers for filtering by DEX protocol.
</ParamField>

<ParamField body="pool_type_ids" type="number[]">
  AMM model filters. Use [Pool Type enumeration](/api-reference/enumerations/pool-type) values.
</ParamField>

<ParamField body="chain_id" type="number" required>
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField body="include_adjusted_amounts" type="boolean" default="false">
  Off by default. When set to `true`, reserve amounts and tick amounts are also returned scaled by ERC-20
  token decimals. Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency,
  so it is opt-in; when omitted or `false`, only the always-present raw base-unit fields are populated.
</ParamField>

### Usage Guidance

* **Join with pools metadata** — Link reserve snapshots to pool metadata via `pool_uid` for complete context
* **Time-series analysis** — Reserve data is optimized for chronological queries; use block/time ranges for historical analysis
* **Filter by exchange** — Use `exchange_ids` to focus on specific DEX protocols (Uniswap, Curve, etc.)
* **Concentrated liquidity** — Use [`/v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) for per-tick breakdown with a configurable price window (1–10%)
* **Decimals-adjusted amounts** — Enable `include_adjusted_amounts` (off by default) to receive human-readable token amounts alongside raw base-unit values; it adds a decimals lookup, so opt in only when you need the scaled values
* **Cache recent snapshots** — Latest reserve states change frequently; cache with short TTL (1–5 minutes)

### Reserve Data Models

**Even-Distribution Pools** (Uniswap v2, SushiSwap, Balancer):

* `reserves`: Array of raw token balances (base units)
* `reserves_decimals_adjusted`: Same values divided by each token's decimals (e.g. `/ 10^18` for ETH)
* `current_tick`: `null`
* `current_sqrt_price`: `null`

**Concentrated Liquidity** (Uniswap v3/v4, SushiSwap v3, PancakeSwap v3):

* `reserves`: `null` (reserves are distributed across ticks)
* `current_tick`: Active tick position
* `current_sqrt_price`: Q64.96 sqrt price
* For per-tick distribution → use [`/v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution)

**Bin-Based Pools** (TraderJoe v2, Aerodrome Slipstream):

* `current_bin`: Active bin identifier

### Common Patterns

**Track pool reserves over time:**

```json theme={null}
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-01-01T00:00:00Z",
  "to_timestamp": "2025-01-31T23:59:59Z",
  "include_adjusted_amounts": true
}
```

**Get reserves for all Uniswap v2 pools (raw amounts only):**

```json theme={null}
{
  "chain_id": 1,
  "pool_type_ids": [201],
  "from_block": 18000000,
  "to_block": 18001000,
  "include_adjusted_amounts": false
}
```

**Analyze concentrated liquidity tick distribution (±5% around spot):**

```json theme={null}
{
  "chain_id": 1,
  "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
  "from_block": 20000000,
  "to_block": 20001000,
  "price_window_percent": 5.0,
  "include_adjusted_amounts": true
}
```

### Dataset Relationships

* **Pools → Reserves**: Join pool metadata to reserve snapshots using `pool_uid`
* **Reserves → Swap Fees**: Combine swap-fee time-series with reserve state for pool economics
* **Swap Fees → Yields**: Yield predictions are derived from swap fees and current reserves
* **Reserves → Prices**: Reserve changes drive pricing calculations in L1/L2/L3 layers
* **Reserves → Transactions**: Reserve snapshots link to transaction logs via `_parent_tracing_ids`

### See Also

* [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves) — Reserve snapshots with decimals-adjusted amounts
* [`POST /v1/evm/reserves/liquidity-distribution`](/api-reference/evm/reserves/liquidity-distribution) — Per-tick liquidity distribution
* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Per-swap fee accounting
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications
* [Digital Exchange](/api-reference/enumerations/digital-exchange) — DEX protocol identifiers
* [Pricing Suite Overview](/api-reference/evm/prices/crypto/overview) — Price data derived from reserves