> 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/coin-metrics-prices/coin-metrics-prices/principal-market-price-metrics.md). # Principal Market Price Metrics ## Overview The Coin Metrics Principal Market Price is the price of an asset taken from a single market, the one where the asset actually trades most, rather than from an average across many venues. Alongside the price, Coin Metrics publishes the identity of that market, so every price can be traced back to the specific venue and trade it came from. This construction exists to answer an accounting question rather than a trading one: what is the fair value of this asset, measured in the principal market for it, as defined by IFRS 13 and FASB ASC 820. Fund administrators, auditors, and corporate treasury teams use it to value crypto holdings and prepare financial statements. It is also used to set closing prices for indexes and financial benchmarks that require a single observable transaction price rather than a computed average. ## At a Glance
Data typeEntitiesFrequency / cadenceUnitPrimary endpointCoverage
MetricAssets1d, 1d-ny-close, 1h, 1m, 1s (HTTP); 1s, 1h (websocket, price only)USD for the price, a market identifier for the market/timeseries/asset-metrics🔗
## Metrics The family is one calculation that yields two published values: the price, and the identity of the market it was taken from. Both are served from the same underlying record, so requesting them together costs no more than requesting either alone and the two can never disagree.
MetricDescriptionFrequencyCoverage
principal_market_price_usdThe price of an asset quoted in U.S. dollars derived from the asset's principal market, the market with the most trading volume or activity.1d, 1d-ny-close, 1h, 1m, 1s🔗
principal_market_usdThe asset's principal market, the market with the most trading volume or activity. Returned as a Coin Metrics market identifier, for example coinbase-btc-usd-spot.1d, 1d-ny-close, 1h, 1m, 1s🔗
Only the U.S. dollar quotation is published. There is no principal market price in euros, Bitcoin, or Ethereum. {% hint style="info" %} **Conventions.** Decimals are returned as JSON strings to preserve precision. Timestamps are UTC ISO-8601 with nanosecond resolution, and `time` is the instant the value describes. `principal_market_price_usd` is a decimal in U.S. dollars. `principal_market_usd` is not a number: it returns a market identifier string in the standard `exchange-base-quote-type` form, which resolves against [Market Reference Data](/market-data/market-data-overview/market-reference-data.md). Both metrics carry the `_usd` suffix to denote the quotation of the price, so `principal_market_usd` means "the market behind the U.S. dollar price", not "a market denominated in U.S. dollars". {% endhint %} ## Methodology The principal market price is a two-part calculation, repeated once per second for every covered asset: choose the asset's principal market from its constituent markets, then publish the price of the most recent trade on that market. Unlike a reference rate, no averaging or median is applied across venues. The published number is an observed transaction price from one venue. The authoritative statement of the methodology is the [Coin Metrics Prices Methodology](/coin-metrics-prices/methodologies/coin-metrics-prices-methodology.md), which governs these prices alongside the reference rates. The subsections below describe how that methodology behaves in practice. ### Constituent markets and trade collection The candidate venues are the same vetted constituent markets used for the [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md): a rules-based selection per asset, described under [Data Inputs](/coin-metrics-prices/methodologies/coin-metrics-prices-methodology.md#data-inputs) in the methodology and informed by the [Talos Exchange Scorecard](/market-data/methodologies/talos-exchange-scorecard.md). They are centralized exchange spot markets and, where relevant, decentralized exchange pools. Trades on those markets are collected continuously from exchange websocket and REST interfaces and normalized into a common trade record. Only executed transactions are used. Quotes, order book levels, and indicative prices are never inputs. Each version of an asset's constituent market set carries an effective date, so a change to the set takes effect from the start of a day rather than partway through one. ### Selecting the principal market The selection looks at two hours of trading on each constituent market: the **selection window**, the hour immediately before the calculation time, and the **calibration window**, the hour before that. The selection window supplies the volumes and the candidate prices. The calibration window is used only to set the outlier threshold described below. The markets are ranked by traded volume over the selection window, highest first, and then walked in that order. A market is skipped as inactive if its last trade is more than 10 minutes old, or if its last trade is more than 1 minute old and is further in the past than 100 times that market's own average interval between trades. The second condition scales to the market: a venue that normally trades every second is treated as stale far sooner than one that normally trades every minute. A market with no trading at all in the calibration window is also skipped, since there is nothing to calibrate its threshold against. Each remaining candidate is then screened for outlying trades. Within the calibration window, the standard deviation of trade prices is computed for each one-minute interval, and those per-minute figures are averaged and tripled to give a price band: $$\text{band} = 3 \cdot \frac{1}{N}\sum\_{i=1}^{N} \sigma\_i$$ where $$\sigma\_i$$ is the standard deviation of trade prices in the $$i$$-th minute of the calibration window and $$N$$ is the number of minutes in that window with trades. The screen is then applied to the selection window: each one-minute interval is examined in turn, and any trade whose price sits further than the band from that interval's own mean price is discarded. Intervals with fewer than five trades are left unscreened, since a standard deviation over so few observations is not informative. The walk down the volume ranking then resolves as follows. Each candidate that loses trades to the screen has its post-screen volume compared against the best seen so far, and the walk stops as soon as a candidate's screened volume falls below that best, since the raw volumes are already descending and no later candidate can overtake it. The walk also stops at the first candidate that loses no trades at all, which is then selected unless an earlier candidate had already recorded a higher screened volume. The market that wins this walk is the asset's principal market, and is what `principal_market_usd` returns. ### The published price `principal_market_price_usd` is the price of the single most recent trade on the selected principal market as of the calculation time. It is not an average, a median, or a volume-weighted figure over the hour. The hour of trading data is used to choose the market, not to compute the price. This is the substantive difference from the [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md), which blend many venues into one number. A principal market price is an observable transaction on an identifiable venue, which is what fair value measurement under IFRS 13 and ASC 820 calls for. A reference rate is a manipulation-resistant composite, which is what a benchmark fixing calls for. ### Converting to U.S. dollars An asset's principal market is not always quoted in U.S. dollars. Where the winning market is quoted in another currency, the trade price is converted using the Coin Metrics Reference Rate for that currency, so a DOGE/USDT trade on Binance yields a U.S. dollar price by way of the USDT rate. The conversion currencies are Bitcoin, Ethereum, USD Coin, and Tether. This creates a deliberate ordering: Bitcoin and Ethereum are priced first, and their rates then feed the assets that depend on them. The returned `principal_market_usd` still names the market in its native quotation, so it is normal to see a value like `binance-doge-usdt-spot` paired with a U.S. dollar price. ### Frequencies and how each one is produced There is only one calculation, running once per second. Every frequency the API exposes is that same series sampled at a different point, and the value stamped `12:00:00` is the same number whether it is read at `1s`, `1m`, `1h`, or `1d`. * **`1s`** returns the series directly, one value per second. * **`1m`** returns the series sampled on minute boundaries. * **`1h`** returns the series sampled on the hour. * **`1d`** returns the hourly sample once per day, at midnight in the requested `timezone`. That parameter defaults to UTC, so the default daily observation is 00:00 UTC. Setting `timezone=Asia/Tokyo` returns the 15:00 UTC observation instead. * **`1d-ny-close`** returns the daily observation at 16:00 America/New\_York, the standard close reference for U.S. financial products. That lands at 20:00 UTC during daylight saving time and 21:00 UTC outside it. * **A custom daily offset** of the form `1d-HH:MM` returns the daily observation at that time of day, including offsets off the hour such as `1d-10:30`. Because there is a single underlying calculation, values across frequencies are internally consistent. This is unlike the reference rates, where the daily and hourly frequencies and the real-time frequencies come from two different algorithms and are not resamplings of each other. The calculation reads only the hour of trading before its timestamp and is not held back for late-arriving trades, so a value is available at the moment it is stamped rather than several minutes later. ### When no market qualifies If no constituent market has any trades in the preceding hour, or the selected trade price is not a usable number, the previous published value is repeated rather than a null being returned. A flat stretch in a quiet market may therefore reflect this carry-forward rather than a genuinely unchanged price. ## Accessing the Data The metrics are served through one HTTP endpoint and one websocket endpoint: * `/timeseries/asset-metrics` * `/timeseries-stream/asset-metrics` The HTTP endpoint supports the `1d`, `1d-ny-close`, `1h`, `1m`, and `1s` frequencies plus custom `1d-HH:MM` offsets, and serves both metrics. The websocket endpoint supports `1s` and `1h`, and streams `principal_market_price_usd` only. The tabs below pull the hourly price and principal market for BTC. {% tabs %} {% tab title="Python Client" %} ```python from coinmetrics.api_client import CoinMetricsClient from datetime import timedelta import os client = CoinMetricsClient(os.environ["CM_API_KEY"]) df = client.get_asset_metrics( assets=["btc"], metrics=["principal_market_price_usd", "principal_market_usd"], frequency="1h", start_time="2026-01-01", end_time="2026-08-01", format="json_stream", ).parallel(time_increment=timedelta(days=7)).to_dataframe() ``` {% endtab %} {% tab title="Shell" %} ```shell curl --compressed "https://api.coinmetrics.io/v4/timeseries/asset-metrics?assets=btc&metrics=principal_market_price_usd,principal_market_usd&frequency=1h&start_time=2026-01-01&end_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/asset-metrics", params={ "assets": "btc", "metrics": "principal_market_price_usd,principal_market_usd", "frequency": "1h", "start_time": "2026-01-01", "end_time": "2026-08-01", "page_size": 10000, "api_key": os.environ["CM_API_KEY"], }, ).json() ``` {% endtab %} {% endtabs %} For the per-second price, the websocket endpoint delivers each value as it is produced instead of requiring a poll: ```python from coinmetrics.api_client import CoinMetricsClient import os client = CoinMetricsClient(os.environ["CM_API_KEY"]) client.get_stream_asset_metrics( assets=["btc"], metrics=["principal_market_price_usd"], frequency="1s", ).run() ``` Full parameter reference: see the API Reference for [`/timeseries/asset-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesAssetMetrics) and [`/timeseries-stream/asset-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getTimeseriesStreamAssetMetrics). ## Examples ### Example: hourly price with its principal market The two metrics returned together, one row per hour. [Run this query](https://api.coinmetrics.io/v4/timeseries/asset-metrics?assets=btc\&metrics=principal_market_price_usd,principal_market_usd\&frequency=1h\&limit_per_asset=4\&paging_from=end\&page_size=10000\&api_key=YOUR_API_KEY). ```json { "data": [ { "asset": "btc", "time": "2026-08-08T04:00:00.000000000Z", "principal_market_price_usd": "64989.86", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "btc", "time": "2026-08-08T05:00:00.000000000Z", "principal_market_price_usd": "64973.64", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "btc", "time": "2026-08-08T06:00:00.000000000Z", "principal_market_price_usd": "64961", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "btc", "time": "2026-08-08T07:00:00.000000000Z", "principal_market_price_usd": "64965.5", "principal_market_usd": "coinbase-btc-usd-spot" } ] } ``` ### Example: several assets, showing quote conversion DOGE and SOL are priced from USDT-quoted markets, converted to U.S. dollars, while BTC and ETH are priced from markets quoted in U.S. dollars directly. [Run this query](https://api.coinmetrics.io/v4/timeseries/asset-metrics?assets=btc,eth,sol,doge\&metrics=principal_market_price_usd,principal_market_usd\&frequency=1d\&limit_per_asset=1\&paging_from=end\&page_size=10000\&api_key=YOUR_API_KEY). ```json { "data": [ { "asset": "btc", "time": "2026-08-08T00:00:00.000000000Z", "principal_market_price_usd": "64891.61", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "doge", "time": "2026-08-08T00:00:00.000000000Z", "principal_market_price_usd": "0.06961612078057162", "principal_market_usd": "binance-doge-usdt-spot" }, { "asset": "eth", "time": "2026-08-08T00:00:00.000000000Z", "principal_market_price_usd": "1913.15", "principal_market_usd": "coinbase-eth-usd-spot" }, { "asset": "sol", "time": "2026-08-08T00:00:00.000000000Z", "principal_market_price_usd": "73.6241702325471", "principal_market_usd": "binance-sol-usdt-spot" } ] } ``` ### Example: daily price at New York close The observation used as a closing price for U.S. financial products, stamped 20:00 UTC while daylight saving time is in effect. [Run this query](https://api.coinmetrics.io/v4/timeseries/asset-metrics?assets=btc\&metrics=principal_market_price_usd,principal_market_usd\&frequency=1d-ny-close\&limit_per_asset=3\&paging_from=end\&page_size=10000\&api_key=YOUR_API_KEY). ```json { "data": [ { "asset": "btc", "time": "2026-08-05T20:00:00.000000000Z", "principal_market_price_usd": "64794.63", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "btc", "time": "2026-08-06T20:00:00.000000000Z", "principal_market_price_usd": "64390.13", "principal_market_usd": "coinbase-btc-usd-spot" }, { "asset": "btc", "time": "2026-08-07T20:00:00.000000000Z", "principal_market_price_usd": "64914.79", "principal_market_usd": "coinbase-btc-usd-spot" } ] } ``` ### Example: one second stream Messages from `/timeseries-stream/asset-metrics` at `1s`. Note that the stream carries the price only, without the principal market identity. On `cm_sequence_id`, see [the reference rates page](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md#what-is-cm_sequence_id-in-the-websocket-messages). ```json {"time":"2026-08-08T07:02:04.000000000Z","asset":"btc","principal_market_price_usd":"64970.14","cm_sequence_id":"0"} {"time":"2026-08-08T07:02:05.000000000Z","asset":"btc","principal_market_price_usd":"64970.13","cm_sequence_id":"1"} ``` ## Coverage Coverage lists every asset with a principal market price and the available time range. {% embed url="" %} ## Usage * **Value a holding for financial statements.** This is the construction's purpose. It gives a price observed in the asset's principal market, which is what fair value measurement under IFRS 13 and FASB ASC 820 asks for, and `principal_market_usd` supplies the venue attribution an auditor will want alongside it. * **Strike a closing price or a valuation point.** Use `1d-ny-close`, or a custom `1d-HH:MM` offset to match a fund's own valuation time. * **Show provenance in a report.** Pull both metrics together so each price carries the market it came from. The identifier resolves against [Market Reference Data](/market-data/market-data-overview/market-reference-data.md) for the exchange, pair, and market type behind it. * **Track where liquidity sits.** Because the principal market is republished each second, the `principal_market_usd` series is itself a record of which venue dominated an asset's trading over time, and when that changed. * **Compare against a composite price.** Run the principal market price beside the [Reference Rate](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md) for the same asset. Divergence between a single-venue price and a multi-venue composite is often the point of interest. ## Limitations * **Single-venue by construction.** The price comes from one market and one trade, so it carries that venue's idiosyncrasies. It is deliberately not manipulation-resistant in the way a composite is. Where a manipulation-resistant benchmark is required, use the [Reference Rates](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md). * **The principal market can change.** The selection is re-run every second, so an asset's principal market can switch between venues, and does. A price series can therefore contain a step where the venue changed rather than where the market moved. * **Stale-market carry-forward.** When no constituent market trades in the preceding hour, the previous value repeats rather than going null. * **Conversion dependency.** Assets whose principal market is quoted in another currency are converted through the Bitcoin, Ethereum, USD Coin, or Tether reference rate, so error in a conversion rate propagates into the price. * **U.S. dollars only.** There is no principal market price in euros, Bitcoin, or Ethereum. * **The market identity is not streamed.** `/timeseries-stream/asset-metrics` carries `principal_market_price_usd` only. Requesting `principal_market_usd` over the websocket does not produce an error, but the field is absent from the messages. Use the HTTP endpoint when the venue attribution is needed. * **No `200ms` frequency.** Unlike the reference rates, the fastest frequency is `1s`, on both HTTP and the websocket. * **Community keys see seven days.** On a community API key these metrics are limited to the last seven days of history, at every frequency. A pro key is required for full history. ## FAQ ### How is this different from the Reference Rate? The reference rate blends trades from many vetted venues into a manipulation-resistant composite. The principal market price takes the most recent trade from the single venue where the asset trades most. Use the reference rate for a benchmark fixing or settlement, and the principal market price for fair value measurement where an observable transaction in the principal market is required. ### Is the price an average over the hour? No. The preceding hour of trading is used only to rank and screen the markets. Once the principal market is chosen, the published price is the price of its single most recent trade. ### Why is the principal market quoted in USDT when the price is in U.S. dollars? Because the market where an asset trades most is often not quoted in U.S. dollars. The trade price is converted through the Coin Metrics Reference Rate for the quote currency, while `principal_market_usd` continues to name the market in its native quotation. ### Do the two metrics ever disagree? No. They are read from the same stored record, so the market returned is always the one the price was taken from. ### Do values differ between frequencies? No. There is one per-second calculation and every frequency is a sample of it, so the value stamped at a given instant is the same at `1s`, `1m`, `1h`, and `1d`. This differs from the reference rates, where the daily and hourly frequencies use a different algorithm from the real-time ones. ### How do I get a daily price at a time other than midnight UTC? Use a frequency offset. `1d-ny-close` gives 16:00 America/New\_York, and a custom `1d-HH:MM` gives any time of day. ### Which assets have a principal market price? The [coverage page](https://coverage.coinmetrics.io/search-results?query=principal_market%2A) is the authoritative list. Not every asset with a daily and hourly price also has the one-second and one-minute frequencies, which are enabled separately. ## Related * [CM Prices](/coin-metrics-prices/coin-metrics-prices.md): the overview of the Coin Metrics price products. * [Reference Rate Metrics](/coin-metrics-prices/coin-metrics-prices/reference-rate-metrics.md): the manipulation-resistant composite price, calculated across many constituent markets. * [Market Reference Data](/market-data/market-data-overview/market-reference-data.md): resolves the market identifier returned by `principal_market_usd` to its exchange, pair, and market type. * [Coin Metrics Prices Methodology](/coin-metrics-prices/methodologies/coin-metrics-prices-methodology.md): the governing methodology document, including constituent market selection. * [Coin Metrics Prices Policies](/coin-metrics-prices/methodologies/coin-metrics-prices-policies.md): administration, oversight, recalculation, and material change policies. * [Talos Exchange Scorecard](/market-data/methodologies/talos-exchange-scorecard.md): the exchange evaluation that feeds candidate market selection. --- # 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/coin-metrics-prices/coin-metrics-prices/principal-market-price-metrics.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.