Place an order
Sends one trade request (MT5's TRADE_ACTION_DEAL for buy and sell, TRADE_ACTION_PENDING for the rest) to the account's terminal, with the stop loss and take profit in the same request, and waits up to 5 seconds for the trade server's answer. The request goes as you send it: nothing is split, retried, rounded or adjusted.
If the trade server has not answered by then, you get 202 with "state": "pending" and the request's id in request. It is never sent again: look the request up to see how it ended, or watch for it on the stream.
Path
The account's id, acc_ and 26 characters, as the dashboard shows it.
Headers
Your own key for this request, 1 to 128 characters. A request with a key the account has used before (in the last 7 days) is not sent: the first request's answer comes back instead, as it stands now.
Body
Left out: MT5's empty valuesThe symbol exactly as the broker names it, such as EURUSD.
What to send. buy and sell fill now; the others wait at price. close_by is refused here: use Close by.
Lots. MT5 rejects a volume outside the symbol's minimum, maximum and step.
How the order may fill. Required: each symbol allows its own modes (its filling_modes).
Required for pending orders: the price the order waits for. For a market order it is sent as given (0 if left out): brokers with instant or request execution need it, those with market or exchange execution ignore it.
Required for buy_stop_limit and sell_stop_limit: the price of the limit order placed once price is reached.
Stop loss price, set in the same request. 0 or left out: none.
Take profit price, set in the same request. 0 or left out: none.
The largest difference from price MT5 accepts, in points, for instant or request execution.
How long a pending order lasts. gtc if left out.
When a pending order expires: broker server time, seconds since 1970. Required for type_time specified and specified_day.
Your own number for the order, kept by MT5 on the order, its deals and its position.
Up to 31 characters, kept by MT5 on the order. Brokers may replace it.
Response
The request's id (req_...): look it up with GET /requests/{request}.
A trade request's state: pending (sent, no answer yet: never sent again), done (MT5 answered: filled, placed or rejected, as result.retcode says), unknown (no answer within 130 seconds; it becomes done if the terminal reports the answer later) or refused (the terminal did not send it).
MT5's MqlTradeRequest, field for field, exactly as recorded to send to the terminal: the request's state and result say whether it reached MT5. Fields the call does not use carry MT5's empty values (0, "", fok, gtc).
Fields of sent
What the request does.
The symbol, exactly as the broker names it.
The order type.
Lots.
The price: a pending order's, or the one instant and request execution trade at.
A stop-limit order's limit price, placed once price is reached.
Stop loss price; 0 for none.
Take profit price; 0 for none.
The largest difference from price MT5 accepts, in points.
How the order may fill.
How long a pending order lasts.
Broker server time, seconds since 1970, as MT5 takes it.
The pending order the request is about (modify, remove).
The position the request is about (close, stops, close by).
The opposite position, for close by.
Your own number, kept by MT5 on the order, its deals and its position.
Up to 31 characters, kept by MT5 on the order.
MT5's MqlTradeResult once done; why it was not sent once refused; otherwise null.
MT5's `MqlTradeResult`, as the trade server (or the terminal, refusing to send) answered: fields
MT5's return code: see Errors and retcodes.
The return code's name; UNKNOWN for a code MT5 doesn't document.
The broker's comment on the answer.
The order's ticket, if one was placed.
The deal's ticket, if one was made.
The position's ticket, where the trade server gives it.
The volume dealt.
The price dealt.
The bid when the request was handled (requotes).
The ask when the request was handled (requotes).
The external trading system's code, if the broker routes to one.
A refusal: fields
What went wrong, as a stable code.
What went wrong, for people. Its wording may change.
What the answer means, in a sentence.
Errors
| 401 | invalid_api_key | The key is not a workspace's current key (a rolled key stops working within about a minute). |
| 401 | missing_api_key | No API key: send it as |
| 404 | no_such_account | No such account, or one the key's workspace doesn't have: the two look the same. |
| 422 | invalid_request | A field, query parameter or header is missing, malformed or not allowed, or the body is not JSON. Nothing was sent. |
| 423 | kill_switch_engaged | The account's kill switch is engaged: new orders and changes to pending orders are refused until it is lifted. Nothing was sent. |
| 503 | account_not_connected | The account's terminal is not connected to the engine (stopped, starting, or restarting). Nothing was sent, except by the kill switch: engaging it still engages it, and may already have deleted pending orders. |
| 503 | account_restarting | The account's terminal is being replaced. Nothing was sent; try again in a minute. |
| 503 | bridge_outdated | The account's terminal runs an older bridge that can't trade: restart the account to update it. Nothing was sent. |
| 503 | engine_busy | The account's engine host has too many calls in flight (256). Nothing was done; try again. |
| 503 | engine_unavailable | The account's engine host is not connected to Pipsocket, or disconnected while the call waited. A trade it already had is still settled: look it up. |
| 503 | refused | A stored request the terminal did not send ( |
| 504 | engine_timeout | The account's engine did not answer within 30 seconds. |