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 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 for how that scope is expressed in the API, and Accessing the Data for how to filter by it.

At a Glance

Data type	Entities	Frequency / cadence	Unit	Primary endpoint	Coverage
DeFi protocol metrics (rates, size, and governance parameters, exact set depends on protocol type)	Protocol markets, identified by the combination of protocol, chain, and market (for example aave_v3 / ethereum / core-weth)	1d and 1m. There is no hourly frequency	Per-metric: percent, U.S. dollars, native units, or dimensionless (see each metrics page)	/timeseries/protocol-metrics	coming soon....

Metrics

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

Category	Covers
Rates and Yield	Supply and borrow APY and APR, utilization rate, and the interest-accrual indices they compound against
Liquidity and Size	Total market size, total borrowed, and total available liquidity, each in native units and U.S. dollars
Risk Parameters	Supply and borrow caps, maximum loan-to-value, liquidation threshold, and liquidation bonus
Vault Metrics	Vault share price and performance fee (vault protocols only)

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 below for what the two forms mean.

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

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

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

Python Client

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()

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"

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)

Full parameter reference: see the API Reference for /timeseries/protocol-metrics.

Protocol Reference Data

/reference-data/protocols 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.

Python Client

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()

Shell

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

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)

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

{
  "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

Coin Metrics CoverageCoin Metrics Coverage

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

• /catalog-all-v2/protocol-metrics: complete availability by protocol, chain, and market, independent of the requesting key.
• /catalog-v2/protocol-metrics: the same view, restricted to what a key is entitled to.

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: supply and borrow APY, utilization, and interest-accrual indices.
• Liquidity and Size: total market size, borrowed, and available liquidity.
• Risk Parameters: caps, loan-to-value, and liquidation parameters.
• Vault Metrics: vault share price and performance fee.