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,000 lines • 358 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", {
value: true
});
Object.defineProperty(exports, "default", {
enumerable: true,
get: function() {
return _default;
}
});
const _randomstring = /*#__PURE__*/ _interop_require_default(require("randomstring"));
const _socketioclient = /*#__PURE__*/ _interop_require_default(require("socket.io-client"));
const _timeoutError = /*#__PURE__*/ _interop_require_default(require("../timeoutError"));
const _errorHandler = require("../errorHandler");
const _optionsValidator = /*#__PURE__*/ _interop_require_default(require("../optionsValidator"));
const _notSynchronizedError = /*#__PURE__*/ _interop_require_default(require("./notSynchronizedError"));
const _notConnectedError = /*#__PURE__*/ _interop_require_default(require("./notConnectedError"));
const _tradeError = /*#__PURE__*/ _interop_require_default(require("./tradeError"));
const _packetOrderer = /*#__PURE__*/ _interop_require_default(require("./packetOrderer"));
const _synchronizationThrottler = /*#__PURE__*/ _interop_require_default(require("./synchronizationThrottler"));
const _subscriptionManager = /*#__PURE__*/ _interop_require_default(require("./subscriptionManager"));
const _logger = /*#__PURE__*/ _interop_require_default(require("../../logger"));
const _promiseany = /*#__PURE__*/ _interop_require_default(require("promise.any"));
const _latencyService = /*#__PURE__*/ _interop_require_default(require("./latencyService"));
const _lodash = /*#__PURE__*/ _interop_require_default(require("lodash"));
_export_star(require("./metaApiWebsocket.client.schemas"), exports);
function _define_property(obj, key, value) {
if (key in obj) {
Object.defineProperty(obj, key, {
value: value,
enumerable: true,
configurable: true,
writable: true
});
} else {
obj[key] = value;
}
return obj;
}
function _export_star(from, to) {
Object.keys(from).forEach(function(k) {
if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
Object.defineProperty(to, k, {
enumerable: true,
get: function() {
return from[k];
}
});
}
});
return from;
}
function _interop_require_default(obj) {
return obj && obj.__esModule ? obj : {
default: obj
};
}
let PacketLogger;
if (typeof window === "undefined") {
PacketLogger = require("./packetLogger").default;
}
/**
* MetaApi websocket API client (see https://metaapi.cloud/docs/client/websocket/overview/)
*/ let MetaApiWebsocketClient = class MetaApiWebsocketClient {
/**
* 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() {
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() {
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
*/ _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, replicas) {
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, replicas) {
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) {
var _this__regionsByAccounts_accountId;
if (((_this__regionsByAccounts_accountId = this._regionsByAccounts[accountId]) === null || _this__regionsByAccounts_accountId === void 0 ? void 0 : _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) {
var _this__socketInstances, _region, _this__socketInstances_region, _instanceNumber;
if (this._region && region !== this._region) {
throw new _errorHandler.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 = this._socketInstances)[_region = region] || (_this__socketInstances[_region] = {});
(_this__socketInstances_region = this._socketInstances[region])[_instanceNumber = instanceNumber] || (_this__socketInstances_region[_instanceNumber] = []);
const socketInstanceIndex = this._socketInstances[region][instanceNumber].length;
const instance = {
id: socketInstanceIndex,
reconnectWaitTime: this._socketMinimumReconnectTimeout,
connected: false,
requestResolves: {},
resolved: false,
connectResult: result,
sessionId: _randomstring.default.generate(32),
isReconnecting: false,
socket: null,
synchronizationThrottler: new _synchronizationThrottler.default(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 = (0, _socketioclient.default)(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)=>{
var _this__regionsByAccounts, _data_accountId;
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 = this._regionsByAccounts)[_data_accountId = data.accountId] || (_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)=>{
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(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.default.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.default(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 update