> 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.md).

# Protocol Metrics

## Overview

Protocol metrics describe the on-chain state of a DeFi protocol: the rates it pays and charges, the size of what it holds, and the parameters that govern how it can be used. They are computed directly from the protocol's own on-chain contracts rather than from a market's trades or order book, so they answer a different question than market data does: not "what did this asset trade for," but "what is this protocol doing right now." Protocol engineers, risk teams, and researchers use them to monitor rates and utilization, track how much value a protocol market holds over time, and watch governance-set parameters change as protocols update them. The specific metrics available depend on the protocol type. See [At a Glance](#at-a-glance) for what is covered today.

A protocol metric is always scoped to a **protocol market**: a specific market or vault within a specific protocol deployment on a specific chain, for example the WETH lending market on Aave v3 on Ethereum, or a specific Morpho vault. See [At a Glance](#at-a-glance) for how that scope is expressed in the API, and [Accessing the Data](#accessing-the-data) for how to filter by it.

## 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>DeFi protocol metrics (rates, size, and governance parameters, exact set depends on protocol type)</td><td>Protocol markets, identified by the combination of protocol, chain, and market (for example <code>aave_v3</code> / <code>ethereum</code> / <code>core-weth</code>)</td><td>1d and 1m. There is no hourly frequency</td><td>Per-metric: percent, U.S. dollars, native units, or dimensionless (see each metrics page)</td><td><code>/timeseries/protocol-metrics</code></td><td><em>coming soon....</em></td></tr></tbody></table>

## Metrics

Every metric on every page is available at both the 1d and 1m frequency (see [Frequency and the daily mean](#frequency-and-the-daily-mean)).

<table data-full-width="true"><thead><tr><th width="220">Category</th><th>Covers</th></tr></thead><tbody><tr><td><a href="/pages/1WBsvDcW5dEOwYIkGdVG">Rates and Yield</a></td><td>Supply and borrow APY and APR, utilization rate, and the interest-accrual indices they compound against</td></tr><tr><td><a href="/pages/zQ8MdOzzXNJzZCyTW4dR">Liquidity and Size</a></td><td>Total market size, total borrowed, and total available liquidity, each in native units and U.S. dollars</td></tr><tr><td><a href="/pages/iArw1oJ0qUt8dRLKhuaX">Risk Parameters</a></td><td>Supply and borrow caps, maximum loan-to-value, liquidation threshold, and liquidation bonus</td></tr><tr><td><a href="/pages/BaWbViIjuxHaeox5oAFw">Vault Metrics</a></td><td>Vault share price and performance fee (vault protocols only)</td></tr></tbody></table>

Most metrics come in two forms: an instantaneous value and a `_mean` variant. Not every category has both, since risk parameters (caps, LTV, thresholds) do not have a `_mean` form. See each page's Metrics table for which of its metrics carry which form, and [Frequency and the daily mean](#frequency-and-the-daily-mean) below for what the two forms mean.

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

* Metric values are returned as JSON strings to preserve precision.
* Timestamps are UTC ISO-8601 with nanosecond resolution.
* `time` marks the **beginning** of the interval the row covers, not the end: a `1d` row timestamped `00:00:00` covers that whole day going forward, and a `1m` row timestamped `HH:MM:00` covers that minute going forward.
* Every response row also carries `protocol`, `chain`, and `market`, identifying which protocol market the row describes.
* `_usd` metrics are published only where Coin Metrics has a reference rate for the market's underlying asset (where available): where no reference rate exists, the `_usd` variant is absent even though the native-unit (`_ntv`) variant is published.
  {% endhint %}

## Methodology

### Entity model

Every protocol metric row is keyed by three fields: `protocol` (the protocol deployment, for example `aave_v3` or `morpho_vaults_v1`), `chain` (the chain the deployment runs on, for example `ethereum`), and `market` (the specific market or vault within that protocol, for example `core-weth` or `ausdc`). A market ID is only unique within its protocol, so a query should generally scope by `protocols` and/or `markets` together rather than by market alone. [Protocol Reference Data](#protocol-reference-data) resolves the full list of markets available under a protocol, along with the on-chain contract addresses and asset each one references.

### Frequency and the daily mean

Every metric is available at two frequencies: 1m and 1d. There is no 1h frequency on this endpoint. At both frequencies, the timestamp convention used is the **beginning of interval convention**. For additional details refer to our [FAQs](https://docs.coinmetrics.io/resources/faqs#what-timestamp-conventions-does-coin-metrics-use). Instantaneous metrics and their `_mean` counterpart mean different things:

* At the **1m** frequency:
  * An **instantaneous** metric (no `_mean` suffix, for example `borrowed_total_usd`) is the closing (point-in-time) reading for that minute.
  * A **`_mean`** metric (for example `borrowed_total_mean_usd`) is the average of the metric's value across every block produced during that minute, rather than a single closing reading.
* At the **1d** frequency:
  * An **instantaneous** metric is the closing reading at the end of the day.
  * A **`_mean`** metric is the mean of the metric's closing value for each hour over the day: the protocol's internal calculation samples the metric once per hour at the end of the hour and averages those 24 hourly closes into the daily value. This is why a `_mean` metric and its instantaneous counterpart carry close but not identical values on the same day (see the [Liquidity and Size example](/network-data/protocol-metrics/liquidity-and-size.md#example-instantaneous-vs-mean)).

There is no 1h frequency to query directly. The hourly sampling behind the 1d `_mean` figures is an internal step in computing that value, not a separately queryable series.

## Accessing the Data

All protocol metrics are served on one endpoint. Filter by any combination of `protocols`, `chains`, and `markets`, pass the metric names in `metrics`, and set `frequency` to `1d` or `1m`.

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

The example below pulls `supply_apy` for the Aave v3 WETH market on Ethereum over a time range.

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

```python
import os
from datetime import timedelta
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="supply_apy",
    frequency="1d",
    start_time="2026-07-01",
    end_time="2026-08-01",
    format="json_stream",
).parallel(time_increment=timedelta(days=30)).to_dataframe()
```

{% endtab %}

{% tab title="Shell" %}

```shell
curl --compressed "https://api.coinmetrics.io/v4/timeseries/protocol-metrics?protocols=aave_v3&markets=core-weth&metrics=supply_apy&frequency=1d&start_time=2026-07-01&end_time=2026-08-01&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": "supply_apy",
            "frequency": "1d", "start_time": "2026-07-01", "end_time": "2026-08-01",
            "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).

### Protocol Reference Data

[`/reference-data/protocols`](https://docs.coinmetrics.io/api/v4/#operation/getReferenceDataProtocols) lists every protocol market, its `full_name`, its `type` (for example `aave_pool` or `morpho_vault`), and the on-chain contract details for each chain it runs on. Use it to discover which `market` values exist under a `protocol` before querying the timeseries endpoint.

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

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

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

protocols = client.reference_data_protocols(protocols="aave_v3").to_dataframe()
```

{% endtab %}

{% tab title="Shell" %}

```shell
curl --compressed "https://api.coinmetrics.io/v4/reference-data/protocols?protocols=aave_v3&page_size=3&api_key=$CM_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

response = requests.get(
    "https://api.coinmetrics.io/v4/reference-data/protocols",
    params={"protocols": "aave_v3", "page_size": 3, "api_key": os.environ["CM_API_KEY"]},
).json()
print(response)
```

{% endtab %}
{% endtabs %}

Responses are paginated: the Python client follows pagination automatically, while direct HTTP callers page through results using `next_page_token`.

```json
{
  "data": [
    {
      "market": "core-1inch",
      "full_name": "Core Aave Market 1inch",
      "protocol": "aave_v3",
      "type": "aave_pool",
      "chains": [
        {
          "chain": "ethereum",
          "address": "0x87870bca3f3fd6335c3f4ce8392d69350b4fa4e2",
          "asset": "1inch",
          "asset_address": "0x111111111117dc0aa78b770fa6a738034120c302",
          "asset_decimals": "18",
          "configurator_address": "0x64b761d848206f447fe2dd461b0c635ec39ebb27",
          "atoken_address": "0x71aef7b30728b9bb371578f36c5a1f1502a5723e",
          "variable_debt_token_address": "0xa38fca8c6bf9bda52e76eb78f08caa3be7c5a970",
          "stable_debt_token_address": "0x102633152313c81cd80419b6ecf66d14ad68949a"
        }
      ]
    }
  ]
}
```

The `chains[]` object carries different fields depending on the protocol's `type`. An `aave_pool` market carries lending-market fields such as `atoken_address` and `variable_debt_token_address`, while a `morpho_vault` market carries vault fields such as `curator_address` instead.

## Coverage

{% embed url="<https://coverage.coinmetrics.io/protocols-v2>" %}

To check what protocols are available right now, query the catalog directly:

* [`/catalog-all-v2/protocol-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getCatalogAllV2ProtocolMetrics): complete availability by protocol, chain, and market, independent of the requesting key.
* [`/catalog-v2/protocol-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getCatalogV2ProtocolMetrics): the same view, restricted to what a key is entitled to.

```shell
curl --compressed "https://api.coinmetrics.io/v4/catalog-all-v2/protocol-metrics?page_size=10000&api_key=$CM_API_KEY"
```

## Limitations

* **No hourly frequency.** Only 1d and 1m are available. The hourly sampling behind the `_mean` daily figures is not itself queryable.
* **Market IDs are not globally unique.** A `market` value is only unique within its `protocol`, so queries that filter by `markets` without also filtering by `protocols` can be ambiguous if the same market name is reused across protocols in the future.

## Related

* [Rates and Yield](/network-data/protocol-metrics/rates-and-yield.md): supply and borrow APY, utilization, and interest-accrual indices.
* [Liquidity and Size](/network-data/protocol-metrics/liquidity-and-size.md): total market size, borrowed, and available liquidity.
* [Risk Parameters](/network-data/protocol-metrics/risk-parameters.md): caps, loan-to-value, and liquidation parameters.
* [Vault Metrics](/network-data/protocol-metrics/vault-metrics.md): vault share price and performance fee.


---

# 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.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.