Skip to main content

​
Description

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

​
Endpoint Matrix

EndpointSummaryDataset IDTypical Latency
POST /evm/reservesNormalized pool reserve snapshots with tick/bin data0301< 250 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_details
boolean
Include tick-range or bin-level liquidity breakdowns for concentrated liquidity pools.

​
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 details — Enable include_details for Uniswap v3/v4 pools to analyze tick distribution
  • Cache recent snapshots — Latest reserve states change frequently; cache with short TTL (1-5 minutes)

​
Reserve Data Models

Even-Distribution Pools (Uniswap v2, SushiSwap):
  • reserves: Array of token balances
  • current_tick: null
  • current_sqrt_price: null
Concentrated Liquidity (Uniswap v3/v4):
  • reserves: null
  • current_tick: Active tick position
  • current_sqrt_price: Q64.96 sqrt price
  • details: Tick-range liquidity breakdowns
Bin-Based Pools (TraderJoe v2):
  • current_bin: Active bin identifier
  • details: Bin-level liquidity data

​
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"
}
Get reserves for all Uniswap v3 pools: 
{
  "chain_id": 1,
  "pool_type_ids": [
    2
  ],
  "from_block": 18000000
}
Analyze concentrated liquidity: 
{
  "chain_id": 1,
  "pool_uids": [
    "0x..."
  ],
  "include_details": true
}

​
Dataset Relationships

  • Pools → Reserves: Join pool metadata to reserve snapshots using pool_uid
  • 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