Skip to main content

​
Description

The TVL endpoint provides Total Value Locked snapshots in USD for liquidity pools. Each snapshot represents the pool’s total value computed from reserves multiplied by fiat prices, providing a standardized USD-denominated measure of pool liquidity at each on-chain event.

​
Endpoint Matrix

EndpointSummaryDataset IDTypical Latency
POST /evm/tvlPool TVL snapshots in USD0601< 300 ms

​
Parameter Conventions

​
chain_id
number
required
Chain identifier for the target EVM network. See Chain enumeration for supported values.
​
from_block
number
Starting block height (inclusive) for TVL snapshots.
​
to_block
number
Ending block height (inclusive) for TVL 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 filtering TVL data by pool.
​
pool_addresses
string[]
Pool contract addresses to scope TVL data.
​
min_tvl_usd
number
Minimum TVL threshold in USD for filtering pools.

​
Usage Guidance

  • Pool ranking — Use TVL to rank pools by liquidity depth
  • Liquidity migration — Track TVL changes over time to identify liquidity flows
  • Protocol health — Monitor aggregate TVL across pools for protocol-level metrics
  • Risk assessment — Filter pools by minimum TVL for routing and execution quality
  • Dashboards — Build TVL charts and leaderboards with full provenance

​
TVL Calculation

TVL is computed as: 
tvl_usd = sum(token_amounts[i] × fiat_price[i])
Where:
  • token_amounts[i] is the decimals-adjusted reserve amount for token i
  • fiat_price[i] is the USD price for token i at the snapshot time

​
Common Patterns

Rank pools by TVL: 
{
  "chain_id": 1,
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z",
  "min_tvl_usd": 1000000
}
Get TVL history for specific pools: 
{
  "chain_id": 1,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_block": 19000000,
  "to_block": 19100000
}

​
Dataset Relationships

  • Reserves → TVL: Reserve snapshots provide token amounts for TVL calculation
  • Prices → TVL: Fiat prices provide USD conversion for TVL
  • Pools → TVL: Join pool metadata to TVL snapshots using pool_uid
  • TVL → Yields: TVL can be used alongside yields for liquidity-adjusted ROI analysis

​
See Also