Differences

This shows you the differences between two versions of the page.

--- developers:websocket:orders [2025/03/14 20:15] – created chad
+++ developers:websocket:orders [2025/03/14 22:10] (current) – chad
@@ Line 1: / Line 1: @@
-==== Order Routing ====
+===== Order Routing =====
-The WebSocket API provides real-time order routing functionality, allowing clients to submit, revise, and pull orders efficiently. All order-related operations are sent within a **ClientMessage** envelope and responses are received within a **ServerMessage** envelope.
+The WebSocket API provides real-time order routing, allowing clients to submit, revise, and pull orders. [[developers:websocket#message_structure_overview|All order-related operations are sent within a **ClientMessage** envelope and responses are received within a **ServerMessage** envelope.]]
-This section covers:
-  * Submitting Orders
-  * Revising Orders
-  * Pulling Orders
-  * Handling Order Updates
-A **C# helper tool** is available to assist developers in constructing order messages. **[Repository Placeholder - Add Link]**
+==== Submitting an Order ====
-=== Submitting an Order ===
+To submit an order, clients send an **OrderSubmit** message.
-To submit an order, clients must send an **OrderSubmit** message. This includes key details such as the **account ID, market ID, order type, price, and volume**.
+<bootnote>
+You must subscribe to the Account before submitting an order into it. Orders will be rejected if the account is not subscribed.
+</bootnote>
 Example **OrderSubmit** message:
 <code>
-message ClientMessage {
+OrderSubmit {
-  oneof payload {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
-    OrderSubmit order_submit = X;
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
-  }
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 5,
+         LimitPrice = "4200.50"
+      }
+   ]
 }
-message OrderSubmit {
+</code>
-  string user_id = 1;
-  string account_id = 2;
-  string market_id = 3;
-  repeated Order orders = 4;
-  message Order {
+<bootnote>
-    BuySell buy_sell = 1;
+The **OrderSubmit** message allows submitting multiple orders at once.
-    PriceType price_type = 2;
+</bootnote>
-    TimeType time_type = 3;
-    int32 volume = 4;
-    optional Price limit_price = 5;
+==== Revising an Order ====
-  }
+To revise an existing order, clients send an **OrderRevise** message.
+Example **OrderRevise** message:
+<code>
+OrderRevise {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Revisions = [
+      {
+         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1",
+         Volume = 10,
+         LimitPrice = "4250.00"
+      }
+   ]
 }
 </code>
-The **OrderSubmit** message allows submitting multiple orders at once, each with its own **BuySell**, **PriceType**, and **TimeType**.
+<bootnote>
+The **OrderRevise** message allows revising multiple orders at once.
+</bootnote>
-=== Revising an Order ===
-To revise an existing order, clients must send an **OrderRevise** message. This allows modifying key parameters such as **price, volume, and time type**, but the market and buy/sell direction cannot be changed.
+==== Pulling (Cancelling) an Order ====
-Example **OrderRevise** message:
+To cancel an order, clients must send an **OrderPull** message with the **order ID**.
+Example **OrderPull** message:
 <code>
-message ClientMessage {
+OrderPull {
-  oneof payload {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
-    OrderRevise order_revise = X;
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
-  }
+   MarketId = "XCME_C ZC (H25)",
+   Pulls = [
+      {
+         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1"
+      }
+   ]
 }
+</code>
-message OrderRevise {
+<bootnote>
-  string order_id = 1;
+The **OrderPull** message allows pulling multiple orders at once.
-  optional Price new_limit_price = 2;
+</bootnote>
-  optional int32 new_volume = 3;
-  optional TimeType new_time_type = 4;
+===== Order Types =====
+The WebSocket API supports a variety of order types to accommodate different trading strategies. Below are the supported order types, along with their corresponding **OrderSubmit** messages.
+==== Market Order ====
+A Market Order executes immediately at the best available price.
+Example **Market Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Market,
+         TimeType = TimeType.Normal,
+         Volume = 1
+      }
+   ]
 }
 </code>
-Only fields that need to be changed should be included.
-=== Pulling (Cancelling) an Order ===
-To cancel an order, clients must send an **OrderPull** message with the **order ID**.
-Example **OrderPull** message:
+==== Limit Order ====
+A Limit Order is submitted with a specific limit price. The order will only execute at the specified price or better.
+Example **Limit Order** message:
 <code>
-message ClientMessage {
+OrderSubmit {
-  oneof payload {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
-    OrderPull order_pull = X;
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
-  }
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         LimitPrice = "2376.50"
+      }
+   ]
 }
+</code>
-message OrderPull {
-  string order_id = 1;
+==== Stop Order ====
+A Stop Market Order becomes a Market Order when the stop price is reached.
+Example **Stop Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.StopMarket,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         StopPrice = "2376.50"
+      }
+   ]
 }
 </code>
-Once an order is successfully canceled, an **OrderUpdate** message will be sent in the **ServerMessage**.
-=== Handling Order Updates ===
-All order state changes, including new orders, fills, revisions, and cancellations, are communicated via the **OrderUpdate** message.
-Example **OrderUpdate** message:
+==== Stop Limit Order ====
+A Stop Limit Order becomes a Limit Order when the stop price is reached.
+Example **Stop Limit Order** message:
 <code>
-message ServerMessage {
+OrderSubmit {
-  oneof payload {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
-    OrderUpdate order_update = X;
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
-  }
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.StopLimit,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         StopPrice = "2375.00",
+         LimitPrice = "2375.00"
+      }
+   ]
 }
+</code>
-message OrderUpdate {
-  string order_id = 1;
-  OrderStatus status = 2;
-  optional Price filled_price = 3;
+==== Trailing Stop Order ====
-  optional int32 filled_volume = 4;
+A Trailing Stop Order moves the stop price automatically based on price movement.
+Example **Trailing Stop Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.StopMarket,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         StopPrice = "2375.00",
+         TrailPrice = "50"
+      }
+   ]
+}
+</code>
+==== Fill or Kill (FOK) Order ====
+A Fill or Kill (FOK) Order must be executed immediately in full or it is canceled.
+Example **Fill or Kill (FOK) Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.CompleteVolume,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      }
+   ]
+}
+</code>
+==== Immediate or Cancel (IOC) Order ====
+An Immediate or Cancel (IOC) Order executes immediately for the available quantity and cancels the rest.
+Example **Immediate or Cancel (IOC) Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.ImmediateAndCancel,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      }
+   ]
+}
+</code>
+==== Good Till Canceled (GTC) Order ====
+A Good Till Canceled (GTC) Order remains open until it is filled or explicitly canceled.
+Example **Good Till Canceled (GTC) Order** message:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.GoodTillCancelled,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      }
+   ]
+}
+</code>
+==== Order Cancels Order (OCO) ====
+An OCO (One Cancels Other) order is a pair of orders submitted together. Both orders are on the same side of the market: one is a Limit Order and the other is a Stop Order. When one fills, the other is automatically canceled. If one order is partially filled, the remaining volume of the other order is adjusted accordingly.
+OCO orders must be placed for the **same Market and Account**.
+Example OrderSubmit message for an OCO order:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   OrderLink = OrderLink.OCO,
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      },
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.StopMarket,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         StopPrice = "2380.00"
+      }
+   ]
+}
+</code>
+Both orders are placed at the same time. If the Limit Order is filled, the Stop Order is automatically canceled, and vice versa.
+==== AutoOCO Order ====
+An AutoOCO Order is a batch of three orders:
+  * A Trigger Order that initiates the trade.
+  * Two OCO Orders (Take Profit and Stop Loss) that execute based on the trigger order's fill price.
+If the Trigger Order fills, the OCO Orders are submitted. If the OCO Orders begin filling, any remaining volume in the Trigger Order is canceled.
+Example OrderSubmit message for an AutoOCO order:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   OrderLink = OrderLink.AutoOCO,
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      },
+      {
+         BuySell = BuySell.Sell,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 0,
+         LimitPrice = "2380.00"
+      },
+      {
+         BuySell = BuySell.Sell,
+         PriceType = PriceType.StopMarket,
+         TimeType = TimeType.Normal,
+         Volume = 0,
+         StopPrice = "2365.00"
+      }
+   ]
+}
+</code>
+==== Take Profit and Stop Loss ====
+Take profit and stop loss orders are a type of OCO order. The first order in the batch is the **Trigger Order**. Once it fills, the **Take Profit** and **Stop Loss** orders are submitted.
+Example OrderSubmit message for a Take Profit / Stop Loss order:
+<code>
+OrderSubmit {
+   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
+   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
+   MarketId = "XCME_C ZC (H25)",
+   OrderLink = OrderLink.OCO,
+   Orders = [
+      {
+         BuySell = BuySell.Buy,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 1,
+         LimitPrice = "2375.00"
+      },
+      {
+         BuySell = BuySell.Sell,
+         PriceType = PriceType.Limit,
+         TimeType = TimeType.Normal,
+         Volume = 0,
+         LimitPrice = "2385.00"
+      },
+      {
+         BuySell = BuySell.Sell,
+         PriceType = PriceType.StopMarket,
+         TimeType = TimeType.Normal,
+         Volume = 0,
+         StopPrice = "2360.00"
+      }
+   ]
 }
 </code>
-Developers should listen for **OrderUpdate** messages to track order execution status.
+When the **Trigger Order** executes, the **Take Profit** and **Stop Loss** orders are placed. If the price reaches the take profit level, the stop loss order is canceled, and vice versa.
-This structure ensures a **consistent, efficient**, and **real-time** approach to order routing.