> ## Documentation Index
> Fetch the complete documentation index at: https://kb.talostrading.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Market orderbooks

> Returns orderbooks for specified markets.<br/> Results are ordered by tuple `(market, time)`.<br/> To fetch the next page of results use `next_page_url` JSON response field.<br/> With `type=event_contract`, only prediction markets are selected. Selectors must name an exchange and may use prefix wildcards. Prediction results traverse `(normalized exchange, raw symbol, time)` in C order; `paging_from=end` returns each page in ascending order after traversing backward. Prediction-market books are full-depth snapshots taken hourly, plus once per minute during the 15 minutes before a market closes. Smaller depths are cut from the full book. Only `dataset=snapshots` is supported, and `granularity=raw` returns every stored snapshot.



## OpenAPI

````yaml /coinmetrics/openapi/coinmetrics.yaml get /timeseries/market-orderbooks
openapi: 3.0.2
info:
  title: Coin Metrics API v4
  description: >-
    [Coin Metrics Homepage](https://coinmetrics.io/)<br/> [API Backward
    Compatibility
    Policy](https://docs.coinmetrics.io/access-our-data/api#backward-compatibility)<br/>
    [Python API
    Client](https://coinmetrics.github.io/api-client-python/site/index.html)<br/><br/>

    HTTP API root endpoint URL is `https://api.coinmetrics.io/v4`. Coin
    Metrics&apos; paid product.<br/> WebSocket API root endpoint is
    `wss://api.coinmetrics.io/v4`. Coin Metrics&apos; paid product.<br/><br/>
    The Community HTTP API root endpoint URL is
    `https://community-api.coinmetrics.io/v4`. API key is not required when
    accessing community endpoints. Available to the community under the
    [Creative Commons](https://creativecommons.org/licenses/by-nc/4.0/) license.

    # Authentication

    <!-- ReDoc-Inject: <security-definitions> -->

    # Response headers

    Note that Coin Metrics API responses have a `CF-RAY` HTTP header e.g.
    `88a6ec1d2f930774-IAD` which can be used for diagnostic purposes. When
    raising Support requests, please ensure to provide the value of this
    header. 
  termsOfService: https://coinmetrics.io/api/terms
  contact:
    name: Coin Metrics Support
    url: https://coinmetrics.io/support/
    email: support@coinmetrics.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 4.0.0
servers:
  - url: https://api.coinmetrics.io/v4
  - url: wss://api.coinmetrics.io/v4
  - url: https://community-api.coinmetrics.io/v4
security: []
tags:
  - name: Rate limits
    description: >-
      To ensure the quality of Coin Metrics services, API is subject to rate
      limiting.<br/> <table> <tr><th>Rate Limit Plan</th><th>REST API: Requests
      per Second (sliding window)</th><th>REST API: Download Speed</th><th>REST
      API: Max Parallel Requests</th><th>WebSocket API: Max Parallel
      Connections</th></tr> <tr><td>Community</td><td>10 requests per 6 seconds
      per IP address</td><td>Reduced speed</td><td>10</td><td>N/A</td></tr>
      <tr><td>Trial</td><td>10 requests per 6 seconds per API key</td><td>Max
      speed</td><td>10</td><td>200</td></tr> <tr><td>Default (PRO)</td><td>6000
      requests per 20 seconds per API key</td><td>Standard
      speed</td><td>10</td><td>200</td></tr> <tr><td>Download (PRO)</td><td>6000
      requests per 20 seconds per API key</td><td>Max
      speed</td><td>10</td><td>200</td></tr> </table> <br/> All PRO keys by
      default get the "default" rate limits. To download historical data at max
      speed, you need to switch to the "download" plan. <br/> <br/> The paid and
      community versions of the API have a limit of 10 parallel REST API
      requests. After this limit is reached, further parallel requests will be
      queued, so performance will be slower.<br/> <br/> If you reach the
      request-per-second limit, API starts to return `429 Too Many Requests`
      HTTP response status.<br/> API also provides `X-RateLimit-*` response
      headers formatted according to
      https://tools.ietf.org/html/draft-polli-ratelimit-headers-03.<br/>
      Additionally, the API provides the `X-RateLimit-Plan` header which
      indicates the current rate limiting plan. This header may have values:
      `default`, `trial`, `download`, or `community`.
    x-cm-gitbook:
      foldIntoInfo: true
  - name: Reference Data
    description: Metadata information of entities supported by Coin Metrics.
    x-cm-gitbook:
      tag: Meta Data
      icon: book
  - name: Catalog
    x-displayName: Catalog (deprecated)
    description: >-
      Catalog of available for your `api_key` data.<br/> Use the [Full
      catalog](#tag/Full-catalog) endpoints for the full list of supported by
      Coin Metrics data. <br/>DEPRECATED: See
      https://coinmetrics.io/important-changes-to-coin-metrics-api-catalog-endpoints/.
    x-cm-gitbook:
      remove: true
  - name: Catalog v2
    description: >-
      Catalog of available for your `api_key` data.<br/> Use the [Full catalog
      V2](#tag/Full-catalog-v2) endpoints for the full list of supported by Coin
      Metrics data.
    x-cm-gitbook:
      icon: list-check
  - name: Full catalog
    x-displayName: Full catalog (deprecated)
    description: >-
      The Full catalog returns the full range of data that is supported by Coin
      Metrics across all our products.<br/> If you are a client looking to
      understand the data that is available for your API key and data license,
      please use the [Catalog](#tag/Catalog) endpoint. <br/>DEPRECATED: See
      https://coinmetrics.io/important-changes-to-coin-metrics-api-catalog-endpoints/.
    x-cm-gitbook:
      remove: true
  - name: Full catalog v2
    description: >-
      The Full catalog returns the full range of data that is supported by Coin
      Metrics across all our products.<br/> If you are a client looking to
      understand the data that is available for your API key and data license,
      please use the [Catalog](#tag/Catalog-v2) endpoint.
    x-cm-gitbook:
      tag: Catalog v2
      icon: layer-group
  - name: Timeseries
    description: >-
      Endpoints for fetching metrics, market data, indexes and other time series
      data.
    x-cm-gitbook:
      icon: chart-line
      renameOperationsTo: Timeseries REST
  - name: Timeseries stream
    description: >-
      WebSocket endpoints for getting a real-time stream of metrics, market
      data, indexes and other time series data.
    x-cm-gitbook:
      tag: Timeseries
      icon: wifi
  - name: Taxonomy
    description: Taxonomy endpoints
    x-cm-gitbook:
      icon: sitemap
  - name: Taxonomy Metadata
    description: Taxonomy Metadata endpoints
    x-cm-gitbook:
      tag: Taxonomy
      icon: tags
  - name: Profile
    description: Profile endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: id-card
  - name: List of blockchain entities v2
    description: Endpoints for fetching lists of blockchain entities.
    x-cm-gitbook:
      tag: ATLAS
      icon: list
  - name: Full blockchain entities v2
    description: Endpoints for fetching full blockchain entities.
    x-cm-gitbook:
      tag: List of blockchain entities v2
      icon: database
  - name: Jobs
    description: Jobs API endpoints
    x-cm-gitbook:
      tag: ATLAS
      icon: briefcase
  - name: Blockchain Explorer Job
    description: Endpoints for creating async jobs for blockchain entities.
    x-cm-gitbook:
      tag: ATLAS
      icon: clock
  - name: Blockchain Explorer Job Results
    description: Schema definitions of results of Blockchain Explorer Job endpoints.
    x-cm-gitbook:
      foldInto: Blockchain Explorer Job
  - name: Chain Monitor tools
    description: Endpoints for working with chain monitor data.
    x-cm-gitbook:
      tag: ATLAS
      icon: wrench
  - name: Security Master
    description: Security Master endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: shield
  - name: Constituent Snapshots
    description: Endpoints for getting the snapshots of various constituents
    x-cm-gitbook:
      tag: Meta Data
      icon: camera
  - name: Constituent Timeframes
    description: Endpoints for getting the timeframes of various constituents
    x-cm-gitbook:
      tag: Meta Data
      icon: calendar
  - name: Blockchain Metadata
    description: Blockchain metadata endpoints
    x-cm-gitbook:
      tag: Meta Data
      icon: database
  - name: Meta Data
    x-cm-gitbook:
      icon: database
  - name: ATLAS
    x-cm-gitbook:
      icon: map
  - name: Timeseries REST
    x-cm-gitbook:
      tag: Timeseries
      icon: table
paths:
  /timeseries/market-orderbooks:
    servers:
      - url: https://api.coinmetrics.io/v4
      - url: https://community-api.coinmetrics.io/v4
    get:
      tags:
        - Timeseries
      summary: Market orderbooks
      description: >-
        Returns orderbooks for specified markets.<br/> Results are ordered by
        tuple `(market, time)`.<br/> To fetch the next page of results use
        `next_page_url` JSON response field.<br/> With `type=event_contract`,
        only prediction markets are selected. Selectors must name an exchange
        and may use prefix wildcards. Prediction results traverse `(normalized
        exchange, raw symbol, time)` in C order; `paging_from=end` returns each
        page in ascending order after traversing backward. Prediction-market
        books are full-depth snapshots taken hourly, plus once per minute during
        the 15 minutes before a market closes. Smaller depths are cut from the
        full book. Only `dataset=snapshots` is supported, and `granularity=raw`
        returns every stored snapshot.
      operationId: getTimeseriesMarketOrderbooks
      parameters:
        - $ref: '#/components/parameters/MarketId'
        - $ref: '#/components/parameters/TimeseriesMarketOrderbooksType'
        - $ref: '#/components/parameters/MarketOrderBooksAndQuotesGranularity'
        - $ref: '#/components/parameters/StartTime'
        - $ref: '#/components/parameters/EndTime'
        - $ref: '#/components/parameters/StartInclusive'
        - $ref: '#/components/parameters/EndInclusive'
        - $ref: '#/components/parameters/Timezone'
        - $ref: '#/components/parameters/BookPageSize'
        - $ref: '#/components/parameters/BookDepth'
        - $ref: '#/components/parameters/CatalogResponseFormat'
        - $ref: '#/components/parameters/PagingFrom'
        - $ref: '#/components/parameters/LimitPerMarket'
        - $ref: '#/components/parameters/Pretty'
        - $ref: '#/components/parameters/NextPageToken'
        - $ref: '#/components/parameters/OrderBookDataset'
        - $ref: '#/components/parameters/OrderBookStartWithSnapshot'
      responses:
        '200':
          $ref: '#/components/responses/MarketOrderBooks'
        '400':
          $ref: '#/components/responses/MarketNotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '414':
          $ref: '#/components/responses/UriTooLong'
      security:
        - api_key: []
      x-codeSamples:
        - lang: Shell
          label: Shell
          source: >
            curl --compressed
            "https://api.coinmetrics.io/v4/timeseries/market-orderbooks?start_time=2020-06-08T21:00:00Z&end_time=2020-06-08T22:00:00Z&paging_from=start&markets=coinbase-btc-usd-spot&pretty=true&api_key=<your_key>"
        - lang: Python
          label: Python
          source: >
            import requests

            response =
            requests.get('https://api.coinmetrics.io/v4/timeseries/market-orderbooks?start_time=2020-06-08T21:00:00Z&end_time=2020-06-08T22:00:00Z&paging_from=start&markets=coinbase-btc-usd-spot&pretty=true&api_key=<your_key>').json()

            print(response)
        - lang: Python
          label: Python Client
          source: >
            from coinmetrics.api_client import CoinMetricsClient

            client = CoinMetricsClient(<your_key>)


            response =
            client.get_market_orderbooks(start_time="2020-06-08T21:00:00Z",
            end_time="2020-06-08T22:00:00Z", paging_from="start",
            markets="coinbase-btc-usd-spot").to_list()

            print(response)
components:
  parameters:
    MarketId:
      description: >-
        Comma separated list of markets or market patterns like `exchange-*` or
        `exchange-*-spot` or `*USDT-future`.<br/> Use a corresponding
        `/catalog-all-v2/market-{dataType}` endpoint for the full list of
        supported markets for a given data type.
      in: query
      name: markets
      required: true
      schema:
        type: array
        items:
          type: string
      explode: false
    TimeseriesMarketOrderbooksType:
      description: >-
        Selects prediction-market order books. Without this parameter,
        prediction markets are excluded.
      in: query
      name: type
      schema:
        type: string
        enum:
          - event_contract
    MarketOrderBooksAndQuotesGranularity:
      description: >-
        Downsampling granularity of market order books and quotes. Supported
        values are `raw`, `1m`, `1h`, and `1d`.
      in: query
      name: granularity
      schema:
        default: raw
        type: string
        enum:
          - raw
          - 1m
          - 1h
          - 1d
    StartTime:
      description: >-
        Start of the time interval.<br/> This field refers to the `time` field
        in the response.<br/> 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`.<br/> Inclusive by default.<br/> UTC timezone
        by default. `Z` suffix is optional and `timezone` parameter has a
        priority over it.<br/> If `start_time` is omitted, response will include
        time series from the **earliest** time available.
      in: query
      name: start_time
      schema:
        type: string
    EndTime:
      description: >-
        End of the time interval.<br/> This field refers to the `time` field in
        the response.<br/> 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`.<br/> Inclusive by default.<br/> UTC timezone
        by default. `Z` suffix is optional and `timezone` parameter has a
        priority over it.<br/> If `end_time` is omitted, response will include
        time series up to the **latest** time available.
      in: query
      name: end_time
      schema:
        type: string
    StartInclusive:
      description: Inclusive or exclusive corresponding `start_*` parameters.
      in: query
      name: start_inclusive
      schema:
        default: true
        type: boolean
    EndInclusive:
      description: Inclusive or exclusive corresponding `end_*` parameters.
      in: query
      name: end_inclusive
      schema:
        default: true
        type: boolean
    Timezone:
      description: >-
        Timezone name for `start_time` and `end_time` timestamps.<br/> This
        parameter does not modify the output times, which are always `UTC`.<br/>
        Format is defined by [TZ
        database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
      in: query
      name: timezone
      schema:
        example: America/New_York
        default: UTC
        type: string
    BookPageSize:
      description: >-
        Number of items per single page of results. Maximum value for unlimited
        order books is 100.<br/> The value of this parameter is ignored if the
        endpoint supports the `format` parameter and its value is set to
        `json_stream`.
      in: query
      name: page_size
      schema:
        default: 100
        type: integer
        format: int32
        minimum: 1
        maximum: 10000
    BookDepth:
      description: >-
        Book depth limit. Supported values are between 1 and 30000,
        `10pct_mid_price` or `full_book`.
      in: query
      name: depth_limit
      schema:
        default: '100'
        type: string
    CatalogResponseFormat:
      description: Format of the response. Supported values are `json`, `json_stream`.
      in: query
      name: format
      schema:
        type: string
        default: json
    PagingFrom:
      description: >-
        Where does the first page start, at the start of the interval or at the
        end.<br/> The value of this parameter is ignored if the endpoint
        supports the `format` parameter and its value is set to `json_stream`.
      in: query
      name: paging_from
      schema:
        default: end
        enum:
          - start
          - end
        type: string
        format: PagingFrom
    LimitPerMarket:
      description: >-
        How many entries per market result should contain. It is useful when
        multiple markets are requested.
      in: query
      name: limit_per_market
      schema:
        type: integer
        format: int32
    Pretty:
      description: Human-readable formatting of JSON responses.
      in: query
      name: pretty
      schema:
        type: boolean
        default: false
    NextPageToken:
      description: >-
        Token for receiving the results from the next page of a query.<br/>
        Should not be used directly. To iterate through pages just use
        `next_page_url` response field.
      in: query
      name: next_page_token
      schema:
        type: string
    OrderBookDataset:
      description: >-
        Logical order book dataset to return.<br/><br/> `snapshots` (default)
        returns snapshot rows only.<br/><br/> `updates` returns Book Streams
        snapshot/update rows for migrated exchanges.<br/><br/> Caveats:<br/>
        <ul>
            <li>`dataset=updates` is currently supported for `full_book` and `30000` depths, `raw` granularity, `json_stream` format, `paging_from=start`, and migrated exchanges only.</li>
            <li>When the `updates` dataset is requested, there are no guarantees on how snapshots are placed inside the data. Snapshots can appear at arbitrary timestamps and at irregular intervals.</li>
            <li>Clients should reset their order book state on every snapshot row, not only on the first one. Snapshots may be emitted mid-stream, for example when the upstream feed is switched, and can carry book state that differs from prior updates. Treating every snapshot as a full state replacement is always safe while skipping snapshots is not.</li>
            <li>When the `updates` dataset is requested, the response may contain redundant snapshots that do not change order book state and are there for state synchronization. Such redundant snapshots have the same timestamp and `coin_metrics_id` as the previous row. Clients may use this to detect redundant snapshots, but the safe default is still to reset state on every snapshot.</li>
        </ul>
      in: query
      name: dataset
      schema:
        type: string
        enum:
          - snapshots
          - updates
        default: snapshots
    OrderBookStartWithSnapshot:
      description: >-
        Applies only when `dataset=updates`.<br/><br/> When `false` (default),
        rows are returned from the exact readable range. This is useful when the
        order book state is already initialized so the timestamp of the last row
        received can be used to resume downloading order book data.<br/><br/>
        When `true`, the response starts with a snapshot row when one is
        available at or before the effective dataset start. This is useful for
        order book state initialization. The API may include a snapshot from
        before `start_time` so client state can be initialized before the first
        update row is applied.<br/><br/> This parameter is ignored when
        `dataset=snapshots`.
      in: query
      name: start_with_snapshot
      schema:
        type: boolean
        default: false
  responses:
    MarketOrderBooks:
      description: Time series of market order books.
      content:
        application/json:
          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'
            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
          schema:
            $ref: '#/components/schemas/MarketOrderbookResponse'
    MarketNotFound:
      content:
        application/json:
          example:
            error:
              type: bad_parameter
              message: >-
                Bad parameter 'markets'. Market 'sdvwbtc-as-asd-spot' is not
                supported.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Market not found.
    Unauthorized:
      description: Requested resource requires authorization.
      content:
        application/json:
          examples:
            unauthorized:
              summary: Unauthorized error response.
              value:
                error:
                  type: unauthorized
                  message: Requested resource requires authorization.
            wrong_credentials:
              summary: Wrong credentials error response.
              value:
                error:
                  type: wrong_credentials
                  message: Supplied credentials are not valid.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      content:
        application/json:
          example:
            error:
              type: forbidden
              message: >-
                Requested metric 'SplyBMXNtv' with frequency '1d' for asset
                'btc' is not available with supplied credentials.
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Requested resource is not available with supplied credentials.
    UriTooLong:
      description: Provided URI is too long. It must not be greater than 10000 symbols.
  schemas:
    MarketOrderbookResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/MarketOrderBook'
          type: array
        next_page_token:
          $ref: '#/components/schemas/NextPageToken'
        next_page_url:
          $ref: '#/components/schemas/NextPageUrl'
      required:
        - data
      type: object
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
      required:
        - error
      type: object
    MarketOrderBook:
      description: Information about order book.
      properties:
        market:
          $ref: '#/components/schemas/MarketId'
        time:
          $ref: '#/components/schemas/Time'
        coin_metrics_id:
          $ref: '#/components/schemas/OrderBookAndQuoteCoinMetricsId'
        asks:
          $ref: '#/components/schemas/OrderBookAsks'
        bids:
          $ref: '#/components/schemas/OrderBookBids'
        database_time:
          $ref: '#/components/schemas/DatabaseTime'
        collect_time:
          $ref: '#/components/schemas/OrderBookCollectTime'
      type: object
      required:
        - market
        - time
        - coin_metrics_id
        - asks
        - bids
        - database_time
    NextPageToken:
      description: Token of the next page results for a given request.
      type: string
    NextPageUrl:
      description: URL of the next page results for a given request.
      type: string
    ErrorObject:
      properties:
        type:
          description: Error type string. Can be used for error identification.
          type: string
        message:
          description: >-
            Human-friendly error description. Can be amended without prior
            notification. Do not use for error identification in your code.
          type: string
      required:
        - type
        - description
      type: object
    MarketId:
      description: Unique name of the market.
      type: string
    Time:
      description: >-
        The time in ISO 8601 date-time format. Always with nanoseconds
        precision.
      type: string
      format: date-time
    OrderBookAndQuoteCoinMetricsId:
      description: >-
        ID of an order book or quote. It can be generated by Coin Metrics or
        provided by an exchange. If it is generated by Coin Metrics it is
        unique. If it is generated by exchange we can't guarantee its
        uniqueness.
      type: string
    OrderBookAsks:
      description: The ask orders on the order book.
      items:
        $ref: '#/components/schemas/BookEntry'
      type: array
    OrderBookBids:
      description: The bids orders on the order book.
      items:
        $ref: '#/components/schemas/BookEntry'
      type: array
    DatabaseTime:
      description: >-
        A time when we saved the data in the database. The time is in ISO 8601
        date-time format. Always with nanoseconds precision.
      type: string
      format: date-time
    OrderBookCollectTime:
      description: Time of when the order book was received from the exchange.
      type: string
      format: date-time
    BookEntry:
      properties:
        price:
          $ref: '#/components/schemas/OrderBookPrice'
        size:
          $ref: '#/components/schemas/OrderBookSize'
      required:
        - price
        - size
      type: object
    OrderBookPrice:
      description: The limit price of the order on the order book.
      type: string
      format: decimal
    OrderBookSize:
      description: >-
        The size of the limit order on the order book in units of the base
        asset.
      type: string
      format: decimal
  securitySchemes:
    api_key:
      description: Coin Metrics API key can be specified as `?api_key=` query parameter.
      in: query
      name: api_key
      type: apiKey

````