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 22:08] – chaddevelopers:websocket:orders [Unknown date] (current) – external edit (Unknown date) 127.0.0.1
Line 1: Line 1:
 +<note warning>**Legacy — V1.** This page documents the ''/v1'' WebSocket API and is retained for existing integrations. New development should use [[developers:apiv2|V2]]. See [[developers:apiv2:migrating|Migrating from V1]].</note>
 +
 ===== Order Routing ===== ===== Order Routing =====
  
Line 85: Line 87:
 The **OrderPull** message allows pulling multiple orders at once. The **OrderPull** message allows pulling multiple orders at once.
 </bootnote> </bootnote>
 +
 +==== Routing Orders on Behalf of Another User ====
 +
 +Firms that trade on behalf of their own customers can submit, revise and pull orders for another user without that user being logged in. Set **OnBehalfOfUserName** to the **username** of the user the order belongs to.
 +
 +The **UserId** field continues to identify the authenticated (routing) user - do not put the customer's id there.
 +
 +<bootnote>
 +**OnBehalfOfUserName** is a username, not a user id. Leave it empty or omit it to trade as the authenticated user - existing applications are unaffected.
 +</bootnote>
 +
 +Requirements:
 +
 +  * The authenticated (routing) user must have the **OrderRouting** role. This role is not enabled by default - a firm administrator must enable it on that user before any routed order will be accepted.
 +  * The user named in **OnBehalfOfUserName** must belong to the authenticated user's firm or one of its child firms, and must be enabled and not deleted.
 +  * The account must be one the named user is entitled to trade, and it must be subscribed by the authenticated session.
 +
 +Example **OrderSubmit** on behalf of another user:
 +
 +<code>
 +OrderSubmit {
 +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
 +   OnBehalfOfUserName = "jsmith",
 +   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>
 +
 +The same field is available on **OrderRevise** and **OrderPull**:
 +
 +<code>
 +OrderPull {
 +   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
 +   OnBehalfOfUserName = "jsmith",
 +   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
 +   MarketId = "XCME_C ZC (H25)",
 +   Pulls = [
 +      {
 +         UniqueId = "a3b1c5f2-7d43-4f9b-88e2-1e2f75c6d9a1"
 +      }
 +   ]
 +}
 +</code>
 +
 +<bootnote>
 +Supply **OnBehalfOfUserName** when revising or pulling a routed order as well. If it is omitted, the revision or cancellation is attributed to the authenticated user rather than to the user the order belongs to.
 +</bootnote>
 +
 +Order validation - roles, entitled exchanges, accounts and permitted order types - is applied using the named user's own settings, not the authenticated user's.
 +
 +Order updates identify both parties, so routed activity remains fully attributable:
 +
 +  * **UserName** - the user the order belongs to.
 +  * **RoutingUserName** - the authenticated user that submitted it.
 +
 +If the named user cannot be resolved - an unknown username, a user outside the firm hierarchy, a disabled or deleted user, or an authenticated user without the **OrderRouting** role - the order is rejected with:
 +
 +<code>
 +Specified user not found
 +</code>
 +
 +<bootnote>
 +Resolved users are cached, so changes to a routed user's roles, accounts or enabled state may not take effect immediately.
 +</bootnote>
 +
  
  
Line 92: Line 168:
  
  
----- 
  
 ==== Market Order ==== ==== Market Order ====
Line 117: Line 192:
  
  
----- 
  
-=== Limit Order ===+ 
 +==== Limit Order ====
  
 A Limit Order is submitted with a specific limit price. The order will only execute at the specified price or better. A Limit Order is submitted with a specific limit price. The order will only execute at the specified price or better.
Line 143: Line 218:
  
  
----- 
  
-=== Stop Order ===+ 
 +==== Stop Order ====
  
 A Stop Market Order becomes a Market Order when the stop price is reached. A Stop Market Order becomes a Market Order when the stop price is reached.
Line 169: Line 244:
  
  
----- 
  
-=== Stop Limit Order ===+ 
 +==== Stop Limit Order ====
  
 A Stop Limit Order becomes a Limit Order when the stop price is reached. A Stop Limit Order becomes a Limit Order when the stop price is reached.
Line 196: Line 271:
  
  
----- 
  
-=== Trailing Stop Order ===+ 
 +==== Trailing Stop Order ====
  
 A Trailing Stop Order moves the stop price automatically based on price movement. A Trailing Stop Order moves the stop price automatically based on price movement.
Line 216: Line 291:
          Volume = 1,          Volume = 1,
          StopPrice = "2375.00",          StopPrice = "2375.00",
-         TrailPrice = "50"+         TrailDistance = "50"
       }       }
    ]    ]
Line 223: Line 298:
  
  
----- 
  
-=== Fill or Kill (FOK) Order ===+ 
 +==== Fill or Kill (FOK) Order ====
  
 A Fill or Kill (FOK) Order must be executed immediately in full or it is canceled. A Fill or Kill (FOK) Order must be executed immediately in full or it is canceled.
Line 249: Line 324:
  
  
----- 
  
-=== Immediate or Cancel (IOC) Order ===+ 
 +==== Immediate or Cancel (IOC) Order ====
  
 An Immediate or Cancel (IOC) Order executes immediately for the available quantity and cancels the rest. An Immediate or Cancel (IOC) Order executes immediately for the available quantity and cancels the rest.
Line 275: Line 350:
  
  
----- 
  
-=== Good Till Canceled (GTC) Order ===+ 
 +==== Good Till Canceled (GTC) Order ====
  
 A Good Till Canceled (GTC) Order remains open until it is filled or explicitly canceled. A Good Till Canceled (GTC) Order remains open until it is filled or explicitly canceled.
Line 301: Line 376:
  
  
----- 
  
-=== Order Cancels Order (OCO) ===+ 
 +==== 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. 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.
Line 339: Line 414:
  
  
----- 
  
-=== AutoOCO Order ===+ 
 +==== AutoOCO Order ====
  
 An AutoOCO Order is a batch of three orders: An AutoOCO Order is a batch of three orders:
   * A Trigger Order that initiates the trade.   * 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.+  * Two OCO Orders (Take Profit and Stop Loss) that are submitted with prices that are differentials to the fill price of the trigger order.
  
 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. 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: Example OrderSubmit message for an AutoOCO order:
 +
 +<code>
 +{
 +  "UserId": "",
 +  "HasUserId": false,
 +  "AccountId": "60B90323-E72A-4BBF-A129-3882019E622C",
 +  "MarketId": "XCME_Eq ES (H26)",
 +  "OrderLink": 2,
 +  "ManualOrderIndicator": true,
 +  "Orders": [
 +    {
 +      "BuySell": 1,
 +      "PriceType": 1,
 +      "TimeType": 0,
 +      "Volume": 1,
 +      "MaxShow": 0,
 +      "HasMaxShow": false,
 +      "MaxVolume": 0,
 +      "HasMaxVolume": false,
 +      "LimitPrice": {
 +        "Value": "685800"
 +      },
 +      "StopPrice": null,
 +      "TrailDistance": null,
 +      "Tag": "",
 +      "HasTag": false,
 +      "ActivationType": 0,
 +      "HasActivationType": false,
 +      "ActivationData": null
 +    },
 +    {
 +      "BuySell": -1,
 +      "PriceType": 1,
 +      "TimeType": 2,
 +      "Volume": 0,
 +      "MaxShow": 0,
 +      "HasMaxShow": false,
 +      "MaxVolume": 0,
 +      "HasMaxVolume": false,
 +      "LimitPrice": {
 +        "Value": "250"
 +      },
 +      "StopPrice": null,
 +      "TrailDistance": null,
 +      "Tag": "",
 +      "HasTag": false,
 +      "ActivationType": 1,
 +      "HasActivationType": true,
 +      "ActivationData": null
 +    },
 +    {
 +      "BuySell": -1,
 +      "PriceType": 2,
 +      "TimeType": 2,
 +      "Volume": 0,
 +      "MaxShow": 0,
 +      "HasMaxShow": false,
 +      "MaxVolume": 0,
 +      "HasMaxVolume": false,
 +      "LimitPrice": null,
 +      "StopPrice": {
 +        "Value": "125"
 +      },
 +      "TrailDistance": null,
 +      "Tag": "",
 +      "HasTag": false,
 +      "ActivationType": 1,
 +      "HasActivationType": true,
 +      "ActivationData": null
 +    }
 +  ]
 +}
 +</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> <code>
Line 356: Line 513:
    AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",    AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
    MarketId = "XCME_C ZC (H25)",    MarketId = "XCME_C ZC (H25)",
-   OrderLink = OrderLink.AutoOCO,+   OrderLink = OrderLink.OCO,
    Orders = [    Orders = [
       {       {
Line 370: Line 527:
          TimeType = TimeType.Normal,          TimeType = TimeType.Normal,
          Volume = 0,          Volume = 0,
-         LimitPrice = "2380.00"+         LimitPrice = "2385.00"
       },       },
       {       {
Line 377: Line 534:
          TimeType = TimeType.Normal,          TimeType = TimeType.Normal,
          Volume = 0,          Volume = 0,
-         StopPrice = "2365.00"+         StopPrice = "2360.00"
       }       }
    ]    ]
Line 383: Line 540:
 </code> </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.
  
----- 
  
-=== Take Profit and Stop Loss ===+==== Flatten Position ====
  
-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.+A Flatten Position Order closes the entire position in the specified market by submitting an offsetting order at market price.
  
-Example OrderSubmit message for a Take Profit / Stop Loss order:+Example **Flatten Position Order** message:
  
 <code> <code>
Line 397: Line 554:
    AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",    AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
    MarketId = "XCME_C ZC (H25)",    MarketId = "XCME_C ZC (H25)",
-   OrderLink = OrderLink.OCO, 
    Orders = [    Orders = [
       {       {
-         BuySell = BuySell.Buy, +         PriceType = PriceType.Flatten
-         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"+
       }       }
    ]    ]
Line 424: Line 562:
 </code> </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.+<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.1741990123.txt.gz
  • Last modified: 2025/03/14 22:08
  • by chad