> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TVL Overview

> Access Total Value Locked (TVL) snapshots in USD for liquidity pools across chains.

## Overview

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

| Endpoint                                          | Summary                   | Dataset ID | Typical Latency |
| ------------------------------------------------- | ------------------------- | ---------- | --------------- |
| [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd) | Pool TVL snapshots in USD | `0701`     | \< 300 ms       |

### Parameter Conventions

<ParamField body="chain_id" type="number" required>
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField body="from_block" type="number">
  Starting block height (inclusive) for TVL snapshots.
</ParamField>

<ParamField body="to_block" type="number">
  Ending block height (inclusive) for TVL snapshots.
</ParamField>

<ParamField body="from_timestamp" type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField body="to_timestamp" type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField body="pool_uids" type="string[]">
  BlockDB pool identifiers for filtering TVL data by pool.
</ParamField>

<ParamField body="pool_addresses" type="string[]">
  Pool contract addresses to scope TVL data.
</ParamField>

<ParamField body="min_tvl_usd" type="number">
  Minimum TVL threshold in USD for filtering pools.
</ParamField>

### 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] x 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

* [`POST /evm/tvl`](/api-reference/evm/tvl/tvl-usd) — TVL snapshots endpoint
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Pool reserves (input to TVL)
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield predictions
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications