TABLE OF CONTENTS
- Endpoints
- Authentication
- Keeping connection alive
- Client Order ID and Order ID
- Comments
- Retrieve status
- Sending new orders
- Execution Reports and status of an order
- Cancel an order
- Mass cancellation
- Modify an order
- Collapse positions
Endpoints
Authentication
Keeping connection alive
Refer to this article.
Client Order ID and Order ID
All requests from the client (new orders, order cancellations, mass actions, etc.) must contain a Client Order ID. This field is used for identifying the orders and de-duplication on the server side. The server keeps Client Order IDs for 24 hours (so you can repeat them each 24 hours, provided there are no active orders with the same Client Order ID), but we recommend you to always use unique IDs. The uniqueness is checked within an API key.
The server will assign its own ID (called Order ID) to each order when the order reaches the trading engine. This ID will be reported to you in the respective Execution Report. Then you can refer to an order (e.g. to cancel it) using either its Client Order ID or Order ID. You can send subsequent messages (e.g. cancel an order) without waiting for the assignment of an Order ID, by referring to the order by the Client Order ID.
Comments
In addition to the Client Order ID you can assign an arbitrary text comment to your orders. The comment can be used to identify orders related to different trading strategies, to map orders on the exchange to orders in your trading algorithms or in other cases. The comment is assigned when the order is created and cannot be changed later.
Retrieve status
Websocket push notifications
After successful authentication, the API will be sending following messages to the client:
ExecutionReport (8) — on any change of the status of an order (see Execution Reports and status of an order for further details)
PositionReport (AP) — on any change of the status of a position (latest state of the position is sent)
AccountStatusReportIncrementalRefresh (XAF) — any change of the balance (latest known balance)
MarginRequirementsReport (CJ) — any change of total margin requirements for an account (latest margin requirements)
If the list of accounts has been provided by the client in the Logon message, only updates for these accounts will be sent; otherwise, for all accounts belonging to the profile.
Status of a particular order
To retrieve the status of a particular order:
Please note that the history is available within 7 days after an order gets into a terminal status. More information about statuses of the orders: link.
Active orders
To retrieve the snapshot of active orders:
Completed orders
To retrieve all orders in terminal statuses (such as Filled, Cancelled and Rejected):
Please note that the history is available within 7 days after an order gets into a terminal status.
Orders history
To retrieve all orders in terminal statuses (such as Filled, Cancelled and Rejected):
Please note that the history is available within 7 days after an order gets into a terminal status.
Positions
To retrieve the snapshot of current opened positions:
Positions history
Recent trades (fills)
To retrieve fills:
Balance and margin requirements
Sending new orders
To send a new order:
Please note, that once you receive the first Execution Report for an order (Pending New), you can be sure that the order is delivered to the exchange (not lost due to network issues). However, this doesn’t guarantee that the order will not be rejected (e.g. due to insufficient margin) — these checks are executed later in the processing flow.
Cookbook
Cancel on Connection Loss
Cancel on Connection Loss orders require special messages (ApplicationHeartbeat (XAH)) to be sent by the client regularly. If the exchange doesn’t receive the message after the defined timeout (which is N seconds), it will cancel COCL orders on all client’s accounts.
If you have complex infrastructure (multiple trading robots, connections and accounts), use GrpID in orders and Application Heartbeats. Timeouts are calculated separately for each GrpID that you use; e.g. all orders with GrpID == 1 may be cancelled by the server, but orders with other GrpIDs will remain active if the exchange hasn’t received the Application Heartbeat with GrpID == 1.
For simpler cases, omit GrpID in all messages; in this case all COCL orders on all accounts belonging to your profile will be cancelled after a timeout.
Do not mistake Application Heartbeat with the transport-level Heartbeat messages. Using another message for keeping COCL orders alive allows to ensure all parts of your trading solution and the exchange are alive. Send Application Heartbeats from your application level (trading robots): if they fail (but the connection is still alive, defined by the transport-level Heartbeats), the orders will be automatically cancelled.
The timeout is 5 seconds by default. The minimum heartbeat interval and the reaction time is 1 second.
Execution Reports and status of an order
All changes in order statuses are reported to clients by Execution Reports. Each Execution Report (except those in “Pending XXX” statuses) contains full information about the latest (current) status of an order:
Order Status
Order Quantity — quantity of the order submitted by the client. May change only when the client modifies the order.
Cumulative Quantity — total executed (filled) amount as of the generation of the Execution Report.
Average Price — average price over all trades (fills) related to the order.
Last Quantity — if the Execution Report is related to a new trade (fill), contains the trade amount
Last Price — the price of the trade (fill)
Leaves Quantity — yet unfilled part of the order (this part is in the order book).
Examples of messages exchanged by the client and the server in different cases: link
Cancel an order
Please note, that once you receive the first Execution Report (Pending Cancel), you can be sure that the request is delivered to the exchange (not lost due to network or other transport issues). However, this doesn’t guarantee that the request will not be rejected (e.g. due to insufficient wrong Order ID) — these checks are executed later in the processing flow.
Mass cancellation
Modify an order
You can change the following attributes of a placed order:
Price
Stop price
Quantity
Execution instructions
Stop loss and take profit prices (hedged accounting only)
Please note, that once you receive the first Execution Report for an order (Pending Replace), you can be sure that the order is delivered to the exchange (not lost due to network or other transport issues). However, this doesn’t guarantee that the order will not be rejected (e.g. due to insufficient margin) — these checks are executed later in the processing flow.
The following rules apply to modifying orders:
If the quantity of an order decreases, the order keeps its position in the queue at its price level
If the new quantity of an order is less than the Cumulative quantity (already filled), the order gets the terminal status Filled
If the quantity of an order increases or its price changes, it is put to the end of the queue at the new price level
Changes in additional attributes (such as SLTP) does not affect the place of the order in the queue
Collapse positions
Collapsing positions allows to gather several active positions in one symbol into one netted position (applicable only for hedged accounting):