Package cloud.metaapi.sdk.meta_api

Class MetaApiConnection

java.lang.Object

cloud.metaapi.sdk.clients.meta_api.SynchronizationListener

cloud.metaapi.sdk.meta_api.MetaApiConnection

All Implemented Interfaces:

ReconnectListener

public class MetaApiConnection
extends SynchronizationListener
implements ReconnectListener

Exposes MetaApi MetaTrader API connection to consumers

Constructor Summary

Constructors

Constructor	Description
MetaApiConnection(MetaApiWebsocketClient websocketClient, MetatraderAccount account, HistoryStorage historyStorage, ConnectionRegistry connectionRegistry)	Constructs MetaApi MetaTrader Api connection

Method Summary

Modifier and Type	Method	Description
void	addSynchronizationListener(SynchronizationListener listener)	Adds synchronization listener
CompletableFuture<MetatraderTradeResponse>	cancelOrder(String orderId)	Cancels order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
void	close()	Closes the connection.
CompletableFuture<MetatraderTradeResponse>	closePosition(String positionId, MarketTradeOptions options)	Fully closes a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	closePositionPartially(String positionId, double volume, MarketTradeOptions options)	Partially closes a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	closePositionsBySymbol(String symbol, MarketTradeOptions options)	Closes position by a symbol (see https://metaapi.cloud/docs/client/websocket/api/trade/)
CompletableFuture<MetatraderTradeResponse>	createLimitBuyOrder(String symbol, double volume, double openPrice, Double stopLoss, Double takeProfit, PendingTradeOptions options)	Creates a limit buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	createLimitSellOrder(String symbol, double volume, double openPrice, Double stopLoss, Double takeProfit, PendingTradeOptions options)	Creates a limit sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	createMarketBuyOrder(String symbol, double volume, Double stopLoss, Double takeProfit, MarketTradeOptions options)	Creates a market buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	createMarketSellOrder(String symbol, double volume, Double stopLoss, Double takeProfit, MarketTradeOptions options)	Creates a market sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	createStopBuyOrder(String symbol, double volume, double openPrice, Double stopLoss, Double takeProfit, PendingTradeOptions options)	Creates a stop buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	createStopSellOrder(String symbol, double volume, double openPrice, Double stopLoss, Double takeProfit, PendingTradeOptions options)	Creates a stop sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderAccountInformation>	getAccountInformation()	Returns account information (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readAccountInformation/).
CompletableFuture<MetatraderDeals>	getDealsByPosition(String positionId)	Returns history deals for a specific position id (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByPosition/).
CompletableFuture<MetatraderDeals>	getDealsByTicket(String ticket)	Returns history deals with a specific ticket number (see https://metaapi.cloud/docs/client/websocket/api/retrieveHistoricalData/readDealsByTicket/).
CompletableFuture<MetatraderDeals>	getDealsByTimeRange(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 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 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(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/)
HistoryStorage	getHistoryStorage()	Returns local history storage
CompletableFuture<MetatraderOrder>	getOrder(String orderId)	Returns specific open order (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrder/).
CompletableFuture<List<MetatraderOrder>>	getOrders()	Returns open orders (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrders/).
CompletableFuture<MetatraderPosition>	getPosition(String positionId)	Returns specific position (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPosition/).
CompletableFuture<List<MetatraderPosition>>	getPositions()	Returns positions (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPositions/).
CompletableFuture<MetatraderSymbolPrice>	getSymbolPrice(String symbol)	Retrieves specification for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolPrice/).
CompletableFuture<MetatraderSymbolSpecification>	getSymbolSpecification(String symbol)	Retrieves specification for a symbol (see https://metaapi.cloud/docs/client/websocket/api/retrieveMarketData/getSymbolSpecification/).
TerminalState	getTerminalState()	Returns local copy of terminal state
CompletableFuture<Void>	initialize()	Initializes meta api connection
CompletableFuture<Boolean>	isSynchronized(String synchronizationId)	Returns flag indicating status of state synchronization with MetaTrader terminal
CompletableFuture<MetatraderTradeResponse>	modifyOrder(String orderId, double openPrice, double stopLoss, double takeProfit)	Modifies a pending order (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<MetatraderTradeResponse>	modifyPosition(String positionId, Double stopLoss, Double takeProfit)	Modifies a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).
CompletableFuture<Void>	onConnected()	Invoked when connection to MetaTrader terminal established
CompletableFuture<Void>	onDealSynchronizationFinished(String synchronizationId)	Invoked when a synchronization of history deals on a MetaTrader account have finished
CompletableFuture<Void>	onDisconnected()	Invoked when connection to MetaTrader terminal terminated
CompletableFuture<Void>	onOrderSynchronizationFinished(String synchronizationId)	Invoked when a synchronization of history orders on a MetaTrader account have finished
CompletableFuture<Void>	onReconnected()	Invoked when connection to MetaTrader terminal re-established
CompletableFuture<Void>	reconnect()	Reconnects to the Metatrader terminal (see https://metaapi.cloud/docs/client/websocket/api/reconnect/).
CompletableFuture<Void>	removeHistory()	Clears the order and transaction history of a specified account so that it can be synchronized from scratch (see https://metaapi.cloud/docs/client/websocket/api/removeHistory/).
void	removeSynchronizationListener(SynchronizationListener listener)	Removes synchronization listener for specific account
CompletableFuture<Void>	subscribe()	Initiates subscription to MetaTrader terminal
CompletableFuture<Void>	subscribeToMarketData(String symbol)	Subscribes on market data of specified symbol (see https://metaapi.cloud/docs/client/websocket/marketDataStreaming/subscribeToMarketData/).
CompletableFuture<Void>	synchronize()	Requests the terminal to start synchronization process (see https://metaapi.cloud/docs/client/websocket/synchronizing/synchronize/)
CompletableFuture<Void>	waitSynchronized()	Waits until synchronization to MetaTrader terminal is completed.
CompletableFuture<Void>	waitSynchronized(String synchronizationId)	Waits until synchronization to MetaTrader terminal is completed.
CompletableFuture<Void>	waitSynchronized(String synchronizationId, Integer timeoutInSeconds, Integer intervalInMilliseconds)	Waits until synchronization to MetaTrader terminal is completed.

Methods inherited from class cloud.metaapi.sdk.clients.meta_api.SynchronizationListener

onAccountInformationUpdated, onBrokerConnectionStatusChanged, onDealAdded, onHistoryOrderAdded, onOrderCompleted, onOrderUpdated, onPositionRemoved, onPositionUpdated, onSymbolPriceUpdated, onSymbolSpecificationUpdated

Methods inherited from class java.lang.Object

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

Constructor Detail

MetaApiConnection

public MetaApiConnection(MetaApiWebsocketClient websocketClient,
                         MetatraderAccount account,
                         HistoryStorage historyStorage,
                         ConnectionRegistry connectionRegistry)

Constructs MetaApi MetaTrader Api connection

Parameters:

websocketClient - MetaApi websocket client

account - MetaTrader account to connect to

historyStorage - terminal history storage or null. By default an instance of MemoryHistoryStorage will be used.

connectionRegistry - metatrader account connection registry

Method Detail

getAccountInformation

public CompletableFuture<MetatraderAccountInformation> getAccountInformation()

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

getPositions

public CompletableFuture<List<MetatraderPosition>> getPositions()

Returns positions (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readPositions/).

getPosition

public CompletableFuture<MetatraderPosition> getPosition(String positionId)

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

Parameters:

positionId - position id

Returns:

completable future resolving with MetaTrader position found

getOrders

public CompletableFuture<List<MetatraderOrder>> getOrders()

Returns open orders (see https://metaapi.cloud/docs/client/websocket/api/readTradingTerminalState/readOrders/).

Returns:

completable future resolving with open MetaTrader orders

getOrder

public CompletableFuture<MetatraderOrder> getOrder(String orderId)

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

Parameters:

orderId - order id (ticket number)

Returns:

completable future resolving with metatrader order found

getHistoryOrdersByTicket

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByTicket(String ticket)

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

Parameters:

ticket - ticket number (order id)

getHistoryOrdersByPosition

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByPosition(String positionId)

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

Parameters:

positionId - position id

getHistoryOrdersByTimeRange

public CompletableFuture<MetatraderHistoryOrders> getHistoryOrdersByTimeRange(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:

startTime - start of time range, inclusive

endTime - end of time range, exclusive

offset - pagination offset

limit - pagination limit

getDealsByTicket

public CompletableFuture<MetatraderDeals> getDealsByTicket(String ticket)

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

Parameters:

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

getDealsByPosition

public CompletableFuture<MetatraderDeals> getDealsByPosition(String positionId)

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

Parameters:

positionId - position id

getDealsByTimeRange

public CompletableFuture<MetatraderDeals> getDealsByTimeRange(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:

startTime - start of time range, inclusive

endTime - end of time range, exclusive

offset - pagination offset

limit - pagination limit

removeHistory

public CompletableFuture<Void> removeHistory()

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

Returns:

completable future resolving when the history is cleared

createMarketBuyOrder

public CompletableFuture<MetatraderTradeResponse> createMarketBuyOrder(String symbol,
                                                                       double volume,
                                                                       Double stopLoss,
                                                                       Double takeProfit,
                                                                       MarketTradeOptions options)

Creates a market buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

createMarketSellOrder

public CompletableFuture<MetatraderTradeResponse> createMarketSellOrder(String symbol,
                                                                        double volume,
                                                                        Double stopLoss,
                                                                        Double takeProfit,
                                                                        MarketTradeOptions options)

Creates a market sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

createLimitBuyOrder

public CompletableFuture<MetatraderTradeResponse> createLimitBuyOrder(String symbol,
                                                                      double volume,
                                                                      double openPrice,
                                                                      Double stopLoss,
                                                                      Double takeProfit,
                                                                      PendingTradeOptions options)

Creates a limit buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

openPrice - order limit price

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

createLimitSellOrder

public CompletableFuture<MetatraderTradeResponse> createLimitSellOrder(String symbol,
                                                                       double volume,
                                                                       double openPrice,
                                                                       Double stopLoss,
                                                                       Double takeProfit,
                                                                       PendingTradeOptions options)

Creates a limit sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

openPrice - order limit price

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

createStopBuyOrder

public CompletableFuture<MetatraderTradeResponse> createStopBuyOrder(String symbol,
                                                                     double volume,
                                                                     double openPrice,
                                                                     Double stopLoss,
                                                                     Double takeProfit,
                                                                     PendingTradeOptions options)

Creates a stop buy order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

openPrice - order stop price

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

createStopSellOrder

public CompletableFuture<MetatraderTradeResponse> createStopSellOrder(String symbol,
                                                                      double volume,
                                                                      double openPrice,
                                                                      Double stopLoss,
                                                                      Double takeProfit,
                                                                      PendingTradeOptions options)

Creates a stop sell order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

symbol - symbol to trade

volume - order volume

openPrice - order stop price

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

options - optional trade options or null

modifyPosition

public CompletableFuture<MetatraderTradeResponse> modifyPosition(String positionId,
                                                                 Double stopLoss,
                                                                 Double takeProfit)

Modifies a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

positionId - position id to modify

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

closePositionPartially

public CompletableFuture<MetatraderTradeResponse> closePositionPartially(String positionId,
                                                                         double volume,
                                                                         MarketTradeOptions options)

Partially closes a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

positionId - position id to modify

volume - volume to close

options - optional trade options or null

closePosition

public CompletableFuture<MetatraderTradeResponse> closePosition(String positionId,
                                                                MarketTradeOptions options)

Fully closes a position (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

positionId - position id to modify

options - optional trade options or null

closePositionsBySymbol

public CompletableFuture<MetatraderTradeResponse> closePositionsBySymbol(String symbol,
                                                                         MarketTradeOptions options)

Closes position by a symbol (see https://metaapi.cloud/docs/client/websocket/api/trade/)

Parameters:

symbol - symbol to trade

options - optional trade options or null

modifyOrder

public CompletableFuture<MetatraderTradeResponse> modifyOrder(String orderId,
                                                              double openPrice,
                                                              double stopLoss,
                                                              double takeProfit)

Modifies a pending order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

orderId - order id (ticket number)

openPrice - order stop price

stopLoss - optional stop loss price or null

takeProfit - optional take profit price or null

cancelOrder

public CompletableFuture<MetatraderTradeResponse> cancelOrder(String orderId)

Cancels order (see https://metaapi.cloud/docs/client/websocket/api/trade/).

Parameters:

orderId - order id (ticket number)

reconnect

public CompletableFuture<Void> reconnect()

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

synchronize

public CompletableFuture<Void> synchronize()

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

initialize

public CompletableFuture<Void> initialize()

Initializes meta api connection

Returns:

completable future which resolves when meta api connection is initialized

subscribe

public CompletableFuture<Void> subscribe()

Initiates subscription to MetaTrader terminal

subscribeToMarketData

public CompletableFuture<Void> subscribeToMarketData(String symbol)

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

Parameters:

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

getSymbolSpecification

public CompletableFuture<MetatraderSymbolSpecification> getSymbolSpecification(String symbol)

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

Parameters:

symbol - symbol to retrieve specification for

getSymbolPrice

public CompletableFuture<MetatraderSymbolPrice> getSymbolPrice(String symbol)

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

Parameters:

symbol - symbol to retrieve price for

getTerminalState

public TerminalState getTerminalState()

Returns local copy of terminal state

getHistoryStorage

public HistoryStorage getHistoryStorage()

Returns local history storage

addSynchronizationListener

public void addSynchronizationListener(SynchronizationListener listener)

Adds synchronization listener

Parameters:

listener - synchronization listener to add

removeSynchronizationListener

public void removeSynchronizationListener(SynchronizationListener listener)

Removes synchronization listener for specific account

Parameters:

listener - synchronization listener to remove

onConnected

public CompletableFuture<Void> onConnected()

Description copied from class: SynchronizationListener

Invoked when connection to MetaTrader terminal established

Overrides:

onConnected in class SynchronizationListener

Returns:

completable future which resolves when the asynchronous event is processed

onDisconnected

public CompletableFuture<Void> onDisconnected()

Description copied from class: SynchronizationListener

Invoked when connection to MetaTrader terminal terminated

Overrides:

onDisconnected in class SynchronizationListener

Returns:

completable future which resolves when the asynchronous event is processed

onDealSynchronizationFinished

public CompletableFuture<Void> onDealSynchronizationFinished(String synchronizationId)

Description copied from class: SynchronizationListener

Invoked when a synchronization of history deals on a MetaTrader account have finished

Overrides:

onDealSynchronizationFinished in class SynchronizationListener

Parameters:

synchronizationId - synchronization request id

Returns:

completable future which resolves when the asynchronous event is processed

onOrderSynchronizationFinished

public CompletableFuture<Void> onOrderSynchronizationFinished(String synchronizationId)

Description copied from class: SynchronizationListener

Invoked when a synchronization of history orders on a MetaTrader account have finished

Overrides:

onOrderSynchronizationFinished in class SynchronizationListener

Parameters:

synchronizationId - synchronization request id

Returns:

completable future which resolves when the asynchronous event is processed

onReconnected

public CompletableFuture<Void> onReconnected()

Description copied from interface: ReconnectListener

Invoked when connection to MetaTrader terminal re-established

Specified by:

onReconnected in interface ReconnectListener

Returns:

completable future which resolves when the asynchronous event is processed

isSynchronized

public CompletableFuture<Boolean> isSynchronized(String synchronizationId)

Returns flag indicating status of state synchronization with MetaTrader terminal

Parameters:

synchronizationId - optional synchronization request id, last synchronization request id will be used by default

Returns:

completable future resolving with a flag indicating status of state synchronization with MetaTrader terminal

waitSynchronized

public CompletableFuture<Void> waitSynchronized()

Waits until synchronization to MetaTrader terminal is completed. Completes exceptionally with TimeoutError if application failed to synchronize with the teminal withing timeout allowed. Last synchronization request id will be used as synchronization id. Wait timeout in seconds is 5m and interval between account reloads while waiting for a change is 1s.

Returns:

completable future which resolves when synchronization to MetaTrader terminal is completed

waitSynchronized

public CompletableFuture<Void> waitSynchronized(String synchronizationId)

Waits until synchronization to MetaTrader terminal is completed. Completes exceptionally with TimeoutError if application failed to synchronize with the teminal withing timeout allowed. Wait timeout in seconds is 5m and interval between account reloads while waiting for a change is 1s.

Parameters:

synchronizationId - optional synchronization id, last synchronization request id will be used by default

Returns:

completable future which resolves when synchronization to MetaTrader terminal is completed

waitSynchronized

public CompletableFuture<Void> waitSynchronized(String synchronizationId,
                                                Integer timeoutInSeconds,
                                                Integer intervalInMilliseconds)

Waits until synchronization to MetaTrader terminal is completed. Completes exceptionally with TimeoutError if application failed to synchronize with the teminal withing timeout allowed.

Parameters:

synchronizationId - optional synchronization id, last synchronization request id will be used by default

timeoutInSeconds - optional wait timeout in seconds, default is 5m

intervalInMilliseconds - optional interval between account reloads while waiting for a change, default is 1s

Returns:

completable future which resolves when synchronization to MetaTrader terminal is completed

close

public void close()

Closes the connection. The instance of the class should no longer be used after this method is invoked.