Index Candles

Overview

An index candle summarizes the movement of a Coin Metrics index over a fixed time interval as a set of open, high, low, and close values. Each candle answers a simple question: over this interval, where did the index open and close, and how far did it move? Candles are the standard input for charting and for technical-analysis indicators, so they let analysts study an index's path over time without pulling every individual level.

Index candles are built by Coin Metrics from its own published Index Levels, not from any exchange-reported series. They cover the Coin Metrics Bletchley Indexes (CMBI) and the third-party index series that Coin Metrics distributes. The intervals and the aggregation rules match those of Market Candles, which makes an index chart directly comparable to a market chart at the same frequency. The one structural difference is that an index has no traded volume, so index candles carry no volume fields.

Index candles are accessed over the HTTP endpoint /timeseries/index-candles.

At a Glance

Data type	Entities	Frequency / cadence	Unit	Primary endpoint	Coverage
Index candles (OHLC)	Indexes (single-asset, multi-asset, momentum, mining, total market, and distributed third-party series)	Fixed intervals: 1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 1d-HH:00. Support varies per index, and some indexes have no candles	Index points, in the index's own denomination	/timeseries/index-candles	🔗

Schema

One observation is a single candle for one index and one interval. Every candle carries the same fields regardless of index type.

Field	Type	Description	Notes
index	string	Name of the index.	Required
time	string (date-time)	The start of the candle interval. ISO 8601, nanosecond precision.	Required. Interval start (see Interval timing)
price_open	string (decimal)	The opening price of the candle.	Required. The first index level in the interval
price_high	string (decimal)	The high price of the candle.	Required
price_low	string (decimal)	The low price of the candle.	Required
price_close	string (decimal)	The closing price of the candle.	Required. The last index level in the interval
candle_trades_count	string (int64)	The number of trades used for candle calculation.	Required. Non-zero only for indexes calculated from trades, and it is not a count of distinct trades (see Trade count)

Conventions. Values are returned as JSON strings to preserve precision. Timestamps are UTC ISO-8601 with nanosecond resolution, and time marks the start of the candle interval, not its end. Prices are index points in the index's own denomination, so candles are comparable across time within one index but not across indexes. Index candles carry no volume fields, because an index is not traded.

Methodology

From levels to candles

Each base candle is computed directly from the Index Levels published inside its interval. Levels are ordered by time within the interval, and the candle fields follow from them:

• price_open is the first level in the interval and price_close is the last.
• price_high and price_low are the maximum and minimum levels in the interval.
• candle_trades_count sums the trade counts attached to those levels (see Trade count).

Only positive levels are considered, so a placeholder or invalid value cannot become a candle's low. For most indexes the base candle is one minute, built from the sub-minute level series. For indexes that publish only an hourly close, the base candle is one hour, built from that close series.

Aggregating to longer intervals

Candles at intervals longer than the base (5m, 10m, 15m, 30m, 1h, 4h, 1d) are built by aggregating the shorter candles that fall inside them. The open is the first sub-candle's open, the close is the last sub-candle's close, the high and low are the maximum and minimum across the sub-candles, and the trade count is summed. Because the aggregation composes, a 1d candle and the one-minute candles inside it describe the same interval consistently.

Interval timing

A candle's time is the start of its interval. A one-minute candle stamped 13:31:00 covers levels from 13:31:00 up to, but not including, 13:32:00. Daily candles are bucketed in UTC by default, and the returned timestamps are always UTC.

Custom daily boundaries (offsets and time zones)

By default a 1d candle covers a UTC calendar day, from 00:00 UTC to the next 00:00 UTC. Two request parameters realign that boundary, which lets you build daily candles that close at a specific local time such as a 4:00 PM New York close.

• timezone moves the day boundary to local midnight in the given TZ database zone. frequency=1d&timezone=Asia/Tokyo returns candles that each cover a Tokyo calendar day, stamped 15:00:00Z because Tokyo midnight is 15:00 the previous day in UTC.
• 1d-HH:00 moves the daily boundary from midnight to the whole hour HH. Combined with timezone, the boundary is HH:00 in that zone. For example, frequency=1d-16:00&timezone=America/New_York returns daily candles running from 16:00 one day to 16:00 the next in New York. Without timezone, the offset is applied in UTC.

Offset daily candles are assembled from the underlying hourly candles, so a few rules follow:

• Both parameters affect 1d only. Sub-daily intervals keep their standard UTC grid, so frequency=4h&timezone=Asia/Tokyo still returns candles at 00:00, 04:00, 08:00 UTC and so on. Passing timezone with a sub-daily frequency changes only how your start_time and end_time are interpreted.
• Offsets are whole hours. HH is 00 through 23 and the minutes are always 00, so 1d-16:00 is valid and 1d-16:30 is not.
• The time field is still the start of the interval, expressed in UTC. For 1d-16:00&timezone=America/New_York, a candle stamped 2026-08-05T20:00:00Z starts at 16:00 New York time on 2026-08-05 (UTC-4 in August) and ends at 16:00 New York time the next day.
• Boundaries track the zone's local time, so they follow daylight-saving changes, and a candle's UTC time shifts by an hour when the zone's offset changes.
• Only complete days are returned. A partial interval at either end of your time range is dropped rather than returned as a short candle.

Trade count

candle_trades_count is carried over from the levels the candle was built from, and its meaning depends on how the index is calculated.

For single-asset indexes, which are computed from collected trades, each published level carries the number of trades in that level's trailing calculation window. The candle sums those counts across every level in the interval. Because consecutive levels share overlapping windows, the same trade contributes to many levels, so the total runs far above the number of distinct trades in the interval. Read it as a relative measure of activity across comparable intervals, not as a trade count.

For multi-asset and other derived indexes, which are computed from reference rates and supply data rather than directly from trades, no trade count is attached to the level, so candle_trades_count is 0. A zero here means the field does not apply to that index, not that the index was flat or that data is missing.

Frequency support

Candle frequencies are published per index, and some indexes, particularly hourly-only series, have no candles at all. The per-index list is in the "Candles" column of the coverage tool, and in /catalog-v2/index-candles. Requesting an unsupported frequency for an index returns an error naming both.

Accessing the Data

Index candles are available over HTTP at /timeseries/index-candles. Choose an interval with the frequency parameter.

Python Client

import os
from datetime import timedelta
from coinmetrics.api_client import CoinMetricsClient

client = CoinMetricsClient(os.environ["CM_API_KEY"])

# 1-hour candles over a time range, fetched in parallel and returned as a DataFrame.
# format="json" is required: this endpoint does not support json_stream, which is
# what the client would otherwise default to.
df = client.get_index_candles(
    indexes=["CMBIBTC", "CMBI10"],
    frequency="1h",
    start_time="2025-01-01",
    end_time="2025-02-01",
    format="json",
).parallel(time_increment=timedelta(days=7)).to_dataframe()

print(df)

# For just the latest candles, use limit_per_index instead (uses format="json"):
# client.get_index_candles(indexes=["CMBIBTC"], frequency="1m", limit_per_index=5).to_dataframe()

Shell

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

Python

import os
import requests

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

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. Supported frequency values are 1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, and 1d-HH:00 for a daily candle whose boundary is offset to a whole hour and time zone (see Custom daily boundaries).

Full parameter reference: see the API Reference for /timeseries/index-candles.

Examples

The examples below show candles for representative indexes. Values are returned as JSON strings.

Example: one-minute candles (/timeseries/index-candles)

The latest one-minute candles for the single-asset CMBIBTC. Run this query.

{
  "data": [
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:31:00.000000000Z",
      "price_open": "64969.1275",
      "price_close": "64968.16",
      "price_high": "64969.1275",
      "price_low": "64968.16",
      "candle_trades_count": "40347"
    },
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:32:00.000000000Z",
      "price_open": "64968.16",
      "price_close": "64970.64",
      "price_high": "64970.65",
      "price_low": "64968.16",
      "candle_trades_count": "39054"
    },
    {
      "index": "CMBIBTC",
      "time": "2026-08-08T13:33:00.000000000Z",
      "price_open": "64970.6399999999994",
      "price_close": "64964.0999999999985",
      "price_high": "64970.6399999999994",
      "price_low": "64964.0999999999985",
      "candle_trades_count": "39050"
    }
  ]
}

Example: daily candles for a multi-asset index (1d)

Daily candles for CMBI10. candle_trades_count is 0 because a multi-asset index is not computed from trades directly (see Trade count). Run this query.

{
  "data": [
    {
      "index": "CMBI10",
      "time": "2026-08-05T00:00:00.000000000Z",
      "price_open": "5673.5071687304162",
      "price_close": "5721.24465990579392",
      "price_high": "5756.24251957474462",
      "price_low": "5651.6329543396987",
      "candle_trades_count": "0"
    },
    {
      "index": "CMBI10",
      "time": "2026-08-06T00:00:00.000000000Z",
      "price_open": "5721.86295959618928",
      "price_close": "5688.34280586638124",
      "price_high": "5745.38746106339386",
      "price_low": "5673.66634097151018",
      "candle_trades_count": "0"
    },
    {
      "index": "CMBI10",
      "time": "2026-08-07T00:00:00.000000000Z",
      "price_open": "5689.31709447708454",
      "price_close": "5732.73828481943019",
      "price_high": "5773.93778435045624",
      "price_low": "5668.33729943295384",
      "candle_trades_count": "0"
    }
  ]
}

Example: New York close daily candles (1d-16:00 + timezone)

Daily candles for CMBIBTC aligned to a 4:00 PM New York close, using frequency=1d-16:00 with timezone=America/New_York. Each time is the interval start in UTC, so 20:00:00Z is 16:00 in New York during Eastern Daylight Time. Run this query.

{
  "data": [
    {
      "index": "CMBIBTC",
      "time": "2026-08-05T20:00:00.000000000Z",
      "price_open": "64822.93",
      "price_close": "64391.97",
      "price_high": "64948.5",
      "price_low": "64100",
      "candle_trades_count": "141334618"
    },
    {
      "index": "CMBIBTC",
      "time": "2026-08-06T20:00:00.000000000Z",
      "price_open": "64396.69",
      "price_close": "64914.01",
      "price_high": "65336.3700000000026",
      "price_low": "64115.51",
      "candle_trades_count": "145484796"
    }
  ]
}

Coverage

Coin Metrics CoverageCoin Metrics Coverage

Usage

• Charting an index. Candles are the standard OHLC input for index charts and for indicators such as moving averages, RSI, and Bollinger Bands.
• Comparing an index against a market. Index candles share their intervals and aggregation rules with Market Candles, so the same frequency lines up directly for benchmark-versus-venue comparisons.
• Reducing data volume. A day of one-second index levels is 86,400 observations. The equivalent 1d candle is one row that still preserves the day's range.
• Aligning to a trading day. Use 1d-HH:00 with timezone to produce daily candles that close at 4:00 PM New York, or at whichever local hour your reporting cycle uses.
• Choosing an interval. Use short intervals (1m, 5m) for intraday work and longer intervals (1h, 1d) for trend and longer-horizon analysis.

Limitations

• No volume fields. An index is not traded, so index candles carry no volume, candle_usd_volume, or vwap. If you need traded volume, use Market Candles for the underlying markets.
• candle_trades_count is not a distinct-trade count. For single-asset indexes it sums overlapping trailing-window counts, so it over-counts. For multi-asset indexes it is always 0. See Trade count.
• Not every index has candles. Candle frequency support is per index, and some hourly-only series have none. Check the "Candles" column in the coverage tool.
• History follows the index. A candle series reaches back only as far as the index levels it is built from.

FAQ

How do index candles differ from market candles?

They share the same intervals, the same interval-start convention, and the same aggregation rules, so charts line up directly. The differences are the input and the fields: index candles are built from Coin Metrics index levels rather than from trades on one venue, and they carry no volume or VWAP fields because an index is not traded.

Why is candle_trades_count zero?

Because the index is not calculated directly from trades. Multi-asset and other derived indexes are computed from reference rates and supply data, so no trade count is attached to their levels and the field is 0. See Trade count.

Why is candle_trades_count so large on single-asset indexes?

Each index level carries the number of trades in its own trailing calculation window, and the candle sums those counts across every level in the interval. Consecutive levels share overlapping windows, so the same trade is counted many times. Treat the number as a relative activity indicator rather than as a count of distinct trades.

What candle intervals are available?

1m, 5m, 10m, 15m, 30m, 1h, 4h, and 1d, plus 1d-HH:00 for a daily candle whose boundary is offset to a specific hour. Support is per index, so check the coverage tool or /catalog-v2/index-candles.

What time does the time field represent?

The start of the candle interval. A one-minute candle stamped 13:31:00 covers 13:31:00 up to 13:32:00.

How do I get daily candles that close at 4 PM New York?

Use frequency=1d-16:00 with timezone=America/New_York. The returned time values stay in UTC, so the interval start appears as 20:00:00Z during Eastern Daylight Time.

Is there a websocket feed for index candles?

No. Index candles are HTTP only. For a real-time index feed, stream Index Levels over /timeseries-stream/index-levels.

Related

• Index Overview: the index families, how to choose between the three data types, and the discovery loop.
• Index Levels: the point-in-time index values these candles are built from.
• Index Constituents: the assets and weights behind a multi-asset index.
• Market Candles: OHLCV candles for an individual market, sharing these intervals and aggregation rules.
• Pair Candles: OHLC candles built from Coin Metrics' cross-exchange reference rate for an asset pair.
• Methodologies: the versioned methodology document for each CMBI series.