Trading


Flow

  1. Send a login message with a list of desired accounts.
  2. The API responds with a login message and starts sending execution reports and balance updates related to all requested accounts in real time.
  3. Send an order mass status request to get a snapshot of open orders.
  4. Send an account status report request to get a snapshot of the balances for all currencies.
  5. Send a new order single to submit a new order.
  6. Send an order cancel request to cancel an existing order.

Endpoint

/api/ws/trading

Logging in

Login message

The first message to be sent after the web socket is opened is the login message. It contains a nonce string signed by your API Keys. Refer to this dedicated article to learn how to authenticate your login.

FieldTag Type / possible valuesDescription
MsgType35MA (Logon) 
Username553MStringAPI Key
SendingTime52MLong — Unix timestamp in nanosecondsNonce
RawData96MString"AUTH<nonce>"
Password554MStringSignature

Sample

{
    "1":[1327743,1324322],
    "35":"A",
    "553": "",
    "52": …,
    "96": "",
    "554": ""
}

Logon message response

FieldTag Type / possible valuesDescription
MsgType35MA (Logon) 
Accounts1MArray of intList of accounts
SendingTime52MLong — Unix timestamp in nanoseconds 
SessionStatus1409MString
  • 0 (SessionActive)
  • 5 (InvalidUsernameOrPassword)
  • 6 (AccountLocked)
 
RejectText1328OStringReason for logon failure
HeartBtInt108MintHeartbeat interval in seconds

Sample

{
    "1":[1,2],
    "1409":"0",
    "35":"A",
    "52":1520415869093505337
}

Requesting the active orders snapshot

Order Mass Status Request

FieldTag Type / possible valuesDescription
MsgType35MAF (OrderMassStatusRequest) 
Account1Mint 

Sample

{
    "1":1,
    "35":"H"
}

Order Mass Status Response

FieldTag Type / possible valuesDescription
MsgType35MU8 (Order Mass Status Response) 
Account1Mint 
Orders1268MArray of Execution ReportsActive orders (New, Partially filled)
Fills1269MArray of Execution Reports30 last history orders (Filled, Partially filled)

Sample

TODO

Balance updates

After logging on, API will start sending all changes of the balance of accounts requested in the Logon message.

Requesting the snapshot

Request information about current balances for all currencies by sending the following message:

FieldTag Type / possible valuesDescription
MsgType35M
  • XAA (Account Status Report Request)
 
Account1Mint 

Snapshot and update messages

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.

FieldTag Type / possible valuesDescription
MsgType35M
  • XAR (Account Status Report Snapshot)
  • XAF (Account Status Report Incremental Refresh)
XAF contains new balance for particular currency 
Account1 int 
LastUpdateTime779 Long — Unix timestamp in nanoseconds 
Repeating group Balance (1800) 
Currency15MString 
AvailableBalance1801MdecimalAvailable = Settled - Locked
LockedBalance1802MdecimalBalance locked in orders
SettledBalance1803MdecimalBalance of the account
Repeating group PositionInfo (1804), inside the Balance group, optional field
Currency15MstringPosition calculation currency
AvgPx6MdecimalPosition open price
PositionId2618Mint 
PositionOpenDate1805MLong — Unix timestamp in nanoseconds 
RealizedPL1806Mdecimal 

Samples

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
}

Sending orders

New order single

FieldTag Type / possible valuesDescription
MsgType35MD (NewOrderSingle) 
ClOrdId11MString, 20 symbols maxClOrdId must be unique within 24 hours moving frame.
Symbol55MString 
Side54Mint
  • 1 Buy
  • 2 Sell
 
SettlType63MString1 Cash (TOD / T+0) 
TransactTime60MLong — Unix timestamp in nanoseconds 
OrderQty38MDecimal 
OrdType40Mstring
  • 1 Market
  • 2 Limit
  • 3 Stop
 
Price44CDecimalMandatory for limit orders. Will be omitted for market orders.
Account1Mint 
TimeInForce59Oint
  • 1 Good Till Cancel (default value)
  • 3 Immediate Or Cancel
  • 4 Fill Or Kill
 

Sample

{
    "1":1,
    "11":"akBZL9xeQ",
    "35":"D",
    "38":"1",
    "40":”2”,
    "44":"10493.5",
    "54":1,
    "55":"BTC/USDT",
    "60":1520424185040000000,
    "63":"1"
}

Cancelling orders

Order Cancel Request

FieldTag Type / possible valuesDescription
MsgType35MF (Order Cancel Request) 
OrigClOrdID41CStringOne of the fields must be submitted.
OrderID37CString / Guid
ClOrdID11MStringClOrdId must be unique within 24 hours moving frame.
Side54Mint
  • 1 Buy
  • 2 Sell
 
Symbol55MString 
TransactTime60MLong — Unix timestamp in nanoseconds 
Account1Mint 

Sample

{
    "1":1,
    "11":"wOQYGqklK",
    "35":"F",
    "37":"3975158b-2c25-4d26-acfd-c78921408eb6",
    "54":1,
    "55":"BTC/USDT",
    "60":1520424390152000000
}

Order Cancel Reject

FieldTag Type / possible valuesDescription
MsgType35M9 (Order Cancel Reject) 
OrderId37OString / GuidOrderId of the order being cancelled, if it has been found
OrigClOrdId41OStringClOrdId of the order being cancelled, if it has been found, or if OrigClOrdId has been submitted in the request
ClOrdId11MString 
OrdStatus39M
  • 2 Filled
  • 4 Cancelled
  • 6 Pending Cancel
  • 8 Rejected
Current status of the order being cancelled
CxlRejResponseTo434M
  • 1 Order Cancel Request
 
CxlRejReason102M
  • 0 TooLateToCancel
  • 1 UnknownOrder
  • 3 OrderAlreadyInPendingStatus
  • 6 DuplicateClOrdID
  • 99 Other
 
RejectText1328OStringReject reason
TransactTime60MLong — Unix timestamp in nanoseconds 
Account1Mint 

Sample

TODO

Execution reports

Order status matrices

There is a separate article describing order statuses in different scenarios.

Execution report

FieldTag Type / possible valuesDescription
MsgType35M8 (ExecutionReport) 
OrderId37MString / Guid 
ClOrdId11MString 
OrigClOrdId41OStringClOrdId of the order being cancelled, if OrigClOrdId has been submitted in the request.
TradeId1003CintConditionally required when ExecType = Trade
Symbol55MString 
ExecType150M
  • 0 New
  • F Trade
  • 4 Cancelled
  • 8 Rejected
According to order status matrices.
OrdStatus39M
  • 0 New
  • 1 Partially Filled
  • 2 Filled
  • 4 Cancelled
  • 8 Rejected
  • 9 Suspended
According to order status matrices.
Side54Mint
  • 1 Buy
  • 2 Sell
 
OrdType40Mint
  • 1 Market
  • 2 Limit
  • 3 Stop
 
Price44CDecimalConditionally required for limit orders.
OrderQty38MDecimalAccording to order status matrices.
LeavesQty151MDecimalAccording to order status matrices.
CumQty14MDecimalAccording to order status matrices.
LastQty32CDecimalAccording to order status matrices. Conditionally required when ExecType is Trade.
LastPx31CDecimalConditionally required when ExecType is Trade.
CalculatedCcyLastQty1056CDecimalNet payment of the fill, not including commission.Conditionally required when ExecType is Trade.
NetMoney118CDecimalGross amount of the fill, including commission.Conditionally required when ExecType is Trade.
TransactTime60MLong — Unix timestamp in nanosecondsTimestamp of the event.
LastLiquidityInd851C
  • 1 AddedLiquidity (maker)
  • 2 RemovedLiquidity (taker)
Conditionally required when ExecType is Trade.
Commission12ODecimal 
CommCurrency479OString 
Account1MInt 
Currency15MStringPair base currency
SettlCurrency120MStringPair quote currency

Sample

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