The WebSocket API provides real-time order routing, allowing clients to submit, revise, and pull orders. All order-related operations are sent within a **ClientMessage** envelope and responses are received within a **ServerMessage** envelope.

To submit an order, clients send an OrderSubmit message.

Example OrderSubmit message:

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"
      }
   ]
}

To revise an existing order, clients send an OrderRevise message.

Example OrderRevise message:

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"
      }
   ]
}

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

Example OrderPull message:

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"
      }
   ]
}

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.

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:

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"
      }
   ]
}

The same field is available on OrderRevise and OrderPull:

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"
      }
   ]
}

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:

Specified user not found

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.

A Market Order executes immediately at the best available price.

Example Market Order message:

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
      }
   ]
}

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:

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"
      }
   ]
}

A Stop Market Order becomes a Market Order when the stop price is reached.

Example Stop Order message:

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"
      }
   ]
}

A Stop Limit Order becomes a Limit Order when the stop price is reached.

Example Stop Limit Order message:

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"
      }
   ]
}

A Trailing Stop Order moves the stop price automatically based on price movement.

Example Trailing Stop Order message:

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",
         TrailDistance = "50"
      }
   ]
}

A Fill or Kill (FOK) Order must be executed immediately in full or it is canceled.

Example Fill or Kill (FOK) Order message:

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"
      }
   ]
}

An Immediate or Cancel (IOC) Order executes immediately for the available quantity and cancels the rest.

Example Immediate or Cancel (IOC) Order message:

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"
      }
   ]
}

A Good Till Canceled (GTC) Order remains open until it is filled or explicitly canceled.

Example Good Till Canceled (GTC) Order message:

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"
      }
   ]
}

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:

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"
      }
   ]
}

Both orders are placed at the same time. If the Limit Order is filled, the Stop Order is automatically canceled, and vice versa.

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

Example OrderSubmit message for an AutoOCO order:

{
  "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
    }
  ]
}

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:

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"
      }
   ]
}

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.

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:

OrderSubmit {
   UserId = "efda0709-af12-4b65-8971-5089edb4aaf0",
   AccountId = "448c9ddd-6a50-4852-85ea-aad3b6d60620",
   MarketId = "XCME_C ZC (H25)",
   Orders = [
      {
         PriceType = PriceType.Flatten
      }
   ]
}

When displaying order status to end users, combining the OrderStatus and OrderChange fields provides more meaningful feedback than either field alone. The following table maps these field combinations to user-friendly status messages.