====== Market Data ======

[[developers:apiv2|◀ WebSocket API (V2)]]

Send a [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L9|MarketSubscribe]] message in order to subscribe for market data. You may have multiple active market subscriptions (up to the subscription limit set for your user.)

^ Feed ^ Description ^
| **Depth of Market (Top of Book)** | Provides the best bid and best offer. |
| **Depth of Market (Full Order Book)** | Provides the 10 best bids and offers in the market. |
| **Market by Order (CME Only)** | Provides the complete order book, including order id's and position in queue information. |
| **Ticker** | Provides a ticker of every trade in the market. |

Note: Trade ticker includes order id's when subscribed for MBO.


===== Identifying a Market =====

Subscriptions are keyed by ''exchange_id'', ''contract_id'' and ''market_id''. Retrieve them from the REST-based [[developers:markets|Instruments API]]

===== Subscribe =====

<code>
market_subscribe {
  exchange_id: "CME_Eq"
  contract_id: "ES"
  market_id:   "XME_Eq ES ()"
  quotes: QUOTES_FULL_ORDER_BOOK   // detail level (see below)
  ticker: true                     // also stream trade prints
}
</code>

The [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/common/enums.proto#L95|Quotes]] enum selects the market data feed:

^ Value ^ You receive ^
| ''QUOTES_NONE'' | **Unsubscribes** the market |
| ''QUOTES_TOP_OF_BOOK'' | Best bid / best offer (TOB) market depth feed |
| ''QUOTES_FULL_ORDER_BOOK'' | Top-10 bids and offfers (FOB) market depth feed |
| ''QUOTES_MARKET_BY_ORDER'' | Market by order (MBO) feed |

**''ticker''** — when true, trade prints stream as [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L119|MarketTrade]] messages.

**Unsubscribe** — Send a [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L9|MarketSubscribe]] for the same market with ''quotes: QUOTES_NONE''.

===== What You Receive =====

**Quote Feed** (''TOP_OF_BOOK'' / ''FULL_ORDER_BOOK''):
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L190|MarketSnapshot]] — full current state on subscribe (bundles depth, trades, high/low, price limits, settlement).
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L79|MarketDepth]] — incremental bid/offer/implied updates thereafter.

**Market by Order Feed** (''MARKET_BY_ORDER''):
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L213|MarketByOrderSnapshot]] — all resting orders plus ''last_sequence''.
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L231|MarketByOrderUpdate]] — per-order changes; each has a ''sequence'' and ''updates[]'' of type ''ADD_OR_UPDATE'', ''DELETE'' or ''CLEAR''. Apply in order; on a gap, resubscribe.

**Ticker Feed**
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L119|MarketTrade]] — when ''ticker'' is set. For an MBO subscription it also carries the trade ''sequence'' and the participating resting orders

**Always:**
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L29|MarketDetails]] — the instrument definition.
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L144|MarketHighLow]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L155|MarketPriceLimits]], [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L165|MarketSettlement]] — as they occur.
  * [[https://github.com/CTS-Futures/t4-api-tools/blob/main/proto/t4/v2/market/market.proto#L21|MarketSubscribeReject]] — subscription refused.