Quotes

Contents

• Market Quotes

• Pair Quotes

• Asset Quotes

Definition

Quotes consist of the best bid and the best ask for a market at a given point in time. The best bid represents the highest price that a buyer is willing to pay for one unit of the base asset for a spot market or one contract for a derivatives market. The best ask represents the lowest price that a seller is willing to sell.

Coin Metrics collects quotes representing the best bid order and best ask order residing at the top of the order book for individual markets like coinbase-btc-usd-spot. To calculate our pair quotes, we aggregate the quotes across a selection of high-quality constituent markets to derive quotes for a pair like btc-usd. To calculate our asset quotes, we aggregate the quotes across a selection of high-quality constituent markets to derive quotes for an asset like btc.

Our quotes are conceptually similar to the National Best Bid Offer (NBBO), a regulation issued by the United States Securities and Exchange Commission that requires brokers to execute customer trades at the best available price.

Market Quotes

Details

Quotes data is derived from our order book snapshot data by extracting the best bid and best ask. We serve quotes data through a separate endpoint as a convenience for users.

Coin Metrics stores three types of order book snapshots. One type consists of a snapshot of the top 100 bids and top 100 asks taken once every 10 seconds for major markets. The second type includes all levels where the price is within 10 percent of the midprice taken once every 10 seconds. The third type consists of a full order book snapshot (every bid and every ask) taken once every hour for all markets that we are collecting order book data for. Quotes derived from these snapshots are served through our HTTP API endpoint /timeseries/market-quotes.

Coin Metrics also serves quotes in real-time for major markets through our websocket API endpoint /timeseries-stream/market-quotes.

For more information about our quotes data, please reference our market order book page.

API Endpoints

Market quotes can be accessed using the timeseries/market-quotes and timeseries-stream/market-quotes for markets.

Market quotes

get

Returns quotes for specified markets. Results are ordered by tuple (market, time). To fetch the next page of results use next_page_url JSON response field.

Authorizations

Query parameters

marketsstring[]Required

Comma separated list of markets or market patterns like exchange-* or exchange-*-spot or *USDT-future. Use the /catalog-all/markets endpoint for the full list of supported markets.

granularitystring · enumOptional

Downsampling granularity of market order books and quotes. Supported values are raw, 1m, 1h, and 1d.

Default: rawPossible values:

start_timestringOptional

Start of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If start_time is omitted, response will include time series from the earliest time available.

end_timestringOptional

End of the time interval. This field refers to the time field in the response. Multiple formats of ISO 8601 are supported: 2006-01-20T00:00:00Z, 2006-01-20T00:00:00.000Z, 2006-01-20T00:00:00.123456Z, 2006-01-20T00:00:00.123456789Z, 2006-01-20, 20060120. Inclusive by default. UTC timezone by default. Z suffix is optional and timezone parameter has a priority over it. If end_time is omitted, response will include time series up to the latest time available.

start_inclusivebooleanOptional

Inclusive or exclusive corresponding start_* parameters.

Default: true

end_inclusivebooleanOptional

Inclusive or exclusive corresponding end_* parameters.

Default: true

timezonestringOptional

Timezone name for start_time and end_time timestamps. This parameter does not modify the output times, which are always UTC. Format is defined by TZ database.

Default: UTCExample: America/New_York

formatstringOptional

Format of the response. Supported values are json, json_stream.

Default: json

page_sizeinteger · int32 · min: 1 · max: 10000Optional

Number of items per single page of results. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: 100

paging_fromstring · enumOptional

Where does the first page start, at the start of the interval or at the end. The value of this parameter is ignored if the endpoint supports the format parameter and its value is set to json_stream.

Default: endPossible values:

limit_per_marketinteger · int32Optional

How many entries per market result should contain. It is useful when multiple markets are requested.

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

next_page_tokenstringOptional

Token for receiving the results from the next page of a query. Should not be used directly. To iterate through pages just use next_page_url response field.

include_one_sidedbooleanOptional

Include one-side and empty books in quotes response.

Default: false

Responses

200

Time series of market quotes.

application/json

400

Market not found.

application/json

401

Requested resource requires authorization.

application/json

403

Requested resource is not available with supplied credentials.

application/json

414

Provided URI is too long. It must not be greater than 10000 symbols.

get

HTTPcURLJavaScriptPython

GET /v4/timeseries/market-quotes HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

{
  "data": [
    {
      "time": "2020-06-08T21:14:48.215145000Z",
      "market": "coinbase-btc-usd-spot",
      "coin_metrics_id": "1591479594286046-27326992",
      "ask_price": "9685.02",
      "ask_size": "0.04340557",
      "bid_price": "9685.01",
      "bid_size": "0.00484254"
    }
  ],
  "next_page_token": "0.MjAyMC0wNi0wOFQyMToxNDo0OC4yMTUxNDVafDE1OTE0Nzk1OTQyODYwNDY",
  "next_page_url": "https://api.coinmetrics.io/v4/timeseries/market-quotes?markets=coinbase-btc-usd-spot&api_key=<your_key>&pretty=true&page_size=1&next_page_token=0.MjAyMC0wNi0wOFQyMToxNDo0OC4yMTUxNDVafDE1OTE0Nzk1OTQyODYwNDY"
}

Shell

curl --compressed "https://api.coinmetrics.io/v4/timeseries/market-quotes?markets=coinbase-btc-usd-spot&limit_per_market=1&api_key=<your_key>"

Python

import requests
response = requests.get('https://api.coinmetrics.io/v4/timeseries/market-quotes?markets=coinbase-btc-usd-spot&limit_per_market=1&api_key=<your_key>').json()
print(response)

Python Client

from coinmetrics.api_client import CoinMetricsClient

api_key = "<API_KEY>"
client = CoinMetricsClient(api_key)

print(
    client.get_market_quotes(
        markets=["coinbase-btc-usd-spot"], limit_per_market=5
    ).to_dataframe()
)

Example

An sample of the quotes data the coinbase-btc-usd-spot market from our /timeseries/market-quotes API endpoint is provided below.

{
  "data": [
    {
      "time": "2020-06-08T21:14:48.215145000Z",
      "market": "coinbase-btc-usd-spot",
      "coin_metrics_id": "1591479594286046-27326992",
      "ask_price": "9685.02",
      "ask_size": "0.04340557",
      "bid_price": "9685.01",
      "bid_size": "0.00484254"
    }
  ]
}

• market: The id of the market. Market ids use the following naming convention: exchangeName-baseAsset-quoteAsset-spot for spot markets, exchangeName-futuresSymbol-future for futures markets, and exchangeName-optionsSymbol-option for options markets.

• time: The exchange-reported time in ISO 8601 date-time format.\

• coin_metrics_id: Unique identifier of the order snapshot.\

• ask_price: The price of the ask on the order book in units of the quote currency.\

• ask_size: The size of the ask on the order book in units of the base asset for a spot market or number of contracts for a derivatives market.\

• bid_price: The price of the bid on the order book in units of the quote currency.\

• bid_size: The size of the bid on the order book in units of the base asset for a spot market or number of contracts for a derivatives market.

Frequently Asked Questions

Since our quotes data is derived from our order book data, please reference our market order book page for many frequently asked questions about order book data.

Orderbooks

Release History

• CM MDF v1.0 on April 2019: Quotes for major btc-usd and eth-usd markets. \

• CM MDF v1.0 on July 30, 2019: Added support for websocket endpoint which serves quotes in real-time. \

• CM MDF v2.0 on December 9, 2019: Expanded coverage universe to include cex.io-btc-usd and bitflyer-btc-spot.\
• CM MDF v2.4 on September 1, 2021: Expanded our coverage universe to additional markets on Coinbase, Binance, FTX, Bitfinex, itBit. \
• CM MDF v2.5 on November 22, 2021: Expanded our coverage universe to additional spot markets on Binance, Binance.US, Bitfinex, bitFlyer, Bitstamp, Bittrex, CEX.io, Coinbase, FTX, Gemini, Huobi, itBit, Kraken, Kucoin, Liquid, and LMAX. Initiated coverage of futures markets on Binance, Bitfinex, bitFlyer, BitMEX, Bybit, Deribit, FTX, Huobi, Kraken, OKEx. Initiated real-time coverage of CME market quotes.
• CM MDF v2.7 on October 24, 2022: Expanded our market coverage to include every single market, both spot and futures, on the following 12 exchanges: Binance, Binance.US, Bybit, Coinbase, Deribit, FTX, FTX.US, Gemini, HitBTC, Huobi, Kraken, OKEx. Began storing every single quote update in flat files starting in February 2022, suitable for any use cases that require historical data.

Availability

The previous 24 hours of quotes data is available through our Community API. Community data is available via HTTP API only and is limited to 10 API requests per 6 seconds per IP address. All of our order book data is available through our professional API with higher rate limits.

Our coverage universe is expanding rapidly. Please contact us at [email protected] for the latest quotes coverage.

Pair Quotes

Our /timeseries-stream/pair-quotes endpoints supports multiple aggregation methods to aggregate the quotes data from individual constituent markets for a given pair. The different aggregation methods can be specified using the aggregation_method parameter.

Currently, only the aggregated_spread method is implemented, and alternative methods will be implemented in the future.

Aggregated Spread

The aggregated_spread method uses the following methodology:

For a given pair, select major spot markets where the market contains the given pair. For each market i, calculate the bid ask spread in percentage terms and the midprice:

$$MidpointPrice_i = \frac{BestAskPrice_i + BestBidPrice_i}{2}$$

$$Spread_i = \frac{BestAskPrice_i - BestBidPrice_i}{MidpointPrice_i}$$

Calculate the weighted-average bid-ask spread and weighted-average midprice where the weight is determined by Volume_i, the cumulative volume over some time period [t-1, t] on market i. The advantage of using a trailing volume as opposed to other volume measures, such as order size at the top of the book, is that volume indicates the real contribution of a given exchange to the market. Using order sizes from the book would allow for the random behavior of market participants to bias the aggregate in a way that does not represent the actual contribution of an exchange to the broader crypto market. Using these weights will measure the trading activity actually realized on a market at a given spread. In this way, the volume-weighted spread (as opposed to size-weighted spread) will indicate the spread that is realized via real volume for a given asset or asset-pair.

$$AvgMidpointPrice = \frac{\sum_{i=1}^{n} Volume_i \times MidpointPrice_i}{\sum_{i=1}^{n} Volume_i}$$

$$AvgSpread = \frac{\sum_{i=1}^{n} Volume_i \times Spread_i}{\sum_{i=1}^{n} Volume_i}$$

Using weighted-average midprice and weighted-average spread, calculate the aggregated bid and aggregated ask. The aggregated bid amount and aggregated ask amount are the sum of bid amounts and ask amounts from major markets, respectively.

$$AggBidPrice = AvgMidpointPrice - 0.5 \times AvgSpread \times AvgMidpointPrice$$

$$AggAskPrice = AvgMidpointPrice + 0.5 \times AvgSpread \times AvgMidpointPrice$$

$$AggBidAmount = \sum_{i=1}^{n} BestBidAmount_i$$

$$AggAskAmount = \sum_{i=1}^{n} BestAskAmount_i$$

API Endpoints

Pair quotes can be accessed using the timeseries-stream/pair-quotes endpoints.

Pair quotes

get

Returns a stream of quotes for specified pairs. If you are falling behind (slow client) you will get warning message first, then error message and disconnection will happen.

Authorizations

Query parameters

pairsstring[]Required

Comma separated list of asset pairs or patterns like btc-*, or *-btc. Use the /catalog-all/pairs endpoint for the full list of supported asset pairs.

aggregation_methodstringOptional

The method to use for aggregation.

Default: aggregated_spread

backfillstring · enumOptional

What data should be sent upon a connection. By default the latest values are sent just before real-time data.

Default: latestPossible values:

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

Responses

414

Provided URI is too long. It must not be greater than 10000 symbols.

default

Aggregated spread quote WebSocket message.

application/json

get

HTTPcURLJavaScriptPython

GET /v4/timeseries-stream/pair-quotes HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

No content

Example

{
  "time": "2020-06-08T21:15:45.771742000Z",
  "pair": "btc",
  "ask_price": "24343.725954328216",
  "ask_size": "2.96375165",
  "bid_price": "24342.036360171896",
  "bid_size": "12.00588437",
  "mid_price": "24342.881157250056",
  "spread": "0.0000694081421754166",
  "cm_sequence_id": "0"
}

• time: The exchange-reported time in ISO 8601 date-time format. Always with nanoseconds precision.\

• pair: The id of the pair.\

• ask_price: The price of the ask order in units of the quote currency as determined by the aggregation method.\

• ask_size: The size of the ask order in units of the base asset as determined by the aggregation method.\

• bid_price: The price of the bid order in units of the quote currency as determined by the aggregation method.\

• bid_size: The size of the bid order in units of the base asset as determined by the aggregation method.\

• mid_price: The average of the ask_price and bid_price.\

• spread: The bid-ask spread in raw units.\

• cm_sequence_id: The sequence id number of the websocket message.

Asset Quotes

Our /timeseries-stream/asset-quotes endpoint supports multiple aggregation methods to aggregate the quotes data from individual constituent markets for a given asset. The different aggregation methods can be specified using the aggregation_method parameter.

Currently, only the aggregated_spread method is implemented, and alternative methods will be implemented in the future.

API Endpoints

Asset quotes can be accessed using the /timeseries-stream/asset-quotes endpoint.

Asset quotes

get

Returns a stream of quotes for specified assets. If you are falling behind (slow client) you will get warning message first, then error message and disconnection will happen.

Authorizations

Query parameters

assetsstring[]Required

Comma separated list of assets. Use the /catalog-all/assets endpoint for the full list of supported assets.

aggregation_methodstringOptional

The method to use for aggregation.

Default: aggregated_spread

backfillstring · enumOptional

What data should be sent upon a connection. By default the latest values are sent just before real-time data.

Default: latestPossible values:

prettybooleanOptional

Human-readable formatting of JSON responses.

Default: false

Responses

414

Provided URI is too long. It must not be greater than 10000 symbols.

default

Aggregated spread quote WebSocket message.

application/json

get

HTTPcURLJavaScriptPython

GET /v4/timeseries-stream/asset-quotes HTTP/1.1
Host: api.coinmetrics.io
Accept: */*

No content

Example

{
  "time": "2020-06-08T21:15:45.771742000Z",
  "asset": "btc",
  "ask_price": "24343.725954328216",
  "ask_size": "2.96375165",
  "bid_price": "24342.036360171896",
  "bid_size": "12.00588437",
  "mid_price": "24342.881157250056",
  "spread": "0.0000694081421754166",
  "cm_sequence_id": "0"
}

• time: The exchange-reported time in ISO 8601 date-time format. Always with nanoseconds precision.\

• asset: The id of the asset.\

• ask_price: The price of the ask order in units of the quote currency as determined by the aggregation method.\

• ask_size: The size of the ask order in units of the base asset as determined by the aggregation method.\

• bid_price: The price of the bid order in units of the quote currency as determined by the aggregation method.\

• bid_size: The size of the bid order in units of the base asset as determined by the aggregation method.\

• mid_price: The average of the ask_price and bid_price.\

• spread: The bid-ask spread in raw units.\

• cm_sequence_id: The sequence id number of the websocket message.

Frequently Asked Questions

What are the constituent markets used in the calculation?

Coin Metrics uses our Trusted Exchange Framework v2.0 to seelct a set of high-quality and trustworthy exchanges in selection of our constituent markets. The set of exchanges includes Bitstamp, Coinbase, Bitfinex, Binance, Gemini, Kraken, OKEx, Huobi, Binance.US, KuCoin, LMAX, and Bybit.

Coin Metrics performed an analysis of the distribution of volume across markets with different quote currencies and selected all major quote currencies such that we capture over 95 percent of the available volume for each asset. The selected quote currencies are: usd, usdt, usdc, busd, eur, try.

All markets from trusted exchanges for which the given asset is the base asset and the quote asset is listed above are selected.

How often is the data updated?

Our websocket API will send a new message once every 250 milliseconds.

Release History

• CM Market Data Feed v2.8 on May 2023.

Availability

The asset quotes are currently available for the following assets: btc, eth, ltc, xrp, bnb, usdt, trx link, doge, usdc, ada, atom, matic, dai, sol, dot, avax, uni.