> ## 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 a WebSocket stream of orderbooks for specified markets.<br/> Prediction markets (`<exchange>-<symbol>-event_contract`) are supported, both by name and via market patterns, e.g. `kalshi-*` or `*-event_contract`. Patterns match prediction markets of the exchanges available with the supplied credentials. `backfill` is ignored for prediction markets: only live books are sent. A market requested by name gets a full snapshot within about 10 seconds. A prediction market matched only by a pattern is sent from the first snapshot after its first change, so idle markets are not streamed.<br/> Orderbooks are delivered using a sequence of `snapshot` and `update` messages.<br/> Zero value of the `size` response field for `asks` or `bids` means negative `update`.<br/> If you are falling behind (slow client) you will get `warning` message first, then `error` message and disconnection will happen.



## OpenAPI

````yaml /coinmetrics/openapi/coinmetrics.yaml get /timeseries-stream/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-stream/market-orderbooks:
    get:
      tags:
        - Timeseries stream
      summary: Market orderbooks
      description: >-
        Returns a WebSocket stream of orderbooks for specified markets.<br/>
        Prediction markets (`<exchange>-<symbol>-event_contract`) are supported,
        both by name and via market patterns, e.g. `kalshi-*` or
        `*-event_contract`. Patterns match prediction markets of the exchanges
        available with the supplied credentials. `backfill` is ignored for
        prediction markets: only live books are sent. A market requested by name
        gets a full snapshot within about 10 seconds. A prediction market
        matched only by a pattern is sent from the first snapshot after its
        first change, so idle markets are not streamed.<br/> Orderbooks are
        delivered using a sequence of `snapshot` and `update` messages.<br/>
        Zero value of the `size` response field for `asks` or `bids` means
        negative `update`.<br/> If you are falling behind (slow client) you will
        get `warning` message first, then `error` message and disconnection will
        happen.
      operationId: getTimeseriesStreamMarketOrderbooks
      parameters:
        - $ref: '#/components/parameters/MarketId'
        - $ref: '#/components/parameters/StreamingBookDepth'
        - $ref: '#/components/parameters/Backfill'
        - $ref: '#/components/parameters/Pretty'
      responses:
        default:
          $ref: '#/components/responses/StreamingMarketOrderbooks'
      security:
        - api_key: []
      servers:
        - url: wss://api.coinmetrics.io/v4
      x-codeSamples:
        - lang: JavaScript
          label: JavaScript
          source: >
            ws = new
            WebSocket("wss://api.coinmetrics.io/v4/timeseries-stream/market-orderbooks?markets=coinbase-btc-usd-spot&pretty=true&api_key=<your_key>")

            ws.onmessage = m => console.log(m.data); ws.onclose = () =>
            console.log("closed")
        - lang: Python
          label: Python
          source: >
            import asyncio

            import websockets


            async def handle(uri):
                async with websockets.connect(uri) as websocket:
                    while True:
                        print(await websocket.recv())

            asyncio.get_event_loop().run_until_complete(handle('wss://api.coinmetrics.io/v4/timeseries-stream/market-orderbooks?markets=coinbase-btc-usd-spot&pretty=true&api_key=<your_key>'))
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
    StreamingBookDepth:
      description: Book depth limit.
      in: query
      name: depth_limit
      schema:
        default: '100'
        enum:
          - '100'
          - full_book
        type: string
    Backfill:
      description: >-
        What data should be sent upon a connection.<br/> By default the latest
        values are sent just before real-time data.
      in: query
      name: backfill
      schema:
        type: string
        default: latest
        enum:
          - latest
          - none
    Pretty:
      description: Human-readable formatting of JSON responses.
      in: query
      name: pretty
      schema:
        type: boolean
        default: false
  responses:
    StreamingMarketOrderbooks:
      description: Orderbook WebSocket message.
      content:
        application/json:
          examples:
            snapshot_message:
              summary: Example of an order book snapshot message.
              value:
                time: '2020-06-08T21:07:27.015507000Z'
                market: coinbase-btc-usd-spot
                coin_metrics_id: 1591540219445728-16126985
                asks:
                  - price: '9695.09'
                    size: '1.58265903'
                  - price: '9695.1'
                    size: '0.01056118'
                  - price: '9695.14'
                    size: '0.0257'
                bids:
                  - price: '9695.07'
                    size: '0.97684462'
                  - price: '9694.38'
                    size: '0.14852787'
                  - price: '9694.37'
                    size: '0.90808736'
                  - price: '9693.24'
                    size: '0.46738235'
                  - price: '9693'
                    size: '0.0023'
                type: snapshot
                collect_time: '2020-06-08T21:07:27.082612000Z'
                cm_sequence_id: '0'
            update_message:
              summary: Example of an order book update message.
              value:
                time: '2020-06-09T11:19:48.028405000Z'
                market: coinbase-btc-usd-spot
                coin_metrics_id: 1591673013698762-3620038
                asks:
                  - price: '9716.86'
                    size: '0.01732866'
                  - price: '9695.09'
                    size: '0'
                bids: []
                type: update
                collect_time: '2020-06-09T11:19:48.095655000Z'
                cm_sequence_id: '1'
            warning:
              summary: Example of a warning message.
              value:
                warning:
                  type: falling_behind
                  message: >-
                    Your connection is falling behind and messages are being
                    queued for delivery to you. Your queue is now over 60% full.
                    You will be disconnected when the queue is full.
            error:
              summary: Example of an error message.
              value:
                error:
                  type: stall
                  message: >-
                    The client was reading too slowly and was disconnected by
                    the server.
          schema:
            $ref: '#/components/schemas/StreamingMarketOrderbook'
  schemas:
    StreamingMarketOrderbook:
      allOf:
        - type: object
          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'
            type:
              $ref: '#/components/schemas/OrderBookType'
            collect_time:
              $ref: '#/components/schemas/OrderBookCollectTime'
            cm_sequence_id:
              $ref: '#/components/schemas/cmSequenceId'
          required:
            - market
            - time
            - coin_metrics_id
            - asks
            - bids
            - type
            - collect_time
            - cm_sequence_id
    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
    OrderBookType:
      description: Type of the order book.
      enum:
        - snapshot
        - update
      type: string
    OrderBookCollectTime:
      description: Time of when the order book was received from the exchange.
      type: string
      format: date-time
    cmSequenceId:
      description: The monotonically increasing message number, resets on disconnection.
      type: string
    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

````