TABLE OF CONTENTS


Endpoints


Environment

WS

REST

Production

wss://api.xena.exchange/trading/ws

https://api.xena.exchange/trading

Demo

wss://api.demo.xena.io/trading/ws

https://api.demo.xena.io/trading

Authentication

WS

REST

  • After establishing the websocket connection, send the Logon message. The message must contain your API Key, and a cryptographic signature generated with your API Secret.

  • The server responds with the Logon message containing information about available accounts and heartbeat interval (in case of successful authentication) or description of authentication error

  • By default, after successful logon, you will receive information about events on all accounts to which your API key has access. If you need to work with certain accounts only, pass the list of accounts in the Logon message.

  • If you do not send the Logon message in 5 seconds after establishing the connection, the server will terminate the connection.

Provide authentication headers for each request

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:


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:


WS

REST


In case the order is not found by the given ID, the ER will contain OrdStatus == Rejected and OrdRejReason == UnknownOrder.

GET accounts/{accountId}/order

  • Params: order_id, client_order_id (one of them must be submitted)

  • Returns: ExecutionReport


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:

WS

REST

GET accounts/{accountId}/active-orders

Completed orders

To retrieve all orders in terminal statuses (such as Filled, Cancelled and Rejected):


WS

REST

GET accounts/{accountId}/last-order-statuses

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


WS

REST

GET accounts/{accountId}/last-order-statuses

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:

WS

REST

GET accounts/{accountId}/positions

Positions history

WS

REST

Not supported

GET accounts/{accountId}/positions-history

Recent trades (fills)

To retrieve fills:


WS

REST

GET accounts/{accountId}/trade-history

Balance and margin requirements

WS

REST

GET accounts/{accountId}/balance


GET accounts/{accountId}/margin-requirements

Sending new orders

To send a new order:


WS

REST

POST order/new


Note that the call doesn’t guarantee the successful submission of the order (as there are additional checks later on the flow due to which the order might be rejected). Check the status of orders on your account by retrieving the list of all active orders or on an individual basis.


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

Market order

Send NewOrderSingle, setting OrdType = Market

Limit order

Send NewOrderSingle, setting OrdType = Limit and filling the Price field

Stop order

Send NewOrderSingle, setting OrdType = Stop and filling the StopPx field

Stop Limit order

Send NewOrderSingle, setting OrdType = StopLimit and filling both Price (execution price) and StopPx (trigger price) fields

Good till Cancel (default value)

Send Good till Cancel (default value) in TimeInForce in NewOrderSingle

Applicable to all types of orders.

Immediate or Cancel order

Send Immediate or Cancel in TimeInForce in NewOrderSingle

Applicable only to Limit and Stop Limit orders.

Fill or Kill orders

Send Fill or Kill in TimeInForce in NewOrderSingle

Applicable to all types of orders. Note that for stop orders, this instruction is applied when the order is triggered.

Stay on offer side orders (maker only, cancel)

Send Stay on offer side in ExecInst in NewOrderSingle

If a Stay On Offer Side order hits another order upon entering the book, it gets immediately cancelled without execution.

Peg to offer side (maker only, adjust)

Send Peg to offer side in ExecInst in NewOrderSingle

If a Peg To Offer Side order hits another order upon entering the book, its price is changed to the best possible level (Best Bid + 1 tick for sell orders, Best Ask - 1 tick for buy orders).

Cancel on Connection Loss orders

Send Cancel on Connection Loss in ExecInst in NewOrderSingle and optionally fill the GrpID

Send Application Heartbeat (with respective GrpID) regularly to tell the exchange that your client is alive. See this section for further details.

Take Profit and Stop Loss orders (only for hedged accounting)

Add the SLTP group to the NewOrderSingle. The SLTP group can contain up to one limit order (take profit) and up to one stop order (stop loss). These orders will not be active until the main order is executed and the position is opened. After that, they will adjust their quantity according to the position volume.

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.


WS

REST

POST order/heartbeat

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

WS

REST

POST order/cancel


Note that the call doesn’t guarantee the successful cancellation of the order. Check the status of orders on your account by retrieving the list of all active orders or on an individual basis.


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

WS

REST

POST order/mass-cancel


Note that the call doesn’t guarantee the successful cancellation of all orders. Check the status of orders on your account by retrieving the list of all active orders or on an individual basis.

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)

WS

REST

POST order/replace


Note that the call doesn’t guarantee the successful modification of the order. Check the status of orders on your account by retrieving the list of all active orders or on an individual basis.


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

WS

REST

POST position/maintenance


Check the result of the operation by retrieving the new snapshot of active positions.