Open stream for the account

Error while loading OpenAPI operation — Invalid OpenAPI document

Parameters Upgrade andCoonection are the standard options for working with web sockets. Together, these options allow the client and server to establish a Web Sockets connection.

In our case, the value Connection: Upgradein the request and response headers is a signal to change the protocol from standard HTTP to the web socket protocol and Upgrade: websocket.

Features of working with open stream

Streaming connection: impormant to make ping request each 30 sec.

While opening open stream you should specify the query parameter as stream-auth (header Authorization in stream will be ignored).

1. If header Authorization is specified and server_code, but query parameter stream-auth is not specified, the authorization will not be succeed:

Handshake Details
Request URL: https://{{HOST}}/api/v2/fxtr/stream?server_code=mt5_trial1
Request Method: GET
Status Code: 422 Unprocessable Entity

Request Headers
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: {{WS_KEY}}
Connection: Upgrade
Upgrade: websocket
Authorization: Bearer eyJ0eXAiOi...jxcohLWGgbw
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Host: {{HOST}}

Response Headers
Date: Tue, 20 Jun 2023 06:24:45 GMT
Content-Type: application/json
Content-Length: 57
Connection: keep-alive

1. When the header and the query parameter are specified both, when authorization will succeed:

Handshake Details
Request URL: https://{{HOST}}/api/v2/fxtr/stream?server_code=mt5_trial1&stream-auth=eyJ0eXAiOi...jxcohLWGgbw
Request Method: GET
Status Code: 101 Switching Protocols

Request Headers
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: {{WS_KEY}}
Connection: Upgrade
Upgrade: websocket
Authorization: Bearer eyJ0eXAiOi...jxcohLWGgbw
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Host: {{HOST}}

Response Headers
Date: Tue, 20 Jun 2023 06:26:33 GMT
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: {{WS_ACCEPT}}

1. When opening stream query parameter is specified but header is not specified, when authorization will also succeed:

Handshake Details
Request URL: https://{{HOST}}/api/v2/fxtr/stream?server_code=mt5_trial1&stream-auth=eyJ0eXAiOi...jxcohLWGgbw
Request Method: GET
Status Code: 101 Switching Protocols

Request Headers
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: {{WS_KEY}}
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Host: {{HOST}}

Response Headers
Date: Tue, 20 Jun 2023 06:29:47 GMT
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: {{WS_ACCEPT}}

1. If authorization is not specified at all, you will get error = 401:

Handshake Details
Request URL: https://{{HOST}}/api/v2/fxtr/stream?server_code=mt5_trial1
Request Method: GET
Status Code: 401 Unauthorized

Request Headers
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: {{WS_KEY}}
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Host: {{HOST}}

Response Headers
Date: Tue, 20 Jun 2023 06:34:56 GMT
Content-Type: application/json
Content-Length: 64
Connection: keep-alive

WebSocket request format is a JSON structure with the following fields:

Key	Type	Description
id	big integer	unique identification of message the will be used in an asynchronous responce to the request
type	string	a request type, defined in below section
body	JSON structure	contains a set of fields/parameters for the request execution

example 1. with empty body:

{"id": 11, "type":"GetServerTime", "body": {}}

example 2. Subscription to ticks:

{"id": 11, "type":"TicksSubscribe", "body": {"symbol":"EURUSD.s"}}

Webscoket response structure

Key	Type	Description
id	big integer [optional]	a unique identification of the message that was specified in the request doesn’t used in subscriptions messages
type	string	a responce type, defined in below section
body	JSON structure	contains a set of fields/values returning after a request execution or in subscription messages

Example 1:

request:{"id": 11, "type":"GetServerTime", "body": {}}

responce:  {"type": "Time", "id":11, "body": {"time":1686296926114}}

Example 2. Subscription to ticks:

request: {"id": 11, "type":"TicksSubscribe", "body": {"symbol":"EURUSD.s"}}

response: {"type": "TicksSubscribe", "id":11, "body": {"symbol": "EURUSD.s"}}

subscritption: {"type": "Tick", "body": {"symbol":"EURUSD.s", "time":1686296999397, "bid":1.07668,"ask":1.07688,"rate_to_account_currency":1}}

In case of an error during a request execution the body of the responce include only two fields:

• code - an integer code of the error from the MetaTrader Server if the code > 0 otherwise a system error code;

• message - a string with error description.

Also the response will have an object “error” with the following fields:

• code - an integer code of the error from the MetaTrader Server if the code > 0 otherwise a system error code

• message - a string with error description

Example:

request: {"id": 11, "type":"CloseOrder", "body": {"ticket":969016, "volume": 0.01, "deviation": 100}}

response: {"id": 11, "type": "CloseOrder", "body": {"code":10036, "message":"Position doesn't exist"}, "error": {"code": 10036, "message": "unknown MT5 error"}}

The following errors can be generated by the system:

Code	Description
-1	when the requested type is not supported
-2	when the system throttles recieved message due to number of requests more then expected number of requests in a second
-3	when the system removes a message from the message queue due to big number unprocessed messages in the message queue
-9	timeout when the system did not get a responce from MT5 in expected timefrime specifically for acynchronus request for open/close/midification positions
-10017	Trade (for client) is disabled
-10018	Market closed (open/modificaion/close trade is not allowed)

Errors from MetaTrader

Constant	Value
MT_RET_ERROR	2	Common error.
MT_RET_ERR_PARAMS	3	Invalid parameters.
MT_RET_ERR_DATA	4	Invalid information.
MT_RET_ERR_DISK	5	Hard disk error.
MT_RET_ERR_MEM	6	Memory error.
MT_RET_ERR_NETWORK	7	Network error.
MT_RET_ERR_PERMISSIONS	8	Not enough permissions to perform the operation.
MT_RET_ERR_TIMEOUT	9	Timeout expired.
MT_RET_ERR_CONNECTION	10	No connection.
MT_RET_ERR_NOSERVICE	11	Service is not available.
MT_RET_ERR_FREQUENT	12	Too frequent requests.
MT_RET_ERR_NOTFOUND	13	Not found.
MT_RET_ERR_PARTIAL	14	Partial error.
MT_RET_ERR_SHUTDOWN	15	Server shutdown in progress.
MT_RET_ERR_CANCEL	16	The operation has been canceled.
MT_RET_ERR_DUPLICATE	17	Duplicate information.