developers:websocket:orders [Documentation]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== 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.]]


==== Submitting an Order ====

To submit an order, clients send an **OrderSubmit** message.

<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>
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.Normal,
         Volume = 5,
         LimitPrice = "4200.50"
      }
   ]
}

</code>

<bootnote>
The **OrderSubmit** message allows submitting multiple orders at once.
</bootnote>


==== 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>

<bootnote>
The **OrderRevise** message allows revising multiple orders at once.
</bootnote>


==== Pulling (Cancelling) an Order ====

To cancel an order, clients must send an **OrderPull** message with the **order ID**.

Example **OrderPull** message:

<code>
OrderPull {
   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
   MarketId = "XCME_C ZC (H25)",
   Pulls = [
      {
         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1"
      }
   ]
}
</code>

<bootnote>
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>




==== 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>
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.Normal,
         Volume = 1,
         LimitPrice = "2376.50"
      }
   ]
}
</code>




==== 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>




==== 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) | |