> 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/index-data/index-overview/index-levels.md).

# Index Levels

## Overview

An index level is the published value of a Coin Metrics index at a point in time. It is the single number that summarizes what the index measures, whether that is the market value of one asset, the capitalization-weighted performance of a basket, or the aggregate work securing a network. Each level answers one question: as of this timestamp, where does the index stand?

Index levels are the primary output of the Coin Metrics Bletchley Indexes (CMBI) and of the third-party index series that Coin Metrics distributes. Asset managers use them as the reference for benchmarks and structured products, exchanges use them for settlement, and researchers use them as a consistent performance series that does not depend on any one venue.

Index levels can be accessed via the following endpoints:

* Historical levels over the HTTP endpoint [`/timeseries/index-levels`](https://docs.coinmetrics.io/api/v4#operation/getTimeseriesIndexLevels)
* A real-time streaming feed over the websocket endpoint [`/timeseries-stream/index-levels`](https://docs.coinmetrics.io/api/v4#operation/getTimeseriesStreamIndexLevels)

## 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 endpoints</th><th>Coverage</th></tr></thead><tbody><tr><td>Index levels</td><td>Indexes (single-asset, multi-asset, momentum, mining, total market, and distributed third-party series)</td><td>Coin Metrics indexes: <code>1s</code>, <code>15s</code>, <code>1h</code>, <code>1d</code>, <code>1d-ny-close</code>, <code>1d-sg-close</code>, <code>1d-HH:00</code>. Third-party indexes publish their own native frequency. Support varies per index</td><td>Index points, in the index's own denomination</td><td><code>/timeseries/index-levels</code><br><br><code>/timeseries-stream/index-levels</code></td><td><a href="https://coverage.coinmetrics.io/indexes-v2">🔗</a></td></tr></tbody></table>

## Schema

One observation is the level of a single index at a single timestamp. The websocket feed carries the same fields and adds a `cm_sequence_id`. The columns below are the response schema for `/timeseries/index-levels`.

| Field            | Type               | Description                                                                                | Notes                                                                                                                              |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `index`          | string             | Name of the index.                                                                         | Required                                                                                                                           |
| `time`           | string (date-time) | The time in ISO 8601 date-time format. Always with nanoseconds precision.                  | Required. The instant the level applies to (see [Frequencies and daily closes](#frequencies-and-daily-closes))                     |
| `level`          | string (decimal)   | The value of the index.                                                                    | Required                                                                                                                           |
| `verification`   | object             | Information about verification.                                                            | Optional. Returned only with `include_verification=true`, and only for indexes that publish it (see [Verification](#verification)) |
| `cm_sequence_id` | string             | Per-connection message sequence number for ordering a live stream. Resets on reconnection. | Websocket messages only                                                                                                            |

The `verification` object carries these sub-fields:

| Sub-field   | Type               | Description                          |
| ----------- | ------------------ | ------------------------------------ |
| `timestamp` | string (date-time) | The verification time of the index.  |
| `level`     | string (decimal)   | The verification value of the index. |
| `signature` | string             | The signature information.           |

{% hint style="info" %}
**Conventions.** Levels are returned as JSON strings to preserve precision. Timestamps are UTC ISO-8601 with nanosecond resolution, and `time` is the instant the level applies to rather than the start of a window. A level is expressed in the index's own points, so levels are comparable across time within one index but not across indexes. The websocket feed adds a per-connection `cm_sequence_id` for ordering.
{% endhint %}

## Methodology

Every Coin Metrics index resolves to the same output shape, a level at a timestamp, but the calculation behind that level depends on what the index is designed to measure. The subsections below describe the mechanics in plain language. The authoritative, versioned methodology for each series is published under [Methodologies](/index-data/methodologies.md), and the rules governing market events, forks, and index changes are in the [CMBI Index Policies](/index-data/methodologies/cmbi-index-policies.md).

### Single-asset indexes

A single-asset index tracks the market value of one cryptoasset. Its level is computed continuously from the individual trades that Coin Metrics collects across a defined set of eligible markets for that asset, using the same market-selection discipline as the Coin Metrics [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md).

At each calculation instant, the trades from each eligible market over a trailing window are summarized into a per-market price and volume. Markets whose most recent trade is stale relative to the observed trading pace are set aside, so an inactive venue cannot pin the index. Each remaining market is then weighted by a blend of its share of volume and the inverse of its price variance, so venues that trade more, and trade with less dispersion, count for more. The index level is the volume-and-variance weighted median of the per-market prices, which makes the level robust to a single outlying venue rather than sensitive to it.

Because the level is a weighted median over a trailing window, it moves continuously with the market and does not reset on any fixed schedule.

### Multi-asset market-capitalization indexes

A market-capitalization index tracks a basket of assets weighted by their market capitalization. At each calculation instant, each constituent's index-eligible supply is valued at its current US dollar reference rate, those values are summed, and the sum is scaled by a divisor:

$$
\text{Level}*t = \frac{\sum*{i} Q\_i \times P\_{i,t}}{D}
$$

* $$Q\_i$$: the index-eligible supply of constituent $$i$$, as defined by that index's series methodology.
* $$P\_{i,t}$$: the US dollar reference rate for constituent $$i$$ at time $$t$$.
* $$D$$: the index divisor, held fixed between rebalances.

**The supply measure differs by series.** The Multi Asset Series uses **adjusted free float** supply, which discounts holdings that are restricted or effectively unavailable to the market (see the [Adjusted Free Float Supply Methodology](/index-data/methodologies.md#adjusted-free-float-supply-methodology)). The Total Market Series uses **estimated** supply, giving an estimated rather than free-float market capitalization. Consult the [methodology document](/index-data/methodologies.md) for the series you are using.

Each constituent's weight is its share of that sum, which is what the [Index Constituents](/index-data/index-overview/index-constituents.md) endpoint publishes.

Constituent selection and supply inputs are refreshed on the index's rebalance schedule, which takes effect at 16:00 New York time. At each rebalance the divisor is reset so that the level computed from the new basket equals the level computed from the old basket at the moment of the change:

$$
D\_{\text{new}} = D\_{\text{old}} \times \frac{\text{Sum}*{\text{new}}}{\text{Sum}*{\text{old}}}
$$

This is what keeps the series continuous. A rebalance changes what the index holds without introducing a jump in what it reports, so levels remain comparable across the full history.

### Equal-weighted indexes

An equal-weighted index starts each rebalance period holding the same dollar amount in every constituent. At the rebalance, the index value is divided evenly across constituents to produce a per-asset multiplier, and between rebalances the level is the sum of those multipliers valued at current reference rates. Weights then drift with relative performance until the next rebalance resets them to equal.

### Mining and network indexes

The CMBI Mining Series measures network work rather than price, so its levels are derived from on-chain network data instead of from market prices. The methodology documents for that series are published under [Methodologies](/index-data/methodologies.md).

### Frequencies and daily closes

The `frequency` parameter selects which published series you receive. `time` is the instant the level applies to, not the start of an interval.

* `1s` and `15s` are intraday series computed at that cadence.
* `1h` is the hourly close, the level at the top of each hour.
* `1d` is the daily close at 00:00 UTC, unless you pass `timezone`, which moves it to local midnight in that zone. `frequency=1d&timezone=Asia/Tokyo` returns Tokyo midnight closes, stamped `15:00:00Z`.
* `1d-ny-close` is 16:00 New York time and `1d-sg-close` is 16:00 Singapore time. Each shorthand carries its own time zone, so no separate `timezone` parameter is needed. Returned timestamps are still UTC, so a New York close appears as `20:00:00Z` during Eastern Daylight Time.
* `1d-HH:00` takes a daily close at the whole hour `HH`, applied in UTC unless a `timezone` is supplied.

`timezone` only relocates a **daily** close. With a sub-daily frequency it changes nothing about which instants you get back, only how your `start_time` and `end_time` are interpreted. In every case the returned `time` is rendered in UTC rather than in the requested zone, which is why a relocated boundary shows up as an offset-looking timestamp such as `15:00:00Z`.

**Not every index publishes every frequency.** Real-time single-asset indexes carry `1s`, multi-asset indexes typically start at `15s`, and some series are hourly only. Requesting a frequency an index does not publish returns a `bad_parameter` error naming the index. The per-index frequency list is available from the [coverage tool](https://coverage.coinmetrics.io/indexes-v2) and from `/catalog-v2/index-levels`.

The list above describes the indexes Coin Metrics calculates. **A third-party index publishes its own native frequency instead, and rejects the values above.** A provider may publish once per second, or only at a single daily fixing, so there is no shared default: `frequency=1s` is right for one provider index and an error for another, and `frequency=1d` works for no third-party index at all. Read the value off `/catalog-v2/index-levels` before querying, then see [External and third-party indexes](#external-and-third-party-indexes) for reshaping it.

### Verification

Some indexes are published together with a signed verification record, which lets a consumer confirm that a level came from Coin Metrics unaltered. Pass `include_verification=true` to receive it. The response then carries a `verification` object holding the verified timestamp, the verified level, and the signature. Indexes that do not publish verification data simply omit the object, so the flag is safe to set on any request.

### External and third-party indexes

Most of the indexes on this endpoint are not calculated by Coin Metrics. Alongside the CMBI series, Coin Metrics distributes index levels produced by third-party index providers, including crypto benchmark administrators and traditional-finance interest rate benchmarks. They are served through the same endpoint and the same schema, and they differ only in how you select and reshape the series.

**Selecting.** Pass the provider's native frequency, which `/catalog-v2/index-levels` reports per index. A provider that publishes continuously exposes `frequency=1s`, and one that publishes a single daily fixing exposes only that fixing, such as `frequency=1d-ldn-close`.

**Reshaping.** The `granularity` parameter downsamples a native series to a daily boundary, and it applies to these external indexes only. It accepts `raw` (the default, meaning no downsampling), `1d-ny-close`, `1d-ldn-close`, `1d-sg-close`, their `-last-second` variants, and custom `1d-HH:00` offsets. So a provider index published every second can be read as a New York close series with `frequency=1s&granularity=1d-ny-close`, and the returned timestamps land on that boundary. `granularity` is ignored for indexes calculated by Coin Metrics, which publish their daily closes as first-class frequencies instead.

## Accessing the Data

Index levels are available over HTTP at `/timeseries/index-levels` for historical queries, and as a real-time websocket feed at `/timeseries-stream/index-levels`.

### Historical levels (HTTP)

Choose a series with the `frequency` parameter.

{% 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"])

# Daily closes over a time range, fetched in parallel and returned as a DataFrame.
df = client.get_index_levels(
    indexes=["CMBIBTC", "CMBI10"],
    frequency="1d",
    start_time="2025-01-01",
    end_time="2025-02-01",
    format="json_stream",
).parallel(time_increment=timedelta(days=7)).to_dataframe()

print(df)

# For just the latest levels, use limit_per_index instead (uses format="json"):
# client.get_index_levels(indexes=["CMBIBTC"], frequency="1s", limit_per_index=5).to_dataframe()
```

{% endtab %}

{% tab title="Shell" %}

```shell
curl --compressed "https://api.coinmetrics.io/v4/timeseries/index-levels?indexes=CMBIBTC&frequency=1s&limit_per_index=5&page_size=10000&api_key=$CM_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

response = requests.get(
    "https://api.coinmetrics.io/v4/timeseries/index-levels",
    params={
        "indexes": "CMBIBTC",
        "frequency": "1s",
        "limit_per_index": 5,
        "page_size": 10000,
        "api_key": os.environ["CM_API_KEY"],
    },
).json()
```

{% endtab %}
{% endtabs %}

The `indexes` parameter accepts a comma-separated list or wildcard patterns such as `CMBI*` or `*BTC`, so you can query many indexes in one call. Set `include_verification=true` to receive the signed [verification](#verification) record where an index publishes one.

### Real-time stream (websocket)

The stream pushes each new level as it is computed, carrying a per-connection `cm_sequence_id` for ordering.

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

```python
stream = client.get_stream_index_levels(indexes=["CMBIBTC"])
stream.run()   # prints levels as they arrive, Ctrl-C to stop
```

{% endtab %}

{% tab title="Shell" %}

```shell
websocat "wss://api.coinmetrics.io/v4/timeseries-stream/index-levels?indexes=CMBIBTC&api_key=$CM_API_KEY"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
ws = new WebSocket("wss://api.coinmetrics.io/v4/timeseries-stream/index-levels?indexes=CMBIBTC&api_key=<YOUR_API_KEY>")
ws.onmessage = m => console.log(m.data)
ws.onclose = () => console.log("closed")
```

{% endtab %}
{% endtabs %}

Full parameter reference: see the API Reference for [`/timeseries/index-levels`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesIndexLevels) and [`/timeseries-stream/index-levels`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesStreamIndexLevels).

## Examples

The examples below show levels for representative indexes. Levels are returned as JSON strings.

### Example: one-second levels (`/timeseries/index-levels`)

The latest one-second levels for `CMBIBTC`. [Run this query](https://api.coinmetrics.io/v4/timeseries/index-levels?indexes=CMBIBTC\&frequency=1s\&limit_per_index=3\&paging_from=end\&api_key=YOUR_API_KEY).

```json
{
  "data": [
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:33:58.000000000Z",
      "level": "64964.1"
    },
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:33:59.000000000Z",
      "level": "64964.1"
    },
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:34:00.000000000Z",
      "level": "64964.1"
    }
  ]
}
```

### Example: New York close daily levels (`1d-ny-close`)

Daily closes for the multi-asset `CMBI10` at 16:00 New York time. Each `time` is the close instant in UTC, so `20:00:00Z` is 16:00 in New York during Eastern Daylight Time. [Run this query](https://api.coinmetrics.io/v4/timeseries/index-levels?indexes=CMBI10\&frequency=1d-ny-close\&limit_per_index=3\&paging_from=end\&api_key=YOUR_API_KEY).

```json
{
  "data": [
    {
      "index": "CMBI10",
      "time": "2026-08-05T20:00:00.000000000Z",
      "level": "5748.59813146804"
    },
    {
      "index": "CMBI10",
      "time": "2026-08-06T20:00:00.000000000Z",
      "level": "5696.85788386351"
    },
    {
      "index": "CMBI10",
      "time": "2026-08-07T20:00:00.000000000Z",
      "level": "5737.14467775557"
    }
  ]
}
```

### Example: real-time stream (`/timeseries-stream/index-levels`)

Messages from `wss://api.coinmetrics.io/v4/timeseries-stream/index-levels?indexes=CMBIBTC`. Each message carries an incrementing `cm_sequence_id`:

```json
{"index": "CMBIBTC", "time": "2026-08-08T13:34:01.000000000Z", "level": "64964.1", "cm_sequence_id": "0"}
{"index": "CMBIBTC", "time": "2026-08-08T13:34:02.000000000Z", "level": "64964.1", "cm_sequence_id": "1"}
{"index": "CMBIBTC", "time": "2026-08-08T13:34:03.000000000Z", "level": "64964.1", "cm_sequence_id": "2"}
{"index": "CMBIBTC", "time": "2026-08-08T13:34:04.000000000Z", "level": "64964.1", "cm_sequence_id": "3"}
```

## Coverage

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

## Usage

* **Benchmarking.** A single-asset index gives a venue-independent performance series for one asset, and a multi-asset index gives one for a defined basket. Both are designed to be referenced by third parties rather than recomputed by them.
* **Settlement and product reference.** Daily-close frequencies exist so that products can settle against a named, reproducible point in time such as a 16:00 New York close.
* **Real-time consumption.** The websocket feed and the `1s` frequency suit dashboards and trading systems that need the current level rather than a historical series.
* **Aligning across time zones.** Use `1d-ny-close`, `1d-sg-close`, or `1d-HH:00` with `timezone` to line index closes up with the trading day that matters to you.
* **Charting.** For open, high, low, and close over an interval rather than a point-in-time level, use [Index Candles](/index-data/index-overview/index-candles.md), which are built from these levels.

## Limitations

* **Frequency support varies by index.** No index publishes every frequency. Check the per-index list before assuming a series exists, or a request will return a `bad_parameter` error.
* **Levels are not comparable across indexes.** An index level is expressed in its own points on its own base, so the ratio of two indexes' levels is not meaningful. Compare returns, not levels.
* **Verification is not universal.** `include_verification=true` returns a record only for indexes that publish one. The flag is accepted for all indexes, but the object is absent where there is nothing to verify against.
* **`granularity` applies to external indexes only.** It is ignored for indexes calculated by Coin Metrics.

## FAQ

### What is the difference between an index level and a reference rate?

A [Reference Rate](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md) is a price for an asset, expressed in a quote currency such as US dollars. An index level is the value of an index, expressed in that index's own points. A single-asset index is built with the same market-selection and aggregation discipline as a reference rate, but it is a distinct, governed product with its own methodology document and its own eligible-market rules.

### Which frequencies does a given index publish?

That varies by index. Look it up in the [coverage tool](https://coverage.coinmetrics.io/indexes-v2) or query `/catalog-v2/index-levels`, which returns the available frequencies and the time range for each. This is not optional for a third-party index, which publishes only its provider's native frequency rather than the Coin Metrics set.

### What time is a `1d` level taken at?

00:00 UTC. For other daily boundaries use `1d-ny-close` (16:00 New York), `1d-sg-close` (16:00 Singapore), or `1d-HH:00` with an optional `timezone`.

### Does `time` mark the start of an interval?

No. A level is a point-in-time value, so `time` is the instant the level applies to. Interval semantics apply to [Index Candles](/index-data/index-overview/index-candles.md), where `time` is the start of the candle.

### Why did my request return "frequency is not supported for index"?

The index does not publish that series. Multi-asset indexes, for example, generally publish `15s` rather than `1s`. Check the per-index frequency list in the coverage tool.

### How do I get the constituents behind a multi-asset index level?

Use the [Index Constituents](/index-data/index-overview/index-constituents.md) endpoint, which publishes the assets and their weights at the same timestamps.

## Related

* [Index Overview](/index-data/index-overview.md): the index families, how to choose between the three data types, and the discovery loop.
* [Index Candles](/index-data/index-overview/index-candles.md): OHLC candles aggregated from these levels.
* [Index Constituents](/index-data/index-overview/index-constituents.md): the assets and weights behind a multi-asset index level.
* [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md): the asset prices that feed multi-asset index calculations.
* [Methodologies](/index-data/methodologies.md): the versioned methodology document for each CMBI series.
* [CMBI Index Policies](/index-data/methodologies/cmbi-index-policies.md): how market events, forks, and index changes are handled.
* [Indexes Glossary](/index-data/indexes-glossary.md): definitions of the index terms used on this page.


---

# 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/index-data/index-overview/index-levels.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.