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

# 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><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 `aave_v3` / `ethereum` / `core-weth`)</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>`/timeseries/protocol-metrics`</td><td>*coming soon....*</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><thead><tr><th width="220">Category</th><th>Covers</th></tr></thead><tbody><tr><td>[Rates and Yield](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/rates-and-yield.md)</td><td>Supply and borrow APY and APR, utilization rate, and the interest-accrual indices they compound against</td></tr><tr><td>[Liquidity and Size](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/liquidity-and-size.md)</td><td>Total market size, total borrowed, and total available liquidity, each in native units and U.S. dollars</td></tr><tr><td>[Risk Parameters](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/risk-parameters.md)</td><td>Supply and borrow caps, maximum loan-to-value, liquidation threshold, and liquidation bonus</td></tr><tr><td>[Vault Metrics](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/vault-metrics.md)</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.

> [!NOTE]
>
> **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.

## 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://kb.talostrading.com/coinmetrics/service-and-support/faqs.md#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](https://kb.talostrading.com/coinmetrics/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.

> [tab] Python Client
>
> ```python theme={null}
> 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()
> ```

> [tab] Shell
>
> ```shell theme={null}
> 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"
> ```

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

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.

> [tab] Python Client
>
> ```python theme={null}
> 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()
> ```

> [tab] Shell
>
> ```shell theme={null}
> curl --compressed "https://api.coinmetrics.io/v4/reference-data/protocols?protocols=aave_v3&page_size=3&api_key=$CM_API_KEY"
> ```

> [tab] Python
>
> ```python theme={null}
> 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)
> ```

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

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

[https://coverage.coinmetrics.io/protocols-v2](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 theme={null}
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](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/rates-and-yield.md): supply and borrow APY, utilization, and interest-accrual indices.
* [Liquidity and Size](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/liquidity-and-size.md): total market size, borrowed, and available liquidity.
* [Risk Parameters](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/risk-parameters.md): caps, loan-to-value, and liquidation parameters.
* [Vault Metrics](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/vault-metrics.md): vault share price and performance fee.
