> 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-candles.md). # 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](/index-data/index-overview/index-levels.md), 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](/market-data/market-data-overview/market-candles.md), 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`](https://docs.coinmetrics.io/api/v4#operation/getTimeseriesIndexCandles). ## At a Glance
Data typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
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 candlesIndex 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](#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](#trade-count)) | {% hint style="info" %} **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. {% endhint %} ## Methodology ### From levels to candles Each base candle is computed directly from the [Index Levels](/index-data/index-overview/index-levels.md) 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](#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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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](https://coverage.coinmetrics.io/indexes-v2), 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. {% 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"]) # 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() ``` {% endtab %} {% tab title="Shell" %} ```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" ``` {% endtab %} {% tab title="Python" %} ```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() ``` {% 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. 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](#custom-daily-boundaries-offsets-and-time-zones)). Full parameter reference: see the API Reference for [`/timeseries/index-candles`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesIndexCandles). ## 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](https://api.coinmetrics.io/v4/timeseries/index-candles?indexes=CMBIBTC\&frequency=1m\&limit_per_index=3\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "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](#trade-count)). [Run this query](https://api.coinmetrics.io/v4/timeseries/index-candles?indexes=CMBI10\&frequency=1d\&limit_per_index=3\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "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](https://api.coinmetrics.io/v4/timeseries/index-candles?indexes=CMBIBTC\&frequency=1d-16:00\&timezone=America/New_York\&limit_per_index=2\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "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 {% embed url="" %} ## 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](/market-data/market-data-overview/market-candles.md), 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](/market-data/market-data-overview/market-candles.md) 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](#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](#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](/index-data/index-overview/index-levels.md) over `/timeseries-stream/index-levels`. ## Related * [Index Overview](/index-data/index-overview.md): the index families, how to choose between the three data types, and the discovery loop. * [Index Levels](/index-data/index-overview/index-levels.md): the point-in-time index values these candles are built from. * [Index Constituents](/index-data/index-overview/index-constituents.md): the assets and weights behind a multi-asset index. * [Market Candles](/market-data/market-data-overview/market-candles.md): OHLCV candles for an individual market, sharing these intervals and aggregation rules. * [Pair Candles](/market-data/market-data-overview/pair-candles.md): OHLC candles built from Coin Metrics' cross-exchange reference rate for an asset pair. * [Methodologies](/index-data/methodologies.md): the versioned methodology document for each CMBI series. --- # 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-candles.md?ask=&goal= ``` `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.