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

# Market Data Overview

The [Coin Metrics Market Data Feed](https://coinmetrics.io/market-data-feed/) (MDF) provides historical and real-time data from the world's leading centralized and [decentralized](/network-data/defi-data-overview/decentralized-exchange-data.md) spot and derivatives crypto exchanges. Coin Metrics collects data directly from each venue, harmonizes the differing formats into a single schema, and publishes it alongside a set of metrics calculated on top of it. This section documents every data type and metric family in the feed.

If the feed is new to you, read the three orientation sections below first. They cover the one distinction (raw data versus metrics) and the one naming convention (entities) that together determine which endpoint you call and what you pass to it, followed by the discovery loop that almost every query against the API follows. After that, jump to the group that matches what you are trying to measure.

## Raw Data and Metrics

Every page in this section documents one of two things, and the difference decides which endpoint you query.

**Raw data** is what a venue reported, harmonized but not aggregated. A trade is one trade, an order book is one book, a funding rate is one venue's rate for one contract. Raw data is always served per market, and it arrives either event-driven (one record per event, as with trades and liquidations) or as a snapshot on a fixed cadence (as with order books and open interest). It lives on the `/timeseries/market-*` endpoints, and most types also have a matching `/timeseries-stream/market-*` websocket for real-time delivery.

**Metrics** are values Coin Metrics calculates from that raw data. They aggregate across markets, convert to a common unit (usually US dollars), and publish on a fixed frequency such as `1m`, `1h`, or `1d`. Aggregation is what makes venues comparable: adding the activity of `binance-BTCUSDT-future` to that of `coinbase-btc-usd-spot` first requires converting contracts and base-asset amounts into one unit. Metrics live on the `/timeseries/<entity>-metrics` endpoints.

Use raw data when you need to see or reconstruct exactly what happened on one venue. Use metrics when you need a number that is comparable across venues, assets, and time.

## Entities

An entity is the thing a row of data describes, and its identifier is what you pass to an endpoint. Raw data is published for markets, and metrics are published at whichever levels the aggregation is meaningful for.

| Entity         | Example                 | What it identifies                                                 | Primary endpoints                                                   |
| -------------- | ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| Market         | `coinbase-btc-usd-spot` | One listed pair or contract on one exchange                        | All `/timeseries/market-*` data types, `/timeseries/market-metrics` |
| Asset          | `btc`                   | One asset across the market as a whole                             | `/timeseries/asset-metrics`                                         |
| Asset pair     | `btc-usd`               | One asset against one quote currency, across the market as a whole | `/timeseries/pair-metrics`, `/timeseries/pair-candles`              |
| Exchange       | `binance`               | One venue, across every market it lists                            | `/timeseries/exchange-metrics`                                      |
| Exchange-asset | `binance-btc`           | One asset on one venue                                             | `/timeseries/exchange-asset-metrics`                                |
| Exchange-pair  | `deribit-btc-usd`       | One trading pair on one venue                                      | `/timeseries/exchange-pair-metrics`                                 |
| Institution    | `grayscale`             | One issuer of investment products                                  | `/timeseries/institution-metrics`                                   |

A market identifier encodes the venue, the instrument, and the market type. Spot markets follow `<exchange>-<base>-<quote>-spot`, as in `coinbase-btc-usd-spot`. Futures and options append `-future` or `-option` to the exchange's own symbol, as in `binance-BTCUSDT-future` and `deribit-BTC-16MAY21-58000-C-option`, so the middle segment is exactly what the venue publishes rather than a Coin Metrics rewriting of it.

Exchange-asset and exchange-pair look alike and are not interchangeable. `deribit-btc` covers every Deribit market whose base asset is BTC. `deribit-btc-usd` covers the BTC-USD pair on Deribit specifically, which keeps option chains on the same underlying quoted in different currencies from being mixed together.

## The Discovery Loop

Almost every query follows the same three steps, and the pattern holds across the whole Coin Metrics API rather than just market data. Find out what exists, check the time range, then pull the data.

**1. What exists?** The `/reference-data/*` endpoints describe the coverage universe, and they come in two flavors. The entity endpoints ([`/reference-data/markets`](https://docs.coinmetrics.io/api/v4/#operation/getReferenceDataMarkets), plus `assets`, `exchanges`, `pairs`, and `indexes`) return which entities exist and what their attributes are, such as trading rules and contract terms. The metric endpoints (one per entity level, for example [`/reference-data/asset-metrics`](https://docs.coinmetrics.io/api/v4/#operation/getReferenceDataAssetMetrics)) return which metrics exist, along with their descriptions, units, and frequencies.

**2. Over what time range?** The `/catalog-v2/*` endpoints list every entity that supports a given data type together with the `min_time` and `max_time` of the data available for it. There are two variants. `/catalog-v2/*` reflects what your API key is entitled to, while `/catalog-all-v2/*` reflects the entire Coin Metrics dataset, so comparing the two shows what sits outside your subscription.

**3. Pull the data.** The `/timeseries/*` endpoints serve history over HTTP, and `/timeseries-stream/*` serves the same data as a real-time websocket feed for the data types that support one.

Charting Coinbase BTC-USD trades runs the loop like this:

| Step | Call                                                      | What it gives you                                                                  |
| ---- | --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 1    | `/reference-data/markets?exchange=coinbase`               | The market identifier `coinbase-btc-usd-spot`, and its precision, fees, and status |
| 2    | `/catalog-v2/market-trades?markets=coinbase-btc-usd-spot` | The `min_time` and `max_time` of trades available for that market                  |
| 3    | `/timeseries/market-trades?markets=coinbase-btc-usd-spot` | The trades themselves, within that range                                           |

The [Coin Metrics Coverage Tool](https://coverage.coinmetrics.io/) presents the same universe and time ranges visually, which is often faster than the first two calls when you are exploring rather than automating. [API Conventions](/access-our-data/api.md) documents all four endpoint families in full, including pagination, rate limits, and timestamp handling.

* [Market Reference Data](/market-data/market-data-overview/market-reference-data.md): the identity, trading rules, and contract terms of every market Coin Metrics collects, and the way to build or filter the universe of markets you want to query.

## Trades, Candles, and Volume

What traded, at what price, and how much. Trades are the tick-level record, candles summarize them over fixed intervals, and volume metrics aggregate them into comparable US dollar totals.

| Page                                                                  | What it gives you                                                                                                                           | Entity                                |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [Market Trades](/market-data/market-data-overview/market-trades.md)   | Every executed trade on a market, with price, amount, and the taker's side                                                                  | Market (spot, futures, options, DeFi) |
| [Market Candles](/market-data/market-data-overview/market-candles.md) | Open, high, low, close, and volume over fixed intervals, computed by Coin Metrics from collected trades rather than taken from the exchange | Market (spot, futures, options, DeFi) |
| [Pair Candles](/market-data/market-data-overview/pair-candles.md)     | Open, high, low, and close of the Coin Metrics Reference Rate for a pair, a cross-exchange price that is not tied to any single venue       | Asset pair                            |
| [Volume Metrics](/market-data/market-data-overview/volume-metrics.md) | Trading volume in US dollars aggregated across markets, published as both reported volume and trusted volume                                | Asset, exchange, exchange-asset, pair |

## Order Books, Quotes, and Liquidity

What is resting on the book and what it would cost to trade against it. These datasets describe available liquidity rather than executed activity, so they answer questions about execution cost that trades and candles cannot.

| Page                                                                          | What it gives you                                                                                                            | Entity                          |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| [Market Order Books](/market-data/market-data-overview/market-order-books.md) | Point-in-time book snapshots, plus the full stream of level updates needed to reconstruct the book at an arbitrary timestamp | Market (spot, futures, options) |
| [Market Quotes](/market-data/market-data-overview/market-quotes.md)           | Best bid and best ask on one venue, the level-1 top-of-book view of the order book                                           | Market (spot, futures, options) |
| [Aggregated Quotes](/market-data/market-data-overview/aggregated-quotes.md)   | A consolidated best bid and best ask derived from a selection of high-quality constituent markets, streamed over websocket   | Asset, asset pair               |
| [Liquidity Metrics](/market-data/market-data-overview/liquidity-metrics.md)   | Bid-ask spread, order book depth within a band around the midprice, and the slippage a given order size would incur          | Market (spot, futures)          |

## Futures and Perpetuals

Positioning, cost of carry, and forced deleveraging on derivatives venues. The raw per-market series a venue reports come first, followed by the metrics that aggregate them across markets and convert them to US dollars. Most concepts appear in both halves, so open interest, funding, and liquidations can each be read per contract or per asset.

| Page                                                                                                  | What it gives you                                                                                                                                              | Entity                                |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [Market Contract Prices](/market-data/market-data-overview/market-contract-prices.md)                 | The mark, index, and estimated settlement prices an exchange publishes for a contract, which are the values it uses to mark positions and trigger liquidations | Market (futures, options)             |
| [Market Open Interest](/market-data/market-data-overview/market-open-interest.md)                     | The number of contracts currently outstanding and unsettled on one market                                                                                      | Market (futures, options)             |
| [Market Funding Rates](/market-data/market-data-overview/market-funding-rates.md)                     | The realized funding rate a perpetual market settled at the end of each funding interval                                                                       | Market (perpetual futures)            |
| [Market Funding Rates Predicted](/market-data/market-data-overview/market-funding-rates-predicted.md) | The venue's running estimate of the rate that will apply at the end of the current interval, before it settles                                                 | Market (perpetual futures)            |
| [Market Liquidations](/market-data/market-data-overview/market-liquidations.md)                       | Every forced position close a futures venue reported, as an individual order or trade                                                                          | Market (futures)                      |
| [Open Interest Metrics](/market-data/market-data-overview/open-interest-metrics.md)                   | Open interest converted to US dollars and summed across markets                                                                                                | Asset, exchange, exchange-asset, pair |
| [Funding Rate Metrics](/market-data/market-data-overview/funding-rate-metrics.md)                     | Open-interest-weighted average funding across markets, standardized to fixed periods and accumulated over rolling windows                                      | Asset, exchange-asset                 |
| [Basis Metrics](/market-data/market-data-overview/basis-metrics.md)                                   | The annualized spread between dated futures and spot at fixed 30, 60, 90, and 120 day horizons                                                                 | Exchange-asset                        |
| [Liquidation Metrics](/market-data/market-data-overview/liquidation-metrics.md)                       | Liquidation volume summed over fixed windows and split into buys and sells, in native units and US dollars                                                     | Asset, exchange, exchange-asset, pair |

## Options and Volatility

Contract-level option data as venues report it, plus the derived surfaces that make it comparable through time. Realized volatility sits here as well, because it is most often read against implied volatility at a matching horizon.

| Page                                                                                            | What it gives you                                                                                                        | Entity                        |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| [Market Implied Volatility](/market-data/market-data-overview/market-implied-volatility.md)     | Exchange-reported implied volatility per option contract, computed separately from bid, ask, mark, and trade prices      | Market (options)              |
| [Market Greeks](/market-data/market-data-overview/market-greeks.md)                             | Delta, gamma, vega, theta, and rho per option contract, as the exchange reports them                                     | Market (options)              |
| [Implied Volatility Metrics](/market-data/market-data-overview/implied-volatility-metrics.md)   | The option surface interpolated onto a fixed grid of tenors and deltas, plus at-the-money levels and call-minus-put skew | Exchange-pair, exchange-asset |
| [Realized Volatility Metrics](/market-data/market-data-overview/realized-volatility-metrics.md) | Annualized standard deviation of returns over eleven rolling windows, computed on the Coin Metrics Reference Rate        | Asset                         |

## Institutional Products

Fund-level data for institutional digital asset investment products, which sits outside the exchange coverage universe and is published on its own endpoint.

| Page                                                                            | What it gives you                                                                                                                                                                             | Entity      |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| [Institution Metrics](/market-data/market-data-overview/institution-metrics.md) | Daily fund statistics for exchange-traded funds and investment trusts, including assets under management, net asset value per share, market price, shares outstanding, and holdings per share | Institution |

## Exchange Coverage

Coin Metrics collects from dozens of the leading spot and derivatives venues, and the set changes as venues are added, renamed, or wound down. Rather than repeat a count here, consult the sources that track it directly.

* The [Coin Metrics Coverage Tool](https://coverage.coinmetrics.io/exchanges-v2/) shows the exchanges covered, the number of spot, futures, and options markets on each, and the history available.
* [`/reference-data/exchanges`](https://docs.coinmetrics.io/api/v4/#operation/getReferenceDataExchanges) returns the same universe programmatically.
* Each data type page carries its own coverage link, because not every venue supports every data type. Historical order book updates, for example, are served only for supported exchanges, while trades are collected from every venue in the universe.

## Related

* [CM Prices](/coin-metrics-prices/coin-metrics-prices.md): the Coin Metrics Reference Rates and Principal Market Prices, the cross-exchange price series behind pair candles, realized volatility, and the US dollar conversions used throughout the metrics.
* [Talos Exchange Scorecard](/market-data/methodologies/talos-exchange-scorecard.md): the quantitative evaluation of exchange quality that defines the trusted exchange set used by volume metrics.
* [Decentralized Exchange Data](/network-data/defi-data-overview/decentralized-exchange-data.md): swap coverage on supported decentralized exchanges, which flows into market trades and market candles.
* [Access Our Data](/access-our-data.md): the HTTP API, websocket API, Python client, and cloud delivery options for pulling everything in this section.
* [Tutorials and Examples](/tutorials-and-examples.md): worked notebooks and guides that build on these datasets.


---

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