cloud.metaapi.sdk.clients.meta_api

Class MetaApiWebsocketClient

java.lang.Object

cloud.metaapi.sdk.clients.meta_api.MetaApiWebsocketClient

All Implemented Interfaces:

OutOfOrderListener

public class MetaApiWebsocketClient
extends Object
implements OutOfOrderListener

MetaApi websocket API client (see https://metaapi.cloud/docs/client/websocket/overview/)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MetaApiWebsocketClient.ClientOptions Websocket client options
static class	MetaApiWebsocketClient.PacketLoggerOptions Packet logger options

Constructor Summary

Constructors

Constructor and Description
MetaApiWebsocketClient(String token) Constructs MetaApi websocket API client instance with default parameters
MetaApiWebsocketClient(String token, MetaApiWebsocketClient.ClientOptions opts) Constructs MetaApi websocket API client instance

Method Summary

Modifier and Type	Method and Description
void	addLatencyListener(LatencyListener listener) Adds latency listener
void	addReconnectListener(ReconnectListener listener) Adds reconnect listener
void	addSynchronizationListener(String accountId, SynchronizationListener listener) Adds synchronization listener for specific account
void	close() Closes connection to MetaApi server
CompletableFuture<Void>	connect() Connects to MetaApi server via socket.io protocol
CompletableFuture<MetatraderAccountInformation>	getAccountInformation(String accountId) Returns account information for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readAccountInformation/).
CompletableFuture<MetatraderDeals>	getDealsByPosition(String accountId, String positionId) Returns history deals for a specific position id (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByPosition/).
CompletableFuture<MetatraderDeals>	getDealsByTicket(String accountId, String ticket) Returns history deals with a specific ticket number (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByTicket/).
CompletableFuture<MetatraderDeals>	getDealsByTimeRange(String accountId, IsoTime startTime, IsoTime endTime, int offset, int limit) Returns history deals with for a specific time range (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByTimeRange/).
CompletableFuture<MetatraderHistoryOrders>	getHistoryOrdersByPosition(String accountId, String positionId) Returns the history of completed orders for a specific position id (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByPosition/)
CompletableFuture<MetatraderHistoryOrders>	getHistoryOrdersByTicket(String accountId, String ticket) Returns the history of completed orders for a specific ticket number (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByTicket/).
CompletableFuture<MetatraderHistoryOrders>	getHistoryOrdersByTimeRange(String accountId, IsoTime startTime, IsoTime endTime, int offset, int limit) Returns the history of completed orders for a specific time range (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByTimeRange/).
CompletableFuture<MetatraderOrder>	getOrder(String accountId, String orderId) Returns specific open order for a MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrder/).
CompletableFuture<List<MetatraderOrder>>	getOrders(String accountId) Returns open orders for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrders/).
CompletableFuture<MetatraderPosition>	getPosition(String accountId, String positionId) Returns specific position for a MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPosition/).
CompletableFuture<List<MetatraderPosition>>	getPositions(String accountId) Returns positions for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPositions/).
CompletableFuture<MetatraderSymbolPrice>	getSymbolPrice(String accountId, String symbol) Retrieves price for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolPrice/).
CompletableFuture<MetatraderSymbolSpecification>	getSymbolSpecification(String accountId, String symbol) Retrieves specification for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolSpecification/).
void	onOutOfOrderPacket(String accountId, int instanceIndex, long expectedSequenceNumber, long actualSequenceNumber, com.fasterxml.jackson.databind.JsonNode packet, IsoTime receivedAt) Restarts the account synchronization process on an out of order packet
CompletableFuture<Void>	reconnect(String accountId) Reconnects to the Metatrader terminal (see https://metaapi.cloud/docs/client/websocket/api/reconnect/).
void	removeAllListeners() Removes all listeners.
CompletableFuture<Void>	removeApplication(String accountId) Clears the order and transaction history of a specified application and removes the application (see https://metaapi.cloud/docs/client/websocket/api/removeApplication/).
CompletableFuture<Void>	removeHistory(String accountId) Clears the order and transaction history of a specified application so that it can be synchronized from scratch (see https://metaapi.cloud/docs/client/websocket/api/removeHistory/).
CompletableFuture<Void>	removeHistory(String accountId, String application) Clears the order and transaction history of a specified application so that it can be synchronized from scratch (see https://metaapi.cloud/docs/client/websocket/api/removeHistory/).
void	removeLatencyListener(LatencyListener listener) Removes latency listener
void	removeReconnectListener(ReconnectListener listener) Removes reconnect listener
void	removeSynchronizationListener(String accountId, SynchronizationListener listener) Removes synchronization listener for specific account
protected CompletableFuture<com.fasterxml.jackson.databind.JsonNode>	rpcRequest(String accountId, com.fasterxml.jackson.databind.node.ObjectNode request, Long timeoutInSeconds)
CompletableFuture<Void>	saveUptime(String accountId, Map<String,Double> uptime) Sends client uptime stats to the server.
void	setUrl(String url) Patch server URL for use in unit tests
CompletableFuture<Void>	subscribe(String accountId) Subscribes to the Metatrader terminal events (see https://metaapi.cloud/docs/client/websocket/api/subscribe/).
CompletableFuture<Void>	subscribe(String accountId, Integer instanceIndex) Subscribes to the Metatrader terminal events (see https://metaapi.cloud/docs/client/websocket/api/subscribe/).
CompletableFuture<Void>	subscribeToMarketData(String accountId, int instanceIndex, String symbol) Subscribes on market data of specified symbol (see https://metaapi.cloud/docs/client/websocket/marketDataStreaming/subscribeToMarketData/).
CompletableFuture<Void>	synchronize(String accountId, int instanceIndex, String synchronizationId, IsoTime startingHistoryOrderTime, IsoTime startingDealTime) Requests the terminal to start synchronization process (see https://metaapi.cloud/docs/client/websocket/synchronizing/synchronize/).
CompletableFuture<MetatraderTradeResponse>	trade(String accountId, MetatraderTrade trade) Execute a trade on a connected MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<com.fasterxml.jackson.databind.JsonNode>	unsubscribe(String accountId) Unsubscribe from account (see https://metaapi.cloud/docs/client/websocket/api/synchronizing/unsubscribe).
CompletableFuture<Void>	unsubscribeFromMarketData(String accountId, int instanceIndex, String symbol) Unsubscribes from market data of specified symbol (see https://metaapi.cloud/docs/client/websocket/marketDataStreaming/unsubscribeFromMarketData/).
CompletableFuture<Void>	waitSynchronized(String accountId, int instanceIndex, String applicationPattern, Long timeoutInSeconds) Waits for server-side terminal state synchronization to complete.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MetaApiWebsocketClient

public MetaApiWebsocketClient(String token)
                       throws IOException

Constructs MetaApi websocket API client instance with default parameters

Parameters:

token - authorization token

Throws:

IOException - if packet logger is enabled and failed to create the log directory

MetaApiWebsocketClient

public MetaApiWebsocketClient(String token,
                              MetaApiWebsocketClient.ClientOptions opts)
                       throws IOException

Constructs MetaApi websocket API client instance

Parameters:

token - authorization token

opts - websocket client options

Throws:

IOException - if packet logger is enabled and failed to create the log directory

Method Detail

onOutOfOrderPacket

public void onOutOfOrderPacket(String accountId,
                               int instanceIndex,
                               long expectedSequenceNumber,
                               long actualSequenceNumber,
                               com.fasterxml.jackson.databind.JsonNode packet,
                               IsoTime receivedAt)

Restarts the account synchronization process on an out of order packet

Specified by:

onOutOfOrderPacket in interface OutOfOrderListener

Parameters:

accountId - account id

instanceIndex - instance index

expectedSequenceNumber - expected s/n

actualSequenceNumber - actual s/n

packet - packet data

receivedAt - time the packet was received at

setUrl

public void setUrl(String url)

Patch server URL for use in unit tests

Parameters:

url - patched server URL

connect

public CompletableFuture<Void> connect()

Connects to MetaApi server via socket.io protocol

Returns:

completable future which resolves when connection is established

close

public void close()

Closes connection to MetaApi server

getAccountInformation

public CompletableFuture<MetatraderAccountInformation> getAccountInformation(String accountId)

Returns account information for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readAccountInformation/).

Parameters:

accountId - id of the MetaTrader account to return information for

Returns:

completable future resolving with account information

getPositions

public CompletableFuture<List<MetatraderPosition>> getPositions(String accountId)

Returns positions for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPositions/).

Parameters:

accountId - id of the MetaTrader account to return information for

Returns:

completable future resolving with list of open positions

getPosition

public CompletableFuture<MetatraderPosition> getPosition(String accountId,
                                                         String positionId)

Returns specific position for a MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPosition/).

Parameters:

accountId - id of the MetaTrader account to return information for

positionId - position id

Returns:

completable future resolving with MetaTrader position found

getOrders

public CompletableFuture<List<MetatraderOrder>> getOrders(String accountId)

Returns open orders for a specified MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrders/).

Parameters:

accountId - id of the MetaTrader account to return information for

Returns:

completable future resolving with open MetaTrader orders

getOrder

public CompletableFuture<MetatraderOrder> getOrder(String accountId,
                                                   String orderId)

Returns specific open order for a MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrder/).

Parameters:

accountId - id of the MetaTrader account to return information for

orderId - order id (ticket number)

Returns:

completable future resolving with metatrader order found

getHistoryOrdersByTicket

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByTicket(String accountId,
                                                                           String ticket)

Returns the history of completed orders for a specific ticket number (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByTicket/).

Parameters:

accountId - id of the MetaTrader account to return information for

ticket - ticket number (order id)

Returns:

completable future resolving with request results containing history orders found

getHistoryOrdersByPosition

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByPosition(String accountId,
                                                                             String positionId)

Returns the history of completed orders for a specific position id (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByPosition/)

Parameters:

accountId - id of the MetaTrader account to return information for

positionId - position id

Returns:

completable future resolving with request results containing history orders found

getHistoryOrdersByTimeRange

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByTimeRange(String accountId,
                                                                              IsoTime startTime,
                                                                              IsoTime endTime,
                                                                              int offset,
                                                                              int limit)

Returns the history of completed orders for a specific time range (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readHistoryOrdersByTimeRange/).

Parameters:

accountId - id of the MetaTrader account to return information for

startTime - start of time range, inclusive

endTime - end of time range, exclusive

offset - pagination offset

limit - pagination limit

Returns:

completable future resolving with request results containing history orders found

getDealsByTicket

public CompletableFuture<MetatraderDeals> getDealsByTicket(String accountId,
                                                           String ticket)

Returns history deals with a specific ticket number (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByTicket/).

Parameters:

accountId - id of the MetaTrader account to return information for

ticket - ticket number (deal id for MT5 or order id for MT4)

Returns:

completable future resolving with request results containing deals found

getDealsByPosition

public CompletableFuture<MetatraderDeals> getDealsByPosition(String accountId,
                                                             String positionId)

Returns history deals for a specific position id (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByPosition/).

Parameters:

accountId - id of the MetaTrader account to return information for

positionId - position id

Returns:

completable future resolving with request results containing deals found

getDealsByTimeRange

public CompletableFuture<MetatraderDeals> getDealsByTimeRange(String accountId,
                                                              IsoTime startTime,
                                                              IsoTime endTime,
                                                              int offset,
                                                              int limit)

Returns history deals with for a specific time range (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByTimeRange/).

Parameters:

accountId - id of the MetaTrader account to return information for

startTime - start of time range, inclusive

endTime - end of time range, exclusive

offset - pagination offset

limit - pagination limit

Returns:

completable future resolving with request results containing deals found

removeHistory

public CompletableFuture<Void> removeHistory(String accountId)

Clears the order and transaction history of a specified application so that it can be synchronized from scratch (see https://metaapi.cloud/docs/client/websocket/api/removeHistory/).

Parameters:

accountId - id of the MetaTrader account to remove history for

Returns:

completable future resolving when the history is cleared

removeHistory

public CompletableFuture<Void> removeHistory(String accountId,
                                             String application)

Clears the order and transaction history of a specified application so that it can be synchronized from scratch (see https://metaapi.cloud/docs/client/websocket/api/removeHistory/).

Parameters:

accountId - id of the MetaTrader account to remove history for

application - application to remove history for, or null

Returns:

completable future resolving when the history is cleared

removeApplication

public CompletableFuture<Void> removeApplication(String accountId)

Clears the order and transaction history of a specified application and removes the application (see https://metaapi.cloud/docs/client/websocket/api/removeApplication/).

Parameters:

accountId - id of the MetaTrader account to remove history and application for

Returns:

completable future resolving when the history is cleared

trade

public CompletableFuture<MetatraderTradeResponse> trade(String accountId,
                                                        MetatraderTrade trade)

Execute a trade on a connected MetaTrader account (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

accountId - id of the MetaTrader account to execute trade for

trade - trade to execute (see docs for possible trade types)

Returns:

completable future resolving with trade result, or in case of trade error can be completed exceptionally with TradeException, check error properties for error code details

subscribe

public CompletableFuture<Void> subscribe(String accountId)

Subscribes to the Metatrader terminal events (see https://metaapi.cloud/docs/client/websocket/api/subscribe/).

Parameters:

accountId - id of the MetaTrader account to subscribe to

Returns:

completable future which resolves when subscription started

subscribe

public CompletableFuture<Void> subscribe(String accountId,
                                         Integer instanceIndex)

Subscribes to the Metatrader terminal events (see https://metaapi.cloud/docs/client/websocket/api/subscribe/).

Parameters:

accountId - id of the MetaTrader account to subscribe to

instanceIndex - instance index, or null

Returns:

completable future which resolves when subscription started

reconnect

public CompletableFuture<Void> reconnect(String accountId)

Reconnects to the Metatrader terminal (see https://metaapi.cloud/docs/client/websocket/api/reconnect/).

Parameters:

accountId - id of the MetaTrader account to reconnect

Returns:

completable future which resolves when reconnection started

synchronize

public CompletableFuture<Void> synchronize(String accountId,
                                           int instanceIndex,
                                           String synchronizationId,
                                           IsoTime startingHistoryOrderTime,
                                           IsoTime startingDealTime)

Requests the terminal to start synchronization process (see https://metaapi.cloud/docs/client/websocket/synchronizing/synchronize/).

Parameters:

accountId - id of the MetaTrader account to synchronize

instanceIndex - instance index

synchronizationId - synchronization request id

startingHistoryOrderTime - from what date to start synchronizing history orders from. If not specified, the entire order history will be downloaded.

startingDealTime - from what date to start deal synchronization from. If not specified, then all history deals will be downloaded.

Returns:

completable future which resolves when synchronization started

waitSynchronized

public CompletableFuture<Void> waitSynchronized(String accountId,
                                                int instanceIndex,
                                                String applicationPattern,
                                                Long timeoutInSeconds)

Waits for server-side terminal state synchronization to complete. (see https://metaapi.cloud/docs/client/websocket/synchronizing/waitSynchronized/).

Parameters:

accountId - id of the MetaTrader account to synchronize

instanceIndex - instance index

applicationPattern - MetaApi application regular expression pattern, or null, default is .*

timeoutInSeconds - timeout in seconds, or null, default is 300 seconds

Returns:

completable future which resolves when synchronization started

subscribeToMarketData

public CompletableFuture<Void> subscribeToMarketData(String accountId,
                                                     int instanceIndex,
                                                     String symbol)

Subscribes on market data of specified symbol (see https://metaapi.cloud/docs/client/websocket/marketDataStreaming/subscribeToMarketData/).

Parameters:

accountId - id of the MetaTrader account

instanceIndex - instance index

symbol - symbol (e.g. currency pair or an index)

Returns:

completable future which resolves when subscription request was processed

unsubscribeFromMarketData

public CompletableFuture<Void> unsubscribeFromMarketData(String accountId,
                                                         int instanceIndex,
                                                         String symbol)

Unsubscribes from market data of specified symbol (see https://metaapi.cloud/docs/client/websocket/marketDataStreaming/unsubscribeFromMarketData/).

Parameters:

accountId - id of the MetaTrader account

instanceIndex - instance index

symbol - symbol (e.g. currency pair or an index)

Returns:

completable future which resolves when unsubscription request was processed

getSymbolSpecification

public CompletableFuture<MetatraderSymbolSpecification> getSymbolSpecification(String accountId,
                                                                               String symbol)

Retrieves specification for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolSpecification/).

Parameters:

accountId - id of the MetaTrader account to retrieve symbol specification for

symbol - symbol to retrieve specification for

Returns:

completable future resolving with specification retrieved

getSymbolPrice

public CompletableFuture<MetatraderSymbolPrice> getSymbolPrice(String accountId,
                                                               String symbol)

Retrieves price for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolPrice/).

Parameters:

accountId - id of the MetaTrader account to retrieve symbol price for

symbol - symbol to retrieve price for

Returns:

completable future which resolves when price is retrieved

saveUptime

public CompletableFuture<Void> saveUptime(String accountId,
                                          Map<String,Double> uptime)

Sends client uptime stats to the server.

Parameters:

accountId - id of the MetaTrader account to retrieve symbol price for

uptime - uptime statistics to send to the server

Returns:

completable future which resolves when uptime statistics is submitted

unsubscribe

public CompletableFuture<com.fasterxml.jackson.databind.JsonNode> unsubscribe(String accountId)

Unsubscribe from account (see https://metaapi.cloud/docs/client/websocket/api/synchronizing/unsubscribe).

Parameters:

accountId - id of the MetaTrader account to retrieve symbol price for

Returns:

completable future which resolves when socket unsubscribed

addSynchronizationListener

public void addSynchronizationListener(String accountId,
                                       SynchronizationListener listener)

Adds synchronization listener for specific account

Parameters:

accountId - account id

listener - synchronization listener to add

removeSynchronizationListener

public void removeSynchronizationListener(String accountId,
                                          SynchronizationListener listener)

Removes synchronization listener for specific account

Parameters:

accountId - account id

listener - synchronization listener to remove

addLatencyListener

public void addLatencyListener(LatencyListener listener)

Adds latency listener

Parameters:

listener - latency listener to add

removeLatencyListener

public void removeLatencyListener(LatencyListener listener)

Removes latency listener

Parameters:

listener - latency listener to remove

addReconnectListener

public void addReconnectListener(ReconnectListener listener)

Adds reconnect listener

Parameters:

listener - reconnect listener to add

removeReconnectListener

public void removeReconnectListener(ReconnectListener listener)

Removes reconnect listener

Parameters:

listener - listener to remove

removeAllListeners

public void removeAllListeners()

Removes all listeners. Intended for use in unit tests.

rpcRequest

protected CompletableFuture<com.fasterxml.jackson.databind.JsonNode> rpcRequest(String accountId,
                                                                                com.fasterxml.jackson.databind.node.ObjectNode request,
                                                                                Long timeoutInSeconds)