Order Entry Protocol
- Body encoding
OE(See BTP Body Encoding). - Requires a login (See Login Protocol).
- Sends market state updates (See Market State Protocol).
Order Entry IDs
-
orderId: A customer-defined, per connectionId, unique order identifier. This ID stays the same across subsequent modifications of the specific order.
-
modifyId: A customer-defined, per orderId, unique modify identifier. This ID must be different across subsequent modifications of the specific order.
-
ackId: A matching engine-defined, per engine instance, unique identifier for messages successfully applied to the order book. This ID includes Ack, Fill, and Closed messages but excludes Reject messages.
-
The (ackId, orderId) pair uniquely identifies an order accepted by the matching engine and applied to the order book.
-
The (ackId, orderId, modifyId) triplet uniquely identifies a modify to the respective order.
Order Entry Request
Open
Order types: All orders are limit orders. We do not support market orders, stops, stop limits, etc. We support Day and IOC orders for Time in Force.
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always O |
| 1 | 8 | uint64 | orderId | Order ID from customer |
| 9 | 8 | uint64 | productId | Product ID |
| 17 | 1 | char | side | Side: B = bid, A = ask |
| 18 | 8 | int64 | price | Price in ticks |
| 26 | 4 | uint32 | quantity | Quantity |
| 30 | 1 | char | timeInForce | Time in force: D = Day, I = IOC |
| 31 |
Modify
Cancels: A modify with a quantity less than or equal to the order’s fill quantity cancels the
order. A modify that changes the price and sets the quantity to less than or equal to the order’s
fill quantity cancels the order and the price change is ignored. A quantity = 0 will short circuit
the price limit rules. A modify order with quantity > 0 must conform to the price limit rules
regardless of order cancellation.
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always M |
| 1 | 8 | uint64 | orderId | Order ID from customer |
| 9 | 8 | uint64 | modifyId | Modify ID from customer |
| 17 | 8 | int64 | price | Price in ticks |
| 25 | 4 | uint32 | quantity | Quantity |
| 29 |
Note: NULL is indistinguishable from 0 in the case of modifyId. It is highly
recommended to not use 0 as a modifyId to avoid this ambiguity.
Order Entry Reply
Ack
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always A |
| 1 | 8 | uint64 | ackId | Matching engine acked sequence |
| 9 | 8 | uint64 | orderId | Order ID from customer |
| 17 | 8 | uint64 | modifyId | Modify ID from customer, NULL for open acks |
| 25 |
Reject
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always R |
| 1 | 8 | uint64 | orderId | Order ID from customer |
| 9 | 8 | uint64 | modifyId | Modify ID from customer, NULL for open rejects |
| 17 | 1 | uint8 | rejectReason | See Reject Reason |
| 18 |
Reject Reason
Request processing, and respective reject precedence, is as follows:
- Connection state (ex: enabled/disabled)
- Order state (ex: order closed)
- Quantity (a modify with a closing quantity is processed regardless of an invalid price modification)
- Price
| Value | Reason |
|---|---|
0x01 |
Account not found |
0x02 |
Product not found |
0x03 |
Order not found |
0x04 |
Order already exists |
0x05 |
Order already closed |
0x06 |
Order not changed by modify |
0x07 |
Quantity greater than max order size |
0x08 |
Quantity less than min order size |
0x09 |
Price outside price bands |
0x0A |
Price outside price limits |
0x0B |
Price not tick aligned (reserved) |
0x0C |
Market halted. Only close requests accepted |
0x0D |
Market closed. No requests accepted |
0x0E |
Give-up account not found |
0x0F |
Give-up unauthorized |
0x10 |
Messaging rate exceeded |
0x11 |
Position limit exceeded |
0x12 |
Connection disabled |
0x13 |
Feature not supported |
Closed
A closed message will be sent when the order state cannot be inferred from the normal request-reply flow. This happens when an IOC is finished matching, self-match is prevented, or a customer cancels an order outside the order entry gateway connection.
A closed message will not be sent when an order is fully filled or a modify is acked, closing the order. For example, if an IOC misses or is partially filled, a closed message will be sent. If the IOC is fully filled, a closed message will not be sent.
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always C |
| 1 | 8 | uint64 | ackId | Matching engine acked sequence |
| 9 | 8 | uint64 | orderId | Order ID from customer |
| 17 | 1 | char | closeReason | See Close Reason |
| 18 |
Close Reason
| Value | Reason |
|---|---|
I |
IOC finished |
G |
Non-connection cancel |
S |
self-match prevention canceled |
Fill
| Byte Offset | Byte Length | Type | Name | Description |
|---|---|---|---|---|
| 0 | 1 | char | messageType | Always F |
| 1 | 8 | uint64 | ackId | Matching engine acked sequence |
| 9 | 8 | uint64 | orderId | Order ID from customer |
| 17 | 8 | int64 | price | Price in ticks |
| 25 | 4 | uint32 | quantity | Quantity |
| 29 | 1 | char | liquidity | Liquidity: A = Add, R = Remove, S = Spread leg match |
| 30 |
When dealing with calendar spreads, you can expect 3 Fill messages
for each match. One will have either A or R liquidity corresponding to the spread contract itself. Then there will
be one Fill message for each leg with S liquidity and 0 quantity which have the implied price.
Message Rate Throttling
Order entry requests are limited using a sliding window throttle. Unless otherwise stated or negotiated, order entry
gateways have a 500 message per 3 seconds messaging rate. Cancels are always allowed past the messaging rate throttle.
Rejects are sent in response to messages exceeding the message rate limit with a reason code 0x10 (Message rate
exceeded).