metaapi.cloud-sdk
Version:
SDK for MetaApi, a professional cloud forex API which includes MetaTrader REST API and MetaTrader websocket API. Supports both MetaTrader 5 (MT5) and MetaTrader 4 (MT4). CopyFactory copy trading API included. (https://metaapi.cloud)
1,072 lines (1,012 loc) • 109 kB
text/typescript
'use strict';
import randomstring from 'randomstring';
import socketIO from 'socket.io-client';
import TimeoutError from '../timeoutError';
import {ValidationError, NotFoundError, InternalError, UnauthorizedError, TooManyRequestsError, ForbiddenError}
from '../errorHandler';
import OptionsValidator from '../optionsValidator';
import NotSynchronizedError from './notSynchronizedError';
import NotConnectedError from './notConnectedError';
import TradeError from './tradeError';
import PacketOrderer from './packetOrderer';
import SynchronizationThrottler from './synchronizationThrottler';
import SubscriptionManager from './subscriptionManager';
import LoggerManager from '../../logger';
import any from 'promise.any';
import LatencyService from './latencyService';
import {MetatraderSymbolSpecification} from './metaApiWebsocket.client.schemas';
import MetatraderAccount from '../../metaApi/metatraderAccount';
import DomainClient from '../domain.client';
import _ from 'lodash';
export * from './metaApiWebsocket.client.schemas';
let PacketLogger;
if (typeof window === 'undefined') { // don't import PacketLogger for browser version
PacketLogger = require('./packetLogger').default;
}
/**
* MetaApi websocket API client (see https://metaapi.cloud/docs/client/websocket/overview/)
*/
class MetaApiWebsocketClient {
private _domainClient: DomainClient;
private _application: any;
private _domain: any;
private _region: any;
private _hostname: string;
private _metaApi: any;
private _url: null;
private _requestTimeout: number;
private _connectTimeout: number;
private _retries: any;
private _minRetryDelayInSeconds: any;
private _maxRetryDelayInSeconds: any;
private _maxAccountsPerInstance: number;
private _subscribeCooldownInSeconds: any;
private _sequentialEventProcessing: boolean;
private _useSharedClientApi: any;
private _unsubscribeThrottlingInterval: number;
private _socketMinimumReconnectTimeout: number;
private _latencyService: LatencyService;
private _token: any;
private _synchronizationListeners: {};
private _latencyListeners: any[];
private _reconnectListeners: any[];
private _connectedHosts: {};
private _socketInstances: SocketInstances = {};
private _socketInstancesByAccounts: {[instanceNumber: number]: {[accountId: string]: number}} = {};
private _regionsByAccounts: RegionsByAccounts = {};
private _accountsByReplicaId: MetaApiWebsocketClient.AccountsByReplica = {};
private _accountReplicas: MetaApiWebsocketClient.AccountReplicas = {};
private _synchronizationThrottlerOpts: any;
private _subscriptionManager: any;
private _statusTimers: {};
private _eventQueues: {[accountId: string]: Array<() => Promise<any>>} = {};
private _synchronizationFlags: {[synchronizationId: string]: SynchronizationFlag} = {};
private _synchronizationIdByInstance: {};
private _subscribeLock: any;
private _firstConnect: boolean;
private _lastRequestsTime: {};
private _packetOrderer: PacketOrderer;
private _synchronizationHashes: {};
private _updateEvents: {[instanceId: string]: Packet[]} = {};
private _packetLogger: any;
private _logger: any;
private _clearAccountCacheInterval: NodeJS.Timeout;
private _clearInactiveSyncDataInterval: NodeJS.Timeout;
/**
* @typedef MetaApiWebsocketClientOptions MetaApi websocket client options
* @property {string} [region] region to connect
* @property {Boolean} [disableInternalJobs] whether to not run internal interval jobs. Used for tests only
*/
/**
* Constructs MetaApi websocket API client instance
* @param {MetaApi} metaApi metaApi instance
* @param {DomainClient} domainClient domain client
* @param {String} token authorization token
* @param {MetaApiWebsocketClientOptions} opts websocket client options
*/
// eslint-disable-next-line complexity,max-statements
constructor(metaApi, domainClient, token, opts) {
const validator = new OptionsValidator();
opts = opts || {};
opts.packetOrderingTimeout = validator.validateNonZero(opts.packetOrderingTimeout, 60, 'packetOrderingTimeout');
opts.synchronizationThrottler = opts.synchronizationThrottler || {};
this._domainClient = domainClient;
this._application = opts.application || 'MetaApi';
this._domain = opts.domain || 'agiliumtrade.agiliumtrade.ai';
this._region = opts.region;
this._hostname = 'mt-client-api-v1';
this._metaApi = metaApi;
this._url = null;
this._requestTimeout = validator.validateNonZero(opts.requestTimeout, 60, 'requestTimeout') * 1000;
this._connectTimeout = validator.validateNonZero(opts.connectTimeout, 60, 'connectTimeout') * 1000;
const retryOpts = opts.retryOpts || {};
this._retries = validator.validateNumber(retryOpts.retries, 5, 'retryOpts.retries');
this._minRetryDelayInSeconds = validator.validateNonZero(retryOpts.minDelayInSeconds, 1,
'retryOpts.minDelayInSeconds');
this._maxRetryDelayInSeconds = validator.validateNonZero(retryOpts.maxDelayInSeconds, 30,
'retryOpts.maxDelayInSeconds');
this._maxAccountsPerInstance = 100;
this._subscribeCooldownInSeconds = validator.validateNonZero(retryOpts.subscribeCooldownInSeconds, 600,
'retryOpts.subscribeCooldownInSeconds');
this._sequentialEventProcessing = true;
this._useSharedClientApi = validator.validateBoolean(opts.useSharedClientApi, false, 'useSharedClientApi');
this._unsubscribeThrottlingInterval = validator.validateNonZero(opts.unsubscribeThrottlingIntervalInSeconds, 10,
'unsubscribeThrottlingIntervalInSeconds') * 1000;
this._socketMinimumReconnectTimeout = 500;
this._latencyService = new LatencyService(this, token, this._connectTimeout);
this._token = token;
this._synchronizationListeners = {};
this._latencyListeners = [];
this._reconnectListeners = [];
this._connectedHosts = {};
this._synchronizationThrottlerOpts = opts.synchronizationThrottler;
this._subscriptionManager = new SubscriptionManager(this, metaApi);
this._statusTimers = {};
this._synchronizationIdByInstance = {};
this._subscribeLock = null;
this._firstConnect = true;
this._lastRequestsTime = {};
this._packetOrderer = new PacketOrderer(this, opts.packetOrderingTimeout);
this._packetOrderer.start();
this._synchronizationHashes = {};
if (opts.packetLogger && opts.packetLogger.enabled) {
this._packetLogger = new PacketLogger(opts.packetLogger);
this._packetLogger.start();
}
this._logger = LoggerManager.getLogger('MetaApiWebsocketClient');
if (!opts.disableInternalJobs) {
this._clearAccountCacheInterval = setInterval(this._clearAccountCacheJob.bind(this), 30 * 60 * 1000);
this._clearInactiveSyncDataInterval = setInterval(this._clearInactiveSyncDataJob.bind(this), 5 * 60 * 1000);
}
}
/**
* Restarts the account synchronization process on an out of order packet
* @param {String} accountId account id
* @param {Number} instanceIndex instance index
* @param {Number} expectedSequenceNumber expected s/n
* @param {Number} actualSequenceNumber actual s/n
* @param {Object} packet packet data
* @param {Date} receivedAt time the packet was received at
*/
onOutOfOrderPacket(accountId, instanceIndex, expectedSequenceNumber, actualSequenceNumber, packet, receivedAt) {
const primaryAccountId = this._accountsByReplicaId[accountId];
if (this._subscriptionManager.isSubscriptionActive(accountId)) {
const level = this._latencyService.getSynchronizedAccountInstances(primaryAccountId).length ? 'debug' : 'error';
this._logger[level]('MetaApi websocket client received an out of order ' +
`packet type ${packet.type} for account id ${accountId}:${instanceIndex}. Expected s/n ` +
`${expectedSequenceNumber} does not match the actual of ${actualSequenceNumber}`);
this.ensureSubscribe(accountId, instanceIndex);
}
}
/**
* Patch server URL for use in unit tests
* @param {String} url patched server URL
*/
set url(url) {
this._url = url;
}
/**
* Websocket client predefined region
* @returns {String} predefined region
*/
get region() {
return this._region;
}
/**
* Returns the list of socket instance dictionaries
* @return {Object[]} list of socket instance dictionaries
*/
get socketInstances() {
return this._socketInstances;
}
/**
* Returns the dictionary of socket instances by account ids
* @return {Object} dictionary of socket instances by account ids
*/
get socketInstancesByAccounts() {
return this._socketInstancesByAccounts;
}
/**
* Returns the dictionary of account replicas by region
* @return {Object} dictionary of account replicas by region
*/
get accountReplicas(): MetaApiWebsocketClient.AccountReplicas {
return this._accountReplicas;
}
/**
* Returns the dictionary of primary account ids by replica ids
* @return {Object} dictionary of primary account ids by replica ids
*/
get accountsByReplicaId(): MetaApiWebsocketClient.AccountsByReplica {
return this._accountsByReplicaId;
}
/**
* Returns clear account cache job. Used for tests
* @return {Function} clear account cache job
*/
get clearAccountCacheJob() {
return this._clearAccountCacheJob.bind(this);
}
/**
* Returns latency service
* @returns {LatencyService} latency service
*/
get latencyService() {
return this._latencyService;
}
/**
* Returns the list of subscribed account ids
* @param {Number} instanceNumber instance index number
* @param {String} socketInstanceIndex socket instance index
* @param {String} region server region
* @return {string[]} list of subscribed account ids
*/
subscribedAccountIds(instanceNumber, socketInstanceIndex, region) {
const connectedIds = [];
if (this._socketInstancesByAccounts[instanceNumber]) {
Object.keys(this._connectedHosts).forEach(instanceId => {
const accountId = instanceId.split(':')[0];
const accountRegion = this.getAccountRegion(accountId);
if (!connectedIds.includes(accountId) &&
this._socketInstancesByAccounts[instanceNumber][accountId] !== undefined && (
this._socketInstancesByAccounts[instanceNumber][accountId] === socketInstanceIndex ||
socketInstanceIndex === undefined) && accountRegion === region) {
connectedIds.push(accountId);
}
});
}
return connectedIds;
}
/**
* Returns websocket client connection status
* @param {Number} instanceNumber instance index number
* @param {Number} socketInstanceIndex socket instance index
* @param {String} region server region
* @returns {Boolean} websocket client connection status
*/
connected(instanceNumber, socketInstanceIndex, region) {
const instance = this._socketInstances[region] &&
this._socketInstances[region][instanceNumber].length > socketInstanceIndex ?
this._socketInstances[region][instanceNumber][socketInstanceIndex] : null;
return (instance && instance.socket && instance.socket.connected) || false;
}
/**
* Returns list of accounts assigned to instance
* @param {Number} instanceNumber instance index number
* @param {String} socketInstanceIndex socket instance index
* @param {String} region server region
* @returns
*/
private _getAssignedAccounts(instanceNumber, socketInstanceIndex, region) {
const accountIds = [];
Object.keys(this._socketInstancesByAccounts[instanceNumber]).forEach(key => {
const accountRegion = this.getAccountRegion(key);
if (accountRegion === region &&
this._socketInstancesByAccounts[instanceNumber][key] === socketInstanceIndex) {
accountIds.push(key);
}
});
return accountIds;
}
/**
* Returns account region by id
* @param {String} accountId account id
* @returns {String} account region
*/
getAccountRegion(accountId) {
return this._regionsByAccounts[accountId] && this._regionsByAccounts[accountId].region;
}
/**
* Adds account cache info
* @param {String} accountId account id
* @param {Object} replicas account replicas, including primary replica
*/
addAccountCache(accountId: string, replicas: MetatraderAccount.AccountsByRegion) {
this._accountReplicas[accountId] = replicas;
Object.keys(replicas).forEach(region => {
const replicaId = replicas[region];
if (!this._regionsByAccounts[replicaId]) {
this._regionsByAccounts[replicaId] = {
region,
connections: 1,
lastUsed: Date.now()
};
} else {
this._regionsByAccounts[replicaId].connections++;
}
this._accountsByReplicaId[replicaId] = accountId;
});
this._logger.debug(`${accountId}: added account cache`);
}
/**
* Updates account cache info
* @param {String} accountId account id
* @param {Object} replicas account replicas
*/
updateAccountCache(accountId: string, replicas: MetatraderAccount.AccountsByRegion) {
const oldReplicas = this._accountReplicas[accountId];
if (oldReplicas) {
const connectionCount = this._regionsByAccounts[accountId].connections;
Object.keys(oldReplicas).forEach(region => {
const replicaId = replicas[region];
delete this._accountsByReplicaId[replicaId];
delete this._regionsByAccounts[replicaId];
});
this._accountReplicas[accountId] = replicas;
Object.keys(replicas).forEach(region => {
const replicaId = replicas[region];
this._regionsByAccounts[replicaId] = {
region,
connections: connectionCount,
lastUsed: Date.now()
};
this._accountsByReplicaId[replicaId] = accountId;
});
this._logger.debug(`${accountId}: updated account cache`);
}
}
/**
* Removes account region info
* @param {String} accountId account id
*/
removeAccountCache(accountId: string) {
if (this._regionsByAccounts[accountId]?.connections > 0) {
this._regionsByAccounts[accountId].connections--;
}
}
/**
* Locks subscription for a socket instance based on TooManyRequestsError metadata
* @param {Number} instanceNumber instance index number
* @param {String} socketInstanceIndex socket instance index
* @param {String} region server region
* @param {Object} metadata TooManyRequestsError metadata
*/
async lockSocketInstance(instanceNumber, socketInstanceIndex, region, metadata) {
if (metadata.type === 'LIMIT_ACCOUNT_SUBSCRIPTIONS_PER_USER') {
this._subscribeLock = {
recommendedRetryTime: metadata.recommendedRetryTime,
lockedAtAccounts: this.subscribedAccountIds(instanceNumber, undefined, region).length,
lockedAtTime: Date.now()
};
} else {
const subscribedAccounts = this.subscribedAccountIds(instanceNumber, socketInstanceIndex, region);
if (subscribedAccounts.length === 0) {
const socketInstance = this.socketInstances[region][instanceNumber][socketInstanceIndex];
socketInstance.socket.close();
await this._reconnect(instanceNumber, socketInstanceIndex, region);
} else {
const instance = this.socketInstances[region][instanceNumber][socketInstanceIndex];
instance.subscribeLock = {
recommendedRetryTime: metadata.recommendedRetryTime,
type: metadata.type,
lockedAtAccounts: subscribedAccounts.length
};
}
}
}
/**
* Connects to MetaApi server via socket.io protocol
* @param {Number} instanceNumber instance index number
* @param {String} region server region
* @returns {Promise} promise which resolves when connection is established
*/
async connect(instanceNumber, region) {
if (this._region && region !== this._region) {
throw new ValidationError(`Trying to connect to ${region} region, but configured with ${this._region}`);
}
let clientId = Math.random();
let resolve;
let result = new Promise((res, rej) => {
resolve = res;
});
this._socketInstances[region] ||= {};
this._socketInstances[region][instanceNumber] ||= [];
const socketInstanceIndex = this._socketInstances[region][instanceNumber].length;
const instance: MetaApiWebsocketClient.SocketInstance = {
id: socketInstanceIndex,
reconnectWaitTime: this._socketMinimumReconnectTimeout,
connected: false,
requestResolves: {},
resolved: false,
connectResult: result,
sessionId: randomstring.generate(32),
isReconnecting: false,
socket: null,
synchronizationThrottler: new SynchronizationThrottler(this, socketInstanceIndex, instanceNumber, region,
this._synchronizationThrottlerOpts),
subscribeLock: null,
instanceNumber
};
instance.connected = true;
this._socketInstances[region][instanceNumber].push(instance);
instance.synchronizationThrottler.start();
const serverUrl = await this._getServerUrl(instanceNumber, socketInstanceIndex, region);
const socketInstance = socketIO(serverUrl, {
path: '/ws',
reconnection: true,
reconnectionDelay: 1000,
reconnectionDelayMax: 5000,
reconnectionAttempts: Infinity,
timeout: this._connectTimeout,
extraHeaders: {
'Client-Id': clientId
},
query: {
'auth-token': this._token,
clientId: clientId,
protocol: 3
}
});
instance.socket = socketInstance;
socketInstance.on('connect', async () => {
// eslint-disable-next-line no-console
this._logger.info(`${region}:${instanceNumber}: MetaApi websocket client connected to the MetaApi server`);
instance.reconnectWaitTime = this._socketMinimumReconnectTimeout;
instance.isReconnecting = false;
if (!instance.resolved) {
instance.resolved = true;
resolve();
} else {
await this._fireReconnected(instanceNumber, instance.id, region);
}
if (!instance.connected) {
instance.socket.close();
}
});
socketInstance.on('reconnect', async () => {
instance.isReconnecting = false;
this._logger.info(`${region}:${instanceNumber}: MetaApi websocket client reconnected`);
await this._fireReconnected(instanceNumber, instance.id, region);
});
socketInstance.on('connect_error', async (err) => {
// eslint-disable-next-line no-console
this._logger.error(`${region}:${instanceNumber}: MetaApi websocket client connection error`, err);
instance.isReconnecting = false;
await this._reconnect(instanceNumber, instance.id, region);
});
socketInstance.on('connect_timeout', async (timeout) => {
// eslint-disable-next-line no-console
this._logger.error(`${region}:${instanceNumber}: MetaApi websocket client connection timeout`);
instance.isReconnecting = false;
if (!instance.resolved) {
await this._reconnect(instanceNumber, instance.id, region);
}
});
socketInstance.on('disconnect', async (reason) => {
instance.synchronizationThrottler.onDisconnect();
// eslint-disable-next-line no-console
this._logger.info(`${region}:${instanceNumber}: MetaApi websocket client disconnected from the ` +
`MetaApi server because of ${reason}`);
instance.isReconnecting = false;
await this._reconnect(instanceNumber, instance.id, region);
});
socketInstance.on('error', async (error) => {
// eslint-disable-next-line no-console
this._logger.error(`${region}:${instanceNumber}: MetaApi websocket client error`, error);
instance.isReconnecting = false;
await this._reconnect(instanceNumber, instance.id, region);
});
socketInstance.on('response', data => {
if (typeof data === 'string') {
data = JSON.parse(data);
}
this._logger.debug(() => `${data.accountId}: Response received: ${JSON.stringify({
requestId: data.requestId, timestamps: data.timestamps})}`);
let requestResolve = (instance.requestResolves[data.requestId] || {resolve: () => {}, reject: () => {}});
delete instance.requestResolves[data.requestId];
this._convertIsoTimeToDate(data);
requestResolve.resolve(data);
if (data.timestamps && requestResolve.type) {
data.timestamps.clientProcessingFinished = new Date();
for (let listener of this._latencyListeners) {
Promise.resolve()
.then(() => requestResolve.type === 'trade' ?
listener.onTrade(data.accountId, data.timestamps) :
listener.onResponse(data.accountId, requestResolve.type, data.timestamps))
.catch(error => this._logger.error('Failed to process onResponse event for account ' +
data.accountId + ', request type ' + requestResolve.type, error));
}
}
});
socketInstance.on('processingError', data => {
let requestResolve = (instance.requestResolves[data.requestId] || {resolve: () => {}, reject: () => {}});
delete instance.requestResolves[data.requestId];
requestResolve.reject(this._convertError(data));
});
// eslint-disable-next-line complexity
socketInstance.on('synchronization', async data => {
if (typeof data === 'string') {
data = JSON.parse(data);
}
if (data.instanceIndex && data.instanceIndex !== instanceNumber) {
this._logger.trace(() => `${data.accountId}:${data.instanceNumber}: received packet with wrong instance ` +
`index via a socket with instance number of ${instanceNumber}, data=${JSON.stringify({
type: data.type, sequenceNumber: data.sequenceNumber, sequenceTimestamp: data.sequenceTimestamp,
synchronizationId: data.synchronizationId, application: data.application, host: data.host,
specificationsUpdated: data.specificationsUpdated, positionsUpdated: data.positionsUpdated,
ordersUpdated: data.ordersUpdated,
specifications: data.specifications ? (data.specifications || []).length : undefined})}`);
return;
}
this._regionsByAccounts[data.accountId] ||= {region, connections: 0, lastUsed: Date.now()};
this._logger.trace(() => `${data.accountId}:${data.instanceIndex}: Sync packet received: ${JSON.stringify({
type: data.type, sequenceNumber: data.sequenceNumber, sequenceTimestamp: data.sequenceTimestamp,
synchronizationId: data.synchronizationId, application: data.application, host: data.host,
specificationsUpdated: data.specificationsUpdated, positionsUpdated: data.positionsUpdated,
ordersUpdated: data.ordersUpdated,
specifications: data.specifications ? (data.specifications || []).length : undefined})}, ` +
`active listeners: ${(this._synchronizationListeners[data.accountId] || []).length}`);
let activeSynchronizationIds = instance.synchronizationThrottler.activeSynchronizationIds;
if (!data.synchronizationId || activeSynchronizationIds.includes(data.synchronizationId)) {
if (this._packetLogger) {
await this._packetLogger.logPacket(data);
}
const ignoredPacketTypes = ['disconnected', 'status', 'keepalive'];
if (!this._subscriptionManager.isSubscriptionActive(data.accountId) &&
!ignoredPacketTypes.includes(data.type)) {
this._logger.debug(`${data.accountId}: Packet arrived to inactive connection, attempting` +
` unsubscribe, packet: ${data.type}`);
if (this._throttleRequest('unsubscribe', data.accountId, data.instanceIndex,
this._unsubscribeThrottlingInterval)) {
this.unsubscribe(data.accountId).catch(err => {
this._logger.warn(`${data.accountId}:${data.instanceIndex || 0}: failed to unsubscribe`, err);
});
}
return;
}
this._convertIsoTimeToDate(data);
} else {
data.type = 'noop';
}
this.queuePacket(instance, data);
});
socketInstance.on('metadata', (data: MetadataPacket) => {
instance.clientApiHostname = data.clientApiHostname;
});
return result;
}
/**
* Closes connection to MetaApi server
*/
close() {
Object.keys(this._socketInstances).forEach(region => {
Object.keys(this._socketInstances[region]).forEach(instanceNumber => {
this._socketInstances[region][instanceNumber].forEach(async (instance) => {
if (instance.connected) {
instance.connected = false;
await instance.socket.close();
for (let requestResolve of Object.values<any>(instance.requestResolves)) {
requestResolve.reject(new Error('MetaApi connection closed'));
}
instance.requestResolves = {};
}
});
this._socketInstancesByAccounts[instanceNumber] = {};
this._socketInstances[region][instanceNumber] = [];
});
});
this._synchronizationListeners = {};
this._latencyListeners = [];
this._packetOrderer.stop();
}
/**
* Stops the client
*/
stop() {
clearInterval(this._clearAccountCacheInterval);
clearInterval(this._clearInactiveSyncDataInterval);
this._latencyService.stop();
}
/**
* Returns account information for a specified MetaTrader account.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {GetAccountInformationOptions} [options] additional request options
* @returns {Promise<MetatraderAccountInformation>} promise resolving with account information
*/
async getAccountInformation(accountId, options?) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getAccountInformation', ...options});
return response.accountInformation;
}
/**
* Returns positions for a specified MetaTrader account.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {GetPositionsOptions} [options] additional request options
* @returns {Promise<Array<MetatraderPosition>} promise resolving with array of open positions
*/
async getPositions(accountId, options?) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getPositions', ...options});
return response.positions;
}
/**
* Returns specific position for a MetaTrader account.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} positionId position id
* @param {GetPositionOptions} [options] additional request options
* @return {Promise<MetatraderPosition>} promise resolving with MetaTrader position found
*/
async getPosition(accountId, positionId, options?) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getPosition', positionId, ...options});
return response.position;
}
/**
* Returns open orders for a specified MetaTrader account.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {GetOrdersOptions} [options] additional request options
* @return {Promise<Array<MetatraderOrder>>} promise resolving with open MetaTrader orders
*/
async getOrders(accountId, options?) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getOrders', ...options});
return response.orders;
}
/**
* Returns specific open order for a MetaTrader account.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} orderId order id (ticket number)
* @param {GetOrderOptions} [options] additional request options
* @return {Promise<MetatraderOrder>} promise resolving with metatrader order found
*/
async getOrder(accountId, orderId, options?) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getOrder', orderId, ...options});
return response.order;
}
/**
* MetaTrader history orders search query response
* @typedef {Object} MetatraderHistoryOrders
* @property {Array<MetatraderOrder>} historyOrders array of history orders returned
* @property {Boolean} synchronizing flag indicating that history order initial synchronization is still in progress
* and thus search results may be incomplete
*/
/**
* Returns the history of completed orders for a specific ticket number.
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} ticket ticket number (order id)
* @returns {Promise<MetatraderHistoryOrders>} promise resolving with request results containing history orders found
*/
async getHistoryOrdersByTicket(accountId, ticket) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getHistoryOrdersByTicket', ticket});
return {
historyOrders: response.historyOrders,
synchronizing: response.synchronizing
};
}
/**
* Returns the history of completed orders for a specific position id
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} positionId position id
* @returns {Promise<MetatraderHistoryOrders>} promise resolving with request results containing history orders found
*/
async getHistoryOrdersByPosition(accountId, positionId) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getHistoryOrdersByPosition',
positionId});
return {
historyOrders: response.historyOrders,
synchronizing: response.synchronizing
};
}
/**
* Returns the history of completed orders for a specific time range
* @param {String} accountId id of the MetaTrader account to return information for
* @param {Date} startTime start of time range, inclusive
* @param {Date} endTime end of time range, exclusive
* @param {Number} offset pagination offset, default is 0
* @param {Number} limit pagination limit, default is 1000
* @returns {Promise<MetatraderHistoryOrders>} promise resolving with request results containing history orders found
*/
async getHistoryOrdersByTimeRange(accountId, startTime, endTime, offset = 0, limit = 1000) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getHistoryOrdersByTimeRange',
startTime, endTime, offset, limit});
return {
historyOrders: response.historyOrders,
synchronizing: response.synchronizing
};
}
/**
* MetaTrader history deals search query response
* @typedef {Object} MetatraderDeals
* @property {Array<MetatraderDeal>} deals array of history deals returned
* @property {Boolean} synchronizing flag indicating that deal initial synchronization is still in progress
* and thus search results may be incomplete
*/
/**
* MetaTrader deal
* @typedef {Object} MetatraderDeal
* @property {String} id deal id (ticket number)
* @property {String} type deal type (one of DEAL_TYPE_BUY, DEAL_TYPE_SELL, DEAL_TYPE_BALANCE, DEAL_TYPE_CREDIT,
* DEAL_TYPE_CHARGE, DEAL_TYPE_CORRECTION, DEAL_TYPE_BONUS, DEAL_TYPE_COMMISSION, DEAL_TYPE_COMMISSION_DAILY,
* DEAL_TYPE_COMMISSION_MONTHLY, DEAL_TYPE_COMMISSION_AGENT_DAILY, DEAL_TYPE_COMMISSION_AGENT_MONTHLY,
* DEAL_TYPE_INTEREST, DEAL_TYPE_BUY_CANCELED, DEAL_TYPE_SELL_CANCELED, DEAL_DIVIDEND, DEAL_DIVIDEND_FRANKED,
* DEAL_TAX). See https://www.mql5.com/en/docs/constants/tradingconstants/dealproperties#enum_deal_type
* @property {String} entryType deal entry type (one of DEAL_ENTRY_IN, DEAL_ENTRY_OUT, DEAL_ENTRY_INOUT,
* DEAL_ENTRY_OUT_BY). See https://www.mql5.com/en/docs/constants/tradingconstants/dealproperties#enum_deal_entry
* @property {String} [symbol] symbol deal relates to
* @property {Number} [magic] deal magic number, identifies the EA which initiated the deal
* @property {Date} time time the deal was conducted at
* @property {String} brokerTime time time the deal was conducted at, in broker timezone, YYYY-MM-DD HH:mm:ss.SSS format
* @property {Number} [volume] deal volume
* @property {Number} [price] the price the deal was conducted at
* @property {Number} [commission] deal commission
* @property {Number} [swap] deal swap
* @property {Number} profit deal profit
* @property {String} [positionId] id of position the deal relates to
* @property {String} [orderId] id of order the deal relates to
* @property {String} [comment] deal comment. The sum of the line lengths of the comment and the clientId
* must be less than or equal to 26. For more information see https://metaapi.cloud/docs/client/clientIdUsage/
* @property {String} [brokerComment] current comment value on broker side (possibly overriden by the broker)
* @property {String} [clientId] client-assigned id. The id value can be assigned when submitting a trade and
* will be present on position, history orders and history deals related to the trade. You can use this field to bind
* your trades to objects in your application and then track trade progress. The sum of the line lengths of the
* comment and the clientId must be less than or equal to 26. For more information see
* https://metaapi.cloud/docs/client/clientIdUsage/
* @property {String} platform platform id (mt4 or mt5)
* @property {String} [reason] optional deal execution reason. One of DEAL_REASON_CLIENT, DEAL_REASON_MOBILE,
* DEAL_REASON_WEB, DEAL_REASON_EXPERT, DEAL_REASON_SL, DEAL_REASON_TP, DEAL_REASON_SO, DEAL_REASON_ROLLOVER,
* DEAL_REASON_VMARGIN, DEAL_REASON_SPLIT, DEAL_REASON_UNKNOWN. See
* https://www.mql5.com/en/docs/constants/tradingconstants/dealproperties#enum_deal_reason.
* @property {Number} [accountCurrencyExchangeRate] current exchange rate of account currency into account base
* currency (USD if you did not override it)
* @property {number} [stopLoss] deal stop loss. For MT5 opening deal this is the SL of the order opening the
* position. For MT4 deals or MT5 closing deal this is the last known position SL.
* @property {number} [takeProfit] deal take profit. For MT5 opening deal this is the TP of the order opening the
* position. For MT4 deals or MT5 closing deal this is the last known position TP.
*/
/**
* Returns history deals with a specific ticket number
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} ticket ticket number (deal id for MT5 or order id for MT4)
* @returns {Promise<MetatraderDeals>} promise resolving with request results containing deals found
*/
async getDealsByTicket(accountId, ticket) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getDealsByTicket', ticket});
return {
deals: response.deals,
synchronizing: response.synchronizing
};
}
/**
* Returns history deals for a specific position id
* @param {String} accountId id of the MetaTrader account to return information for
* @param {String} positionId position id
* @returns {Promise<MetatraderDeals>} promise resolving with request results containing deals found
*/
async getDealsByPosition(accountId, positionId) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getDealsByPosition', positionId});
return {
deals: response.deals,
synchronizing: response.synchronizing
};
}
/**
* Returns history deals with for a specific time range
* @param {String} accountId id of the MetaTrader account to return information for
* @param {Date} startTime start of time range, inclusive
* @param {Date} endTime end of time range, exclusive
* @param {Number} offset pagination offset, default is 0
* @param {Number} limit pagination limit, default is 1000
* @returns {Promise<MetatraderDeals>} promise resolving with request results containing deals found
*/
async getDealsByTimeRange(accountId, startTime, endTime, offset = 0, limit = 1000) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getDealsByTimeRange', startTime,
endTime, offset, limit});
return {
deals: response.deals,
synchronizing: response.synchronizing
};
}
/**
* Clears the order and transaction history of a specified application and removes the application
* @param {String} accountId id of the MetaTrader account to remove history and application for
* @return {Promise} promise resolving when the history is cleared
*/
removeApplication(accountId) {
return this.rpcRequest(accountId, {type: 'removeApplication'});
}
/**
* MetaTrader trade response
* @typedef {Object} MetatraderTradeResponse
* @property {Number} numericCode numeric response code, see
* https://www.mql5.com/en/docs/constants/errorswarnings/enum_trade_return_codes and
* https://book.mql4.com/appendix/errors. Response codes which indicate success are 0, 10008-10010, 10025. The rest
* codes are errors
* @property {String} stringCode string response code, see
* https://www.mql5.com/en/docs/constants/errorswarnings/enum_trade_return_codes and
* https://book.mql4.com/appendix/errors. Response codes which indicate success are ERR_NO_ERROR,
* TRADE_RETCODE_PLACED, TRADE_RETCODE_DONE, TRADE_RETCODE_DONE_PARTIAL, TRADE_RETCODE_NO_CHANGES. The rest codes are
* errors.
* @property {String} message human-readable response message
* @property {String} orderId order id which was created/modified during the trade
* @property {String} positionId position id which was modified during the trade
*/
/**
* Execute a trade on a connected MetaTrader account
* @param {String} accountId id of the MetaTrader account to execute trade for
* @param {MetatraderTrade} trade trade to execute (see docs for possible trade types)
* @param {String} [application] application to use
* @param {String} [reliability] account reliability
* @returns {Promise<MetatraderTradeResponse>} promise resolving with trade result
* @throws {TradeError} on trade error, check error properties for error code details
*/
// eslint-disable-next-line complexity
async trade(accountId, trade, application?, reliability?) {
let response;
if (application === 'RPC') {
response = await this.rpcRequest(accountId, {type: 'trade', trade, application});
} else {
response = await this.rpcRequestAllInstances(accountId, {type: 'trade', trade,
application: application || this._application, requestId: randomstring.generate(32)}, reliability);
}
response.response = response.response || {};
response.response.stringCode = response.response.stringCode || response.response.description;
response.response.numericCode = response.response.numericCode !== undefined ? response.response.numericCode :
response.response.error;
if (['ERR_NO_ERROR', 'TRADE_RETCODE_PLACED', 'TRADE_RETCODE_DONE', 'TRADE_RETCODE_DONE_PARTIAL',
'TRADE_RETCODE_NO_CHANGES'].includes(response.response.stringCode || response.response.description)) {
return response.response;
} else {
throw new TradeError(response.response.message, response.response.numericCode, response.response.stringCode);
}
}
/**
* Creates a task that ensures the account gets subscribed to the server
* @param {String} accountId account id to subscribe
* @param {Number} instanceNumber instance index number
*/
ensureSubscribe(accountId, instanceNumber) {
this._subscriptionManager.scheduleSubscribe(accountId, instanceNumber);
}
/**
* Subscribes to the Metatrader terminal events
* @param {String} accountId id of the MetaTrader account to subscribe to
* @param {Number} instanceNumber instance index number
* @returns {Promise} promise which resolves when subscription started
*/
subscribe(accountId, instanceNumber) {
return this._subscriptionManager.subscribe(accountId, instanceNumber);
}
/**
* Requests the terminal to start synchronization process
* @param {String} accountId id of the MetaTrader account to synchronize
* @param {Number} instanceIndex instance index
* @param {String} host name of host to synchronize with
* @param {String} synchronizationId synchronization request id
* @param {Date} startingHistoryOrderTime from what date to start synchronizing history orders from. If not specified,
* the entire order history will be downloaded.
* @param {Date} startingDealTime from what date to start deal synchronization from. If not specified, then all
* history deals will be downloaded.
* @param {Function} getHashes function to get terminal state hashes
* @returns {Promise} promise which resolves when synchronization started
*/
async synchronize(
accountId, instanceIndex, host, synchronizationId, startingHistoryOrderTime, startingDealTime, hashes
) {
if (this._getSocketInstanceByAccount(accountId, instanceIndex) === undefined) {
this._logger.debug(`${accountId}:${instanceIndex}: creating socket instance on synchronize`);
await this._createSocketInstanceByAccount(accountId, instanceIndex);
}
const syncThrottler = this._getSocketInstanceByAccount(accountId, instanceIndex).synchronizationThrottler;
this._synchronizationHashes[synchronizationId] = hashes;
this._synchronizationHashes[synchronizationId].lastUpdated = Date.now();
return syncThrottler.scheduleSynchronize(accountId, {requestId: synchronizationId, version: 2,
type: 'synchronize', startingHistoryOrderTime, startingDealTime, instanceIndex, host}, hashes);
}
/**
* Waits for server-side terminal state synchronization to complete
* @param {String} accountId id of the MetaTrader account to synchronize
* @param {Number} [instanceNumber] instance index number
* @param {String} applicationPattern MetaApi application regular expression pattern, default is .*
* @param {Number} timeoutInSeconds timeout in seconds, default is 300 seconds
* @param {String} [application] application to synchronize with
* @returns {Promise} promise which resolves when synchronization started
*/
waitSynchronized(accountId, instanceNumber, applicationPattern, timeoutInSeconds, application?) {
return this.rpcRequest(accountId, {type: 'waitSynchronized', applicationPattern, timeoutInSeconds,
instanceIndex: instanceNumber, application: application || this._application},
timeoutInSeconds + 1);
}
/**
* Market data subscription
* @typedef {Object} MarketDataSubscription
* @property {string} type subscription type, one of quotes, candles, ticks, or marketDepth
* @property {string} [timeframe] when subscription type is candles, defines the timeframe according to which the
* candles must be generated. Allowed values for MT5 are 1m, 2m, 3m, 4m, 5m, 6m, 10m, 12m, 15m, 20m, 30m, 1h, 2h, 3h,
* 4h, 6h, 8h, 12h, 1d, 1w, 1mn. Allowed values for MT4 are 1m, 5m, 15m 30m, 1h, 4h, 1d, 1w, 1mn
* @property {number} [intervalInMilliseconds] defines how frequently the terminal will stream data to client. If not
* set, then the value configured in account will be used
*/
/**
* Subscribes on market data of specified symbol
* @param {String} accountId id of the MetaTrader account
* @param {String} symbol symbol (e.g. currency pair or an index)
* @param {Array<MarketDataSubscription>} subscriptions array of market data subscription to create or update
* @param {String} [reliability] account reliability
* @returns {Promise} promise which resolves when subscription request was processed
*/
subscribeToMarketData(accountId, symbol, subscriptions, reliability?) {
return this.rpcRequestAllInstances(accountId,
{type: 'subscribeToMarketData', symbol, subscriptions}, reliability);
}
/**
* Refreshes market data subscriptions on the server to prevent them from expiring
* @param {String} accountId id of the MetaTrader account
* @param {Number} instanceNumber instance index number
* @param {Array} subscriptions array of subscriptions to refresh
*/
refreshMarketDataSubscriptions(accountId, instanceNumber, subscriptions) {
return this.rpcRequest(accountId, {type: 'refreshMarketDataSubscriptions', subscriptions,
instanceIndex: instanceNumber});
}
/**
* Market data unsubscription
* @typedef {Object} MarketDataUnsubscription
* @property {string} type subscription type, one of quotes, candles, ticks, or marketDepth
*/
/**
* Unsubscribes from market data of specified symbol
* @param {String} accountId id of the MetaTrader account
* @param {String} symbol symbol (e.g. currency pair or an index)
* @param {Array<MarketDataUnsubscription>} subscriptions array of subscriptions to cancel
* @param {String} [reliability] account reliability
* @returns {Promise} promise which resolves when unsubscription request was processed
*/
unsubscribeFromMarketData(accountId, symbol, subscriptions, reliability) {
return this.rpcRequestAllInstances(accountId, {type: 'unsubscribeFromMarketData', symbol, subscriptions},
reliability);
}
/**
* Retrieves symbols available on an account
* @param {String} accountId id of the MetaTrader account to retrieve symbols for
* @returns {Promise<Array<string>>} promise which resolves when symbols are retrieved
*/
async getSymbols(accountId) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getSymbols'});
return response.symbols;
}
/**
* Retrieves specification for a symbol
* @param {String} accountId id of the MetaTrader account to retrieve symbol specification for
* @param {String} symbol symbol to retrieve specification for
* @returns {Promise<MetatraderSymbolSpecification>} promise which resolves when specification is retrieved
*/
async getSymbolSpecification(accountId, symbol) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getSymbolSpecification', symbol});
return response.specification;
}
/**
* Retrieves price for a symbol
* @param {String} accountId id of the MetaTrader account to retrieve symbol price for
* @param {String} symbol symbol to retrieve price for
* @param {boolean} keepSubscription if set to true, the account will get a long-term subscription to symbol market
* data. Long-term subscription means that on subsequent calls you will get updated value faster. If set to false or
* not set, the subscription will be set to expire in 12 minutes.
* @returns {Promise<MetatraderSymbolPrice>} promise which resolves when price is retrieved
*/
async getSymbolPrice(accountId, symbol, keepSubscription = false) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getSymbolPrice', symbol,
keepSubscription});
return response.price;
}
/**
* Retrieves price for a symbol
* @param {string} accountId id of the MetaTrader account to retrieve candle for
* @param {string} symbol symbol to retrieve candle for
* @param {string} timeframe defines the timeframe according to which the candle must be generated. Allowed values for
* MT5 are 1m, 2m, 3m, 4m, 5m, 6m, 10m, 12m, 15m, 20m, 30m, 1h, 2h, 3h, 4h, 6h, 8h, 12h, 1d, 1w, 1mn. Allowed values
* for MT4 are 1m, 5m, 15m 30m, 1h, 4h, 1d, 1w, 1mn
* @param {boolean} keepSubscription if set to true, the account will get a long-term subscription to symbol market
* data. Long-term subscription means that on subsequent calls you will get updated value faster. If set to false or
* not set, the subscription will be set to expire in 12 minutes.
* @returns {Promise<MetatraderCandle>} promise which resolves when candle is retrieved
*/
async getCandle(accountId, symbol, timeframe, keepSubscription = false) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getCandle', symbol, timeframe,
keepSubscription});
return response.candle;
}
/**
* Retrieves latest tick for a symbol. MT4 G1 accounts do not support this API
* @param {string} accountId id of the MetaTrader account to retrieve symbol tick for
* @param {string} symbol symbol to retrieve tick for
* @param {boolean} keepSubscription if set to true, the account will get a long-term subscription to symbol market
* data. Long-term subscription means that on subsequent calls you will get updated value faster. If set to false or
* not set, the subscription will be set to expire in 12 minutes.
* @returns {Promise<MetatraderTick>} promise which resolves when tick is retrieved
*/
async getTick(accountId, symbol, keepSubscription = false) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getTick', symbol, keepSubscription});
return response.tick;
}
/**
* Retrieves latest order book for a symbol. MT4 accounts do not support this API
* @param {string} accountId id of the MetaTrader account to retrieve symbol order book for
* @param {string} symbol symbol to retrieve order book for
* @param {boolean} keepSubscription if set to true, the account will get a long-term subscription to symbol market
* data. Long-term subscription means that on subsequent calls you will get updated value faster. If set to false or
* not set, the subscription will be set to expire in 12 minutes.
* @returns {Promise<MetatraderBook>} promise which resolves when order book is retrieved
*/
async getBook(accountId, symbol, keepSubscription = false) {
let response = await this.rpcRequest(accountId, {application: 'RPC', type: 'getBook', symbol, keepSubscription});
return response.book;
}
/**
* Forces refresh of most recent quote updates for symbols subscribed to by the terminal
* @param {string} accountId id of the MetaTr