> For the complete documentation index, see [llms.txt](https://gitbook-docs.coinmetrics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook-docs.coinmetrics.io/network-data/protocol-metrics/liquidity-and-size.md).

# Liquidity and Size

## Overview

Liquidity and size metrics describe how large a protocol market is: the total value supplied, the total value borrowed against it, and what remains available to borrow. Each is published in the market's native asset units, and in U.S. dollars where available. They are part of the [Protocol Metrics](/network-data/protocol-metrics.md) family. See that page for the shared entity model (protocol, chain, market), the beginning-of-interval timestamp convention, and for what an instantaneous value versus a `_mean` value represents at each frequency.

## At a Glance

<table data-full-width="true"><thead><tr><th>Data type</th><th>Entities</th><th width="159">Frequency / cadence</th><th>Unit</th><th>Primary endpoint</th><th>Coverage</th></tr></thead><tbody><tr><td>Total market size, total borrowed, and total available liquidity</td><td>Protocol markets (protocol + chain + market)</td><td>1d and 1m</td><td>Native units, and U.S. dollars where available</td><td><code>/timeseries/protocol-metrics</code></td><td><em>coming soon....</em></td></tr></tbody></table>

## Metrics

Each of the three quantities (market size, borrowed, available liquidity) is published in four forms: native units, U.S. dollars, and the `_mean` of each.

### Total market size

The sum of everything supplied to the market: what is currently borrowed plus what remains available.

<table data-full-width="true"><thead><tr><th width="290">Metric</th><th>Description</th><th width="90">Frequency</th></tr></thead><tbody><tr><td><code>market_size_total_ntv</code></td><td>Total value supplied to the market, in the market's native asset units, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>market_size_total_usd</code></td><td>Total value supplied to the market, in U.S. dollars, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>market_size_total_mean_ntv</code></td><td>The mean <code>market_size_total_ntv</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>market_size_total_mean_usd</code></td><td>The mean <code>market_size_total_usd</code> value over the time interval.</td><td>1d, 1m</td></tr></tbody></table>

### Total borrowed

The sum of everything currently borrowed from the market.

<table data-full-width="true"><thead><tr><th width="290">Metric</th><th>Description</th><th width="90">Frequency</th></tr></thead><tbody><tr><td><code>borrowed_total_ntv</code></td><td>Total value borrowed from the market, in the market's native asset units, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>borrowed_total_usd</code></td><td>Total value borrowed from the market, in U.S. dollars, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>borrowed_total_mean_ntv</code></td><td>The mean <code>borrowed_total_ntv</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>borrowed_total_mean_usd</code></td><td>The mean <code>borrowed_total_usd</code> value over the time interval.</td><td>1d, 1m</td></tr></tbody></table>

### Total available liquidity

The sum of everything supplied to the market that is not currently borrowed (total market size minus total borrowed).\
This metric is often referred to as **Total Value Locked (TVL)** in the industry for many protocols.

<table data-full-width="true"><thead><tr><th width="290">Metric</th><th>Description</th><th width="90">Frequency</th></tr></thead><tbody><tr><td><code>liquidity_total_available_ntv</code></td><td>Value available to borrow or withdraw from the market, in the market's native asset units.<br>For lending pools, this metric is often referred to as Total Value Locked (TVL) in the industry for many protocols.</td><td>1d, 1m</td></tr><tr><td><code>liquidity_total_available_usd</code></td><td>Value available to borrow from the market, in U.S. dollars.<br>For lending pools, this metric is often referred to as Total Value Locked (TVL) in the industry for many protocols.</td><td>1d, 1m</td></tr><tr><td><code>liquidity_total_available_mean_ntv</code></td><td>The mean <code>liquidity_total_available_ntv</code> value over the time interval.<br>For lending pools, this metric is often referred to as Total Value Locked (TVL) in the industry for many protocols.</td><td>1d, 1m</td></tr><tr><td><code>liquidity_total_available_mean_usd</code></td><td>The mean <code>liquidity_total_available_usd</code> value over the time interval.<br>For lending pools, this metric is often referred to as Total Value Locked (TVL) in the industry for many protocols.</td><td>1d, 1m</td></tr></tbody></table>

{% hint style="info" %}
**Conventions.**

* Metric values are returned as JSON strings to preserve precision.
* `time` marks the beginning of the interval a row covers (see [Protocol Metrics: Conventions](/network-data/protocol-metrics.md#at-a-glance)).
* The `_ntv` variants are denominated in the market's own asset (for example WETH for the Aave v3 WETH market).
* The `_usd` variants convert the native value to U.S. dollars, where available: a market whose underlying asset has no Reference Rate in our coverage universe has no `_usd` values, even though its `_ntv` values are published.
* `market_size_total` = `borrowed_total` + `liquidity_total_available`, in either unit, at the same instant.
  {% endhint %}

## Methodology

See [Protocol Metrics: Frequency and the daily mean](/network-data/protocol-metrics.md#frequency-and-the-daily-mean) for how the instantaneous and `_mean` forms differ at each frequency, and the worked example below for how close the two forms are in practice.

### Total borrowed and available liquidity by protocol type

`borrowed_total` and `liquidity_total_available` are not computed the same way across protocol types: each reads a different piece of on-chain state depending on how the protocol itself represents "what is out on loan" versus "what could still be lent."

* **For Aave v3 markets**, available liquidity is the market's aToken total supply minus the sum of its outstanding stable and variable debt, read live from Aave's Pool and ProtocolDataProvider contracts.
* **For Morpho v1 (MetaMorpho) vaults**, available liquidity is the sum, across every market in the vault's withdraw queue, of the lesser of (a) the vault's own supplied position in that market and (b) that market's idle (unborrowed) cash. This reflects that a depositor can withdraw at most the vault's own position, further capped by whatever unborrowed liquidity the underlying market actually holds.

## Accessing the Data

* [`/timeseries/protocol-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesProtocolMetrics)

{% tabs %}
{% tab title="Python Client" %}

```python
import os
from coinmetrics.api_client import CoinMetricsClient

client = CoinMetricsClient(os.environ["CM_API_KEY"])

df = client.get_protocol_metrics(
    protocols="aave_v3",
    markets="core-weth",
    metrics=["market_size_total_usd", "borrowed_total_usd", "liquidity_total_available_usd"],
    frequency="1d",
).to_dataframe()
```

{% endtab %}

{% tab title="Shell" %}

```shell
curl --compressed "https://api.coinmetrics.io/v4/timeseries/protocol-metrics?protocols=aave_v3&markets=core-weth&metrics=market_size_total_usd,borrowed_total_usd,liquidity_total_available_usd&frequency=1d&page_size=10000&api_key=$CM_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

response = requests.get(
    "https://api.coinmetrics.io/v4/timeseries/protocol-metrics",
    params={"protocols": "aave_v3", "markets": "core-weth",
            "metrics": "market_size_total_usd,borrowed_total_usd,liquidity_total_available_usd",
            "frequency": "1d", "page_size": 10000, "api_key": os.environ["CM_API_KEY"]},
).json()
print(response)
```

{% endtab %}
{% endtabs %}

Full parameter reference: see the API Reference for [`/timeseries/protocol-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesProtocolMetrics).

## Examples

The examples below are live pulls, returned as JSON strings, and change on each pull.

### Example: instantaneous vs. mean

`borrowed_total_usd` (closing value) alongside `borrowed_total_mean_usd` (mean of the day's hourly closes) for the same market and day. The two values are close but not identical, consistent with [Protocol Metrics: Frequency and the daily mean](/network-data/protocol-metrics.md#frequency-and-the-daily-mean) ([browser](https://api.coinmetrics.io/v4/timeseries/protocol-metrics?markets=core-weth\&metrics=borrowed_total_usd,borrowed_total_mean_usd\&frequency=1d\&page_size=2\&paging_from=end\&api_key=YOUR_API_KEY)):

```json
[
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-08T00:00:00.000000000Z",
    "borrowed_total_mean_usd": "3320124519.06076767475416114713670911616",
    "borrowed_total_usd": "3319583954.5182641728724592"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-09T00:00:00.000000000Z",
    "borrowed_total_mean_usd": "3310788004.28508721667503704457928648472",
    "borrowed_total_usd": "3312187009.3059277421429076"
  }
]
```

### Example: total market size at the 1m frequency

`market_size_total_usd` for the same market, close to real time ([browser](https://api.coinmetrics.io/v4/timeseries/protocol-metrics?markets=core-weth\&metrics=supply_apy,market_size_total_usd\&frequency=1m\&page_size=3\&paging_from=end\&api_key=YOUR_API_KEY)):

```json
[
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-10T19:57:00.000000000Z",
    "market_size_total_usd": "4067596112.53438854564029603356"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-10T19:58:00.000000000Z",
    "market_size_total_usd": "4067614906.322207655579850468638"
  }
]
```

## Coverage

See [Protocol Metrics: Coverage](/network-data/protocol-metrics.md#coverage) for how to check current availability against the catalog directly.

## Related

* [Protocol Metrics](/network-data/protocol-metrics.md): the parent page, with the shared entity model and frequency semantics.
* [Rates and Yield](/network-data/protocol-metrics/rates-and-yield.md): `utilization_rate`, which is computed from `borrowed_total` and `market_size_total`.
* [Risk Parameters](/network-data/protocol-metrics/risk-parameters.md): the supply and borrow caps that bound how large these figures can grow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook-docs.coinmetrics.io/network-data/protocol-metrics/liquidity-and-size.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.