Skip to main content
POST
/
v1
/
evm
/
reserves
/
liquidity-distribution
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
}'

{
  "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"
  }
}

​
Overview

  • Dataset ID: 0301 - Liquidity Pool 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
  • JSON Sample: Download
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
For even-distribution pools (Uniswap v2, Balancer, etc.) use POST /v1/evm/reserves.

​
Parameters

​
chain_id
number
required
Target EVM network. See the Chain enumeration.

​
Pool Selector (exactly one required)

​
pool_uid
string
BlockDB 32-byte pool identifier (hex, no 0x).
​
pool_address
string
Pool contract address (hex, 20 bytes, no 0x).
​
pool_id
string
Protocol-specific pool ID, e.g. Uniswap V4 pool_id (hex, 32 bytes, no 0x).
Provide exactly one of pool_uid, pool_address, or pool_id. Providing more or fewer results in HTTP 400.

​
Snapshot Selector (exactly one required)

​
tracing_id
string
Direct snapshot key (hex, no 0x). When set, block/time range must not be provided.
​
from_block
number
Starting block number (inclusive). Use with to_block. The most recent snapshot within the range is returned.
​
to_block
number
Ending block number (inclusive). Use with from_block.
​
from_timestamp
string
Starting timestamp (ISO-8601). Use with to_timestamp.
​
to_timestamp
string
Ending timestamp (ISO-8601). Use with from_timestamp.

​
Price Window

​
price_window_percent
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.

​
Amounts

​
include_adjusted_amounts
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.

​
Response Fields

​
Envelope

​
chain_id
number
EVM chain ID echoed from the request.
​
request_window
object
Block/timestamp bounds echoed from the request.
​
filters
object
Filters echoed from the request.
​
snapshot
object
The single resolved snapshot.

​
Snapshot Fields

​
snapshot.pool_uid
string
BlockDB pool identifier.
​
snapshot.exchange_id
number
Exchange identifier.
​
snapshot.type_id
number
Pool type identifier.
​
snapshot.block_number
number
Block height of the snapshot.
​
snapshot.block_time
string
Block timestamp (ISO-8601).
​
snapshot.tx_index
number
Transaction index within the block.
​
snapshot.log_index
number
Log index within the transaction.
​
snapshot.tick_spacing
number
Pool tick spacing (e.g. 60 for a 0.3% Uniswap v3 pool).
​
snapshot.current_tick
number
Active tick at the time of the snapshot.
​
snapshot.current_sqrt_price
string
Q64.96 sqrt price as an integer string.
​
snapshot.price_window_percent
number
Echoed from the request.
​
snapshot.resolved_lower_tick
number
Actual lower bound of the tick range returned (aligned to tick spacing).
​
snapshot.resolved_upper_tick
number
Actual upper bound of the tick range returned.
​
snapshot.token0_address
string | null
Token0 contract address (hex, no 0x). Populated when pool metadata is available.
​
snapshot.token1_address
string | null
Token1 contract address (hex, no 0x). Populated when pool metadata is available.
​
snapshot.token0_decimals
number | null
ERC-20 decimals for token0. null when unavailable or include_adjusted_amounts is false.
​
snapshot.token1_decimals
number | null
ERC-20 decimals for token1. null when unavailable or include_adjusted_amounts is false.
​
snapshot.ticks
object[]
Ordered array of tick rows within the resolved range. Only ticks with non-zero liquidity are included.
​
snapshot._tracing_id
string
Lineage hash for the snapshot row.

​
Tick Row Fields (snapshot.ticks[])

​
snapshot.ticks[].tick
number
Lower tick of this liquidity position (same as lower_tick).
​
snapshot.ticks[].lower_tick
number
Lower bound of the tick interval.
​
snapshot.ticks[].upper_tick
number
Upper bound of the tick interval (lower_tick + tick_spacing).
​
snapshot.ticks[].liquidity
string
Uniswap v3 liquidity value (L) for this tick as an integer string.
​
snapshot.ticks[].amount0_raw
string
Token0 amount at this tick in base units (integer string, no decimals applied).
​
snapshot.ticks[].amount0
string | null
Token0 amount divided by 10^token0_decimals. null when decimals are unavailable or include_adjusted_amounts is false.
​
snapshot.ticks[].amount1_raw
string
Token1 amount at this tick in base units (integer string, no decimals applied).
​
snapshot.ticks[].amount1
string | null
Token1 amount divided by 10^token1_decimals. null when decimals are unavailable or include_adjusted_amounts is false.
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
}'

{
  "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"
  }
}
Last modified on May 29, 2026