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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
}'
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": True
}
)
data = response.json()
print(data)
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
})
});
const data = await response.json();
console.log(data);
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\":\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\",\"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());
}
}
{
"chain_id": 1,
"request_window": {
"from_block": 20000000,
"to_block": 20001000,
"from_timestamp": null,
"to_timestamp": null
},
"filters": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"pool_address": null,
"pool_id": null,
"tracing_id": null,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
},
"snapshot": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 20000842,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 12,
"log_index": 3,
"tick_spacing": 10,
"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": "030100000000000000000000000000000002"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
Reserves
Liquidity Distribution
On-demand per-tick liquidity and token amounts for concentrated liquidity pools.
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
}'
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": True
}
)
data = response.json()
print(data)
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
})
});
const data = await response.json();
console.log(data);
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\":\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\",\"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());
}
}
{
"chain_id": 1,
"request_window": {
"from_block": 20000000,
"to_block": 20001000,
"from_timestamp": null,
"to_timestamp": null
},
"filters": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"pool_address": null,
"pool_id": null,
"tracing_id": null,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
},
"snapshot": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 20000842,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 12,
"log_index": 3,
"tick_spacing": 10,
"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": "030100000000000000000000000000000002"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
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_valuesblob — no pre-aggregated detail table is queried. - CSV Sample: Download
- JSON Sample: Download
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
Target EVM network. See the Chain enumeration.
Pool Selector (exactly one required)
BlockDB 32-byte pool identifier (hex, no
0x). For address-based pools, the 20-byte
contract_address left-padded with 12 zero bytes (24 hex chars).Provide exactly one of
pool_uid, pool_address, or pool_id. Providing more or fewer results in HTTP 400.Snapshot Selector (exactly one required)
Direct snapshot key (18-byte hex, exactly 36 characters, no
0x). When set, block/time range must not be provided.Starting block number (inclusive). Use with
to_block. The most recent snapshot within the range is returned.Price Window
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
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
Snapshot Fields
ERC-20 decimals for token0.
null when unavailable or include_adjusted_amounts is false.ERC-20 decimals for token1.
null when unavailable or include_adjusted_amounts is false.Ordered array of tick rows within the resolved range. Only ticks with non-zero liquidity are included.
Tick Row Fields (snapshot.ticks[])
Token0 amount divided by
10^token0_decimals.
null when decimals are unavailable or include_adjusted_amounts is false.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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
}'
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": True
}
)
data = response.json()
print(data)
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": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"from_block": 20000000,
"to_block": 20001000,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
})
});
const data = await response.json();
console.log(data);
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\":\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\",\"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());
}
}
{
"chain_id": 1,
"request_window": {
"from_block": 20000000,
"to_block": 20001000,
"from_timestamp": null,
"to_timestamp": null
},
"filters": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"pool_address": null,
"pool_id": null,
"tracing_id": null,
"price_window_percent": 5.0,
"include_adjusted_amounts": true
},
"snapshot": {
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 20000842,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 12,
"log_index": 3,
"tick_spacing": 10,
"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": "030100000000000000000000000000000002"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
Last modified on July 19, 2026
Was this page helpful?