# MetaTrader 5 Trading API

Source: https://fxsocket.com/docs/mt5/trading

Place, modify, and close MetaTrader 5 orders over a REST API: market and pending orders, partial closes, plus margin and profit calculators for position sizing. Every order executes inside your own dedicated MT5 terminal, never a shared gateway.

Base URL: `https://api.fxsocket.com/mt5/{account_id}`

Order routes are executed inside your own terminal. A 200 response only means MT5 returned a result; always inspect success and retcode to confirm the broker accepted it.

### POST /mt5/{account_id}/OrderSend

Submit a market or pending order. Market (Buy/Sell) needs symbol + volume; price is ignored. Pending (*Limit/*Stop) additionally needs price; StopLimit variants also need stopLimitPrice. Optional: slippage (default 10 points), stopLoss, takeProfit, expiration (absent → good-till-cancelled), comment, expertId (a.k.a. magic).

Parameters:

- `symbol` (required): Symbol to trade, e.g. EURUSD.
- `operation` (required): Buy, Sell, BuyLimit, SellLimit, BuyStop, SellStop, BuyStopLimit, SellStopLimit (case- and separator-insensitive).
- `volume` (required): Volume in lots.
- `price`: Required for pending orders; ignored for market orders.
- `stopLimitPrice`: Required for *StopLimit operations.
- `stopLoss / takeProfit`: Optional SL/TP prices.
- `slippage`: Max slippage in points (default 10).
- `expiration`: Date string; absent → good-till-cancelled.
- `comment / expertId`: Order comment and magic number.

Request body:

```json
{
  "symbol": "EURUSD",
  "operation": "Buy",
  "volume": 0.1,
  "stopLoss": 1.14800,
  "takeProfit": 1.16200,
  "comment": "my-strategy",
  "expertId": 123456
}
```

Example request:

```bash
curl -X POST https://api.fxsocket.com/mt5/{account_id}/OrderSend \
  -H "X-API-Key: fxs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"symbol":"EURUSD","operation":"Buy","volume":0.1,"stopLoss":1.148,"takeProfit":1.162,"comment":"my-strategy","expertId":123456}'
```

Response:

```json
{
  "success": true,
  "retcode": 10009,
  "retcodeDescription": "Request completed",
  "deal": 211438760,
  "order": 211438761,
  "volume": 0.1,
  "price": 1.15333,
  "bid": 1.15325,
  "ask": 1.15333,
  "comment": ""
}
```

### POST /mt5/{account_id}/OrderModify

Modify an existing position or pending order. The ticket type decides what's modifiable: a position ticket accepts only stopLoss and takeProfit; a pending-order ticket also accepts price, stopLimitPrice, and expiration. Omit a field to keep its current value.

Parameters:

- `ticket` (required): Position or pending-order ticket.
- `stopLoss / takeProfit`: New SL/TP; omit to keep current.
- `price`: New price (pending orders only).
- `stopLimitPrice`: New StopLimit price (*StopLimit pendings only).
- `expiration`: New expiration (date string), pending orders only.

Request body:

```json
{
  "ticket": 211438761,
  "stopLoss": 1.15000,
  "takeProfit": 1.16500
}
```

Example request:

```bash
curl -X POST https://api.fxsocket.com/mt5/{account_id}/OrderModify \
  -H "X-API-Key: fxs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ticket":211438761,"stopLoss":1.15,"takeProfit":1.165}'
```

Response:

```json
{
  "success": true,
  "retcode": 10009,
  "retcodeDescription": "Request completed",
  "deal": 0,
  "order": 211438761,
  "volume": 0.0,
  "price": 0.0,
  "bid": 1.15325,
  "ask": 1.15333,
  "comment": ""
}
```

### POST /mt5/{account_id}/OrderClose

Close a position or delete a pending order: the action is inferred from the ticket type. For a position, supply volume for a partial close (must respect the symbol's volumeStep) or omit it for a full close. For a pending order, volume is ignored and the order is deleted.

Parameters:

- `ticket` (required): Position ticket (closes it) or pending-order ticket (deletes it).
- `volume`: Partial close volume; omit or 0 = full close.
- `slippage`: Max slippage in points.

Request body:

```json
{
  "ticket": 211438761,
  "volume": 0.05
}
```

Example request:

```bash
curl -X POST https://api.fxsocket.com/mt5/{account_id}/OrderClose \
  -H "X-API-Key: fxs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ticket":211438761,"volume":0.05}'
```

Response:

```json
{
  "success": true,
  "retcode": 10009,
  "retcodeDescription": "Request completed",
  "deal": 211438770,
  "order": 211438771,
  "volume": 0.05,
  "price": 1.15325,
  "bid": 1.15325,
  "ask": 1.15333,
  "comment": ""
}
```

### GET /mt5/{account_id}/OrderCalcMargin

Required margin for a hypothetical order. Asks MT5 to compute the broker-side margin needed to open the given volume at the given price, returned in the account currency. Does not place an order, purely a sizing/risk query.

Parameters:

- `symbol` (required): Symbol name as listed by /symbols.
- `operation` (required): Buy, Sell, BuyLimit, SellLimit, BuyStop, SellStop, BuyStopLimit, SellStopLimit.
- `volume` (required): Volume in lots.
- `price` (required): Hypothetical entry price.

Example request:

```bash
curl -H "X-API-Key: fxs_live_..." \
  "https://api.fxsocket.com/mt5/{account_id}/OrderCalcMargin?symbol=EURUSD&operation=Buy&volume=0.1&price=1.15333"
```

Response:

```json
{
  "symbol": "EURUSD",
  "operation": "Buy",
  "volume": 0.1,
  "price": 1.15333,
  "margin": 28.83,
  "currency": "USD"
}
```

### GET /mt5/{account_id}/OrderCalcProfit

Projected P&L for a hypothetical open → close move, returned in the account currency. Does not place an order, useful for position sizing and UI.

Parameters:

- `symbol` (required): Symbol name as listed by /symbols.
- `operation` (required): Buy or Sell (pending variants accepted, only the direction is used).
- `volume` (required): Volume in lots.
- `priceOpen` (required): Hypothetical open price.
- `priceClose` (required): Hypothetical close price.

Example request:

```bash
curl -H "X-API-Key: fxs_live_..." \
  "https://api.fxsocket.com/mt5/{account_id}/OrderCalcProfit?symbol=EURUSD&operation=Buy&volume=0.1&priceOpen=1.15333&priceClose=1.16333"
```

Response:

```json
{
  "symbol": "EURUSD",
  "operation": "Buy",
  "volume": 0.1,
  "priceOpen": 1.15333,
  "priceClose": 1.16333,
  "profit": 100.0,
  "currency": "USD"
}
```

## Related

- [Account Data](https://fxsocket.com/docs/mt5/account-data.md)
- [Market Data](https://fxsocket.com/docs/mt5/market-data.md)
- [Errors & Rate Limits](https://fxsocket.com/docs/mt5/errors.md)