Subscription to market data

This page describes mechanism of receiving market data via websocket

Connection

In order to receive market data, the connection should be opened to wss://sandbox-api.traderevolution.com/traderevolution/v1/stream/quotes.

Please note that the URL specified for connection is default, but it can be customized according to the customer's requirements.

There is a "Ping-Pong" mechanism for WebSocket connections. To maintain active WebSocket connections and detect client inactivity, the following message format is used:

{"event": "PING", "t": 1731538318526}
{"event": "PONG", "t": 1731538318526}

Subscribing to market data

The request body must contain the following parameters:

Body

Name	Type	Description
event	string	Should be always subscribe in this case.
requestId*	integer	Request identifier generated by the client side. Will be used in the response.
payload	object	An object that contains information about the instrument to which the subscription for market data is made, see table below.

Payload object

Parameter	Value
tiId*	The tradable ID of the instrument is specified here.
accountId	This ID is used for determining routes that are available for account. The data will be returned by subscriptions. If this account has no subscriptions to the market data routes, then an error will be in the response.
st*	The subscription type is specified here. The following types are supported: level1, level2, trades, dailyBar, candles.
resolution	This parameter specifies the aggregation type and is required for use with the st = candles only. Available values are: 1m, 5m, 15m, 30m, 1H, 4H, 1D, 1W, 1M. If the parameter is not specified the default value of 1m is used.

Request body example

{
	"event": "subscribe",
	"requestId": 123,
	"payload": {
		"tiId": 22465,
		"accountId": 580,
		"st": "candles",
		"resolution": "5m"
	}
}

Response

The server will return the following parameters in a response:

• event - always returns “subscribe”.

• requestId - id of the request to which the response was sent.

• s - subscription status: ok - if successful, or error - if the subscription failed.

• errmsg - returns an error message in case the subscription fails.

200

{
	"event": "subscribe",
	"requestId": 123,
	"s": "ok"
}

400

Possible errors

errmsg text	Error
Authorization error	All subscription requests must be made after authorization. Otherwise, the following error will be received.
Unsupported event	If an unsupported event is specified in the request, then the following error will be received.
Invalid subscription type	If an unsupported subscription type is specified in the request, then the following error will be received.
Required fields are missing: <parameters>	This error means that some required fields are not specified, with their indication.
Insufficient permissions	If the specified subscription type is not available to the user by permission settings, then this error is received.

Behavior after subscription

For the following subscription types(st), the server immediately sends the latest available data snapshot after a successful subscription:

• level1 – last known quote (best bid/ask)

• level2 – current market depth snapshot

• dailyBar – latest daily OHLC bar

This allows clients to display market data without waiting for the first live update.

For trades and candles, no initial data is sent — updates will arrive only when new trade or candle data is available.

Market data streaming

Level 1

An object with the following parameters will be returned in the response for the subscription to the Level 1 data:

Parameter	Value
d	Considered below in more details.
s	Subscription status indicator: ok or error in case the subscription fails.
errmsg	This parameter contains the text of the error which occurred when s=error.
st	Always returned as level1 for level 1.

Object d structure

Name	Description
ap	ASK
bp	BID
as	ASK volume
bs	BID volume
t	Date/Time in milliseconds (UTC time zone)
tiId	tradableId of the instrument

Response

200

{
	"d": {
		"ap": 140.50,
		"bp": 139.50,
		"as": 10000,
		"bs": 50000,
		"t": 166687337600,
		"tiId": 22462,
	"st": "level1",
	"s": "ok"
	}
}

After subscribing to level1, the server immediately sends the last available quote (if present), even before any new updates are received.

Level 2

Immediately after the subscription, a snapshot of the order book is sent by the server. An object with the following parameters will be returned in the response for the subscription to the Level 2 data:

Parameter	Value
d	Considered below in more details.
s	Subscription status indicator, always ok.
st	Always returned as level2 for level 2.

Object d structure

Name	Description
tiId	tradableId of the instrument.
asks	An array of objects. Each object determines the price level on the ask side. The object contains the following parameters: p - price s - volume t - date/time in milliseconds (UTC time zone) src - source quoteId - position of this quote in the order book
bids	An array of objects. Each object determines the price level on the bid side. The object contains the same parameters as for the ask side.

Response

The response is sorted by the p (price) parameter: for the bid side - in descending order, and for the ask side - in ascending order.

This snapshot is sent immediately after a successful subscription.

Trades

The object with the following parameters will be returned in the response for the subscription to the Trades:

Parameter	Value
d	Considered below in more details.
s	Subscription status indicator:ok or error in case the subscription fails.
errmsg	This parameter contains the text of the error which occurred when s=error.
st	Always returned as trades for level 3.

Object d structure

Name	Description
tiId	tradableId of the instrument
p	Price of the trade
s	Volume of the trade
src	Source of this trade
t	Date/Time in milliseconds (UTC time zone)

Unlike other types, the server does not send a snapshot of the last trade after subscription. New messages will be delivered only when new trades occur.

Daily bar

Only daily bars with the type selected in the Display quotes by setting on the instrument level are sent here. An object with the following parameters will be returned in the response:

Parameter	Value
d	Considered below in more details.
s	Subscription status indicator: ok or error in case the subscription fails.
errmsg	This parameter contains the text of the error which occurred when s=error.
st	Always returned as dailyBar for this type.

Object d structure

Name	Description
tiId	tradableId of the instrument.
o	Bar open price
h	High price
l	Low price
p	Previous close price
v	Volume
t	Date/Time in milliseconds (UTC time zone)

The latest available daily bar is sent immediately after a successful subscription.

Candles

This type of subscription allows subscribing to the aggregated data. The type of aggregation should be specified in the resolution parameter. An object with the following parameters will be returned in the response:

Parameter	Value
d	Considered below in more details.
s	Subscription status indicator: ok or error in case the subscription fails.
errmsg	This parameter contains the text of the error which occurred when s=error.
st	Always returned as candles for this type.
res	Resolution that was received in the request.

Object d structure

Name	Description
tiId	tradableId of the instrument.
o	Bar open price
h	High price
l	Low price
c	Bar close price
v	Volume
T	Number of ticks
t	Date/Time in milliseconds (UTC time zone)

If an access token was expired during the streaming process, the errmsg will contain the Authorization error text.

Unsubscribing from market data

The unsubscribing request stops streaming, its body must contain the following parameters:

Body

Name	Type	Description
event	string	Should be always unsubscribe in this case.
requestId*	integer	Request identifier generated by the client side. Will be used in the response.
payload	object	An object that contains information about the instrument from which the unsubscription is made, see table below.

Payload object

Parameter	Value
tiId*	Tradable ID of the instrument.
accountId	This ID is used for determining routes that are available for account. You can unsubscribe from the required routes only.
st*	The subscription type is specified here. You can unsubscribe from the following types: level1, level2, trades, dailyBar, candles.
resolution	This parameter specifies the aggregation type and should be used with the st = candles only. Available values are: 1m, 5m, 15m, 30m, 1H, 4H, 1D, 1W, 1M. So the unsubscription will be performed for the specified resolution only.

Request body example

{
	"event": "unsubscribe",
	"requestId": 321,
	"payload": {
		"tiId": 33549,
		"accountId": 124,
		"st": "candles",
		"resolution": "1m"
	}
}

Response

The server will return the following parameters in a response:

• event - always returns “unsubscribe”.

• requestId - id of the request to which the response was sent.

• s - unsubscription status: ok - if successful, or error - if the subscription failed.

• errmsg - returns an error message in case the unsubscription fails.

Possible errors

errmsg text	Error
Unsupported event	If an unsupported event is specified in the request, then the following error will be received.
Invalid subscription type	If an unsupported subscription type is specified in the request, then the following error will be received.
Required fields are missing: <parameters>	This error means that some required fields are not specified, with their indication.

Unsubscribing from all market data for an account

It is possible to unsubscribe from all market data subscriptions associated with a specific account by providing only the accountId in the payload, without specifying tiId and st.

Request body example

{
  "event": "unsubscribe",
  "requestId": 555,
  "payload": {
    "accountId": 12345
  }
}

This request will cancel all active market data subscriptions for the specified account.