> 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-constituents.md). # Index Constituents ## Overview An index constituent is a member of an index. For a multi-asset crypto index, a constituent is a cryptoasset, and its weight is the share of the index that the asset accounts for at that moment. Constituent data answers the question behind every index level: what is actually in this index right now, and in what proportion? Constituents are the transparency layer of the Coin Metrics Bletchley Indexes (CMBI) and of the third-party index series that Coin Metrics distributes. Portfolio managers use them to replicate an index, risk teams use them to decompose index exposure into asset exposure, and researchers use the weight history to see how a basket's composition drifted and rebalanced over time. Index constituents are accessed over the HTTP endpoint [`/timeseries/index-constituents`](/api-reference/timeseries/timeseries-rest/index-constituents.md). ## At a Glance
Data typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
Index constituents and weightsIndexes (single-asset, multi-asset, momentum, mining, total market, and distributed third-party series)Hourly for indexes with changing weights. frequency accepts 1h, 1d, 1d-ny-close, 1d-ny-midday, 1d-sg-closeWeight as a decimal fraction of the index, summing to 1/timeseries/index-constituents🔗
## Schema One observation is the full constituent set of a single index at a single timestamp. The `constituents` array holds one entry per member asset, sorted by asset. | 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 composition applies to | | `constituents` | array\[object] | The member assets of the index and their weights at `time`. | Required. One entry per constituent, sorted by asset | Each entry in `constituents` carries these sub-fields: | Sub-field | Type | Description | Notes | | -------------------- | ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset` | string | Unique name of the asset. | Always present. A Coin Metrics asset ID for CMBI indexes, and the provider's own symbol for [third-party indexes](#coin-metrics-indexes-and-third-party-indexes) | | `weight` | string (decimal) | The weight of the constituent. | Always present. A decimal fraction of the index (see [How weights are produced](#how-weights-are-produced)) | | `price` | string (decimal) | The price of the constituent. | Third-party indexes only | | `quantity` | string (decimal) | The quantity of the constituent. | Third-party indexes only | | `weight_basis_value` | string (decimal) | The weight basis value of the constituent. | Third-party indexes only | {% hint style="info" %} **Conventions.** Weights and prices are returned as JSON strings to preserve precision. Timestamps are UTC ISO-8601 with nanosecond resolution, and `time` is the instant the composition applies to rather than the start of a window. Weights are decimal fractions of the index, not percentages, and the weights within one observation sum to 1 up to rounding in the last digits. Constituents are sorted by asset within each observation. {% endhint %} ## Methodology ### How weights are produced For a market-capitalization-weighted index, a constituent's weight is its share of the index's total market capitalization. At the same instant that an [index level](/index-data/index-overview/index-levels.md) is computed, each constituent's index-eligible supply is valued at its US dollar reference rate, and the weight is that value divided by the sum across all constituents: $$ w\_{i,t} = \frac{Q\_i \times P\_{i,t}}{\sum\_{j} Q\_j \times P\_{j,t}} $$ * $$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$$. **Which supply measure fills** $$Q\_i$$ **depends on the series, and the two in use are not interchangeable.** The Multi Asset Series weights by **adjusted free float** market capitalization, which discounts supply that is 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 weights by **estimated** market capitalization instead. Check the [methodology document](/index-data/methodologies.md) for the series you are using rather than assuming free float. Weights therefore drift continuously between rebalances as constituent prices move relative to one another. They are recomputed and stored **once an hour, every hour, including weekends and holidays**, which is the resolution this endpoint publishes. Equal-weighted indexes follow the same shape with a different starting point: the index is divided evenly across constituents at each rebalance, and weights then drift with relative performance until the next rebalance resets them to equal. ### Rebalancing Which assets are in an index, and the supply figures used to weight them, are set on the index's rebalance schedule. A rebalance takes effect at 16:00 New York time. Constituent selection rules are defined per series in the [Methodologies](/index-data/methodologies.md) documents and governed by the [CMBI Index Policies](/index-data/methodologies/cmbi-index-policies.md), with eligible-market rules in the [Candidate Market Guidelines](/index-data/methodologies/candidate-market-guidelines.md). Because the index divisor is reset at each rebalance to preserve continuity, a rebalance shows up in this data as a change in the constituent set or in the weights, and not as a discontinuity in the [index level](/index-data/index-overview/index-levels.md). ### Indexes whose composition does not change Not every index has a drifting basket. A single-asset index has exactly one constituent at a weight of `1`, and the CMBI Mining Series indexes likewise resolve to a single constituent. These indexes have a **fixed** composition rather than an hourly one, so the endpoint stores a single record at the start of the index's history. The two cases behave differently on the wire, and the difference matters when you write a query: * **Changing composition** (multi-asset and momentum indexes): stored hourly, and returned exactly as stored. Gaps are never filled, because a gap could be a real change. * **Fixed composition** (single-asset and mining indexes): stored once. If you request a `frequency`, the last known composition is carried forward so you receive one row per interval across your whole time range. If you omit `frequency`, you receive only the stored record, at its original timestamp. ### Frequency and the default The `frequency` parameter selects the sampling of the returned series. **If you omit it, you get every stored record rather than a sampled one.** How much data that is depends entirely on the index: * For an index whose weights drift, such as a multi-asset index, a record is stored **every hour**, so omitting `frequency` returns an hourly series. Over a month that is roughly 24 times more rows than `frequency=1d`. * For an index whose composition is fixed, such as a single-asset or mining index, there is only ever one stored record, so omitting `frequency` returns that single row at its original timestamp. The API describes this default as returning "only changed constituents", and that is accurate at the storage layer: a record exists because something changed. It is worth being precise about what changed, though. On a market-capitalization index the constituent **weights** change every hour as prices move, while the constituent **set** changes only at a rebalance. So the unsampled series is not a rebalance log, and reconstructing rebalance dates means comparing the asset list between consecutive records rather than counting them. Supported values are `1h`, `1d`, `1d-ny-close`, `1d-ny-midday`, and `1d-sg-close`. The daily shorthands carry their own time zone, so no separate `timezone` parameter is needed: `1d-ny-close` is 16:00 New York, `1d-ny-midday` is 12:00 New York, and `1d-sg-close` is 16:00 Singapore. Returned timestamps are always UTC, so a New York close appears as `20:00:00Z` during Eastern Daylight Time. Because the underlying data is hourly, sub-hourly frequencies are not offered. Plain `1d` samples at 00:00 UTC, and passing `timezone` moves that sample to local midnight in the given zone: `frequency=1d&timezone=Asia/Tokyo` returns one observation per Tokyo day, stamped `15:00:00Z`. With `frequency=1h`, `timezone` changes nothing about which observations you get, only how your `start_time` and `end_time` are read. ### Coin Metrics indexes and third-party indexes Alongside the CMBI series, Coin Metrics distributes constituent data for indexes produced by third-party index providers. These are served through the same endpoint and the same envelope, but their constituent entries are richer: in addition to `asset` and `weight`, a provider index typically supplies `price`, `quantity`, and `weight_basis_value`, which together show how the provider arrived at each weight. Two differences to watch for. First, those three extra fields are **absent for CMBI indexes**, whose entries carry only `asset` and `weight`. Second, the `asset` value on a provider index is the provider's own symbol rather than a Coin Metrics asset ID, so it may appear as something like `BTC-USD` instead of `btc`. ## Accessing the Data Index constituents are available over HTTP at `/timeseries/index-constituents`. There is no websocket feed, because composition is published hourly at most. {% 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 constituent weights over a time range, returned as a DataFrame. # This endpoint does not support json_stream, so leave format at its default. df = client.get_index_constituents( indexes=["CMBI10"], frequency="1d", start_time="2025-01-01", end_time="2025-02-01", ).parallel(time_increment=timedelta(days=7)).to_dataframe() print(df) # Omit frequency to get every stored record instead of a sampled series. # For a multi-asset index that is hourly, so expect roughly 24x more rows: # client.get_index_constituents(indexes=["CMBI10"], start_time="2025-01-01").to_dataframe() ``` {% endtab %} {% tab title="Shell" %} ```shell curl --compressed "https://api.coinmetrics.io/v4/timeseries/index-constituents?indexes=CMBI10&frequency=1d&start_time=2026-08-01&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-constituents", params={ "indexes": "CMBI10", "frequency": "1d", "start_time": "2026-08-01", "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. This endpoint has no per-index row limit, so bound a query with `start_time` and `end_time` rather than by row count. Requesting `format=csv` flattens each observation into one row per constituent, carrying `index`, `time`, `asset`, and `weight`. Full parameter reference: see the API Reference for [`/timeseries/index-constituents`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesIndexConstituents). ## Examples The examples below show constituents for representative indexes. Weights are returned as JSON strings. ### Example: hourly weights for a multi-asset index The latest hourly composition of `CMBI10`. The ten weights sum to 1. [Run this query](https://api.coinmetrics.io/v4/timeseries/index-constituents?indexes=CMBI10\&frequency=1h\&page_size=1\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "data": [ { "index": "CMBI10", "time": "2026-08-08T13:00:00.000000000Z", "constituents": [ { "asset": "ada", "weight": "0.004388832545232537422205579210037017" }, { "asset": "bnb", "weight": "0.05273779870205765714621333182333324" }, { "asset": "btc", "weight": "0.6931201096619557344755545516838591" }, { "asset": "doge", "weight": "0.006534743160786557138067217941759688" }, { "asset": "eth", "weight": "0.139382997897057620099613653118819" }, { "asset": "link", "weight": "0.004424685741616332434912061148642975" }, { "asset": "sol", "weight": "0.0314316379849927800677087510010315" }, { "asset": "trx", "weight": "0.02074865139229890943798866314658388" }, { "asset": "xrp", "weight": "0.04138107583875430733995395972567404" }, { "asset": "zec", "weight": "0.005654082794499847100618764497103202" } ] } ] } ``` ### Example: a single-asset index `CMBIBTC` holds one constituent at a weight of `1`, stored once at the start of its history. Without a `frequency`, the single stored record is returned at its original timestamp. [Run this query](https://api.coinmetrics.io/v4/timeseries/index-constituents?indexes=CMBIBTC\&page_size=2\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "data": [ { "index": "CMBIBTC", "time": "2010-07-18T00:00:00.000000000Z", "constituents": [ { "asset": "btc", "weight": "1" } ] } ] } ``` Adding `frequency=1d` carries that composition forward, one row per day: ```json { "data": [ { "index": "CMBIBTC", "time": "2026-08-06T00:00:00.000000000Z", "constituents": [{ "asset": "btc", "weight": "1" }] }, { "index": "CMBIBTC", "time": "2026-08-07T00:00:00.000000000Z", "constituents": [{ "asset": "btc", "weight": "1" }] }, { "index": "CMBIBTC", "time": "2026-08-08T00:00:00.000000000Z", "constituents": [{ "asset": "btc", "weight": "1" }] } ] } ``` ### Example: a third-party index with full constituent detail A provider index also supplies `price`, `quantity`, and `weight_basis_value` for each constituent. Note that `asset` here is the provider's own symbol rather than a Coin Metrics asset ID. [Run this query](https://api.coinmetrics.io/v4/timeseries/index-constituents?indexes=CD-CD5-USD\&page_size=1\&paging_from=end\&api_key=YOUR_API_KEY). ```json { "data": [ { "index": "CD-CD5-USD", "time": "2026-08-07T19:59:59.000000000Z", "constituents": [ { "asset": "BNB-USD", "weight": "0.0459120060053447", "price": "592.937124710643", "quantity": "0.0826538140425551", "weight_basis_value": "49.0085148447608" }, { "asset": "BTC-USD", "weight": "0.757255171925403", "price": "64918.4058002594", "quantity": "0.0124514427227127", "weight_basis_value": "808.32781147175" }, { "asset": "ETH-USD", "weight": "0.13456811498367", "price": "1917.66142367814", "quantity": "0.0749058109686323", "weight_basis_value": "143.643984103873" }, { "asset": "SOL-USD", "weight": "0.0250683009523173", "price": "73.9662702093152", "quantity": "0.361773251735656", "weight_basis_value": "26.7590180923821" }, { "asset": "XRP-USD", "weight": "0.0371964061332617", "price": "1.02297417497894", "quantity": "38.8133907219814", "weight_basis_value": "39.7050963519542" } ] } ] } ``` ## Coverage {% embed url="" %} ## Usage * **Replication.** The weights are the instruction set for holding an index. Sampling them at `1d-ny-close` gives a reproducible daily target that lines up with a New York close. * **Exposure decomposition.** Multiply index exposure by constituent weights to see the underlying asset exposure, and re-derive it whenever weights drift. * **Rebalance analysis.** Pull the weight history and compare the asset list between consecutive observations. A change in the set of assets marks a rebalance, whereas a change in the weights alone is just price drift. * **Attribution.** Pair a weight history with [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md) for the same assets to attribute index return to individual constituents. * **Transparency and diligence.** The composition of every index is published on the same schedule as its levels, so an index level can always be traced back to what produced it. ## Limitations * **Hourly resolution.** Weights are stored once an hour. Sub-hourly frequencies are not available, even though the [index level](/index-data/index-overview/index-levels.md) itself updates far more often. * **Omitting `frequency` is not a smaller query.** It returns every stored record, which for a multi-asset index is hourly. Set a frequency when you want a sampled series, and expect roughly 24 times more rows without one. * **Gaps are not filled for changing baskets.** For an index whose composition changes hourly, a missing hour is returned as missing rather than carried forward, because a carried-forward value could hide a real change. * **Extra constituent fields are provider-specific.** `price`, `quantity`, and `weight_basis_value` are populated for third-party indexes and absent for CMBI indexes. * **No dedicated catalog endpoint.** There is no `/catalog-v2/index-constituents`. Use `/catalog-v2/index-levels` or `/catalog-all-v2/index-levels` to discover indexes, then query this endpoint. ## FAQ ### Do single-asset indexes return constituents? Yes. A single-asset index returns exactly one constituent at a weight of `1`, and so do the CMBI Mining Series indexes. Their composition is fixed rather than hourly, so a single record is stored, and it is carried forward across your time range when you supply a `frequency`. ### Why did my query return only one row for a whole year? You queried an index whose composition is fixed, such as a single-asset or mining index, without a `frequency`. Those indexes have exactly one stored record. Add `frequency=1d` to carry that composition forward and get one row per day. ### Why did my query return far more rows than I expected? You most likely omitted `frequency` on a multi-asset index. Records are stored hourly, because the weights drift with prices, so an unsampled pull returns roughly 24 times what `frequency=1d` returns. ### Do the weights sum to 1? Yes, within a single observation, up to rounding in the last digits. They are decimal fractions of the index, not percentages, so multiply by 100 to display them as percentages. ### How often do weights change? Continuously in economic terms, and hourly in published terms. Weights drift with constituent prices between rebalances and are recomputed and stored once an hour. The constituent set itself changes only at a rebalance, which takes effect at 16:00 New York time. ### What are `price`, `quantity`, and `weight_basis_value`? They are the provider-supplied inputs behind a weight on a third-party index: the constituent's price, the number of units held per index unit, and the resulting value that the weight is computed from. They are not returned for CMBI indexes. ### Is there a websocket feed for constituents? No. Composition is published hourly at most, so the HTTP endpoint is the only access path. For a real-time feed, stream [Index Levels](/index-data/index-overview/index-levels.md). ### Which indexes have constituent data? Every index served by this endpoint returns constituents, including single-asset and mining indexes with their single fixed member. Discover the index universe through `/catalog-v2/index-levels` or the [coverage tool](https://coverage.coinmetrics.io/indexes-v2). ## 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 index values these weights are computed alongside. * [Index Candles](/index-data/index-overview/index-candles.md): OHLC candles aggregated from index levels. * [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md): the constituent prices used to value the basket. * [Adjusted Free Float Supply Methodology](/index-data/methodologies.md#adjusted-free-float-supply-methodology): how the supply behind each weight is adjusted. * [Candidate Market Guidelines](/index-data/methodologies/candidate-market-guidelines.md): the eligible-market rules behind constituent selection. * [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-constituents.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.