WS Trading API

Spot flow

  1. Send a Login message with the list of desired accounts.
  2. The API will respond with a Login message and start sending Execution reports and Balance information related to all the requested accounts in real time.
  3. Send an Order Mass Status Request to get a snapshot of the open orders.
  4. Send a New Order Single to submit a new order.
  5. Send an Order Cancel Request to cancel an existing order.

Margin flow

  1. Send a Login message with the list of desired accounts.
  2. The API will respond with a Login message and start sending Execution reports, Position reports and Margin requirement reports related to all the requested accounts in real time.
  3. Send an Order Mass Status Request to get a snapshot of the open orders.
  4. Send a Position report request to receive open positions.
  5. The API will respond with a Mass Position report.
  6. Send a New Order Single to submit a new order.
  7. Send an Order Cancel Request to cancel an existing order.
  8. Send a Position maintenance request to collapse your positions.

Endpoint


/api/ws/trading


Authentication


To connect to the Trading API, you need keys. A key consists of two fields: API Key (ID of the key) and API Secret (the private key for the ECSDA algorithm, curve NIST P256, format RFC 5915). XENA keeps only the respective public key to verify auth signatures. One key may grant access to several accounts.


To authorize, one you need to send the following information in the Login message:

  • API ID
  • Auth payload — the string “AUTH<nonce>”
  • Nonce, which is the current UNIX timestamp in nanoseconds (i.e., the UNIX timestamp multiplied by 10^6). The timestamp should be not older than one minute.
  • Auth signature — the result of the following calculation:
  • r, s = ECDSA(SHA256(Auth payload))
  • Auth signature = HEX([r bytes, s bytes])


Learn how to obtain keys for API.


Code snippets

Examples of signature generation:


Logging in


Login message

The first message to be sent after the websocket is opened is the Logon:


Field

Tag

 

Type / possible values

Description

MsgType

35

M

A (Logon)


Accounts

1

M

Array of int

List of accounts to trade on

Username

553

M

String

API Key

SendingTime

52

M

Long — Unix timestamp in nanoseconds

Nonce

RawData

96

M

String

“AUTH<nonce>”

Password

554

M

String

Signature


Example


{

"1":[1,2],

"35":"A",

"553": "",

"52": …,

"96": "",

"554": ""

}


Login message response


Field

Tag

 

Type / possible values

Description

MsgType

35

M

A (Logon)


Accounts

1

M

Array of int

List of accounts

SendingTime

52

M

Long — Unix timestamp in nanoseconds


SessionStatus

1409

M

String

0 (SessionActive)

5 (InvalidUsernameOrPassword)

6 (AccountLocked)


RejectText

1328

O

String

Reason for login failure


Example


{

"1":[1,2],

"1409":"0",

"35":"A",

"52":1520415869093505337

}


Requesting a snapshot of active orders


Order Mass Status Request


Field

Tag

 

Type / possible values

Description

MsgType

35

M

AF (OrderMassStatusRequest)


Account

1

M

int



Example


{

"1":1,

"35":"AF"

}


Order Mass Status Response


Field

Tag

 

Type / possible values

Description

MsgType

35

M

U8 (Order Mass Status Response)


Account

1

M

int


Orders

1268

M

Array of Execution Reports

Active orders (new, partially filled)           

Fills

1269

M

Array of Execution Reports

Last 30 orders (filled, partially filled)


Example


{

"35":"U8",

"1":1012833469,

"1268":[

{

"35":"8",

"1":1012833469,

"11":"MOXVWyjeg",

"37":"1738b10b-c71d-43ac-bdf1-cc5ba02ed68f",

"55":"XBTUSD",

"40":"2",

"44":"1",

"60":1549985312096996061,

"17":"a7afcc3b-b6ea-4d65-bbef-0a1df4889f98",

"150":"D",

"378":"3",

"39":"0",

"54":1,

"38":"5",

"151":"5",

"14":"0",

"32":"0",

"77":"O",

"1645":"5000",

"1644":11,

"5000":[

{

"40":"2",

"44":"3604"

}

]

}

],

"1269":[

{

"35":"8",

"1":1012833469,

"11":"kpkQM7opo",

"37":"88bf154b-979d-40b0-85fe-5c1264828696",

"55":"XBTUSD",

"40":"2",

"44":"3569.4",

"60":1549985302721436948,

"17":"152564c756766fb10f55a4cdcb4930227fa6e0e0",

"150":"F",

"1003":"a44ac5f8-d267-427e-bac8-e02ad4700e06",

"39":"2",

"54":2,

"38":"0.1",

"151":"0",

"14":"0.1",

"32":"0.1",

"31":"3569.4",

"851":2,

"12":"0.28015913",

"1233":"0.1",

"479":"BTC",

"2618":130775254,

"77":"O",

"1645":"0",

"1644":11

}

]

}


Balance updates


After authorizing, API will send a snapshot of the account balance and all changes to the balance.

Each balance object may contain information about the client’s position in the currency of the balance. Position information is calculated in two base currencies — BTC and USDT.


Field

Tag

 

Type / possible values

Description

MsgType

35

M

XAR (Account Status Report Snapshot)

XAF (Account Status Report Incremental Refresh)


Account

1


int


LastUpdateTime

779


Long — Unix timestamp in nanoseconds


Repeating group Balance (1800)


Account

1


int


Currency

15

M

String


AvailableBalance

1801

M

decimal

Available = Settled - Locked

LockedBalance

1802

M

decimal

Balance locked in orders

SettledBalance

1803

M

decimal

Balance of the account

Repeating group PositionInfo (1804), inside the Balance group, optional field

Currency

15

M

string

Position calculation currency

AvgPx

6

M

decimal

Position open price

PositionId

2618

M

int


PositionOpenDate

1805

M

Long — Unix timestamp in nanoseconds


RealizedPL

1806

M

decimal



Examples


Snapshot


{

"1":15,

"1800": [

{

"15":"BTC",

"1801":"7.5",

"1802":"0",

"1803": "7.5",

"1804": [

{

"15":"USDT",

"1618":130722517,

"1805":1526656273317908000,

"1806":"0",

"6":"7350"

},

{

"15":"BTC",

"1618":130722517,

"1805":1526656273317908000,

"1806":

"0",

"6":"1"

}],

"779":1526656379897959000}]

}],

"35":"XAR",

"779":1523018132051736000

}


Update


{

"1":15,

"1800": [

{

"15":"BTC",

"1801":"7.5",

"1802":"0",

"1803": "7.5"

}],

"35":"XAF",

"779":1523018132051736000

}


Balance snapshot request


You can request a balance snapshot with an XAA message type:


Field

Tag

 

Type / possible values

Description

MsgType

H / 35

M

XAA (Account Status Report Request)


Account

1

M




Example: { "35": "XAA", "1": "123456" }


Sending orders


New order single


Field

Tag

 

Type / possible values

Description

MsgType

35

M

D (NewOrderSingle)


ClOrdId

11

M

String, 20 symbols max

ClOrdId must be unique within a moving frame of 24 hours.

Symbol

55

M

String


Side

54

M

int

1 Buy

2 Sell


SettlType

63

M

String

1 Cash (TOD / T+0)


TransactTime

60

M

Long — Unix timestamp in nanoseconds


OrderQty

38

M

Decimal


OrdType

40

M

string

1 Market

2 Limit

3 Stop


Price

44

C

Decimal

Mandatory for limit orders. Omitted for market orders.

Account

1

M

int


TimeInForce

59

O

int

1 Good Till Cancel (default value)

3 Immediate Or Cancel

4 Fill Or Kill


ExecInst

18

O

MultipleCharValue

x IgnoreNotionalValueChecks

For spot trading only

ListSeqNo

67

O

int

For spot trading only

PositionEffect

77

O

char

C Close

O Open


PositionID

2618

O

int


Repeating group Triggering Instructions (1114)

TriggerType

1100

M

1 — PartialExecution


TriggerScope

1628

M

1 — OtherOrder


TriggerAction

1101

M

1 — Activate

4 — SetCapPrice (custom)


RefClOrdID

1806

M



Repeating group SLTP (5000)

OrdType

40

M

2 — Limit (тейк-профит)

3 — Stop (стоп-лосс)

Limit orders are considered take profit orders

Market orders are considered stop loss orders

Price

44

C


Required for take profit orders

StopPx

99

C


Required for stop loss orders

PegOffsetValue

211

C

decimal

For trailing stop and attempt zero loss orders

PegPriceType

1094

C

8 — TrailingStopPeg

For trailing stop and attempt zero loss orders

PegOffsetType

836

C

2 — BasisPoints

For trailing stop and attempt zero loss orders

CapPrice

1199

C

Price

For trailing stop orders — equals zero

For attempt zero loss  — price limit


Example


{

"1":10012833469,

"11":"On7MBagPw",

"35":"D",

"38":"2",

"40":"3",

"54":1,

"55":"XBTUSD",

"60":1547651288262000000,

"63":"1",

"67":2,

"99":"03619.0",

"5000":[

{

"40":"3",

"99":"03100.0"

},

{

"40":"2",

"44":"03650.0"

}

]

}



Order reject


Field

Tag

 

Type / possible values

Description

MsgType

35

M

3 Reject


Text

58

M

String

Error description


Example


{

"35":"3",

"58":"parse error: expected number near offset 156 of '130775248'"

}


Canceling/updating orders


Order Cancel Request


Field

Tag

 

Type / possible values

Description

MsgType

35

M

F (Order Cancel Request)


OrigClOrdID

41

C

String

One of the fields must be submitted.

OrderID

37

C

String / Guid

ClOrdID

11

M

String

ClOrdId must be unique within a moving frame of 24 hours.

Side

54

M

int

1 Buy

2 Sell


Symbol

55

M

String


TransactTime

60

M

Long — Unix timestamp in nanoseconds


Account

1

M

int



Example


{

"1":1,

"11":"wOQYGqklK",

"35":"F",

"37":"3975158b-2c25-4d26-acfd-c78921408eb6",

"54":1,

"55":"BTC/USDT",

"60":1520424390152000000

}


Order cancel replace request


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

G (Order Cancel Replace Request)


OrigClOrdID

41

C

string

One of the fields must be submitted.

OrderID

37

C

string

ClOrdID

11

M

string

ClOrdId must be unique within a moving frame of 24 hours.

Side

54

M

1 — Buy

2 — Sell


Symbol

55

M

String


TransactTime

60

M

Long — Unix timestamp in nanoseconds


Account

1

M

int


OrderQty

38

O

Decimal


Price

44

C

Decimal

For limit orders only

StopPx

99

C

Decimal

For stop and limit orders only

CapPrice

1199

C

Decimal

For trailing stop orders and attempt zero loss orders only

Repeating group SLTP (5000)


Example


{

"1":10012833469,

"11":"oJZYJW01p",

"35":"G",

"37":"00276b5b-4ae5-4885-ba2d-6319583d0af1",

"38":"2",

"54":2,

"55":"XBTUSD",

"60":1547566800847000000,

"5000":[

]

}


Order Cancel Reject (Replace Reject)


Field

Tag

 

Type / possible values

Description

MsgType

35

M

9 (Order Cancel Reject)

 

OrderId

37

O

String / Guid

Order ID of the order being cancelled, if it has been found.

OrigClOrdId

41

O

String

ClOrdId of the order being cancelled, if it has been found, or if OrigClOrdId has been submitted in the request.

ClOrdId

11

M

String

 

OrdStatus

39

M

2 Filled

4 Cancelled

6 Pending Cancel

8 Rejected — if the order hasn’t been found by OrderId or ClOrdId

Current status of the order being cancelled.

CxlRejResponseTo

434

M

1 Order Cancel Request

 

CxlRejReason

102

M

0 TooLateToCancel

1 UnknownOrder

3 OrderAlreadyInPendingStatus

6 DuplicateClOrdID

99 Other

 

RejectText

1328

O

String

Reason for rejection.

TransactTime

60

M

Long — Unix timestamp in nanoseconds

 

Account

1

M

int

 


Example


{

"35":"9",

"1":1012833469,

"11":"NnNRwBgg7",

"37":"1738b10b-c71d-43ac-bdf1-cc5ba02ed68f",

"39":"8",

"434":2,

"102":"99",

"1328":"Wrong OrderQty",

"60":1549986084027439568

}


Execution reports


Order status matrices


Link


Execution report


Field

Tag

 

Type / possible values

Description

MsgType

35

M

8 (ExecutionReport)


OrderId

37

M

String / Guid


ClOrdId

11

M

String


OrigClOrdId

41

O

String

ClOrdId of the order being cancelled, if OrigClOrdId has been submitted in the request.

TradeId

1003

C

String

Conditionally required when ExecType = Trade

Symbol

55

M

String


ExecType

150

M

A PendingNew

0 New

F Trade

6 PendingCancel

4 Cancelled

E PendingReplace

D Reastated

5 Replaced

8 Rejected

9 Suspended

In accordance with order status matrices.

OrdStatus

39

M

0 New

1 Partially Filled

2 Filled

4 Cancelled

8 Rejected

E Pending replace

9 Suspended

In accordance with order status matrices.

Side

54

M

int

1 Buy

2 Sell


OrdType

40

M

int

1 Market

2 Limit

3 Stop


Price

44

C

Decimal

Conditionally required for limit orders.

OrderQty

38

M

Decimal

In accordance with order status matrices.

LeavesQty

151

M

Decimal

In accordance with order status matrices.

CumQty

14

M

Decimal

In accordance with order status matrices.

ExecId

17

M

String / Guid

Unique identifier of the execution message within a 24-hour range

LastQty

32

C

Decimal

In accordance with order status matrices.

Conditionally required when ExecType is Trade.

LastPx

31

C

Decimal

Conditionally required when ExecType is Trade.

CalculatedCcyLastQty

1056

C

Decimal

Net payment of the fill, not including commission.

Conditionally required when ExecType is Trade.

NetMoney

118

C

Decimal

Gross amount of the fill, including commission.

Conditionally required when ExecType is Trade.

TransactTime

60

M

Long — Unix timestamp in nanoseconds

Timestamp of the event.

LastLiquidityInd

851

C

1 AddedLiquidity

2 RemovedLiquidity

Conditionally required when ExecType is Trade.

Commission

12

O

Decimal


CommCurrency

479

O

String


Account

1

M

Int


Currency

15

M

String

Pair base currency

SettlCurrency

120

M

String

Pair quote currency

SettlType

63

M

1 Cash (TOD / T+0)


PositionId

2618

M

int


MarginAmt

1645

M



MarginAmtType

1644

M

11 — Initial Margin


Repeating group SLTP (5000)

OrdType

40

M

2 — Limit (тейк-профит)

3 — Stop (стоп-лосс)

Limit orders are considered take profit orders

Market orders are considered stop loss orders

Price

44

C


Required for take profit orders

StopPx

99

C


Required for stop loss orders

PegOffsetValue

211

C

decimal

For trailing stop and attempt zero loss orders

PegPriceType

1094

C

8 — TrailingStopPeg

For trailing stop and attempt zero loss orders

PegOffsetType

836

C

2 — BasisPoints

For trailing stop and attempt zero loss orders

CapPrice

1199

C

Price

For trailing stop orders — empty

For attempt zero loss orders — stop loss price limit. If CapPrice = 0, CapPrice = Open price


Example


{

"1":1,

"11":"9Naow8V5b",

"14":"0",

"150":"0",

"151":"1",

"17":"8ddc1450-5c26-4a6c-9e21-d7a46756bf8c",

"18":null,

"32":"0",

"35":"8",

"37":"a5012f7f-be4c-4f25-9418-1f99c7af5175",

"38":"1",

"39":"0",

"40":2,

"44":"6000",

"54":1,

"55":"BTC/USDT",

"60":1519897377377284246

}


Position report


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

AP (Position Report)


Account

1

M

int


PositionId

2618

M

int


TransactTime

60

M

Timestamp

Position timestamp

Symbol

55

M

string


PositionOpenDate

1805

M

Timestamp


AvgPx

6

M

decimal

Open Price

Quantity

53

M

decimal


Side

54

M

1 — Buy

2 — Sell


PriorSettlPrice

734

M


Settlement Price

SettlDate

64

C


Close DT — filled for closed positions only

SettlPrice

730

C


Close Price — filled for closed positions only

PreviousClearingBusinessDate

1084

C


Previous variation margin timestamp

ClearingBusinessDate

715

C


Next variation margin timestamp

Repeating group MarginAmount (1643)

MarginAmt

1645

M



MarginAmtType

1644

M

11 — Initial Margin

7 — Core Margin (maintenance)


MarginCurr

1646

M



Repeating group PaymentGrp (40212)

PaymentType

40213


40 — Commission (Commissions)

41 — Interest (Total Interest)

42 — Settlement (RealizedPL)

43 — CumulativePayments (CumulativePL)


PaymentCurrency

40216




PaymentAmount

40217




Repeating group RelatedTradeGrp (1855)

RelatedTradeID

1856



Exec ID

RelatedTradeType

1857


1 — Open (OpenExecId)

2 — Close (CloseExecId)

3 — ParentPosition (ParentPositionId)



Example


{

"35":"AP",

"1":10012833469,

"2618":130722617,

"60":1547567935332784350,

"55":"XBTUSD",

"1805":1547567935320219509,

"6":"3700",

"53":"1",

"54":2,

"734":"3700",

"1643":[

{

"1645":"0.27027028",

"1644":11,

"1646":"BTC"

},

{

"1645":"0.27027028",

"1644":7,

"1646":"BTC"

}

],

"40212":[

{

"40213":40,

"40216":"BTC",

"40217":"2.70270271"

},

{

"40213":42,

"40216":"BTC",

"40217":"0"

},

{

"40213":41,

"40216":"BTC",

"40217":"0"

},

{

"40213":43,

"40216":"BTC",

"40217":"-2.70270271"

}

],

"1855":[

{

"1856":"48026e52-fa0c-4b1c-9e43-280797605378",

"1857":1

}

]

}


Mass position report


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

MAP (Mass Position Report)


Account

1

M

int


TransactTime

60

M

Timestamp

max(PositionReport.TransactTime)

Repeating group OpenPositions (727) — contains an array of the PositionReport of all opened positions

Repeating group PositionHistory (726) — contains an array of the PositionReport of last X closed positions


Example


{

"35":"MAP",

"1":10012833469,

"60":1547568019359251895,

"727":[

{

"35":"AP",

"1":10012833469,

"2618":130722617,

"60":1547568019359471200,

"55":"XBTUSD",

"1805":1547567935320219509,

"6":"3700",

"53":"1",

"54":2,

"734":"3700",

"1643":[

{

"1645":"0.27027028",

"1644":11,

"1646":"BTC"

},

{

"1645":"0.27027028",

"1644":7,

"1646":"BTC"

}

],

"40212":[

{

"40213":40,

"40216":"BTC",

"40217":"2.70270271"

},

{

"40213":42,

"40216":"BTC",

"40217":"0"

},

{

"40213":41,

"40216":"BTC",

"40217":"0"

},

{

"40213":43,

"40216":"BTC",

"40217":"-2.70270271"

}

],

"1855":[

{

"1856":"48026e52-fa0c-4b1c-9e43-280797605378",

"1857":1

}

]

}

]

}


Position report request


{

"1": 1012833470

"35": "AN"

}


Margin requirement report


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

CJ (Margin Requirement Report)


MarginReqmtRptType

1863

M

0 — Summary


Repeating group MarginAmtGrp (1643)

MarginAmt

1645

M



MarginAmtType

1644

M

11 — Total margin

7 — Core margin (maintenance)

Contains multiple MarginAmts for different types of margins:

Total margin — net sum of initial margins

Core margin — net sum of maintenance margins

Margin requirements are grouped by margin currency

MarginAmtCcy

1646

M

string



Example


{

"35":"CJ",

"1863":"0",

"1":10012833469,

"1643":[

{

"1645":"4.3378115",

"1644":11,

"1646":"BTC"

},

{

"1645":"2.21220587",

"1644":7,

"1646":"BTC"

}

]

}


Position maintenance request


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

AL (Position Maintenance Request)


PosReqID

710

O

string

Optional request ID. If set, the reply will contain the same ID.

PosTransType

709

M

20 — Collapse


PosMaintAction

712

M

2 — Replace

Maintenance Action to be performed

Account

1

M



Symbol

55

M




Example


{

"1":1012833469,

"35":"AL",

"55":"XBTUSD",

"709":20,

"710":"1Kx94XEKy",

"712":2

}


Position maintenance report


Field

Tag

M/O/C

Type / possible values

Description

MsgType

H / 35

M

AM (Position Maintenance Report)


PosReqID

710

C

string

PosReqID, if it was sent in the request

PosTransType

709

M

20 — Collapse


PosMaintAction

712

M

2 — Replace


Account

1

M




Example


{

"35":"AM",

"710":"1Kx94XEKy",

"709":20,

"1":1012833469,

"55":"XBTUSD"

}