Skip to main content
POST
/
v1
/
evm
/
tvl
curl -X POST "https://api.blockdb.io/v1/evm/tvl" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "min_tvl_usd": 1000000,
  "limit": 250
}'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "resolved_window": {
      "from_block": 21640000,
      "to_block": 21775000,
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "filters": {
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "min_tvl_usd": 1000000,
      "limit": 250,
      "cursor": null
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "token_amounts": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "tvl_usd": "8750000.00",
      "_tracing_id": "0701c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  ],
  "cursor": null,
  "page_count": 1
}
Not available on the public API yet: This endpoint is scheduled to become available by the end of May 2026. Until then, calls may fail (for example with 404, 403, or 501). For early access or contract timelines, contact support@blockdb.io.

​
Overview

  • Dataset ID: 0701 - Liquidity Pool TVL (USD)
  • Description: Pool TVL (Total Value Locked) snapshots in USD, computed from reserves multiplied by fiat prices. Grain: one row per (pool, event triple); pool_uid → blockdb_evm.b0211_liquidity_pools_v1.
  • CSV Sample: Download
  • JSON Sample: Download

​
Parameters

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

​
Range Filters (mutually exclusive)

​
from_block
number
Starting block number (inclusive) for the query. Use with to_block.
​
to_block
number
Ending block number (inclusive) for the query. Use with from_block.
​
from_timestamp
string
Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with to_timestamp.
​
to_timestamp
string
Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with from_timestamp.
Validation rule:
You must provide either a block range, a time range, or at least one direct selector.
Providing more than one option results in HTTP 400.
Providing none results in HTTP 400.

​
Pool Selectors

​
exchange_ids
number[]
Filter pools by exchange IDs. See the DigitalExchange enumeration for supported values.
​
pool_uids
string[]
Filter by BlockDB pool identifiers (uid from /evm/entities/pools).
​
pool_addresses
string[]
Filter by pool contract addresses (hex string, 20 bytes, no 0x prefix).
​
pool_type_ids
number[]
Filter by AMM archetype. See the PoolType enumeration for supported values.

​
TVL Filters

​
min_tvl_usd
number
Minimum TVL threshold in USD.
​
max_tvl_usd
number
Maximum TVL threshold in USD.

​
Pagination Controls

​
limit
number
default:"250"
Recommended default 250; maximum 1000 to stay under ~10 MB responses.
​
cursor
string
Pagination cursor from a prior call.

​
Response Fields

​
Meta

​
meta
object
Echo of request metadata applied to the response.
​
meta.chain_id
number
EVM chain ID echoed from the request.
​
meta.request_window
object
Pure echo of the window you sent (from_block/to_block/from_timestamp/to_timestamp); unset bounds are null.
​
meta.resolved_window
object | null
The concrete window the query actually executed against, after resolving the request. For a block range on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP), from_timestamp/to_timestamp hold the resolved timestamp window (and from_block/to_block echo your request). For a time range on a block-keyed endpoint, from_block/to_block hold the resolved block range (and the timestamps echo your request). null for selector-only requests (no window). No extra database work is done — these are the values the query already computed.
​
meta.resolved_window.from_block
number | null
Resolved/echoed start block of the executed window.
​
meta.resolved_window.to_block
number | null
Resolved/echoed end block of the executed window.
​
meta.resolved_window.from_timestamp
string | null
Resolved/echoed start timestamp (ISO-8601) of the executed window.
​
meta.resolved_window.to_timestamp
string | null
Resolved/echoed end timestamp (ISO-8601) of the executed window.
​
meta.filters
object
Filters echoed from the request (selectors, TVL filters, pagination state, etc.).

​
Data

​
data
object[]
Array of TVL snapshot records matching the request.
​
data.pool_uid
string
BlockDB pool identifier — 32-byte pool_uid (uid from /evm/entities/pools).
​
data.exchange_id
number
Exchange / DEX identifier for the pool.
​
data.type_id
number
Pool type identifier (AMM archetype).
​
data.block_number
number
Block height of the TVL snapshot.
​
data.block_time
string
UTC timestamp of the TVL snapshot.
​
data.tx_index
number
Zero-based transaction index within the block.
​
data.log_index
number
Zero-based log index within the transaction.
​
data.token_amounts
string[]
Array of token amounts (decimals-adjusted), aligned with pool tokens. Returned as strings to preserve precision.
​
data.tvl_usd
string
Total value locked in USD. Returned as a string to preserve precision.
​
data._tracing_id
string
Row-level lineage hash (hex string, no 0x prefix).
​
data._parent_tracing_ids
string[]
Lineage references of immediate parents.
​
data._created_at
string
Record creation timestamp (ISO-8601).
​
data._updated_at
string
Last update timestamp (ISO-8601).

​
Envelope Fields

​
cursor
string | null
Cursor token for pagination.
​
page_count
number
Number of records returned in data.
curl -X POST "https://api.blockdb.io/v1/evm/tvl" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "min_tvl_usd": 1000000,
  "limit": 250
}'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_block": null,
      "to_block": null,
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "resolved_window": {
      "from_block": 21640000,
      "to_block": 21775000,
      "from_timestamp": "2025-12-01T00:00:00Z",
      "to_timestamp": "2025-12-20T00:00:00Z"
    },
    "filters": {
      "pool_uids": [
        "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
      ],
      "min_tvl_usd": 1000000,
      "limit": 250,
      "cursor": null
    }
  },
  "data": [
    {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "block_number": 19001234,
      "block_time": "2025-12-20T12:34:56Z",
      "tx_index": 7,
      "log_index": 12,
      "token_amounts": [
        "1250.000000000000000000",
        "3950000.000000000000000000"
      ],
      "tvl_usd": "8750000.00",
      "_tracing_id": "0701c0ffee000000000000000000000000000000000000000000000000000001",
      "_parent_tracing_ids": [
        "0301c0ffee000000000000000000000000000000000000000000000000000001"
      ],
      "_created_at": "2025-12-20T12:35:01Z",
      "_updated_at": "2025-12-20T12:35:01Z"
    }
  ],
  "cursor": null,
  "page_count": 1
}
Last modified on May 29, 2026