> 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/rates-and-yield.md).

# Rates and Yield

## Overview

Rates and yield metrics describe the price of borrowing and lending on a protocol market: what suppliers earn, what borrowers pay in both compounding (APY) and non-compounding (APR) form, how heavily the market is utilized, and the compounding indices those rates accrue against. 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>Lending rates, utilization, and interest-accrual indices</td><td>Protocol markets (protocol + chain + market)</td><td>1d and 1m</td><td>Percent (APY, APR, utilization) or dimensionless (indices)</td><td><code>/timeseries/protocol-metrics</code></td><td><em>coming soon....</em></td></tr></tbody></table>

## Metrics

Supply and borrow rates, in both compounding (APY) and non-compounding (APR) form, and utilization each have an instantaneous form and a `_mean` form (see [APR versus APY](#apr-versus-apy) for how the two forms relate). `liquidity_index` and `debt_index_variable` are compounding indices with no `_mean` form: they only make sense as a running cumulative value, not as an hourly average.

<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>supply_apy</code></td><td>The instantaneous annual percentage yield earned by suppliers of the market's asset, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>supply_apy_mean</code></td><td>The mean <code>supply_apy</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apy_variable</code></td><td>The instantaneous annual percentage yield charged to borrowers at the market's variable interest rate, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apy_variable_mean</code></td><td>The mean <code>borrow_apy_variable</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apy_stable</code></td><td>The instantaneous annual percentage yield charged to borrowers at the market's stable interest rate, closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apy_stable_mean</code></td><td>The mean <code>borrow_apy_stable</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>supply_apr</code></td><td>The instantaneous non-compounding annual percentage rate suppliers earn on the market's asset, before compounding into <code>supply_apy</code>. See <a href="#apr-versus-apy">APR versus APY</a>.</td><td>1d, 1m</td></tr><tr><td><code>supply_apr_mean</code></td><td>The mean <code>supply_apr</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apr_variable</code></td><td>The instantaneous non-compounding annual percentage rate charged to borrowers at the market's variable interest rate, before compounding into <code>borrow_apy_variable</code>. See <a href="#apr-versus-apy">APR versus APY</a>.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apr_variable_mean</code></td><td>The mean <code>borrow_apr_variable</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apr_stable</code></td><td>The instantaneous non-compounding annual percentage rate charged to borrowers at the market's stable interest rate, before compounding into <code>borrow_apy_stable</code>. See <a href="#apr-versus-apy">APR versus APY</a>.</td><td>1d, 1m</td></tr><tr><td><code>borrow_apr_stable_mean</code></td><td>The mean <code>borrow_apr_stable</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>utilization_rate</code></td><td>The instantaneous fraction of supplied liquidity that is currently borrowed (total borrowed divided by total market size), closing value for the interval.</td><td>1d, 1m</td></tr><tr><td><code>utilization_rate_mean</code></td><td>The mean <code>utilization_rate</code> value over the time interval.</td><td>1d, 1m</td></tr><tr><td><code>liquidity_index</code></td><td>A cumulative index that tracks compounded interest accrued to suppliers since the market's inception. Used internally to convert principal into interest-bearing balances.</td><td>1d, 1m</td></tr><tr><td><code>debt_index_variable</code></td><td>A cumulative index that tracks compounded interest accrued on variable-rate debt since the market's inception. Used internally to convert principal debt into its current accrued balance.</td><td>1d, 1m</td></tr></tbody></table>

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

* Metric values are returned as JSON strings to preserve precision.
* `supply_apy`, `borrow_apy_variable`, `borrow_apy_stable`, `supply_apr`, `borrow_apr_variable`, `borrow_apr_stable`, and `utilization_rate` are already scaled: APY and APR values are percentages (for example `1.4575` means 1.4575%) and `utilization_rate` is a fraction between 0 and 1.
* Not every market supports a stable borrow rate. Where it is not offered, `borrow_apy_stable`, `borrow_apy_stable_mean`, `borrow_apr_stable`, and `borrow_apr_stable_mean` are absent rather than zero.
  {% endhint %}

## Methodology

* `supply_apy` and the two borrow APYs are the annualized yields based on the rates the protocol's own interest-rate model publishes for the market at that instant.
* `utilization_rate` is the ratio of borrowed liquidity to total market size, and it is what typically drives the interest-rate model: rates rise as utilization approaches 100%, incentivizing more supply and less borrowing.
* `liquidity_index` and `debt_index_variable` are the running multipliers Aave-style pools use internally so that a static principal balance, multiplied by the current index, yields the current interest-accrued balance without needing to replay every historical rate change.

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

### Protocol Specifics

#### Aave APR vs APY

Aave-style pools track their interest rates on-chain as an APR: a simple, non-compounding annualized rate with no assumption about how often interest is reinvested. `supply_apy`, `borrow_apy_variable`, and `borrow_apy_stable` are the compounding version of that same rate.

`supply_apr`, `borrow_apr_variable`, and `borrow_apr_stable` publish the underlying non-compounding rate directly. APY is always greater than or equal to its corresponding APR for a positive rate. The two are related by:

$$
\mathrm{APY} = \left(1 + \frac{\mathrm{APR}}{n}\right)^{n} - 1
$$

where $$n$$ is the number of compounding periods per year implied by the protocol's interest-accrual cadence (for a per-second accrual model, $$n$$ is the number of seconds in a year).

*Note: Morpho vaults expose APY values directly. These are read from the protocol as is.*

## 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=["supply_apy", "borrow_apy_variable", "utilization_rate"],
    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=supply_apy,borrow_apy_variable,utilization_rate&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": "supply_apy,borrow_apy_variable,utilization_rate",
            "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: daily rates and utilization

`supply_apy`, `borrow_apy_variable`, and `utilization_rate` for the Aave v3 WETH market on Ethereum ([browser](https://api.coinmetrics.io/v4/timeseries/protocol-metrics?markets=core-weth\&metrics=supply_apy,borrow_apy_variable,utilization_rate\&frequency=1d\&page_size=3\&paging_from=end\&api_key=YOUR_API_KEY)):

```json
[
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-07T00:00:00.000000000Z",
    "borrow_apy_variable": "2.11922926594",
    "supply_apy": "1.45753532854",
    "utilization_rate": "0.809169209261718752"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-08T00:00:00.000000000Z",
    "borrow_apy_variable": "2.09759089682",
    "supply_apy": "1.42827312202",
    "utilization_rate": "0.801108789868759973"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-09T00:00:00.000000000Z",
    "borrow_apy_variable": "2.1000111088",
    "supply_apy": "1.43154982822",
    "utilization_rate": "0.80198774294377139"
  }
]
```

### Example: 1m frequency

The same market's `supply_apy` at the 1m frequency, 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:56:00.000000000Z",
    "market_size_total_usd": "4066207708.825581682926940026405",
    "supply_apy": "1.4224161144635605"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-10T19:57:00.000000000Z",
    "market_size_total_usd": "4067596112.53438854564029603356",
    "supply_apy": "1.4223895750835744"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-10T19:58:00.000000000Z",
    "market_size_total_usd": "4067614906.322207655579850468638",
    "supply_apy": "1.4223895750835744"
  }
]
```

### Example: liquidity and debt indices

`liquidity_index` and `debt_index_variable` for the same market ([browser](https://api.coinmetrics.io/v4/timeseries/protocol-metrics?markets=core-weth\&metrics=liquidity_index,debt_index_variable\&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",
    "debt_index_variable": "1.104426312288926397401149293",
    "liquidity_index": "1.06914347979207487347415743"
  },
  {
    "protocol": "aave_v3",
    "market": "core-weth",
    "chain": "ethereum",
    "time": "2026-08-09T00:00:00.000000000Z",
    "debt_index_variable": "1.104489702160771097701198238",
    "liquidity_index": "1.069185273533461987214857589"
  }
]
```

## 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.
* [Liquidity and Size](/network-data/protocol-metrics/liquidity-and-size.md): the total market size, borrowed, and available liquidity figures that `utilization_rate` is computed from.
* [Risk Parameters](/network-data/protocol-metrics/risk-parameters.md): the caps and thresholds that bound how far utilization and borrowing can go.


---

# 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/rates-and-yield.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.