Skip to main content

​
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

EndpointSummaryDataset IDTypical Latency
POST /v1/evm/reservesNormalized reserve snapshots with decimals-adjusted amounts0301< 250 ms
POST /v1/evm/reserves/liquidity-distributionPer-tick liquidity distribution for concentrated liquidity pools0301< 400 ms

​
Parameter Conventions

​
from_block
number
Starting block height (inclusive) for reserve snapshots.
​
to_block
number
Ending block height (inclusive) for reserve snapshots.
​
from_timestamp
string
Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
​
to_timestamp
string
Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
​
pool_uids
string[]
BlockDB pool identifiers for direct lookups.
​
pool_addresses
string[]
Pool contract addresses to scope reserve data.
​
pool_ids
string[]
Provider-specific pool identifiers when applicable.
​
exchange_ids
number[]
Exchange identifiers for filtering by DEX protocol.
​
pool_type_ids
number[]
AMM model filters. Use Pool Type enumeration values.
​
chain_id
number
required
Chain identifier for the target EVM network. See Chain enumeration for supported values.
​
include_adjusted_amounts
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.

​
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 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
Bin-Based Pools (TraderJoe v2, Aerodrome Slipstream):
  • current_bin: Active bin identifier

​
Common Patterns

Track pool reserves over time: 
{
  "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): 
{
  "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): 
{
  "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

Last modified on May 28, 2026