Data Encyclopedia
HomeCharts
  • Welcome & Product Overview
  • Getting Started
  • Tutorials and Examples
    • Tutorials
      • Python API Client Walkthrough
      • Getting Started With Market Data
      • Getting Started With Futures Data
      • Aggregating Options Data
      • Examining Orderbook Depth
      • Aggregating Orderbook Depth to Create Liquidity Metrics
      • Comparing Stablecoin Prices Using Different Pricing Methods
      • Comparing Volumes of Exchanges and Assets
      • Creating Custom Network Data Metrics Using ATLAS
      • Applying Different Types of Marketcap Metrics
      • Comparing the Dominance of Mining Pools Using ATLAS
      • Using Staking Metrics to Get Yield and Staked Supply
      • Granular Insights On Chain Using Hourly Network Data Metrics
      • Exploring Options, Open Interest, and Volatility Data
      • Calculating Total Value Locked in Liquidity Pools using DEX Data
      • Calculating DEX Liquidity Pool Fees and Volumes
      • Analyzing DeFi Protocol Balance Sheets
    • How To Guides
      • How To Export Data
      • How To Migrate From Catalog to Catalog V2 and Reference Data
      • How To Use the Coin Metrics API Efficiently
    • Dashboard Examples
  • Packages
    • CM Labs
    • Coin Metrics Community Data
  • Access Our Data
    • API Reference
    • API Conventions
      • Catalog V1 to Catalog V2 Migration
    • Python API Client
    • R API Client
    • Coverage
    • Status Page
  • Data Visualization
    • Charting Tool
      • Formula Builder
      • Correlation Tool
      • Embedded Charts
      • Troubleshooting
    • Dashboard
      • Troubleshooting
    • CMTV Charts (Labs)
      • Troubleshooting
    • Atlas Explorer
  • Network Data
    • Network Data Pro Overview
      • Availability
        • Asset Completion Time
      • Addresses
        • Active Addresses
        • Address Balances
        • New Addresses
      • Economics
        • Mining
        • Valuation
      • Exchange
        • Deposits
        • Exchange Supply
        • Net Flows
        • Transaction Count
        • Withdrawals
      • Fees and Revenue
        • Fees
        • Revenue
      • Market
        • Market Capitalization
        • Price
        • Profitability
        • Returns
        • Volatility
      • Key Risk Indicator (KRI) Feed
        • Blocks
        • Block Attributes
        • Block Size
        • Block Times
        • Empty Blocks
        • Fees
        • Outputs
        • Rewards
        • Feerates
        • Hashrate
        • Transaction Feerates
        • Transaction Fees
        • Transaction Sizes
        • Transactions
      • Mining
        • Balances
        • Difficulty
        • Exchange Flows
        • Flows
        • Hardware Hash Rate
        • Hash Rate
      • Network Usage
        • Blocks
        • Contracts
        • Profitability
        • UTXOs
        • Blobs
      • Staking
        • Consensus Health
        • Flows
        • Penalty Metrics
        • Slashing Metrics
        • Validator Supply
        • Stakers
        • Yield
      • Supply
        • Active Supply
        • Addresses with Balance
        • Burnt Supply
        • Current Supply
        • Free Float Supply
        • Future Expected Supply
        • Miner Revenue
        • Profitability
        • Revived Supply
        • Shielded Supply
        • Supply Issuance
        • Staking Supply
      • Transactions
        • Blobs
        • Contracts
        • Token Transactions
        • Transactions
        • Transfer Value
        • Transfers
        • Velocity
      • Wallets
        • Active Wallets
        • Wallet Balances
    • Atlas Overview
      • Accounts
      • Account Balance
      • Blocks
        • Full Block
      • Transactions
        • Full Transaction
          • Full Transaction Info for Block
      • Balance Updates
    • Methodologies
      • Normalizing Block Times
    • DeFi Overview
      • Decentralized Exchange Data
      • DeFi Balance Sheets
      • DeFi FAQs
    • Tagging Meta Data
    • Transaction Tracker
    • CM Labs
      • Mining Pool Monitor Overview
        • Mining Pool Monitor API Fields
      • Reorg & Fork Tracker Overview
        • Reorg & Fork Tracker Tracker API Fields
    • Deprecated
      • Mempool Monitor
      • WatchTower Alerts Overview - DEPRECATED
        • WatchTower Alerts - DEPRECATED
          • Ethereum Proof-of-Stake Alerts - DEPRECATED
            • Missed Slot Alert - DEPRECATED
            • Fast Increase in Transaction Count Alert - DEPRECATED
            • Fast Decrease in Transaction Count Alert - DEPRECATED
            • Fast Decrease in Base Fees - DEPRECATED
            • Fast Increase in Base Fees - DEPRECATED
            • Fast Decrease in Priority Fees (Tips) Alert - DEPRECATED
            • Fast Increase in Priority Fees (Tips) Alert - DEPRECATED
            • Decrease in Active Addresses Alert - DEPRECATED
            • Increase in Active Addresses Alert - DEPRECATED
            • Decrease in Total Block Fees Alert - DEPRECATED
            • Increase in Total Block Fees Alert - DEPRECATED
          • DeFi Alerts - DEPRECATED
            • Smart Contract Admin Change Alert - DEPRECATED
            • Admin Change with Issuance Event Alert - DEPRECATED
            • Admin Change with Large Issuance Event Alert - DEPRECATED
          • Mining Alerts - DEPRECATED
            • Unknown Miner Predominance Alert - DEPRECATED
            • Mining Pool Conflict Alert - DEPRECATED
            • Persistent Mining Pool Conflict Alert - DEPRECATED
            • Hashrate Decrease Alert - DEPRECATED
            • 1-Block Difficulty Decrease - DEPRECATED
          • Blockchain Alerts - DEPRECATED
            • 1 Block Reorg Alert - DEPRECATED
            • 2 Block Reorg Alert - DEPRECATED
            • 3 Block Reorg Alert - DEPRECATED
            • Satoshi Coins Spent - DEPRECATED
            • Vintage Coins Spent - DEPRECATED
            • Slow Block Alert - DEPRECATED
            • 1 Consecutive Empty Block Alert - DEPRECATED
            • 2 Consecutive Empty Blocks Alert - DEPRECATED
            • 3 Consecutive Empty Blocks Alert - DEPRECATED
            • 6 Consecutive Empty Blocks Alert - DEPRECATED
          • Mempool Alerts - DEPRECATED
            • Mempool Disruption Alert - DEPRECATED
            • Mempool Size 90% Alert - DEPRECATED
            • Mempool Size 95% Alert - DEPRECATED
            • Mempool Size 99% Alert - DEPRECATED
            • Mempool Size 100% Alert - DEPRECATED
            • Mempool Congestion Alert - DEPRECATED
        • WatchTower API Fields - DEPRECATED
    • Network Data Glossary
    • Network Data FAQs
  • Market Data
    • Market Data Overview
      • Basis
      • Candles
      • Contract Prices
      • Funding Rates
        • Funding Rates
        • Predicted Funding Rates
        • Aggregated Futures Funding Rate
        • Cumulative Futures Funding Rate
      • Greeks
      • Institution Metrics
        • Grayscale
          • Shares Outstanding
          • Market Price
          • Net Asset Value
          • Coin Per Share
          • Total Assets
      • Liquidations
        • Market Level Liquidations
        • Liquidation Metrics
      • Liquidity
        • Bid-Ask Spread Percent
        • Order Book Depth
        • Slippage
      • Market Metadata
      • Open Interest
        • Market Level Open Interest
        • Reported Open Interest
      • Orderbooks
      • Quotes
      • Trades
      • Volatility
        • Market Implied Volatility
        • Implied Volatility
        • Realized Volatility
      • Volume
        • Trusted Volume
        • Reported Volume
    • CM Prices
      • Reference Rate
      • Principal Market Price (USD)
      • Principal Market (USD)
    • Methodologies
      • Coin Metrics Prices Policies
      • Coin Metrics Prices Methodology
      • Trusted Exchange Framework
    • Market Data FAQs
      • CM Prices FAQs
      • Trusted Exchange Framework FAQs
  • Index Data
    • Index Overview
      • Index Timeseries
        • Index Levels
        • Index Candles
        • Index Constituents
    • Policies & Charters
      • CMBI Index Policies
      • Governance Committees
    • Methodologies
      • Fork Legitimacy Framework
      • Adjusted Free Float Supply Methodology
      • Candidate Market Guidelines
    • Fact Sheets
      • CMBI Single Asset Series Fact Sheet
      • CMBI Multi Asset Series Fact Sheet
      • CMBI Total Market Series Fact Sheet
      • CMBI Mining Series Fact Sheet
    • Indexes Glossary
    • Index FAQs
  • Reference Data
    • datonomy Overview
      • Taxonomy for Assets
      • Taxonomy Metadata for Assets
      • datonomy FAQs
    • Profiles Overview
      • Asset Profiles
      • Network Profiles
    • Security Master Overview
      • Assets
      • Markets
    • Methodologies
      • Guiding Principles and Methodology for datonomy
  • BITTENSOR
    • Precog Methodology
      • Point Forecast Ranking
      • Interval Forecast Ranking
      • Interval Score Examples
      • Miner Weight from Rank
Powered by GitBook
On this page

Was this helpful?

  1. Market Data
  2. Market Data Overview

Orderbooks

/timeseries/market-orderbooks

PreviousReported Open InterestNextQuotes

Last updated 2 months ago

Was this helpful?

Definition

An order book represents the list of buy orders and the list of sell orders for a given market organized by price level. In this context, a buy order or sell order indicates the amount of the base asset that a buyer or seller wishes to trade for a spot market or the amount of contracts for a derivatives market.

Details

The price and amount that a trader is willing to buy is referred to as the bid. The price and amount that a trader is willing to sell is referred to as the ask. When a trade is executed between a buyer and a seller, an order is removed from the order book. While an order book is constantly updated in real-time as traders post new orders and as orders are matched, this data type represents a snapshot of the order book at a given moment in time.

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 for major markets. 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. All of these snapshots are served through our HTTP API endpoint .

Coin Metrics also serves order book snapshots and updates for the top 100 bids and 100 asks for major markets through our websocket API endpoint . The first message that the client receives is an order book snapshot. All subsequent messages are updates to the order book. This allows a user to maintain the current state of the order book at all times by storing the order book state locally and applying updates to it.

API Endpoints

Market trades can be accessed using the timeseries/market-orderbooks endpoint.

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

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

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

## **Chart**

Example

{
  "data": [
    {
      "time": "2020-06-08T21:01:23.283083000Z",
      "market": "coinbase-btc-usd-spot",
      "coin_metrics_id": "1591479594286046-27268420",
      "asks": [
        {
          "price": "9701.48",
          "size": "2.65178241"
        },
        {
          "price": "9701.49",
          "size": "0.10941481"
        }
      ],
      "bids": [
        {
          "price": "9701.4",
          "size": "4.43779413"
        },
        {
          "price": "9699.94",
          "size": "0.041"
        }
      ]
    }
  ]
}
  • 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.\

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

  • size: The size of the bid or ask 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

What are order book snapshots and order book updates?

An order book snapshot represents the state of the order book at a specific point in time. It contains the price level and amount for each bid and ask order in the order book.

We store 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 for major markets. The third type consists of a full order book snapshot (every bid and every ask) taken once every hour for all markets.

An order book update represents a single change to the state of the order book via an addition, change, or removal of a bid or ask order. Cryptocurrency exchanges typically report order book updates as a new [side, price, size] tuple where the size represents the new value and not the delta from the previous value.

We do not store historical data for order book updates yet, but we serve them in real-time via our websocket feed. By using a recent order book snapshot and applying all order book updates, a user can locally maintain the current state of the order book at all times.

What is the difference between level 1, level 2, and level 3 order book data?

Level 2 order book refers to snapshots or updates where individual orders with identical price level are aggregated to one observation. The majority of cryptocurrency exchanges serve their order book snapshots and updates at level 2 resolution. Coin Metrics currently stores level 2 order book data. If an exchange reports order book data at level 3 resolution, we aggregate it to level 2 resolution before storing it. Level 3 order book data refers to snapshots or updates where each individual order is present. Individual orders with identical price level are not aggregated. Only a small number of cryptocurrency exchanges serve their order book snapshots and updates at level 3 resolution.

Do you offer order book updates in the form of new orders, cancels, and changes to existing orders?

The majority of cryptocurrency exchanges do not report their order book updates with this information. Cryptocurrency exchanges typically report order book updates as a new [side, price, size] tuple where the size represents the new value and not the delta from the previous value. However, some of this information can be derived by examining the change as a result of applying an order book update. If an update contains a tuple with a size of 0, this means that the order was matched with an incoming order (if at the top of the book) or canceled. If an update contains a tuple with size that is greater than the current size, this means that a new order was added to the order book or an existing order was changed.

What is the latency of your order book data?

The exact latency varies depending on the exchange, but our median latency is approximately 150 milliseconds. The 95th percentile latency is 300 milliseconds, and the 99th percentile latency is 400 milliseconds.

Are your order book snapshots taken on exactly the second or hour?

Coin Metrics collects three different sized snapshots for order book data. One snapshot takes the top 100 bids and asks every 10 seconds for major markets. The second snapshot includes all levels where the price is within 10 percent of the midprice every 10 seconds for major markets. The third snapshot takes a a full order book snapshot for all markets that we are collecting order book data for once every hour. Although the value of time field always lies exactly on the second or hour, the actual time of the snapshot is close to but not exactly at this timestamp. We store the exact timestamp that a snapshot was taken and will expose this data through our API in a future release.

How much order book history does Coin Metrics support?

Generally, it is not possible to collect order book history from exchanges directly. Order book data is one of the data types that very few exchanges offer history for, with the exception of a very few like CME and some limited history from Binance. For this reason, our historical coverage begins at the time we started collecting it ourselves.

Are there any limitations to the order book depth provided by each exchange?

While we collect full order book depth for all exchanges that make it available, some exchanges only expose a limited number of levels.

Exchange
Available Depth

Binance

Top 5000 levels

Binance.US

Top 5000 levels

bitFlyer

Full book

BitMEX

Full book

Bitstamp

Full book

Bittrex

Top 500 levels

Bybit

Top 200 levels

CEX.io

Full book

CME

Full book

Coinbase

Full book

Crypto.com

Top 50 levels

Deribit

Full book

FTX

Top 100 levels

FTX.US

Top 100 levels

Gate.io

Top 200 levels

Gemini

Full book

Huobi

Top 150 levels

itbit

Full book

Kraken

Top 500 levels

Kucoin

Full book

Liquid

Full book

LMAX

Top 20 levels

OKX (OkEX)

Top 400 levels

Poloniex

Top 100 levels

Release History

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

  • CM MDF v1.0 on July 30, 2019: Added support for websocket endpoint which serves an initial snapshot and order book updates. \

Availability

The previous 24 hours of order book 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 info@coinmetrics.io for the latest order book coverage.

Source: CM

A sample of the order book snapshot data from the coinbase-btc-usd-spotmarket from our API endpoint is provided below.

Level 1 order book data refers to the top of the book, i.e. the price and amount of the best bid and the price and amount of the best ask. The level 1 data can be derived by extracting the best bid and best ask from our order book snapshots. We also serve this data through our API endpoint.

: Expanded coverage universe to include cex.io-btc-usd and bitflyer-btc-spot.\

: Expanded both the depth of our order book snapshot coverage and our coverage universe. For important markets, we maintain a snapshot of the top 100 levels at 10 second intervals. Started storing full order book snapshots at hourly intervals. Expanded our coverage universe to additional markets on Coinbase, Binance, FTX, Bitfinex, itBit.

: 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 snapshot coverage of futures markets on Binance, Bitfinex, bitFlyer, BitMEX, Bybit, Deribit, FTX, Huobi, Kraken, OKEx. Initiated real-time coverage of CME order book snapshots.

: Added snapshot coverage of the top 100 bids and asks as well as full order book snapshots of OKEx spot markets, FTX.US spot markets, and CME futures markets. Added more frequent order book snapshots for several highly traded perpetual futures across many futures exchanges.

: Expanded our coverage universe to additional spot and futures markets on Binance, Binance.US, Bitfinex, Bitflyer, BitMEX, Bitstamp, Bittrex, Bybit, CEX.io, Coinbase, CME, Deribit, FTX, FTX.US, Gemini, Huobi, Kraken, Kucoin, Liquid, OKEx. Expanded the depth of 10-second snapshots to include the maximum of 100 levels and all levels where the price is within 10 percent of the midprice.

/timeseries/market-orderbooks
market quotes
CM MDF v2.0 on December 9, 2019
CM MDF v2.4 on September 1, 2021
CM MDF v2.5 on November 22, 2021
CM MDF v2.6 on July 13, 2022
CM MDF v2.7 on October 24, 2022
/timeseries/market-orderbooks
/timeseries-stream/market-orderbooks
State of the Market

Market orderbooks

get

Returns orderbooks 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
page_sizeinteger · int32 · min: 1 · max: 10000Optional

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

Default: 100
depth_limitstringOptional

Book depth limit. Supported values are between 1 and 30000, 10pct_mid_price or full_book.

Default: 100
formatstringOptional

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

Default: json
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.

Responses
200
Time series of market order books.
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
GET /v4/timeseries/market-orderbooks HTTP/1.1
Host: api.coinmetrics.io
Accept: */*
{
  "data": [
    {
      "time": "2020-06-08T21:01:23.283083000Z",
      "market": "coinbase-btc-usd-spot",
      "coin_metrics_id": "1591479594286046-27268420",
      "asks": [
        {
          "price": "9701.48",
          "size": "2.65178241"
        },
        {
          "price": "9701.49",
          "size": "0.10941481"
        }
      ],
      "bids": [
        {
          "price": "9701.4",
          "size": "4.43779413"
        },
        {
          "price": "9699.94",
          "size": "0.041"
        }
      ]
    }
  ],
  "next_page_token": "0.MjAyMC0wNi0wOFQyMTowMToyMy4yODMwODNafDE1OTE0Nzk1OTQyODYwNDY",
  "next_page_url": "https://api.coinmetrics.io/v4/timeseries/market-orderbooks?markets=coinbase-btc-usd-spot&api_key=<your_key>&pretty=true&page_size=1&next_page_token=0.MjAyMC0wNi0wOFQyMTowMToyMy4yODMwODNafDE1OTE0Nzk1OTQyODYwNDY"
}
  • Definition
  • Details
  • API Endpoints
  • GETMarket orderbooks
  • Example
  • Frequently Asked Questions
  • What are order book snapshots and order book updates?
  • What is the difference between level 1, level 2, and level 3 order book data?
  • Do you offer order book updates in the form of new orders, cancels, and changes to existing orders?
  • What is the latency of your order book data?
  • Are your order book snapshots taken on exactly the second or hour?
  • How much order book history does Coin Metrics support?
  • Are there any limitations to the order book depth provided by each exchange?
  • Release History
  • Availability