> ## 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.

# Liquidity Distribution

> On-demand per-tick liquidity and token amounts for concentrated liquidity pools.

## Overview

* **Dataset ID:** [`0301 - Liquidity Pool Reserves`](/data-catalog/evm/reserves/liquidity-pools-reserves)
* **Description:** Retrieves the full tick-level liquidity distribution for a single concentrated-liquidity pool snapshot (Uniswap v3/v4-style). Amounts are computed on demand from the stored `liquidity_values` blob — no pre-aggregated detail table is queried.
* **CSV Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.csv?download=true)
* **JSON Sample:** [Download](https://huggingface.co/datasets/BlockDB/Liquidity-Pools-Reserves-Ethereum-And-EVM-Cryptocurrency-Data/resolve/main/data/blockdb_evm.b0301_liquidity_pools_reserves_details_v1.json?download=true)

Returns the full tick-level liquidity distribution for a single concentrated-liquidity pool snapshot
(Uniswap v3/v4-style). Amounts are computed on demand from the stored `liquidity_values` blob —
no pre-aggregated detail table is queried.

**Key characteristics:**

* Returns one snapshot per call (the most recent within the requested block/time window)
* Configurable price window: `1.0`-`10.0`% symmetric band around the current price
* Each tick row carries both raw (`amount0_raw`) and decimals-adjusted (`amount0`) amounts

<Note>
  For **even-distribution** pools (Uniswap v2, Balancer, etc.) use
  [`POST /v1/evm/reserves`](/api-reference/evm/reserves/reserves).
</Note>

## Parameters

<ParamField body="chain_id" type="number" required>
  Target EVM network. *See the [Chain](/api-reference/enumerations/chain) enumeration.*
</ParamField>

#### Pool Selector (exactly one required)

<ParamField body="pool_uid" type="string">
  BlockDB 32-byte pool identifier (hex, no `0x`).
</ParamField>

<ParamField body="pool_address" type="string">
  Pool contract address (hex, 20 bytes, no `0x`).
</ParamField>

<ParamField body="pool_id" type="string">
  Protocol-specific pool ID, e.g. Uniswap V4 `pool_id` (hex, 32 bytes, no `0x`).
</ParamField>

<Warning>
  Provide **exactly one** of `pool_uid`, `pool_address`, or `pool_id`. Providing more or fewer results in HTTP 400.
</Warning>

#### Snapshot Selector (exactly one required)

<ParamField body="tracing_id" type="string">
  Direct snapshot key (hex, no `0x`). When set, block/time range must not be provided.
</ParamField>

<ParamField body="from_block" type="number">
  Starting block number (inclusive). Use with `to_block`. The most recent snapshot within the range is returned.
</ParamField>

<ParamField body="to_block" type="number">
  Ending block number (inclusive). Use with `from_block`.
</ParamField>

<ParamField body="from_timestamp" type="string">
  Starting timestamp (ISO-8601). Use with `to_timestamp`.
</ParamField>

<ParamField body="to_timestamp" type="string">
  Ending timestamp (ISO-8601). Use with `from_timestamp`.
</ParamField>

#### Price Window

<ParamField body="price_window_percent" type="number" required>
  Symmetric percent band around the current price tick, e.g. `5.0` = ±5%.
  Must be between `1.0` and `10.0` inclusive. Values outside this range return HTTP 400.
</ParamField>

#### Amounts

<ParamField body="include_adjusted_amounts" type="boolean" default="false">
  Off by default. When set to `true`, each tick row includes `amount0` and `amount1` scaled by ERC-20
  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`, `amount0`/`amount1` are `null` and only the always-present
  `amount0_raw`/`amount1_raw` fields are populated.
</ParamField>

## Response Fields

#### Envelope

<ResponseField name="chain_id" type="number">
  EVM chain ID echoed from the request.
</ResponseField>

<ResponseField name="request_window" type="object">
  Block/timestamp bounds echoed from the request.
</ResponseField>

<ResponseField name="filters" type="object">
  Filters echoed from the request.
</ResponseField>

<ResponseField name="snapshot" type="object">
  The single resolved snapshot.
</ResponseField>

#### Snapshot Fields

<ResponseField name="snapshot.pool_uid" type="string">
  BlockDB pool identifier.
</ResponseField>

<ResponseField name="snapshot.exchange_id" type="number">
  Exchange identifier.
</ResponseField>

<ResponseField name="snapshot.type_id" type="number">
  Pool type identifier.
</ResponseField>

<ResponseField name="snapshot.block_number" type="number">
  Block height of the snapshot.
</ResponseField>

<ResponseField name="snapshot.block_time" type="string">
  Block timestamp (ISO-8601).
</ResponseField>

<ResponseField name="snapshot.tx_index" type="number">
  Transaction index within the block.
</ResponseField>

<ResponseField name="snapshot.log_index" type="number">
  Log index within the transaction.
</ResponseField>

<ResponseField name="snapshot.tick_spacing" type="number">
  Pool tick spacing (e.g. `60` for a 0.3% Uniswap v3 pool).
</ResponseField>

<ResponseField name="snapshot.current_tick" type="number">
  Active tick at the time of the snapshot.
</ResponseField>

<ResponseField name="snapshot.current_sqrt_price" type="string">
  Q64.96 sqrt price as an integer string.
</ResponseField>

<ResponseField name="snapshot.price_window_percent" type="number">
  Echoed from the request.
</ResponseField>

<ResponseField name="snapshot.resolved_lower_tick" type="number">
  Actual lower bound of the tick range returned (aligned to tick spacing).
</ResponseField>

<ResponseField name="snapshot.resolved_upper_tick" type="number">
  Actual upper bound of the tick range returned.
</ResponseField>

<ResponseField name="snapshot.token0_address" type="string | null">
  Token0 contract address (hex, no `0x`). Populated when pool metadata is available.
</ResponseField>

<ResponseField name="snapshot.token1_address" type="string | null">
  Token1 contract address (hex, no `0x`). Populated when pool metadata is available.
</ResponseField>

<ResponseField name="snapshot.token0_decimals" type="number | null">
  ERC-20 decimals for token0. `null` when unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.token1_decimals" type="number | null">
  ERC-20 decimals for token1. `null` when unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.ticks" type="object[]">
  Ordered array of tick rows within the resolved range. Only ticks with non-zero liquidity are included.
</ResponseField>

<ResponseField name="snapshot._tracing_id" type="string">
  Lineage hash for the snapshot row.
</ResponseField>

#### Tick Row Fields (`snapshot.ticks[]`)

<ResponseField name="snapshot.ticks[].tick" type="number">
  Lower tick of this liquidity position (same as `lower_tick`).
</ResponseField>

<ResponseField name="snapshot.ticks[].lower_tick" type="number">
  Lower bound of the tick interval.
</ResponseField>

<ResponseField name="snapshot.ticks[].upper_tick" type="number">
  Upper bound of the tick interval (`lower_tick + tick_spacing`).
</ResponseField>

<ResponseField name="snapshot.ticks[].liquidity" type="string">
  Uniswap v3 liquidity value (L) for this tick as an integer string.
</ResponseField>

<ResponseField name="snapshot.ticks[].amount0_raw" type="string">
  Token0 amount at this tick in base units (integer string, no decimals applied).
</ResponseField>

<ResponseField name="snapshot.ticks[].amount0" type="string | null">
  Token0 amount divided by `10^token0_decimals`.
  `null` when decimals are unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<ResponseField name="snapshot.ticks[].amount1_raw" type="string">
  Token1 amount at this tick in base units (integer string, no decimals applied).
</ResponseField>

<ResponseField name="snapshot.ticks[].amount1" type="string | null">
  Token1 amount divided by `10^token1_decimals`.
  `null` when decimals are unavailable or `include_adjusted_amounts` is `false`.
</ResponseField>

<RequestExample>
  ```bash cURL — ±5% window theme={null}
  curl -X POST "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution" \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "chain_id": 1,
    "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
    "from_block": 20000000,
    "to_block": 20001000,
    "price_window_percent": 5.0,
    "include_adjusted_amounts": true
  }'
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution",
      headers={
          "Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
          "Content-Type": "application/json"
      },
      json={
          "chain_id": 1,
          "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
          "from_block": 20000000,
          "to_block": 20001000,
          "price_window_percent": 5.0,
          "include_adjusted_amounts": True
      }
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.blockdb.io/v1/evm/reserves/liquidity-distribution", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "chain_id": 1,
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "from_block": 20000000,
      "to_block": 20001000,
      "price_window_percent": 5.0,
      "include_adjusted_amounts": true
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.Http;
  using System.Net.Http.Headers;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main()
      {
          using var client = new HttpClient();
          client.DefaultRequestHeaders.Authorization =
              new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));

          var payload = new StringContent(
              "{\"chain_id\":1,\"pool_uid\":\"88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000\",\"from_block\":20000000,\"to_block\":20001000,\"price_window_percent\":5.0,\"include_adjusted_amounts\":true}",
              Encoding.UTF8,
              "application/json"
          );

          var response = await client.PostAsync(
              "https://api.blockdb.io/v1/evm/reserves/liquidity-distribution", payload);
          response.EnsureSuccessStatusCode();

          Console.WriteLine(await response.Content.ReadAsStringAsync());
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "chain_id": 1,
    "request_window": {
      "from_block": 20000000,
      "to_block": 20001000,
      "from_timestamp": null,
      "to_timestamp": null
    },
    "filters": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "pool_address": null,
      "pool_id": null,
      "tracing_id": null,
      "price_window_percent": 5.0,
      "include_adjusted_amounts": true
    },
    "snapshot": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 301,
      "block_number": 20000842,
      "block_time": "2025-11-11T18:42:15.123Z",
      "tx_index": 12,
      "log_index": 3,
      "tick_spacing": 60,
      "current_tick": 210130,
      "current_sqrt_price": "14614467034852101032872730522039888223787",
      "price_window_percent": 5.0,
      "resolved_lower_tick": 209580,
      "resolved_upper_tick": 210660,
      "token0_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token1_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "token0_decimals": 18,
      "token1_decimals": 6,
      "ticks": [
        {
          "tick": 210060,
          "lower_tick": 210060,
          "upper_tick": 210120,
          "liquidity": "5823941670000000000000000000",
          "amount0_raw": "1000000000000000000",
          "amount0": "1.0",
          "amount1_raw": "2500000000",
          "amount1": "2500.0"
        },
        {
          "tick": 210120,
          "lower_tick": 210120,
          "upper_tick": 210180,
          "liquidity": "9104823200000000000000000000",
          "amount0_raw": "840000000000000000",
          "amount0": "0.84",
          "amount1_raw": "1890000000",
          "amount1": "1890.0"
        },
        "..."
      ],
      "_tracing_id": "0301000000000000000000000000000000000002"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "http_status": 400,
      "message": "price_window_percent must be between 1 and 10.",
      "hint": "Use a value in [1.0, 10.0], e.g. 5.0 for ±5%.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/evm/reserves/liquidity-distribution"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "http_status": 404,
      "message": "No concentrated-liquidity reserves snapshot was found for the given parameters.",
      "hint": "Verify the pool selector and block/time range. This endpoint only returns snapshots that contain liquidity_values data.",
      "severity": "warning",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/evm/reserves/liquidity-distribution"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "http_status": 401,
      "message": "Invalid or missing API key.",
      "hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request.",
      "severity": "error",
      "retryable": false,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "http_status": 500,
      "message": "An unexpected server error occurred.",
      "severity": "critical",
      "retryable": true,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "error": {
      "code": "SERVICE_UNAVAILABLE",
      "http_status": 503,
      "message": "The service is temporarily unable to handle the request.",
      "hint": "The database connection pool is briefly saturated. Retry after a short delay.",
      "severity": "warning",
      "retryable": true,
      "details": null,
      "docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
    }
  }
  ```
</ResponseExample>