Skip to content

Trade#

About#

Execute a trade on a connected MetaTrader account

For more information see Async api documentation

Request#

In order to execute a trade, your application needs to emit request event with one of the payloads below.

General part of the request#

Name Type Required Description
type string Yes request type, must be trade if you want to execute trade
accountId string Yes MetaTrader account id. You can retrieve account id from Web application after you add your MetaTrader account to our platform. The account id can also be obtained via Provisioning API
requestId string Yes request id which your application must supply. Request id must be unique during an API connection
application string MetaApi application id. Default is MetaApi
trade object Yes trade to execute. Allowed trade types are explained below.

Each table below describes the contents of the trade field.

The following describes schemas for each type of command.

ORDER_TYPE_SELL or ORDER_TYPE_BUY#

Submits market order to the trading terminal

Name Type Required Description
actionType string Yes action type, enum: ORDER_TYPE_SELL, ORDER_TYPE_BUY
symbol string Yes symbol to trade
volume number Yes order volume, min: 0
stopLoss number stop loss price, min: 0
takeProfit number take profit price, min: 0
comment string order 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 clientId usage
clientId string client-assigned id. The id value will be present on position, history orders and history deals related to this order. 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 clientId usage
magic number magic number (expert adviser id)
slippage number slippage in points. Should be greater or equal to zero. In not set, default value specified in account entity will be used. Slippage is ignored on position modification, order modification and order cancellation calls. Slippage is also ignored if execution mode set in symbol specification is SYMBOL_TRADE_EXECUTION_MARKET.
fillingModes array allowed filling modes in the order of priority. Default is to allow all filling modes and prefer ORDER_FILLING_FOK over ORDER_FILLING_IOC. See https://www.mql5.com/en/docs/constants/tradingconstants/orderproperties#enum_order_type_filling for extra explanation.
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '7529dcb2-3a73-4abb-9b48-32d57c71ffdb',
    trade: {
        actionType: 'ORDER_TYPE_SELL',
        symbol: 'AUDNZD',
        volume: 0.07
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46870472"
  },
  "requestId": "7529dcb2-3a73-4abb-9b48-32d57c71ffdb",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

ORDER_TYPE_BUY_LIMIT or ORDER_TYPE_SELL_LIMIT or ORDER_TYPE_BUY_STOP or ORDER_TYPE_SELL_STOP#

Submits pending order to the trading terminal

Name Type Required Description
actionType string Yes action type, enum: ORDER_TYPE_BUY_LIMIT, ORDER_TYPE_SELL_LIMIT, ORDER_TYPE_BUY_STOP, ORDER_TYPE_SELL_STOP
symbol string Yes symbol to trade
volume number Yes order volume, min: 0
openPrice number Yes order limit or stop price, min: 0
stopLoss number stop loss price, min: 0
takeProfit number take profit price, min: 0
comment string order 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 clientId usage
clientId string client-assigned id. The id value will be present on position, history orders and history deals related to this order. 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 clientId usage
magic number magic number (expert adviser id)
slippage number slippage in points. Should be greater or equal to zero. In not set, default value specified in account entity will be used. Slippage is ignored on position modification, order modification and order cancellation calls. Slippage is also ignored if execution mode set in symbol specification is SYMBOL_TRADE_EXECUTION_MARKET.
expiration object pending order expiration settings. See Pending order expiration settings section.
Pending order expiration settings#
Name Type Required Description
type string Yes pending order expiration type. See https://www.mql5.com/en/docs/constants/tradingconstants/orderproperties#enum_order_type_time for the list of possible options. MetaTrader4 platform supports only ORDER_TIME_SPECIFIED expiration type. enum: ORDER_TIME_GTC, ORDER_TIME_DAY, ORDER_TIME_SPECIFIED, ORDER_TIME_SPECIFIED_DAY.
time datetime pending order expiration time. Ignored if expiration type is not one of ORDER_TIME_DAY or ORDER_TIME_SPECIFIED
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '24436428-1826-4181-a851-8c9a6af7f3f3',
    trade: {
        actionType: 'ORDER_TYPE_BUY_LIMIT',
        symbol: 'AUDNZD',
        volume: 0.01,
        openPrice: 1.03
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46871284"
  },
  "requestId": "24436428-1826-4181-a851-8c9a6af7f3f3",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

POSITION_MODIFY#

Modifies a position TP/SL price

Name Type Required Description
actionType string Yes action type, enum: POSITION_MODIFY
positionId string Yes position id (ticket number)
stopLoss number stop loss price, min: 0
takeProfit number take profit price, min: 0
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: 'f093a900-a18d-4e85-96d6-3f5519be68ba',
    trade: {
        actionType: 'POSITION_MODIFY',
        positionId: '46648037',
        stopLoss: 1.03
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "positionId": "46648037"
  },
  "requestId": "f093a900-a18d-4e85-96d6-3f5519be68ba",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

POSITION_PARTIAL#

Partially closes a position

Name Type Required Description
actionType string Yes action type, enum: POSITION_PARTIAL
positionId string Yes position id
volume number Yes volume to close, min: 0
comment string order 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 clientId usage
clientId string client-assigned id. The id value will be present on history orders and history deals related to this order. 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 clientId usage
magic number magic number (expert adviser id)
slippage number slippage in points. Should be greater or equal to zero. In not set, default value specified in account entity will be used. Slippage is ignored on position modification, order modification and order cancellation calls. Slippage is also ignored if execution mode set in symbol specification is SYMBOL_TRADE_EXECUTION_MARKET.
fillingModes array allowed filling modes in the order of priority. Default is to allow all filling modes and prefer ORDER_FILLING_FOK over ORDER_FILLING_IOC. See https://www.mql5.com/en/docs/constants/tradingconstants/orderproperties#enum_order_type_filling for extra explanation.
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '4eda6936-9bf2-43ac-a01f-3408e305a713',
    trade: {
        actionType: 'POSITION_PARTIAL',
        positionId: '46648037',
        volume: 0.01
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46873685",
    "positionId": "46648037"
  },
  "requestId": "4eda6936-9bf2-43ac-a01f-3408e305a713",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

POSITION_CLOSE_ID#

Closes a position fully

Name Type Required Description
actionType string Yes action type, enum: POSITION_CLOSE_ID
positionId string Yes position id
comment string order 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 clientId usage
clientId string client-assigned id. The id value will be present on history orders and history deals related to this order. 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 clientId usage
magic number magic number (expert adviser id)
slippage number slippage in points. Should be greater or equal to zero. In not set, default value specified in account entity will be used. Slippage is ignored on position modification, order modification and order cancellation calls. Slippage is also ignored if execution mode set in symbol specification is SYMBOL_TRADE_EXECUTION_MARKET.
fillingModes array allowed filling modes in the order of priority. Default is to allow all filling modes and prefer ORDER_FILLING_FOK over ORDER_FILLING_IOC. See https://www.mql5.com/en/docs/constants/tradingconstants/orderproperties#enum_order_type_filling for extra explanation.
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '5aa530cc-3ef9-4b77-8868-5cbde81b2f5d',
    trade: {
        actionType: 'POSITION_CLOSE_ID',
        positionId: '46732826'
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46879076",
    "positionId": "46732826"
  },
  "requestId": "5aa530cc-3ef9-4b77-8868-5cbde81b2f5d",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

POSITIONS_CLOSE_SYMBOL#

Close positions by a symbol

Name Type Required Description
actionType string Yes action type, enum: POSITIONS_CLOSE_SYMBOL
symbol string Yes symbol to trade
comment string order 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 clientId usage
clientId string client-assigned id. The id value will be present on history orders and history deals related to this order. 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 clientId usage
magic number magic number (expert adviser id)
slippage number slippage in points. Should be greater or equal to zero. In not set, default value specified in account entity will be used. Slippage is ignored on position modification, order modification and order cancellation calls. Slippage is also ignored if execution mode set in symbol specification is SYMBOL_TRADE_EXECUTION_MARKET.
fillingModes array allowed filling modes in the order of priority. Default is to allow all filling modes and prefer ORDER_FILLING_FOK over ORDER_FILLING_IOC. See https://www.mql5.com/en/docs/constants/tradingconstants/orderproperties#enum_order_type_filling for extra explanation.
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '8f471ac1-3a69-4e9f-96a9-a3e14e7a9795',
    trade: {
        actionType: 'POSITIONS_CLOSE_SYMBOL',
        symbol: 'AUDNZD'
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46879076",
    "positionId": "46732826"
  },
  "requestId": "8f471ac1-3a69-4e9f-96a9-a3e14e7a9795",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

Response example for an account that does not support this feature:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10006,
    "stringCode": "TRADE_RETCODE_REJECT",
    "message": "Request completed"
  },
  "requestId": "15bf7f0b-e09d-4df7-90ba-ca8c38ad802d",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

ORDER_MODIFY#

Modifies a pending order

Name Type Required Description
actionType string Yes action type, enum: ORDER_MODIFY
orderId string Yes order id (ticket number)
openPrice number Yes limit or stop price, required for a pending order, min: 0
stopLoss number stop loss price, min: 0
takeProfit number take profit price, min: 0
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '2c9e36ad-ab5c-4aa0-ba1d-451b4dfe3b86',
    trade: {
        actionType: 'ORDER_MODIFY',
        orderId: '46871284',
        openPrice: 1.03,
        stopLoss: 1.05
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46870472"
  },
  "requestId": "2c9e36ad-ab5c-4aa0-ba1d-451b4dfe3b86",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

ORDER_CANCEL#

Cancels an order

Name Type Required Description
actionType string Yes action type, enum: ORDER_CANCEL
orderId string Yes order id (ticket number)
Examples#

Code example:

import ioClient from 'socket.io-client';

const socket = ioClient('https://mt-client-api-v1.agiliumtrade.agiliumtrade.ai', {
    path: '/ws',
    reconnection: false,
    query: {
        'auth-token': 'token'
    }
});

const request = {
    accountId: '865d3a4d-3803-486d-bdf3-a85679d9fad2',
    type: 'trade',
    requestId: '28d4492c-bfc7-40d3-9c3f-0a9203a9c285',
    trade: {
        actionType: 'ORDER_CANCEL',
        orderId: '46871284'
    }
};

socket.on('connect', () => {
    socket.emit('request', request);
});

socket.on('response', response => {
    console.log(response);
});

socket.on('processingError', err => {
  console.error(err);
});

Response example:

{
  "type": "tradeResult",
  "response": {
    "numericCode": 10009,
    "stringCode": "TRADE_RETCODE_DONE",
    "message": "Request completed",
    "orderId": "46871284"
  },
  "requestId": "28d4492c-bfc7-40d3-9c3f-0a9203a9c285",
  "accountId": "865d3a4d-3803-486d-bdf3-a85679d9fad2"
}

Response#

After executing your request the API server will emit response event with the following payload.

Name Type Required Description
type string Yes The value of this field will be tradeResult in the response to the above request
requestId string Yes request id the response relates to
accountId string Yes account id specified in the request
response object Yes trade result. Schema: Trade Response