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

# 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](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics) 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><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>`/timeseries/protocol-metrics`</td><td>*coming soon....*</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><thead><tr><th width="290">Metric</th><th>Description</th><th width="90">Frequency</th></tr></thead><tbody><tr><td>`supply_apy`</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>`supply_apy_mean`</td><td>The mean `supply_apy` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`borrow_apy_variable`</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>`borrow_apy_variable_mean`</td><td>The mean `borrow_apy_variable` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`borrow_apy_stable`</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>`borrow_apy_stable_mean`</td><td>The mean `borrow_apy_stable` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`supply_apr`</td><td>The instantaneous non-compounding annual percentage rate suppliers earn on the market's asset, before compounding into `supply_apy`. See [APR versus APY](#apr-versus-apy).</td><td>1d, 1m</td></tr><tr><td>`supply_apr_mean`</td><td>The mean `supply_apr` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`borrow_apr_variable`</td><td>The instantaneous non-compounding annual percentage rate charged to borrowers at the market's variable interest rate, before compounding into `borrow_apy_variable`. See [APR versus APY](#apr-versus-apy).</td><td>1d, 1m</td></tr><tr><td>`borrow_apr_variable_mean`</td><td>The mean `borrow_apr_variable` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`borrow_apr_stable`</td><td>The instantaneous non-compounding annual percentage rate charged to borrowers at the market's stable interest rate, before compounding into `borrow_apy_stable`. See [APR versus APY](#apr-versus-apy).</td><td>1d, 1m</td></tr><tr><td>`borrow_apr_stable_mean`</td><td>The mean `borrow_apr_stable` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`utilization_rate`</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>`utilization_rate_mean`</td><td>The mean `utilization_rate` value over the time interval.</td><td>1d, 1m</td></tr><tr><td>`liquidity_index`</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>`debt_index_variable`</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>

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

## 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](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics#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)

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

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

> [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,borrow_apy_variable,utilization_rate",
>             "frequency": "1d", "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).

## 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 theme={null}
[
  {
    "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 theme={null}
[
  {
    "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 theme={null}
[
  {
    "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](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics#coverage) for how to check current availability against the catalog directly.

## Related

* [Protocol Metrics](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics): the parent page, with the shared entity model and frequency semantics.
* [Liquidity and Size](https://kb.talostrading.com/coinmetrics/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](https://kb.talostrading.com/coinmetrics/network-data/protocol-metrics/risk-parameters.md): the caps and thresholds that bound how far utilization and borrowing can go.
