developers:websocket:orders

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
developers:websocket:orders [2025/03/14 21:21] – chaddevelopers:websocket:orders [Unknown date] (current) – external edit (Unknown date) 127.0.0.1
Line 1: Line 1:
-==== Order Routing ====+===== Order Routing =====
  
 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.]] 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.]]
  
  
-=== Submitting an Order ===+==== Submitting an Order ====
  
 To submit an order, clients send an **OrderSubmit** message. To submit an order, clients send an **OrderSubmit** message.
Line 16: Line 16:
 <code> <code>
 OrderSubmit { OrderSubmit {
-   UserId = "1111-2222-3333-4444", +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0", 
-   AccountId = "5555-6666-7777-8888", +   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620", 
-   MarketId = "9999-0000-AAAA-BBBB",+   MarketId = "XCME_C ZC (H25)",
    Orders = [    Orders = [
       {       {
Line 32: Line 32:
 </code> </code>
  
-The **OrderSubmit** message allows submitting multiple orders at once, each with its own **BuySell**, **PriceType**, and **TimeType**.+<bootnote> 
 +The **OrderSubmit** message allows submitting multiple orders at once. 
 +</bootnote> 
  
-=== Revising an Order ===+==== 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.+To revise an existing order, clients send an **OrderRevise** message.
  
 Example **OrderRevise** message: Example **OrderRevise** message:
  
 <code> <code>
-message ClientMessage { +OrderRevise { 
-  oneof payload { +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0", 
-    OrderRevise order_revise = X; +   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620", 
-  } +   MarketId = "XCME_C ZC (H25)", 
-} +   Revisions = [ 
- +      { 
-message OrderRevise { +         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1", 
-  string order_id = 1; +         Volume = 10, 
-  optional Price new_limit_price = 2; +         LimitPrice = "4250.00" 
-  optional int32 new_volume = 3; +      } 
-  optional TimeType new_time_type = 4;+   ]
 } }
 </code> </code>
  
-Only fields that need to be changed should be included.+<bootnote> 
 +The **OrderRevise** message allows revising multiple orders at once. 
 +</bootnote>
  
-=== Pulling (Cancelling) an Order ===+ 
 +==== Pulling (Cancelling) an Order ====
  
 To cancel an order, clients must send an **OrderPull** message with the **order ID**. To cancel an order, clients must send an **OrderPull** message with the **order ID**.
Line 64: Line 70:
  
 <code> <code>
-message ClientMessage { +OrderPull { 
-  oneof payload { +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0", 
-    OrderPull order_pull = X; +   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620", 
-  }+   MarketId = "XCME_C ZC (H25)", 
 +   Pulls = [ 
 +      { 
 +         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1" 
 +      } 
 +   ]
 } }
 +</code>
  
-message OrderPull { +<bootnote> 
-  string order_id = 1;+The **OrderPull** message allows pulling multiple orders at once. 
 +</bootnote> 
 + 
 + 
 +===== 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> </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:+==== 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> <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.Limit, 
 +         TimeType = TimeType.Normal, 
 +         Volume = 1, 
 +         LimitPrice = "2376.50" 
 +      } 
 +   ]
 } }
 +</code>
  
-message OrderUpdate { + 
-  string order_id = 1; + 
-  OrderStatus status = 2; + 
-  optional Price filled_price = 3; +==== Stop Order ==== 
-  optional int32 filled_volume = 4;+ 
 +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> </code>
  
-Developers should listen for **OrderUpdate** messages to track order execution status. 
  
-This structure ensures a **consistent, efficient**, and **real-time** approach to order routing. 
  
 +
 +==== Stop Limit Order ====
 +
 +A Stop Limit Order becomes a Limit Order when the stop price is reached.
 +
 +Example **Stop Limit 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.StopLimit,
 +         TimeType = TimeType.Normal,
 +         Volume = 1,
 +         StopPrice = "2375.00",
 +         LimitPrice = "2375.00"
 +      }
 +   ]
 +}
 +</code>
 +
 +
 +
 +
 +==== Trailing Stop Order ====
 +
 +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>
 +
 +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.
 +
 +
 +==== Flatten Position ====
 +
 +A Flatten Position Order closes the entire position in the specified market by submitting an offsetting order at market price.
 +
 +Example **Flatten Position Order** message:
 +
 +<code>
 +OrderSubmit {
 +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
 +   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
 +   MarketId = "XCME_C ZC (H25)",
 +   Orders = [
 +      {
 +         PriceType = PriceType.Flatten
 +      }
 +   ]
 +}
 +</code>
 +
 +<bootnote>
 +The Flatten Position order automatically determines the correct side (Buy/Sell) and volume based on the current position.  Clip size limits are ignored to ensure the entire position is closed.
 +</bootnote>
 +
 +
 +===== Order Status Summary Messages Reference =====
 +
 +When displaying order status to end users, combining the ''OrderStatus'' and <del>OrderChange</del> fields provides more meaningful feedback than either field alone. The following table maps these field combinations to user-friendly status messages.
 +
 +^ Order Status ^ Order Change ^ Status Summary Message ^ Notes ^
 +| **Finished States**  ||||
 +| Finished | ''PullFailed'', ''PullRejected'', ''PullRiskFailed'' | "Cancel Failed" | Includes StatusDetail |
 +| Finished | ''PullSuccess'', ''PullSent'', ''PullRiskSuccess'' //(with fills)// | "Completed, Partial Fill" | When TotalFillVolume ≠ 0 |
 +| Finished | ''PullSuccess'', ''PullSent'', ''PullRiskSuccess'' //(no fills)// | "Canceled" | When TotalFillVolume = 0 |
 +| Finished | ''TradeCompleted'' //(partial)// | "Completed, Partial Fill" | When TotalFillVolume < CurrentVolume |
 +| Finished | ''TradeCompleted'' //(full)// | "Completed, Filled" | When TotalFillVolume = CurrentVolume |
 +| Finished | ''StatusRequestFailed'', ''StatusRequestRejected'', ''StatusRequestRiskFailed'', ''StatusRequestRiskSuccess'', ''StatusRequestSent'', ''StatusRequestSuccess'', ''TagFailed'', ''TagSuccess'' //(partial)// | "Completed, Partial Fill, {OrderChange}" | When TotalFillVolume < CurrentVolume |
 +| Finished | ''StatusRequestFailed'', ''StatusRequestRejected'', ''StatusRequestRiskFailed'', ''StatusRequestRiskSuccess'', ''StatusRequestSent'', ''StatusRequestSuccess'', ''TagFailed'', ''TagSuccess'' //(full)// | "Completed, Filled, {OrderChange}" | When TotalFillVolume = CurrentVolume |
 +| Finished | ''RevisionRiskFailed'' //(filled)// | "Completed, Filled, {OrderChange}" | When TotalFillVolume = CurrentVolume |
 +| Finished | ''TradeBusted'' | "Completed, {OrderChange}" | |
 +| Finished | ''SubmissionSuccess'' //(RFQ only)// | "Completed" | Only for PriceType.RFQ |
 +| **Rejected States**  ||||
 +| Rejected | ''StatusRequestFailed'', ''StatusRequestRejected'', ''StatusRequestRiskFailed'', ''StatusRequestRiskSuccess'', ''StatusRequestSent'', ''StatusRequestSuccess'' | "Rejected, {OrderChange}" | Includes StatusDetail |
 +| Rejected | //(Other changes)// | "Rejected" | Includes StatusDetail |
 +| **Working States**  ||||
 +| Working | ''PullRiskSuccess'', ''PullSent'', ''PullSuccess'' | "Canceling..." | |
 +| Working | ''RevisionSent'', ''RevisionRiskSuccess'' | "Revising..." | |
 +| Working | ''RevisionSuccess'' | "Working, Revised" | |
 +| Working | ''RevisionFailed'', ''RevisionRejected'', ''RevisionRiskFailed'' | "Working, Revision Failed" | Includes StatusDetail |
 +| Working | ''PullFailed'', ''PullRejected'', ''PullRiskFailed'' | "Working, Cancel Failed" | Includes StatusDetail |
 +| Working | ''Trade'', ''SubmissionSent'', ''SubmissionSuccess'', ''SubmissionRiskSuccess'' | "Working..." | |
 +| Working | ''Handover'' | "Working, Handover" | |
 +| Working | ''Rollover'' | "Working, Rollover" | |
 +| Working | ''StatusRequestFailed'', ''StatusRequestRejected'', ''StatusRequestRiskFailed'', ''StatusRequestRiskSuccess'', ''StatusRequestSent'', ''StatusRequestSuccess'', ''TagFailed'', ''TagSuccess'' | "Working, {OrderChange}" | |
 +| Working | //(Any change with fills)// | "{Base Message}, Partial Fill" | Appended when TotalFillVolume > 0 |
 +| **None (Pre-Submission) States**  ||||
 +| None | None | "Submitting..." | |
 +| None | ''SubmissionRiskSuccess'' | "Submitting to Exchange" | |
 +| None | ''SubmissionRejected'', ''SubmissionRiskRejected'' | "Submission Rejected" | |
 +| None | ''SubmissionFailed'' | "Submission Failed" | |
 +| None | ''SubmissionSent'', ''SubmissionSuccess'' | "Submission Sent" | |
 +| **Held States**  ||||
 +| Held | //(Any)// | "Held on Server..." (Real Market) \\ "Held on Client..." (Non-Real Market) | |
  • developers/websocket/orders.1741987313.txt.gz
  • Last modified: 2025/03/14 21:21
  • by chad