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,028 lines • 359 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 _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"));
const _clientStickySocket = /*#__PURE__*/ _interop_require_default(require("../../packages/sticky-sockets/clientStickySocket"));
const _helpers = /*#__PURE__*/ _interop_require_wildcard(require("../../helpers/helpers"));
_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
};
}
function _getRequireWildcardCache(nodeInterop) {
if (typeof WeakMap !== "function") return null;
var cacheBabelInterop = new WeakMap();
var cacheNodeInterop = new WeakMap();
return (_getRequireWildcardCache = function(nodeInterop) {
return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
})(nodeInterop);
}
function _interop_require_wildcard(obj, nodeInterop) {
if (!nodeInterop && obj && obj.__esModule) {
return obj;
}
if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
return {
default: obj
};
}
var cache = _getRequireWildcardCache(nodeInterop);
if (cache && cache.has(obj)) {
return cache.get(obj);
}
var newObj = {
__proto__: null
};
var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
for(var key in obj){
if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
if (desc && (desc.get || desc.set)) {
Object.defineProperty(newObj, key, desc);
} else {
newObj[key] = obj[key];
}
}
}
newObj.default = obj;
if (cache) {
cache.set(obj, newObj);
}
return newObj;
}
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];
await socketInstance.socket.disconnect();
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();
(_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: true,
requestResolves: {},
resolved: false,
connectResult: _helpers.createHandlePromise(),
sessionId: _randomstring.default.generate(32),
isReconnecting: false,
socket: null,
synchronizationThrottler: new _synchronizationThrottler.default(this, socketInstanceIndex, instanceNumber, region, this._synchronizationThrottlerOpts),
subscribeLock: null,
instanceNumber,
region
};
this._socketInstances[region][instanceNumber].push(instance);
instance.synchronizationThrottler.start();
instance.socket = this._createSocket(await this._getServerUrl(instanceNumber, socketInstanceIndex, region), clientId, instance);
return instance.connectResult;
}
/**
* 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.disconnect();
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 updates for symbols subscribed to by the terminal
* @param {string} accountId id of the MetaTrader account
* @returns {Promise<string[]>} promise which resolves with recent quote symbols that was initiated to process
*/ async refreshTerminalState(accountId) {
let response = await this.rpcRequest(accountId, {
application: "RPC",
type: "refreshTerminalState"
});
return response.symbols;
}
/**
* Forces refresh and retrieves latest quotes for a subset of symbols the terminal is subscribed to
* @param {string} accountId id of the MetaTrader account
* @param {string[]} symbols quote symbols to refresh
* @returns {Promise<RefreshedQuotes>} refreshed quotes and basic account information info
*/ async refreshSymbolQuotes(accountId, symbols) {
let response = await this.rpcRequest(accountId, {
application: "RPC",
type: "refreshSymbolQuotes",
symbols
});
return response.refreshedQuotes;
}
/**
* Sends client uptime stats to the server.
* @param {String} accountId id of the MetaTrader account to save uptime
* @param {Object} uptime uptime statistics to send to the server
* @returns {Promise} promise which resolves when uptime statistics is submitted
*/ saveUptime(accountId, uptime) {
return this.rpcRequest(accountId, {
type: "saveUptime",
uptime
});
}
/**
* Unsubscribe from account
* @param {String} accountId id of the MetaTrader account to unsubscribe
* @returns {Promise} promise which resolves when socket unsubscribed
*/ async unsubscribe(accountId) {
const region = this.getAccountRegion(accountId);
this._latencyService.onUnsubscribe(accountId);
Object.keys(this._updateEvents).filter((key)=>key.startsWith(accountId)).forEach((key)=>delete this._updateEvents[key]);
if (this._socketInstances[region]) {
await Promise.all(Object.keys(this._socketInstances[region]).map(async (instanceNumber)=>{
try {
await this._subscriptionManager.unsubscribe(accountId, Number(instanceNumber));
delete this._socketInstancesByAccounts[instanceNumber][accountId];
} catch (err) {
if (![
"TimeoutError",
"NotFoundError"
].includes(err.name)) {
this._logger.warn(`${accountId}:${instanceNumber}: failed to unsubscribe`, err);
}
}
}));
}
}
/**
* Current server time (see https://metaapi.cloud/docs/client/models/serverTime/)
* @typedef {Object} ServerTime
* @property {Date} time current server time
* @property {String} brokerTime current broker time, in broker timezone, YYYY-MM-DD HH:mm:ss.SSS format
* @property {Date} [lastQuoteTime] last quote time
* @property {String} [lastQuoteBrokerTime] last quote time, in broker timezone, YYYY-MM-DD HH:mm:ss.SSS format
*/ /**
* Returns server time for a specified MetaTrader account
* @param {string} accountId id of the MetaTrader account to return server time for
* @returns {Promise<ServerTime>} promise resolving with server time
*/ async getServerTime(accountId) {
let response = await this.rpcRequest(accountId, {
application: "RPC",
type: "getServerTime"
});
return response.serverTime;
}
/**
* Margin required to open a trade (see https://metaapi.cloud/docs/client/models/margin/)
* @typedef {Object} Margin
* @property {number} [margin] margin required to open a trade. If margin can not be calculated, then this field is
* not defined
*/ /**
* Contains order to calculate margin for (see https://metaapi.cloud/docs/client/models/marginOrder/)
* @typedef {Object} MarginOrder
* @property {string} symbol order symbol
* @property {string} type order type, one of ORDER_TYPE_BUY or ORDER_TYPE_SELL
* @property {number} volume order volume, must be greater than 0
* @property {number} openPrice order open price, must be greater than 0
*/ /**
* Calculates margin required to open a trade on the specified trading account
* @param {string} accountId id of the trading account to calculate margin for
* @param {string} application application to send the request to
* @param {string} reliability account reliability
* @param {MarginOrder} order order to calculate margin for
* @returns {Promise<Margin>} promise resolving with margin calculation result
*/ async calculateMargin(accountId, application, reliability, order) {
let response;
if (application === "RPC") {
response = await this.rpcRequest(accountId, {
application,
type: "calculateMargin",
order
});
} else {
response = await this.rpcRequestAllInstances(accountId, {
application,
type: "calculateMargin",
order
}, reliability);
}
return response.margin;
}
/**
* Calls onUnsubscribeRegion listener event
* @param {String} accountId account id
* @param {String} region account region to unsubscribe
*/ async unsubscribeAccountRegion(accountId, region) {
const unsubscribePromises = [];
for (let listener of this._synchronizationListeners[accountId] || []){
unsubscribePromises.push(this._processEvent(()=>listener.onUnsubscribeRegion(region), `${accountId}:${region}:onUnsubscribeRegion`, true).catch((err)=>this._logger.error(`${accountId}:${region}: Failed to notify listener about onUnsubscribeRegion event`, err)));
}
await Promise.all(unsubscribePromises);
}
/**
* Adds synchronization listener for specific account
* @param {String} accountId account id
* @param {SynchronizationListener} listener synchronization listener to add
*/ addSynchronizationListener(accountId, listener) {
this._logger.trace(`${accountId}: Added synchronization listener`);
let listeners = this._synchronizationListeners[accountId];
if (!listeners) {
listeners = [];
this._synchronizationListeners[accountId] = listeners;
}
listeners.push(listener);
}
/**
* Removes synchronization listener for specific account
* @param {String} accountId account id
* @param {SynchronizationListener} listener synchronization listener to remove
*/ removeSynchronizationListener(accountId, listener) {
this._logger.trace(`${accountId}: Removed synchronization listener`);
let listeners = this._synchronizationListeners[accountId];
if (!listeners) {
listeners = [];
}
listeners = listeners.filter((l)=>l !== listener);
this._synchronizationListeners[accountId] = listeners;
}
/**
* Adds latency list