developers:apiv2:migrating [Documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Migrating from V1 ======

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

V1 (''/v1'') and V2 (''/v2'') run side by side, so you can migrate at your own pace. The envelope model is identical — ''ClientMessage'' / ''ServerMessage'' with a ''oneof'' payload. The changes below are what actually differ.

**Regenerate your code from the ''t4/v2'' proto set** (package ''t4proto.v2.*''). Do not point a V1-generated parser at a ''/v2'' stream — several field numbers were reassigned (see order routing and market data).

===== Endpoint =====

''wss://…/v1'' → ''wss://…/v2''. Same hostnames.

===== Market Data: One Subscribe Message =====

V1 had two subscribe messages (''MarketDepthSubscribe'' + ''MarketByOrderSubscribe'') and request-time ''DepthBuffer'' / ''DepthLevels'' parameters. V2 replaces all of that with a single ''MarketSubscribe'':

  * ''quotes'' (''Quotes'' enum) picks the feed in one field: ''NONE'' (unsubscribe), ''TOP_OF_BOOK'', ''FULL_ORDER_BOOK'', ''MARKET_BY_ORDER''.
  * ''ticker'' (bool) turns the trade feed on.

Message changes (''ServerMessage''):

^ V1 ^ V2 ^
| ''MarketDepthSubscribeReject'' (100) + ''MarketByOrderSubscribeReject'' (101) | ''MarketSubscribeReject'' (100) — one reject |
| ''MarketDepthTrade'' (104) | ''MarketTrade'' (104) — one trade message for all feeds |
| ''MarketByOrderTrade'' (111) | *(removed — MBO trades arrive as ''MarketTrade'' with ''sequence'' + participating orders)* |

''MarketDepth'' (103), ''MarketSnapshot'' (108), ''MarketByOrderSnapshot'' (109) and ''MarketByOrderUpdate'' (110) are unchanged. See [[developers:apiv2:markets|Market Data]].

===== Order Updates: 6 Messages Into 1 =====

V1 spread order lifecycle events across six server messages. V2 collapses them into a single ''OrderUpdate'' plus a dedicated ''OrderTrade''.

^ V1 (ServerMessage) ^ V2 ^
| ''OrderUpdate'' (300) | ''OrderUpdate'' (300), discriminated by ''update_type'' |
| ''OrderUpdateMulti'' (301) | *(removed — snapshots arrive as ''OrderUpdate'' with ''update_type=SNAPSHOT'')* |
| ''OrderUpdateFailed'' (302) | ''OrderUpdate'' with ''update_type=FAILED'' |
| ''OrderUpdateStatus'' (303) | ''OrderUpdate'' with ''update_type=STATUS'' |
| ''OrderUpdateTrade'' (304) | ''OrderUpdate'' with ''update_type=TRADE'' + ''OrderTrade'' (301) |
| ''OrderUpdateTradeLeg'' (305) | ''OrderUpdate'' with ''update_type=TRADE_LEG'' |

**Field-number reassignment (order routing responses):** V2 field ''301'' is now ''OrderTrade'' (was ''OrderUpdateMulti'') and ''302'' is now ''MarginInquiryResponse'' (was ''OrderUpdateFailed''). Switch on ''ServerMessage.payload'' from the V2 proto — do not assume V1 numbering.

===== Volumes Are Decimal Strings =====

Every order-routing volume — ''volume'', ''max_show'', ''max_volume'', ''current_volume'', ''new_volume'', ''total_fill_volume'', ''working_volume'', trade ''volume'' — changed from ''int32'' to the ''Decimal'' string type. This supports fractional exchange quantities (e.g. Kalshi ''"1.50"''). See [[developers:apiv2:pricing|Prices & Data Types]].

**Market-data volumes are unchanged** (still ''int32'').

===== New in V2 =====

  * **Margin inquiry** — set ''margin_inquiry'' on a submitted ''Order'' to receive a ''MarginInquiryResponse'' (margins and impact) without placing the order.
  * **Client order id** — ''ClOrdId'' on ''OrderSubmit'' / ''OrderRevise'' / ''OrderPull''; echoed back as ''tag_cl_ord_id''. You can also address revise/pull by ''ClOrdId''.
  * **Batch correlation** — ''OrderBatchAcknowledge'' / ''OrderBatchReject'' echo ''ClOrdId'' alongside the assigned ''unique_id''.

===== Unchanged =====

The account feed (''ServerMessage'' fields 200–207) keeps the same message names and field numbers as V1 — only the proto package changed.

===== Message Reference =====

Message fields are documented in the ''.proto'' files — see the [[developers:apiv2:reference|Message Catalog]].