NAV Navbar

ZUBR API

Introduction

Welcome to ZUBR API documentation page.

The fastest way to reach ZUBR engine is via FAST and our proprietary BYSON protocols. BYSON is designed for trading and account management, while market data can be received via FAST.

How to start?

BYSON and FAST can only be accessed from the datacenter where our hardware is located - the Equinix LD4 data center in London. You can co-locate your trading servers, order x-connect or VPS to get the lowest possible latency to our trading engine. Your software must be certified on our UAT environment in order to get access to production trading. For further instructions please contact us via [email protected]

BYSON Trading Protocol

FIX protocol is used in Order Gate over TCP. The FIX protocol is encoded via Simple Binary Encoding (or just SBE). Specification of this standard should be taken into account (particularly terminology) except certain cases, described in the chapter.

Since the gate performance level does matter, only statically-known message types are used the templates. It is important to notice that this manual contains tags or constants that may differ from the FIX specification.

Types

The schema types mentioned below are presented in the schema:

Integers are encoded in little-endian data format, and the number located after the type (e.g 16 in uint16) specifies the number of bits used for an integer. Here are some encoding examples:

Number Type Encoded (hex)
123 int8 7b
-123 int8 85
12345 int16 39 30
-12345 int16 c7 cf
12345678 int32 4e 61 bc 00
-12345678 int32 b2 9e 43 ff
1234567891234567 int64 07 af 9b 3c d5 62 04 00
-1234567891234567 int64 f9 50 64 c3 2a 9d fb ff
123 uint8 7b
12345 uint16 39 30
12345678 uint32 4e 61 bc 00
1234567891234567 uint64 07 af 9b 3c d5 62 04 00

Mantissa of a decimal is encoded as int64. The number located after the type (e.g 9 in decimal9) specifies the fixed exponent with the minus sign. Here are some encoding examples:

Number Type Encoded (hex)
1 decimal9 00 ca 9a 3b 00 00 00 00
1234567.891234567 decimal9 4e 16 13 39 f0 6c 04 00
-1234567.891234567 decimal9 f9 50 64 c3 2a 9d fb ff

Fixed-sized ASCII strings are encoded as an array of ASCII characters (in range [0x20; 0x7f]), and the length of the array is specified at the end of the type name (e.g 4 in string4). Here are some encoding examples:

String Type Encoded (hex)
\x00\x00\x00\x00 string4 00 00 00 00
ABCD string4 41 42 43 44

An alias is basically an alternative name to another type of which encoding is already defined.

All enumerations are encoded as uint8, thus it is impossible to have more than 256 variants of values.

All values types have valid ranges and a Null magic value, which is used for unset optional fields. The table below shows the minimum, maximum, and null values for different types:

Type Null Value Min Value Max Value
int8 -128 -127 127
int16 -32768 -32767 32767
int32 -2147483648 -2147483647 2147483647
int64 -9223372036854775808 -9223372036854775807 9223372036854775807
uint8 255 0 254
uint16 65535 0 65534
uint32 4294967295 0 4294967294
uint64 18446744073709551615 0 18446744073709551614

Price, Amount and Leverage types are decimals with constant exponent. Composite type value is considered to be Null if the first field is Null.

All the messages can be divided into two main groups: Session and Application layer messages. The session layer messages are used to establish and maintain the connection and application layer messages allow trading actions.

Every message contains a standard message header:

Field name Type Description
blockLength uint16 message body length
templateId uint16 message template identifier
schemaId uint16 schema identifier
version uint16 version number

The following constants are used in this document.

Protocol flow

Session establishment and termination

A client must send the Establish message to set up a connection. The server must respond with the EstablishmentAck if all the parameters are correct. The session is now considered established. In case some parameters are incorrect, or connection is already established, the server must reply with the EstablishmentReject message that provides the specific reason for the reject in the EstablishmentRejectCode field.

A client must send the Terminate message to close the session.

Monitoring session state

A client and the gate should periodically exchange their heartbeat messages (it is called Sequence). A client sets heartbeat sending interval in the Establish message and gate responds within its own interval in the EstablishmentAck message.

The server must send message once during the set interval, but the message is not always a heartbeat. In case the client doesn't send any message during its KeepaliveInterval, it is disconnected from the gate with the Terminate message and the following reason (MissedHeartbeat).

A client should not send more than a certain number of messages per second, otherwise will be disconnected from the gate with the Terminate message and the following reason (TooFastClient).

Message numbering

A client must support a sequence counter of incoming messages. Client receives its initial state in the EstablishmentAck message. After that every application level message should increment this counter.

Message retransmit

A client can request for a message retransmission using the Retransmit request. For that purpose the client must specify the number of the first message to retransmit in the FromSeqNo field. The server must respond with Retransmission message with count field set to the number of messages that are going to be retransmitted. After that all the retransmitted messages will be sent to the client. No new messages are allowed from the client until retransmission is complete.

Session restore

In case the connection is closed, the client should establish a new session and check the sequence number in the EstablishmentAck. If the received sequence number is greater than its own sequence number, the Client should use the RetransmitRequest to receive the lost messages.

Tracing

All the application level messages contain TraceId.

A TraceId received from responses and reports can be used in order to identify the cause of the issue when contacting the technical support.

Currently the gate ignores the TraceId presented in requests and generates its own. The client can get a generated TraceId from a corresponding response.

Application level messages

Placing orders

A client sends the OrderPlaceRequest to place a new order. The gate responds with either OrderReport or OrderPlaceReject messages. OrderReport may be followed by another message depending on the value of TimeInForce parameter:

TimeInForce Messages
GTC ExecutionReport (if order is filled)
IOC ExecutionReport (if order is filled), OrderCancelReport (in case of partly execution)
FOK ExecutionReport (if order is filled), OrderCancelReport (if order is not filled)

Canceling orders

A client may cancel a successfully placed order by using the OrderCancelRequest message. If the order cannot be found (e.g. it was already canceled, executed, or it doesn't even exist), the OrderCancelReject will be returned to the client.

Canceling multiple orders

A client may cancel multiple orders at once by using the OrderMassCancelRequest message. The client may request one or more filters for the request. Filters are additive, for instance: if only the InstrumentId field is set, it means that all orders with matching InstrumentId field will be canceled. If both the InstrumentId and the Side are set, it means that all orders matching both Side and InstrumentId are canceled, etc. The gate will respond with the OrderCancelReport message for each successfully canceled order. In the end of the process the client will receive the OrderMassCancelReport message.

Replacing orders

An existing order can be replaced by another one with different price and quantity using OrderReplaceRequest message. If the order is already canceled or executed, the OrderReplaceReject is returned to the client.

Requesting limits

A client may request its limits by using the BalanceFetchRequest. The gate will respond with BalanceReport message.

Login types

Two login types are used in BYSON protocol. The Trading Login is used to generate transactions and receiveing the execution reports. The Managing Login is used to manage the account's risk-parameters and receive any information regarding the account. While the Managing Login includes includes all the features of the Trading Login, we highly recommend using the Trading login for live trading due to it being faster than the Managing login.

Trading login: Session and Trading messages

Managing login: Session, Trading and Account messages

Session messages Trading messages Account messages
Establish OrderPlaceRequest BalanceFetchRequest
EstablishmentAck OrderCancelRequest PositionFetchRequest
EstablishmentReject OrderReplaceRequest RiskParamsFetchRequest
Terminate OrderMassCancelRequest RiskParamsModifyRequest
RetransmitRequest OrderReport IsolatedMarginChangeRequest
RetransmitReject OrderPlaceReject BalanceReport
Sequence OrderCancelReport BalanceFetchReject
FloodReject OrderCancelReject PositionReport
MessageReject OrderReplaceReport PositionFetchReject
OrderReplaceReject RiskParamsReport
OrderMassCancelReport RiskParamsModifyReject
OrderMassCancelReject RiskParamsFetchReject
ExecutionReport IsolatedMarginChangeReport
EmptyBookReport IsolatedMarginChangeReject
TradingStatusReport FundingReport
TradeReport

BYSON Enumerations

TerminationCode

Value Name Description
1 Request Session is finished by the user request
2 InternalError Internal server error
3 ReRequestOutOfBounds Range specified in RetransmitRequest is out of bounds
4 ReRequestInProgress Retransmit request is in progress
5 TooFastClient Client is sending too many messages
6 TooSlowClient Client is not retrieving messages from TCP socket
7 MissedHeartbeat Client did not send any messages for KeepaliveInterval time
8 InvalidMessage Message is incorrect in terms of protocol
9 InvalidSequenceNumber Response to a Sequence message with incorrect SequenceNumber
10 ServerShutdown Server is shutting down as per schedule

EstablishmentRejectCode

Value Name Description
1 AlreadyEstablished Connection of this user is already established
2 LoginBlocked Client was blocked
3 InvalidKeepaliveInterval Heartbeat interval is outside of allowed range
4 AccessDenied Credentials (LoginId + IP) are incorrect
5 InternalError Internal server error

RetransmitRejectCode

Value Name Description
1 OutOfRange NextSeqNo + Count is beyond the range of sequence numbers
2 RequestLimitExceeded The message Count exceeds a local rule for maximum retransmission size

MessageRejectReason

Value Name Description
1 InvalidValue Field value is incorrect
2 SystemUnavailable Trading system is unavailable
3 DuplicateRequestId Request identifier is not unique
4 ConflictingValue Some field (RefTagId) value conflicts with another
5 UnsupportedOperation Operation is not supported

OrderRejectReason

Value Name Description
1 InternalError Internal system error
2 UnknownInstrument Unknown instrument
3 UnknownAccount Unknown account
4 UnknownOrder Order is not found in the system
5 NothingToChange All changeable fields are empty
6 MinPriceIncrementViolation
7 TooManyOrders
8 TradingStatus
9 PriceBandsViolation Price exceeds the current price band
10 InsufficientFunds
11 RiskLimitReached Order exceeds the risk limits
12 RiskParamsChanging Risk parameters are changing
13 AccountBlocked Account is blocked
14 ConflictingProperties Conflicting of order type and time in force values

OrderType

Value Name Description
1 Limit Limit order
2 PostOnly Passive order

TimeInForce

Value Name Description
1 GTC Good Til Canceled
2 IOC Immediate Or Cancel
3 FOK Fill Or Kill

Side

Value Name Description
1 Buy
2 Sell

MarginMode

Value Name Description
1 Cross
2 Isolated

TradeType

Value Name Description
1 Regular
2 Liquidation
3 Deleverage

PositionFetchRejectReason

Value Name Description
1 InternalError Internal system error
3 NoOpenPosition No open position

BalanceFetchRejectReason

Value Name Description
1 InternalError Internal system error
3 UnknownCurrency Unknown currency
4 UnknownAccount Unknown Account

RiskParamsModifyRejectReason

Value Name Description
1 InternalError Internal system error
3 UnknownInstrument Unknown instrument
4 UnknownAccount Unknown Account
5 NothingToChange All changeable fields are empty
6 MaxRiskLimitExceeded Requested risk limit is too high
7 UnavailableLeverage Leverage is unavailable for risk limit
8 NotionalValueExceeded Notional value exceeds the requested risk limit
9 InsufficientFunds Not enough funds for the operation

RiskParamsFetchRejectReason

Value Name Description
1 InternalError Internal system error
3 UnknownInstrument Unknown instrument
4 UnknownAccount Unknown Account

RiskParamsReportReason

Value Name Description
1 Request User requested report
2 AccountLinked
3 RiskParamsChanged

IsolatedMarginChangeRejectReason

Value Name Description
1 InternalError Internal system error
3 UnknownInstrument Unknown instrument
4 UnknownAccount Unknown Account
5 InsufficientFunds
6 InsufficientMargin
7 NoOpenPosition No open position for instrument
8 NoIsolatedMargin

BalanceReportReason

Value Name Description
1 Request User requested report
2 AccountLinked
3 RiskParamsChanged
4 IsolatedMarginChanged
5 MarketChanged
6 OrderActivity
7 Trading
8 Funding
9 Liquidation
10 Deleverage
100 Other
101 Deposit
102 Withdrawal
103 Correction
104 NonTradingFee
105 InterAccountTransfer
106 LoanIssuance
107 LoanRepayment
108 LoanInterest

PositionReportReason

Value Name Description
1 Request User requested report
2 RiskParamsChanged
3 IsolatedMarginChanged
4 MarketChanged
5 WalletBalanceUpdated
6 Trading
7 Funding
8 Liquidation
9 Deleverage

CancelReason

Value Name Description
1 BookEmptied Book was emptied
2 OrderType Passive only
3 TimeInForce FOK, IOC
4 CrossTrade Cross-trade
5 CancelRequest Canceled by client
6 Liquidation Canceled by liquidation mechanism

TradingStatus

Value Name Description
1 Halted
2 Normal
3 CancelOnly

BYSON Messages

Establish

templateId = 5000

The message is used for creating a session for the current TCP connection

Tag Field name Required Type Description
20004 KeepaliveInterval + DurationNanosecs Requested heartbeat interval
20005 LoginId + LoginId Client login id

EstablishmentAck

templateId = 5001

Confirmation of session creation, as a response to the Establish message

Tag Field name Required Type Description
20004 KeepaliveInterval + DurationNanosecs Session heartbeat interval
20006 NextSeqNo + UInt64 Sequence number of the next message

EstablishmentReject

templateId = 5002

Denial of session creation, as a response to the Establish message

Tag Field name Required Type Description
20007 EstablishmentRejectCode + EstablishmentRejectCode

Terminate

templateId = 5003

Terminates session

Tag Field name Required Type Description
20008 TerminationCode + TerminationCode

RetransmitRequest

templateId = 5004

Request for message retransmission

Tag Field name Required Type Description
20009 FromSeqNo + UInt64 Starting sequence number
20010 Count + UInt32 Number of messages to retrieve

Retransmission

templateId = 5005

The message is used to notify that the following Count messages are responses for RestransmitRequest

Tag Field name Required Type Description
20006 NextSeqNo + UInt64 First returned sequence number
20010 Count + UInt32 Number of messages

RetransmitReject

templateId = 5006

The message is used to notify that the following Count messages are responses for RestransmitRequest

Tag Field name Required Type Description
20011 Reason + RetransmitRejectCode Reject reason

Sequence

templateId = 5007

Heartbeat message. Client should set NextSeqNo to the nullValue. Server sets NextSeqNo to the next message sequence number (counted by application-level messages)

Tag Field name Required Type Description
20006 NextSeqNo C UInt64 Sequence number of the next message

FloodReject

templateId = 5008

The message is used to notify that message flooding has been detected

Tag Field name Required Type Description
11 RequestId + UInt64 Request id of the message leading to flood
20012 QueueSize + UInt32 Number of received messages for the latest second
20013 PenaltyRemain + DurationNanosecs Time left till the end of the block, in nanoseconds

MessageReject

templateId = 5009

The message is sent in response to invalid client messages

Tag Field name Required Type Description
11 RequestId + UInt64 Request id of rejected message
371 RefTagId C UInt32 Invalid field identifier
373 Reason + MessageRejectReason Reject reason code

OrderPlaceRequest

templateId = 6001

New order placement

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
44 Price + Price Price
38 Size + Size Order quantity
40 Type + OrderType Order type
59 TimeInForce + TimeInForce
54 Side + Side

OrderCancelRequest

templateId = 6002

Cancellation of the previously placed order

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
37 OrderId + OrderId Order identifier

OrderReplaceRequest

templateId = 6003

Modification of the previously placed order

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
37 OrderId + OrderId Order identifier to replace
44 Price C Price New price
38 Size C Size New size
40 Type C OrderType Order type
59 TimeInForce C TimeInForce

OrderMassCancelRequest

templateId = 6004

Cancellation of the multiple orders by the selected parameter

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId C AccountId Account identifier
48 InstrumentId C InstrumentId Instrument identifier
54 Side C Side

BalanceFetchRequest

templateId = 8000

Request of the balance information

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
15 Currency + Currency

PositionFetchRequest

templateId = 8001

Request of the position information

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier

RiskParamsFetchRequest

templateId = 8002

Request to retrieve current risk parameters

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier

RiskParamsModifyRequest

templateId = 8003

Request to change risk limit

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
20014 MarginMode C MarginMode
20015 Leverage C Leverage
20016 RiskLimit C Amount

IsolatedMarginChangeRequest

templateId = 8004

Request to change isolated margin

Tag Field name Required Type Description
20002 TraceId C TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
20017 DeltaMargin + Amount

OrderReport

templateId = 7000

The message is used to notify that the order was successfully placed as a response to OrderPlaceRequest

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64 Client request identifier
20003 TradingTimestamp + Timestamp
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
37 OrderId + OrderId
44 Price + Price
38 Size + Size
40 Type + OrderType
59 TimeInForce + TimeInForce
54 Side + Side

OrderPlaceReject

templateId = 7001

The message is used to notify that the order was rejected as a response to OrderPlaceRequest

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
103 Reason + OrderRejectReason

OrderCancelReport

templateId = 7002

The message is used to notify that the order was canceled as a response to OrderCancelRequest or for other reason

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64 Client request identifier
20003 TradingTimestamp + Timestamp
37 OrderId + OrderId
20018 Reason + CancelReason

OrderCancelReject

templateId = 7003

The message is used to notify that the order cancel was rejected as a response to OrderCancelRequest

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
103 Reason + OrderRejectReason

OrderReplaceReport

templateId = 7004

The message is used to notify that the order was successfully replaced as a response to OrderReplaceRequest

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64 Client request identifier
20003 TradingTimestamp + Timestamp
37 NewOrderId + OrderId
44 Price + Price New price
38 Size + Size New size
20019 OldOrderId + OrderId

OrderReplaceReject

templateId = 7005

Reject for replaced order as a response to OrderReplaceRequest

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64 Client request identifier
103 Reason + OrderRejectReason

OrderMassCancelReport

templateId = 7006

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64 Client request identifier

OrderMassCancelReject

templateId = 7007

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
103 Reason + OrderRejectReason

ExecutionReport

templateId = 7008

The message provides the details of the order that was filled.

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
20003 TradingTimestamp + Timestamp Trading system time
1003 TradeId + TradeId Trade identifier
31 TradePrice + Price Trade price
32 TradeSize + Size Trade size
37 OrderId + OrderId Public order identifier
38 OrderSize + Size Remaining size of the order

EmptyBookReport

templateId = 7009

Book was emptied

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
20003 TradingTimestamp + Timestamp
48 InstrumentId + InstrumentId Instrument identifier

TradingStatusReport

templateId = 7010

Message for trading status events notification

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
20003 TradingTimestamp + Timestamp
48 InstrumentId + InstrumentId Instrument identifier
340 Status + TradingStatus

TradeReport

templateId = 9000

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
20003 TradingTimestamp + Timestamp
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
1003 TradeId + TradeId
20020 Type + TradeType
38 Size + Size
31 Price + Price
54 Side + Side
20047 NotionalValue + Amount
20021 TradingPnl + Amount
20022 ExchangeFee + Amount
20023 BrokerFee + Amount

BalanceReport

templateId = 9001

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64
1 AccountId + AccountId Account identifier
15 Currency + Currency
20024 Reason + BalanceReportReason
20025 UnrealizedPnl + Amount
20026 OrdersMargin + Amount
20027 PositionsMargin + Amount
20028 Wallet + Amount
20029 Borrowed + Amount
20030 Available + Amount

BalanceFetchReject

templateId = 9002

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
20031 Reason + BalanceFetchRejectReason

PositionReport

templateId = 9003

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
20032 Reason + PositionReportReason
20033 Size + Size
20034 EntryPrice + Price
20035 PartialLiquidationPrice C Price
20036 FullLiquidationPrice C Price
20037 EntryNotionalValue + Amount
20038 CurrentNotionalValue + Amount
20025 UnrealizedPnl + Amount
20039 Margin + Amount
20040 MaxRemovableMargin + Amount

PositionFetchReject

templateId = 9004

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
20041 Reason + PositionFetchRejectReason

RiskParamsReport

templateId = 9005

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
20042 Reason + RiskParamsReportReason
20014 MarginMode + MarginMode
20015 Leverage C Leverage
20016 RiskLimit + Amount

RiskParamsModifyReject

templateId = 9006

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
20043 Reason + RiskParamsModifyRejectReason

RiskParamsFetchReject

templateId = 9007

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
20044 Reason + RiskParamsFetchRejectReason

IsolatedMarginChangeReport

templateId = 9008

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId C UInt64
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId

IsolatedMarginChangeReject

templateId = 9009

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
11 RequestId + UInt64
20045 Reason + IsolatedMarginChangeRejectReason

FundingReport

templateId = 9010

Tag Field name Required Type Description
20001 SeqNo + UInt64
20002 TraceId + TraceId Trace identifier
1 AccountId + AccountId Account identifier
48 InstrumentId + InstrumentId Instrument identifier
20046 Amount + Amount

FAST Market Data Protocol

The market data gate broadcasts the following information:

Feed Data
Instrument definitions The instruments available on the exchange and their trading status
Instrument statuses Changes of the instrument's properties
Orders snapshots Full order book
Orders incremental Anonymous feed of orders
Book1 snapshots Top of the book
Book1 incremental Changes in the top of the book
Book5 snapshots Aggregated order book with 5 depth
Book5 incremental Changes in Book5
Book25 snapshots Aggregated order book with 25 depth
Book25 incremental Changes in Book25
Trades snapshots Last trade
Trades incremental Anonymous feed of trades

Transfer and encoding

Market data is transmitted as UDP multicast traffic. Market data receivers will be provided with a receiving interface IPv4 address and a multicast IPv4 address for each feed.

The UDP packet payload consists of:

Messages are encoded according to the FAST 1.x.1 standard with FAST version 1.2 Extension Version 10. The provided XML templates should be used for decoding the messages.

Messages use Financial Information Exchange protocol (FIX) Version 5.0 Service Pack 2. However, some fields deviate from the FIX standard when necessary.

If the information to be sent doesn't fit in a single UDP packet, it's split to multiple FIX/FAST messages that are sent sequentially, as allowed by the FIX standard. FirstFragment and LastFragment fields can be used to determine that these messages are parts of a single update.

Notation

The => sign in the Tag column indicates that this field is part of a repeated sequence.

Fields marked as optional can have no value in some messages. They are encoded as specified in the FAST standard. All fields that are not marked as optional are always present.

Fields marked as const are never encoded and always have the same value specified in the XML template.

Note that field names, types, tag names, optional and const attributes are specified in the XML template as well.

Snapshots and incremental updates

Connection to live market data feeds is usually done in the following steps:

  1. Subscribe to the incremental feed and start receiving update messages
  2. Subscribe to the snapshot feed, receive a snapshot for each instrument of interest, and unsubscribe from the snapshot feed
  3. For each instrument, discard received incremental updates that have RptSeq smaller or equal to the RptSeq of the received snapshot for this instrument
  4. Apply the remaining incremental updates to the corresponding snapshots
  5. Keep updating the data as new incremental updates are received

The data is sent to the snapshot feeds at fixed time intervals. The data is sent for each instrument separately. The TotNumReports field present in each snapshot message can be used to determine that a snapshot for each available instrument has been received.

Compatibility notes

All messages contain reserved fields that are currently unused. They may become used in the future, allowing forward-compatible changes to the template.

In addition, new fields may be added to the end of each message. Parsers should ignore unparsed data that may be present at the end of the message.

Recovery gate

Lost packets can be requested at the recovery gate. The recovery gate can be accessed via the HTTP protocol.

Get packets

Endpoint URL: /v1/[feed], where [feed] can be one of the following:

[feed] Feed
orders-incremental Orders incremental
trades-incremental Trades incremental
book1-incremental Book1 incremental
book5-incremental Book5 incremental
book25-incremental Book25 incremental

Other feeds are not available via the recovery gate.

GET parameters:

Parameter Description
from MessageSequenceNo of the first requested message
count Number of requested messages

The number of messages that can be requested in a single request is limited. The time frame of available packets is also limited.

On success, the status code 200 will be returned. The body of the response will contain binary data of the requested packets with length-delimited encoding:

[length of packet1] [data of packet1] [length of packet2] [data of packet2] ...

Length is encoded as uint64 in Little Endian. Packet data uses FIX/FAST and is identical to the UDP payload in the multicast feed.

If no packets matching the parameters were found or the requested packets are too old, the status code 404 is returned.

The most recent packets may not be available via the recovery gate. In this case the request should be retried after a delay.

On bad request, status code 400 is returned.

Header

Each message starts with the StandardHeader:

Tag Field Type & presence Description
1128 AppliedVersionId string (const) FIX version ID
35 MessageType string (const) Message type
34 MessageSequenceNo uint64 Sequential message number
52 SendingTime timestamp Sending time

The MessageType value corresponding to each message type is specified below in the description of each message.

Session level and application level

Heartbeat and Sequence reset are session level messages. Session level messages can be present in every feed.

Other messages are application level messages. Each message can only appear in the corresponding feed.

FAST Messages

SequenceReset

The message that is sent when the gate resets its message counter. The message following the sequence reset will have the specified MsgSeqNum.

MessageType = "4" (Sequence reset)

Tag Field Type Description
36 NewSequenceNo uInt64 Sequence number of the next message in the feed (FIX name: NewSeqNo)

Heartbeat

The message that is sent to a feed when there are no other messages for some time. The heartbeat message doesn't have any additional fields except the fields of the standard header.

MessageType = "0" (Heartbeat)

OrdersIncrementalUpdate

The message is used to show adding, updating, or deleting of an order.

MessageType = "X" (Market Data - Incremental Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
268 EntryCount length Number of MDEntry in this message (FIX name: NoMDEntries)
=>83 ReportSequenceNo uInt64 Report sequence ID (unique monotonically increasing ID, separately for each instrument) (FIX name: RptSeq)
=>279 UpdateAction enum Type of the incremental update. Not present if entry type is EmptyBook (FIX name: MDUpdateAction)
=>278 Id uInt64 Order ID. Not present if entry type is EmptyBook (FIX name: MDEntryID)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
=>270 Price decimal Order price. Not present if entry type is EmptyBook (FIX name: MDEntryPx)
=>271 Size int32 Depends on the update type: for New - order size; for Change - remaining order size; for Delete - remaining size of the order before deletion. Not present if entry type is EmptyBook (FIX name: MDEntrySize)
=>40 OrderType enum Order type. Not present if entry type is EmptyBook (FIX name: OrdType)
=>59 TimeInForce enum Time in force. Not present if entry type is EmptyBook
=>5007 DeleteReason enum Reason of deletion. Only present when UpdateAction = 2 (Delete)
=>1003 TradeId uInt64 ID of the trade that caused this update. Only present for updates caused by order execution
=>31 TradePrice decimal Price of the trade that caused this update. Only present for updates caused by order execution (FIX name: LastPx)
=>32 TradeSize int32 Size of the trade that caused this update. Only present for updates caused by order execution (FIX name: LastQty)
=>273 Timestamp timestamp Time of the update (FIX name: MDEntryTime)
=>5005 EndOfTransaction boolean True if this is the last update for this transaction
=>5010 TraceId uInt64 Trace Id for internal usage

OrdersSnapshot

A full list of active orders. According to the standard, if the book is empty, the snapshot will contain a single entry with Type = EmptyBook.

MessageType = "W" (Market Data - Snapshot / Full Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
83 ReportSequenceNo uInt64 Value of ReportSequenceNo field of the incremental update included in this snapshot (FIX name: RptSeq)
911 TotalReportCount uInt32 Total number of reports (can be used to determine that all reports have been received) (FIX name: TotNumReports)
48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
5010 TraceId uInt64 Trace Id for internal usage
268 EntryCount length Number of MDEntry in this message (FIX name: NoMDEntries)
=>278 Id uInt64 Order ID. Present unless Type is EmptyBook (FIX name: MDEntryID)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>270 Price decimal Order price. Present unless Type is EmptyBook (FIX name: MDEntryPx)
=>271 Size int32 Remaining order size. Present unless Type is EmptyBook (FIX name: MDEntrySize)
=>1003 TradeId uInt64 ID of the last trade for this order. Only present if there was at least one trade for this order

TradesIncrementalUpdate

Information about a trade.

MessageType = "X" (Market Data - Incremental Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
268 EntryCount length Number of MDEntry in this message (FIX name: NoMDEntries)
=>83 ReportSequenceNo uInt64 Report sequence ID (unique monotonically increasing ID, separately for each instrument) (FIX name: RptSeq)
=>279 UpdateAction enum Type of the incremental update (FIX name: MDUpdateAction)
=>278 Id uInt64 Trade ID (FIX name: MDEntryID)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
=>270 Price decimal Trade price (FIX name: MDEntryPx)
=>271 Size int32 Trade size (FIX name: MDEntrySize)
=>5009 TradeType enum Type of the trade
=>5004 AggressiveOrderSide enum Side of the order that initiated the trade
=>273 Timestamp timestamp Time of the trade (FIX name: MDEntryTime)
=>5005 EndOfTransaction boolean True if this is the last update for this transaction
=>5010 TraceId uInt64 Trace Id for internal usage

TradesSnapshot

Information about the last trade for the particular instrument.

MessageType = "W" (Market Data - Snapshot / Full Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
83 ReportSequenceNo uInt64 Value of ReportSequenceNo field of the incremental update included in this snapshot (FIX name: RptSeq)
911 TotalReportCount uInt32 Total number of reports (can be used to determine that all reports have been received) (FIX name: TotNumReports)
48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
5010 TraceId uInt64 Trace Id for internal usage
268 EntryCount length Number of MDEntry in this message (at most 1 for trades snapshot, zero if there was no trades) (FIX name: NoMDEntries)
=>278 Id uInt64 Trade ID (FIX name: MDEntryID)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>270 Price decimal Trade price (FIX name: MDEntryPx)
=>271 Size int32 Trade size (FIX name: MDEntrySize)
=>5009 TradeType enum Type of the trade
=>5004 AggressiveOrderSide enum Side of the order that initiated the trade
=>273 Timestamp timestamp Time of the trade (FIX name: MDEntryTime)

BookIncrementalUpdate

The message about adding, updating, or deleting an entry in the aggregated order book. Note that when entries are added or removed from the aggregated order book, only a single update message is sent. The listener should infer changes in the price levels of all entries below the place of modification.

MessageType = "X" (Market Data - Incremental Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
268 EntryCount length Number of MDEntry in this message (FIX name: NoMDEntries)
=>83 ReportSequenceNo uInt64 Report sequence ID (unique monotonically increasing ID, separately for each instrument) (FIX name: RptSeq)
=>279 UpdateAction enum Type of the incremental update. Not present if entry type is EmptyBook (FIX name: MDUpdateAction)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
=>1023 PriceLevel uInt32 Price level (from 1 to market depth). Not present if entry type is EmptyBook (FIX name: MDPriceLevel)
=>270 Price decimal Price at this price level. Not present if entry type is EmptyBook (FIX name: MDEntryPx)
=>271 Size int32 Total size of orders at this price level. Not present if entry type is EmptyBook (FIX name: MDEntrySize)
=>273 Timestamp timestamp Time of the update (FIX name: MDEntryTime)
=>5005 EndOfTransaction boolean True if this is the last update for this transaction
=>5010 TraceId uInt64 Trace Id for internal usage

BookSnapshot

An order book aggregated by market depth. According to the standard, if the book is empty, the snapshot will contain a single entry with Type = EmptyBook.

MessageType = "W" (Market Data - Snapshot / Full Refresh)

Tag Field Type Description
5006 FirstFragment uInt32 True if this is the first fragment of the update
893 LastFragment uInt32 True if this is the last fragment of the update
83 ReportSequenceNo uInt64 Value of ReportSequenceNo field of the incremental update included in this snapshot (FIX name: RptSeq)
911 TotalReportCount uInt32 Total number of reports (can be used to determine that all reports have been received) (FIX name: TotNumReports)
48 InstrumentId uInt32 Instrument ID (FIX name: SecurityId)
5010 TraceId uInt64 Trace Id for internal usage
268 EntryCount length Number of MDEntry in this message (FIX name: NoMDEntries)
=>269 EntryType enum Entry type (FIX name: MDEntryType)
=>1023 PriceLevel uInt32 Price level (from 1 to market depth). Not present if entry type is EmptyBook (FIX name: MDPriceLevel)
=>270 Price decimal Price at this price level. Present unless Type is EmptyBook (FIX name: MDEntryPx)
=>271 Size int32 Total size of orders at this price level. Present unless Type is EmptyBook (FIX name: MDEntrySize)

InstrumentStatus

Information about current parameters of the instrument.

MessageType = "f" (Security Status)

Tag Field Type Description
48 InstrumentId uInt32 Unique numeric ID of the instrument (FIX name: SecurityId)
326 TradingStatus enum Trading status for this instrument (FIX name: SecurityTradingStatus)
5002 SellPriceBand decimal Minimum allowed sell price
5003 BuyPriceBand decimal Maximum allowed buy price
5008 MarkPrice decimal Mark price of the instrument
5010 TraceId uInt64 Trace Id for internal usage
746 OpenInterest int64 Open interest for this instrument
5011 TimeUntilFunding timestamp Estimated time until the next funding
5012 EstimatedFundingRate decimal Estimated rate for the next funding

InstrumentDefinition

Information about an instrument.

MessageType = "d" (Security definition)

Tag Field Type Description
911 TotalReportCount uInt32 Total number of reports (can be used to determine that all reports have been received) (FIX name: TotNumReports)
48 InstrumentId uInt32 Unique numeric ID of the instrument (FIX name: SecurityId)
55 Symbol string Textual instrument ID
15 PriceCurrency string Currency used for price (FIX name: Currency)
120 SettlementCurrency string Currency code of settlement denomination (FIX name: SettlCurrency)
1079 MaturityTime timestamp Maturity time of the instrument (only if applicable)
969 MinPriceIncrement decimal Minimal price increment
231 ContractMultiplier decimal Contract multiplier, e.g. 1
5010 TraceId uInt64 Trace Id for internal usage
1141 FeedTypeCount length Total number of market data feeds in the following list (FIX name: NoMDFeedTypes)
=>1022 FeedType string Feed identifier: "Orders", "Trades", "Book1", "Book5", "Book25" (FIX name: MDFeedType)
=>264 MarketDepth uInt32 Market depth, e.g. 1, 5, 25. Only for book feeds
=>1021 BookType enum Book type. Only for book feeds (FIX name: MDBookType)

Files

BYSON schema

FAST schema

BYSON PDF Specification

FAST PDF Specification

Certified software

The following software vendors are certified by ZUBR and can offer high-quality connectivity solutions to our exchange.

Quantbox

Exactpro

Websocket API

ZUBR Websocket interface is used for sending transactions and subscribing to data-streams Webscoket API key for trading and account control can be generated in your cabinet: production, testnet

All the messages are in JSON format. Requests are structured to follow a JSON-RPC 2.0 protocol.

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. It specifies several data structures and the rules to process them.

ZUBR has a python-library in PyPi. Please feel free to run: pip3 install zubr

Request

Request sample

{
  "id": 32,
  "method": 9,
  "params":{
    "data":{
      "params": 4507498558766798,
      "method": "cancelOrder"
    }
  }
}

The Server MUST reply with the same id value in the Response object. This member is used to correlate the context between the two objects.

Name Description
method A String containing the name of the method to be invoked. In our case the name of transaction.
params A Structured value that holds the parameter values to be used during the invocation of the method. Contains transaction parameters.
id An identifier established by the Client that MUST contain a Number

Response result

Successful response sample

{
  "id":18,
  "result":{
    "tag":"ok",
    "value":"4507838871482774"
  }
}

When a rpc call is made, the Server MUST reply with a Response.

Name Description
result This member is REQUIRED on success. The value of this member is determined by the method invoked on the Server.
id This member is REQUIRED. It MUST be the same as the value of the id member in the Request Object.

Response error

Error response sample

{
  "id":17,
  "result":{
    "tag":"err",
    "value":{
      "code":"PRICE_BANDS"
    }
  }
}

When a rpc call encounters an error.

Name Description
result This member is REQUIRED on response. The value for this member MUST be an Object.
id This member is REQUIRED. It MUST be the same as the value of the id member in the Request Object.
> tag 'err' on errors
> value Object with data
>> code Error code string

Websocket Authentification

User's session authentification

Client authentication on ZUBR occurs using an API key that is unique to each client. The API-key is a client identifier, which is a 128-bit random number received from a cryptographic source of random numbers. It is formed during the registration of the client and is sent to him.

Authentication itself is done using the HMAC-SHA256 algorithm. This function calculates a unique message authentication code value for each authentication on ZUBR. Input parameters for authentication are:

• hmac key; • time stamp; • API key.

A hmac key is a 256-bit number that is generated by ZUBR during client registration and is sent to it once during the registration process. This number is obtained from a cryptographic source of random numbers and is uniquely linked inside the ZUBR infrastructure with the client API key.

Timestamp - the value in nanoseconds from the beginning of the UNIX era, it is necessary to protect against repeated attacks, since it allows each calculation to generate a unique authentication code value. Each code also has its own lifetime - messages older than 5 minutes from the current time of the ZUBR checking server will be automatically discarded.

The resulting Authentication Code (MAC) value is 32 bytes in size.

MAC = HMAC-SHA256hmac-key (Timestamp + API-key)

With the help of this procedure, it is possible to obtain access rights only to trading operations. The authority of the API key is not enough to withdraw funds and change security settings.

Authentification sample

{
  "method":9,
  "params":{
    "data":{
      "method":"loginSessionByApiToken",
      "params":{
        "apiKey":"UGrJHxrbDY1DfF5YhKz6",
        "time":{
          "seconds":1584974565,
          "nanos":539258000
        },
      "hmacDigest":"d332bea6030fec9ee6c3ca86628a12fc19d6687a1ad07002bc4038b3ed66c7e"
      }
    }
  },
  "id":15
}

Request

Parameter Type Req Description
data Object + Object with transaction details
> method string + 'loginSessionByApiToken' for this transaction type
> params Object + Object with transaction details
>> apiKey string + Api key
>> hmacDigest string + Api key HMAC Digest
>> time Object + Time components
>>> seconds number + Unix time or number of seconds that have elapsed since the Unix epoch, that is the time 00:00:00 UTC on 1 January 1970
>>> nanos number + Nanoseconds inside current second. That number can be random 9-digit number for the case of auth-method usage

Response

Successfull authentification response

{
  "id": 2,
  "result": {
    "tag": "ok",
    "value": {
      "permissions": [
        "GET_ACCOUNT_DATA",
        "MARKET_DATA",
        "ORDER_DATA",
        "SESSION_BASIC",
        "TRADING_SETTINGS",
        "NEW_ORDER",
        "CANCEL_ORDER",
        "SESSION_LOGGED",
        "PUBLIC_DICTIONARIES"
      ],
      "startTime": {
        "seconds": 1585082199,
        "nanos": 189508000
      },
      "expirationTime": {
        "seconds": 1585114599,
        "nanos": 189231000
      },
      "userId": 284
    }
  }
}

Successfull response 'result' Object structure:

Parameter Type Description
tag string 'ok' in successfull responce
value Object Object with information
> permissions list List of login permissions
> startTime Object Session begin time components
>> seconds number Unix time is seconds.
>> nanos number Nanoseconds in the given second
> expirationTime Object Session life end time components
>> seconds number Unix time is seconds.
>> nanos number Nanoseconds in the given second
> userId number User identifier

Error response example

{
  "id":15,
  "result":{
    "tag":"err",
    "value":{
      "code":"INVALID_HMAC_DIGEST"
    }
  }
}

Websocket Trading

Websocket API allows placing and managing orders as well as getting information about user account balance, positions, orders. Additionally it allows changing leverage, risk-limits and margin of a position.

Place new order

New order place request sample

{
  "method":9,
  "params":{
    "data":{
      "method":"placeOrder",
      "params":{
        "instrument":1,
        "price":{
          "mantissa":6000,
          "exponent":0
        },
        "size":1,
        "type":"LIMIT",
        "timeInForce":"GTC",
        "side":"BUY"
      }
    }
  },
  "id":79
}

'params' Object structure:

Parameter Type Req Description
data Object + Object with transaction details
> method string + 'placeOrder' for this transaction type
> params Object + Object with transaction details
>> instrument number + Instrument number
>> price Object + Object with price components
>>> mantissa number + mantissa of the price
>>> exponent number + exponent of the price
>> side string + Order direction: 'BUY' or 'SELL'
>> size number + Order size quantity
>> type string + Order type: 'LIMIT' or 'POST_ONLY'
>> timeInForce string + Order lifetime parameter. Has three possible options:
'GTC' - good 'til cancelled order, active while not cancelled or executed
'IOC' - immediate or cancel order, unfilled part or order immediately canceled
'FOK' - fill or kill order, complete execution or nothing

Response

Successfull response sample

{
  "id":18,
  "result":
  {
    "tag":"ok",
    "value":"4507838871482774"
  }
}

Successfull response 'result' Object structure:

Parameter Type Description
value number Order number from exchange
tag string 'ok' in successfull response

Error response sample

{
  "id":17,
  "result":{
    "tag":"err",
    "value":{
      "code":"PRICE_BANDS"
    }
  }
}

Cancel order

Cancel order request sample

{
  "method":9,
  "params":{
    "data":{
      "method":"cancelOrder",
      "params":4507838871482774
    }
  },
  "id":19
}

'params' Object structure:

Parameter Type Req Description
data Object + Object with cancelled order parameters
> method string + 'cancelOrders' for this transaction
> params number + id of order for cancelation

Response

Successfull response sample

{
  "id":18,
  "result":{
    "tag":"ok",
    "value":"4507838871482774"
  }
}

Successfull response 'result' Object structure:

Parameter Type Description
value number Order number from exchange
tag string 'ok' in successfull response

Error response sample

{
  "id":17,
  "result":{
    "tag":"err",
    "value":{
      "code":"PRICE_BANDS"
    }
  }
}

Replace order

New order place request sample

{
  "method":9,
  "params":{
    "data":{
      "method":"replaceOrder",
      "params":{
        "orderId":4507805847450628,
        "price":{
          "mantissa":6000,
          "exponent":0
        },
        "size":3
      }
    }
  },
 "id":21
}

'params' Object structure:

Parameter Type Req Description
data Object + Object with transaction details
> method string + 'replaceOrder' for this transaction type
> params Object + Object with transaction details
>> price Object + Object with price components
>>> mantissa number + mantissa of the price
>>> exponent number + exponent of the price
>> size number + New order size quantity

Response

Successfull response sample

{
  "id":25,
  "result":{
    "tag":"ok",
    "value":"ok"
  }
}

Successfull response 'result' Object structure:

Parameter Type Description
value number 'ok' in successfull response
tag string 'ok' in successfull response

Error response sample

{
  "id":27,
  "result":{
    "tag":"err",
    "value":{
      "code":"PRICE_BANDS"
    }
  }
}

Get candles inside time range

getCandlesRange request example

{
  "method": 9,
  "params": {
    "data": {
      "method": "getCandlesRange",
      "params": {
        "instrumentId": 1,
        "resolution": "D",
        "from": 1408901333,
        "to": 1429464532
      }
    }
  },
  "id": 34
}

'params' Object structure:

Parameter Type Req Description
data Object + Object with transaction details
> method string + 'getCandlesRange' for this transaction type
> params Object + Object with transaction details
>> instrumentId number + Instrument identificator number
>> resolution number + Data period of the candle
>> from number + Start second of the period (Unix time)
>> to number + Finish second of the period (Unix time)

Response

Successfull response sample

{
  "id": 36,
  "result": [
    {
      "time": 1584901440000,
      "close": 6500,
      "open": 6500,
      "high": 6500,
      "low": 6500,
      "volume": 1
    },
    {
      "time": 1584902880000,
      "close": 6000,
      "open": 6500,
      "high": 6500,
      "low": 6000,
      "volume": 63768
    }
  ]
}

Successfull response 'result' Object structure is a list of the candles objects with the strycture below:

Parameter Type Description
time number Unix time in seconds
close number Candle close price
open number Candle open price
high number Candle highest price
low number Candle lowest price
volume number Volume in the current candle

Error response sample

{
    "id": 1, 
    "result": 
    {
        "code": 2, 
        "metadata": 
        {
            "_internal_repr": {}, 
            "flags": 0
        }, 
    "details': 'candles count limit exceeded"
    }
}

Set risk settings

Transaction allows change leverage and margin mode on a chosen instrument

setRiskSettings request example

{
  "method": 9,
  "params": {
    "data": {
      "method": "setRiskSettings",
      "params": {
        "marginMode": "ISOLATED",
        "leverage": {
          "mantissa": 41,
          "exponent": -1
        },
        "instrumentId": 1
      }
    }
  },
  "id": 38
}

'params' Object structure:

Parameter Type Req Description
data Object + Object with transaction details
> method string + 'setRiskSettings' for this transaction type
> params Object + Object with transaction details
>> instrumentId number + Instrument identificator number
>> marginMode string + Margin mode type: 'ISOLATED' or 'CROSS'
>> leverage number + Leverage level value components
>>> mantissa number + Mantissa of the leverage value
>>> exponent number + Exponent of the leverage value

Response

Successfull response sample

{
    "id":19,
    "result":
    {
        "tag":"ok"
    }
}

Successfull response 'result' Object structure:

Parameter Type Description
tag string 'ok' in successfull response

Error response sample

{
  "id":30,
  "result":{
    "tag":"err",
    "value":{
      "code":"NOTIONAL_VALUE_EXCEEDED"
    }
  }
}

Websocket Subscriptions

ZUBR allows public and private information streaming. Every subscriber automatically receives notifications with information from chosen subscriptions. For subscribing please use method 1 and channel name in 'params' Object.

Public channels are available without authentification.

Private channels available for subscription with authentication:

Channel Public Description
orders - Stream with all client's orders activity
orderFills - Stream with all client's fills
lasttrades + Last trades on the market
orderbook + Orderbook updates
balance - Updates of the balances
candles + Japan candles updates stream
riskSettings - Current risk settings
tickers + Instruments daily statistics plus last and mark price
instruments + Instruments statuses and id's

Starting / cancelling subscription procedures

method number '1' to subscribe or '2' to unsubscribe

subscribing on channel request example

{
  "method":1,
  "params":{
    "channel":"instruments"
  },
  "id":123
}

unsubscribing on channel request example

{
  "method":2,
  "params":{
    "channel":"instruments"
  },
  "id":123
}

request structure

Parameter Type Description
method number '1' for stream subscription or '2' for unsubscription
id number Message id
params Object Object with channel name
> channel string Channel name

Response

response example

{
  "id":123,
  "result":{}
}

Subscribing stream response structure

Parameter Type Description
id number Request id
result Object Empty for initial subscription confirmation i.e. '{}'

orders

All information about your orders. Returns snapshot with last orders and their current status and then update information about any orders activity.

orders stream message example

{
  "result": {
    "channel": "orders",
    "data": {
      "tag": "ok",
      "value": {
        "type": "update",
        "payload": {
          "id": 4507947152880376,
          "accountId": 201446346304438,
          "type": "LIMIT",
          "timeInForce": "GTC",
          "side": "BUY",
          "initialSize": 1,
          "remainingSize": 1,
          "price": {
            "mantissa": 6000000000000,
            "exponent": -9
          },
          "status": "CANCELLED",
          "updateTime": {
            "seconds": 1584904876,
            "nanos": 611543320
          },
          "creationTime": {
            "seconds": 1584904876,
            "nanos": 611543320
          },
          "instrument": 1
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'orders'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> type string Type of the payload. 'update' or 'snapshot'
>> payload Object Order or orders information (in case of snapshot)
>>> id number Order number
>>> accountId number Account id
>>> type string Order type: 'LIMIT' or 'POST_ONLY'
>>> timeInForce string Order lifetime parameter. Has three possible options:
'GTC' - good 'til cancelled order, active while not cancelled or executed
'IOC' - immediate or cancel order, un filled part or order immediately canceled
'FOK' - fill or kill order, complete execution or nothing
>>> side string Order direction: 'BUY' or 'SELL'
>>> initialSize number Initial size of the order
>>> remainingSize number Remaining size of the order
>>> price Object Object with 'price' components of the order
>>>> mantissa number Mantissa of the price
>>>> exponent number Exponent of the price
>>> status string Current order status: "FILLED", "CANCELLED" or "PARTIALLY_FILLED"
>>> updateTime Object Last order update time. Object with time components: seconds and nanoseconds
>>>> seconds number Seconds in timestamp. 10 digits
>>>> nanos number Nanoseconds in timestamp. 9 digits
>>> creationTime Object Initial order placing time. Object with time components: seconds and nanoseconds
>>>> seconds number Seconds in timestamp. 10 digits
>>>> nanos number Unix time. Nanoseconds in timestamp. 9 digits
>>> instrument number Instrument id

orderFills

All information about your fills. Returns snapshot with last trades and then informs you about your further order fills.

orderFills stream message example

{
  "result": {
    "channel": "orderFills",
    "data": {
      "tag": "ok",
      "value": {
        "type": "snapshot",
        "payload": [
          {
            "orderId": 4507809713926904,
            "accountId": 201446346304438,
            "tradeId": 4507481205046965,
            "instrument": 1,
            "orderPrice": {
              "mantissa": 6000000000000,
              "exponent": -9
            },
            "tradePrice": {
              "mantissa": 5976272006618,
              "exponent": -9
            },
            "initialQty": 172000,
            "remainingQty": 345,
            "tradeQty": 171655,
            "exchangeFee": {
              "amount": {
                "mantissa": 1,
                "exponent": 0
              },
              "currency": ""
            },
            "brokerFee": {
              "amount": {
                "mantissa": 1,
                "exponent": 0
              },
              "currency": ""
            },
            "time": {
              "seconds": 1584903585,
              "nanos": 972779652
            },
            "side": "BUY"
          },
          ...

        ]
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'orderFills'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> type string Type of the payload. 'update' or 'snapshot'
>> payload List/Object Object with trade information or list with trades objects (in case of snapshot)
>>> orderId number Identifier of the filled order
>>> accountId number Account identifier
>>> tradeId number Trade identifier
>>> orderPrice Object Price components of the filled order
>>>> mantissa number Mantissa of the order price
>>>> exponent number Exponent of the filled order price
>>> tradePrice Object Price components of the trade
>>>> mantissa number Mantissa of the fill price
>>>> exponent number Exponent of the fill price
>>> side string Order direction: 'BUY' or 'SELL'
>>> initialQty number Initial quantity of the order
>>> remainingQty number Remaining quantity of the order
>>> tradeQty number Trade quantity
>>> exchangeFee Object Object with amount and currency of the exchange fee
>>>> amount Object Amount of the exchange fee
>>>>> mantissa number Mantissa of the exchange fee amount
>>>>> exponent number Exponent of the exchange fee amount
>>>> currency string Exchange fee currency name
>>> brokerFee Object Object with amount and currency of the broker fee
>>>> amount Object Amount of the broker fee
>>>>> mantissa number Mantissa of the broker fee amount
>>>>> exponent number Exponent of the broker fee amount
>>>> currency string Broker fee currency name
>>> time Object Object with time components
>>>> seconds number Unix time. Seconds in timestamp. 10 digits
>>>> nanos number Nanoseconds in timestamp. 9 digits

lasttrades

Stream with all market trades.

lasttrades stream message example

{
  "result": {
    "channel": "lasttrades",
    "data": {
      "tag": "ok",
      "value": {
        "type": "trade",
        "payload": {
          "id": 4507025564620420,
          "side": "buy",
          "price": {
            "mantissa": 133400000000,
            "exponent": -9
          },
          "size": 22,
          "time": {
            "seconds": 1584966969,
            "nanos": 983444634
          },
          "instrumentId": 2
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'lasttrades'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> type string Type of the payload. 'trade' or 'snapshot'
>> payload List/Object Object with trade information or list with trades objects (in case of snapshot)
>>> id number Trade identifier
>>> side string Order direction: 'buy' or 'sell'
>>> price Object Object with price components
>>>> mantissa number Mantissa of the price
>>>> exponent number Exponent of the price
>>> time Object Object with time components
>>>> seconds number Unix time. Seconds in timestamp. 10 digits
>>>> nanos number Nanoseconds in timestamp. 9 digits
>>> instrumentId number Instrument identifier

orderbook

Stream with market orderbook data

orderbook stream message example

{
  "result": {
    "channel": "orderbook",
    "data": {
      "tag": "ok",
      "value": {
        "2": {
          "instrumentId": 2,
          "isSnapshot": false,
          "bids": [
            {
              "price": {
                "mantissa": 133250000000,
                "exponent": -9
              },
              "size": 0
            },
            {
              "price": {
                "mantissa": 133800000000,
                "exponent": -9
              },
              "size": 1287
            }
          ],
          "asks": []
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'orderbook'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> (instrumentId) Object Parameter depends on the instrument it presents. Now it's '1', '2' or '3'
>> isSnapshot bool Snapshot flag: false or true
>> bids List List of objects with bids updates
>>> price Object Object with bid price components
>>>> mantissa number Mantissa of the bid price
>>>> exponent number Exponent of the bid price
>>> size number New quantity on price level. Zero if price level doesn't exists anymore or ask now.
>> asks List List of objects with asks updates
>>> price Object Object with ask price components
>>>> mantissa number Mantissa of the ask price
>>>> exponent number Exponent of the ask price
>>> size number New quantity on price level. Zero if price level doesn't exists anymore or bid now.

balance

Stream with client's balance information updates

balance stream message example

{
  "result": {
    "channel": "balance",
    "data": {
      "tag": "ok",
      "value": {
        "type": "update",
        "payload": {
          "accountId": 201446346304438,
          "currency": "BTC",
          "unrealizedPnl": {
            "mantissa": -541715522392,
            "exponent": -9
          },
          "ordersMargin": {
            "mantissa": 0,
            "exponent": 0
          },
          "positionsMargin": {
            "mantissa": 977839412738,
            "exponent": -9
          },
          "wallet": {
            "mantissa": 99409177724026,
            "exponent": -9
          },
          "borrowed": {
            "mantissa": 0,
            "exponent": 0
          },
          "available": {
            "mantissa": 98431338311288,
            "exponent": -9
          },
          "updateTime": {
            "seconds": 1584978966,
            "nanos": 971106479
          }
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'balance'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> type string Message type: 'update' or 'snapshot'
>> payload Object Object with data
>>> accountId number Account identifier
>>> currency string Name of the wallet currency
>>> unrealizedPnl Object Unrealized profit and loss value components
>>>> mantissa number Mantissa of the unrealized PNL value
>>>> exponent number Exponent of the unrealized PNL value
>>> ordersMargin Object Orders margin value components
>>>> mantissa number Mantissa of the orders margin value
>>>> exponent number Exponent of the orders margin value
>>> positionsMargin Object Positions margin value components
>>>> mantissa number Mantissa of the positions margin value
>>>> exponent number Exponent of the positions margin value
>>> wallet Object Wallet value components
>>>> mantissa number Mantissa of the wallet value
>>>> exponent number Exponent of the wallet value
>>> borrowed Object Borrowed balance value components
>>>> mantissa number Mantissa of the borrowed balance value
>>>> exponent number Exponent of the borrowed balance value
>>> available Object Available balance value components
>>>> mantissa number Mantissa of the available balance value
>>>> exponent number Exponent of the available balance value
>>> updateTime Object Object with timestamp components
>>>> seconds number Unix time or number of seconds that have elapsed since the Unix epoch, that is the time 00:00:00 UTC on 1 January 1970
>>>> nanos number Nanoseconds inside the given second

candles

candles stream request example

{
  "method": 1,
  "params": {
    "channel": "candles:1:D"
  },
  "id": 33
}

Stream with Japan candles updates.

Supports few data periods: 1 and 60 minutes and 1 day. The period and instrument you are interested in can be chosen in subscription request. Please use syntax "candles:instrument_id:data_period" and options 1, 60 and D for subscription.

candles stream message example

{
  "result": {
    "channel": "candles:1:D",
    "data": {
      "tag": "ok",
      "value": {
        "time": 1584835200000,
        "close": 5976.272006618,
        "open": 6397,
        "high": 6500,
        "low": 5952.622988333,
        "volume": 237150
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. For example 'candles:1:D' where candles name of the channel, 1 - id number of the instrument and D - candle period
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> time number Unix time in seconds
>> close number Candle close price
>> open number Candle open price
>> high number Candle highest price
>> low number Candle lowest price
>> volume number Volume in current candle

riskSettings

Stream with risk settings updates.

riskSettings stream message example

{
  "result": {
    "channel": "riskSettings",
    "data": {
      "tag": "ok",
      "value": {
        "type": "update",
        "payload": {
          "instrumentId": 1,
          "marginMode": "ISOLATED",
          "leverage": {
            "mantissa": 4300000000,
            "exponent": -9
          },
          "riskLimit": {
            "mantissa": 400000000000,
            "exponent": -9
          },
          "updateTime": {
            "seconds": 1585076696,
            "nanos": 572014715
          }
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
channel string Name of the channel. In current case 'riskSettings'
data Object Object with information
> tag string 'ok' if message is valid
> value Object Object with information
>> type string Message type 'update' or 'snapshot'
>> payload Object Object with information
>>> instrumentId number Instrument identifier
>>> marginMode string Margin mode: 'ISOLATED' or 'CROSS'
>>> leverage Object Components of the leverage value
>>>> mantissa number Mantissa of the leverage value
>>>> exponent number Exponent of the leverage value
>>> riskLimit Object Components of the risk limit value
>>>> mantissa number Mantissa of the orders margin value
>>>> exponent number Exponent of the orders margin value
>>> updateTime Object Components of the exchange timestamp value
>>>> seconds number Unix time in seconds
>>>> nanos number Nanoseconds in given second

tickers

Stream with information about ticker daily statistisc, last trade price and mark price.

tickers stream message example

{
  "result": {
    "channel": "tickers",
    "data": {
      "tag": "ok",
      "value": {
        "1": {
          "id": 1,
          "lastPrice": {
            "mantissa": 6658100000000,
            "exponent": -9
          },
          "priceChange24h": 5.116829872131348,
          "lowPrice24h": {
            "mantissa": 6181000000000,
            "exponent": -9
          },
          "highPrice24h": {
            "mantissa": 6779200000000,
            "exponent": -9
          },
          "volume24h": 11677964,
          "markPrice": {
            "mantissa": 6662000000000,
            "exponent": -9
          }
        }
      }
    }
  }
}

Stream message 'result' Object structure

Parameter Type Description
tag string 'ok' in successfull responce
value Object Object with information
> (instrument id) Object Parameter depends on the instrument it presents. Now it's '1', '2' or '3'
>> id number Instrument identifier
>> lastPrice Object Object with components of the last trade price value
>>> mantissa number Mantissa of the last price value
>>> exponent number Exponent of the last price value
>> priceCharge24h number Value of price move in the last 24 hours in percent
>> lowPrice24h Object Object with components of the lowest price in last 24 hours value
>>> mantissa number Mantissa of the lowest 24h price value
>>> exponent number Exponent of the lowest 24h price value
>> highPrice24h Object Object with components of the highest price in last 24 hours value
>>> mantissa number Mantissa of the highest 24h price value
>>> exponent number Exponent of the highest 24h price value
>> volume24h number Turnover in contracts for last 24 hours
>> markPrice Object Mark price on the instrument
>>> mantissa number Mantissa of the mark price value
>>> exponent number Exponent of the mark price value

instruments

instruments stream message example

{
  "result": {
    "channel": "instruments",
    "data": {
      "tag": "ok",
      "value": {
        "1": {
          "id": 1,
          "symbol": "BTCUSD",
          "currency": "USD",
          "settlementCurrency": "BTC",
          "status": "READY_TO_TRADE",
          "minPriceIncrement": {
            "mantissa": 100000000,
            "exponent": -9
          },
          "contractMultiplier": {
            "mantissa": 0,
            "exponent": 0
          },
          "minPrice": {
            "mantissa": 7076945456600,
            "exponent": -9
          },
          "maxPrice": {
            "mantissa": 6402950651210,
            "exponent": -9
          }
        },
        "2": {
          "id": 2,
          "symbol": "ETHUSD",
          "currency": "USD",
          "settlementCurrency": "BTC",
          "status": "READY_TO_TRADE",
          "minPriceIncrement": {
            "mantissa": 10000000,
            "exponent": -9
          },
          "contractMultiplier": {
            "mantissa": 0,
            "exponent": 0
          },
          "minPrice": {
            "mantissa": 147683195171,
            "exponent": -9
          },
          "maxPrice": {
            "mantissa": 133618128965,
            "exponent": -9
          }
        },
        "3": {
          "id": 3,
          "symbol": "ETHBTC",
          "currency": "BTC",
          "settlementCurrency": "BTC",
          "status": "READY_TO_TRADE",
          "minPriceIncrement": {
            "mantissa": 10000,
            "exponent": -9
          },
          "contractMultiplier": {
            "mantissa": 0,
            "exponent": 0
          },
          "minPrice": {
            "mantissa": 21911542,
            "exponent": -9
          },
          "maxPrice": {
            "mantissa": 19824730,
            "exponent": -9
          }
        }
      }
    }
  }
}
Parameter Type Description
channel string Name of the channel. In current case 'instruments'
data Object Object with information
tag string 'ok' in successfull responce
value Object Object with information
> (instrument id) Object Parameter depends on the instrument it presents. Now it's '1', '2' or '3'
>> id number Instrument identifier
>> symbol string Ticker name
>> currency string Currency of the price value
>> settlementCurrency string Currency of the settlement. Now only 'BTC'
>> status string Current contract status
>> minPriceIncrement Object Object with components of the minimum price increment value
>>> mantissa number Mantissa of the minimum price increment value
>>> exponent number Exponent of the minimum price increment value
>> contractMultiplier Object Object with components of the contract multiplier value
>>> mantissa number Mantissa of the contract multiplier value
>>> exponent number Exponent of the contract multiplier value
>> minPrice Object Object with components of the minimum price increment value
>>> mantissa number Mantissa of the minimum price increment value
>>> exponent number Exponent of the minimum price increment value
>> maxPrice Object Object with components of the maximum price increment value
>>> mantissa number Mantissa of the maximum price increment value
>>> exponent number Exponent of the maximum price increment value