> ## 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 trades

> Returns a WebSocket stream of trades 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 trades are sent.<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-trades
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-trades:
    get:
      tags:
        - Timeseries stream
      summary: Market trades
      description: >-
        Returns a WebSocket stream of trades 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 trades are sent.<br/> If you are falling
        behind (slow client) you will get `warning` message first, then `error`
        message and disconnection will happen.
      operationId: getTimeseriesStreamMarketTrades
      parameters:
        - $ref: '#/components/parameters/MarketId'
        - $ref: '#/components/parameters/Backfill'
        - $ref: '#/components/parameters/Pretty'
      responses:
        '414':
          $ref: '#/components/responses/UriTooLong'
        default:
          $ref: '#/components/responses/StreamingMarketTrades'
      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-trades?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-trades?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
    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:
    UriTooLong:
      description: Provided URI is too long. It must not be greater than 10000 symbols.
    StreamingMarketTrades:
      description: Trade WebSocket message.
      content:
        application/json:
          examples:
            new_trade:
              summary: Example of a trade message.
              value:
                time: '2020-06-08T21:00:06.138932000Z'
                market: coinbase-btc-usd-spot
                coin_metrics_id: '94233007'
                amount: '0.0197263'
                price: '9702'
                collect_time: '2020-06-08T21:00:06.203893000Z'
                side: buy
                cm_sequence_id: '0'
            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/StreamingMarketTrade'
  schemas:
    StreamingMarketTrade:
      description: Market trade WebSocket message.
      properties:
        market:
          $ref: '#/components/schemas/MarketId'
        time:
          $ref: '#/components/schemas/Time'
        coin_metrics_id:
          $ref: '#/components/schemas/TradesCoinMetricsId'
        amount:
          $ref: '#/components/schemas/TradeAmount'
        price:
          $ref: '#/components/schemas/TradePrice'
        side:
          $ref: '#/components/schemas/TradeSide'
        cm_sequence_id:
          $ref: '#/components/schemas/cmSequenceId'
        collect_time:
          $ref: '#/components/schemas/TradeCollectTime'
        block_hash:
          $ref: '#/components/schemas/TradeBlockHash'
        block_height:
          $ref: '#/components/schemas/TradeBlockHeight'
        txid:
          $ref: '#/components/schemas/TradeTransactionId'
        initiator:
          $ref: '#/components/schemas/TradeInitiator'
        sender:
          $ref: '#/components/schemas/TradeSender'
        beneficiary:
          $ref: '#/components/schemas/TradeBeneficiary'
        mark_price:
          $ref: '#/components/schemas/TradeMarkPrice'
        index_price:
          $ref: '#/components/schemas/TradeIndexPrice'
        iv_trade:
          $ref: '#/components/schemas/TradeImpliedVolatility'
        liquidation:
          $ref: '#/components/schemas/TradeLiquidation'
        raw_outcome:
          description: >-
            Side of the binary outcome the taker traded, as reported by the
            exchange, e.g. `yes` or `no`. Independent of `side`. Available for
            prediction markets (`event_contract`) only.
          type: string
      required:
        - market
        - time
        - coin_metrics_id
        - amount
        - price
        - collect_time
        - cm_sequence_id
      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
    TradesCoinMetricsId:
      description: >-
        ID of a trade (unique per exchange market). We are using exchange
        reported value if exchange reports a unique numeric trade id. If
        exchange reports trade id as a string we convert to numeric using
        Bijective mapping from exchange reported trade id's string. If exchange
        doesn't report unique ID we transform it using exchange reported data to
        form a unique value per market.
      type: string
    TradeAmount:
      description: The amount of the base asset traded.
      type: string
      format: decimal
    TradePrice:
      description: >-
        The price of the base asset quoted in the quote asset that the trade was
        executed at.
      type: string
      format: decimal
    TradeSide:
      description: >-
        The market order side. "buy" means that an ask was removed from the book
        by an incoming buy order, "sell" means that a bid was removed from the
        book by an incoming sell order.
      type: string
    cmSequenceId:
      description: The monotonically increasing message number, resets on disconnection.
      type: string
    TradeCollectTime:
      description: Time of when the trade was received from the exchange.
      type: string
      format: date-time
    TradeBlockHash:
      description: Swap block hash. Available for DeFi markets only.
      type: string
    TradeBlockHeight:
      description: Swap block height. Available for DeFi markets only.
      type: string
      format: int64
    TradeTransactionId:
      description: Swap transaction ID. Available for DeFi markets only.
      type: string
    TradeInitiator:
      description: Swap transaction initiator. Available for DeFi markets only.
      type: string
    TradeSender:
      description: Swap caller. Available for DeFi markets only.
      type: string
    TradeBeneficiary:
      description: Swap output receiver. Available for DeFi markets only.
      type: string
    TradeMarkPrice:
      description: >-
        The price representing the futures' or option's price calculated by the
        exchange for risk management purposes.
      type: string
      format: decimal
    TradeIndexPrice:
      description: >-
        The price index is an aggregate price derived from the major exchanges
        to be representative of the underlying asset's market consensus price.
      type: string
      format: decimal
    TradeImpliedVolatility:
      description: Implied volatility calculated from the trade price.
      type: string
      format: decimal
    TradeLiquidation:
      description: >-
        Indicates whether the maker side, taker side, or both sides of the trade
        is under liquidation.
      type: string
  securitySchemes:
    api_key:
      description: Coin Metrics API key can be specified as `?api_key=` query parameter.
      in: query
      name: api_key
      type: apiKey

````