API reference / Orders

Modify an order

PATCH/v1/accounts/{account}/orders/{order}

Changes a pending order's price, stops and expiry (TRADE_ACTION_MODIFY). Every level is given: MT5 replaces them all.

Waits up to 5 seconds for the broker

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

accountstringrequired

The account's id, acc_ and 26 characters, as the dashboard shows it.

orderintegerrequired

The pending order's ticket.

Headers

Idempotency-Keystringoptional

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 values

pricenumberrequired

MT5 · price

The price the order waits for.

slnumberrequired

MT5 · sl

Stop loss price; 0 removes it.

tpnumberrequired

MT5 · tp

Take profit price; 0 removes it.

type_timeenumrequired

MT5 · type_time

How long the order lasts.

gtcdayspecifiedspecified_day

stoplimitnumberoptional

MT5 · stoplimit

Required when the order is a stop-limit order: the price of the limit order placed once price is reached.

expirationintegeroptional

MT5 · expiration

When the order expires: broker server time, seconds since 1970. Required for type_time specified and specified_day.

Response

requeststring

The request's id (req_...): look it up with GET /requests/{request}.

stateenum

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).

pendingdoneunknownrefused

sentobject

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

actionenum

MT5 · action

What the request does.

dealpendingsltpmodifyremoveclose_by

symbolstring

MT5 · symbol

The symbol, exactly as the broker names it.

typeenum

MT5 · type

The order type.

buysellbuy_limitsell_limitbuy_stopsell_stopbuy_stop_limitsell_stop_limitclose_by

volumenumber

MT5 · volume

Lots.

pricenumber

MT5 · price

The price: a pending order's, or the one instant and request execution trade at.

stoplimitnumber

MT5 · stoplimit

A stop-limit order's limit price, placed once price is reached.

slnumber

MT5 · sl

Stop loss price; 0 for none.

tpnumber

MT5 · tp

Take profit price; 0 for none.

deviationinteger

MT5 · deviation

The largest difference from price MT5 accepts, in points.

type_fillingenum

MT5 · type_filling

How the order may fill.

fokiocreturnboc

type_timeenum

MT5 · type_time

How long a pending order lasts.

gtcdayspecifiedspecified_day

expirationinteger

MT5 · expiration

Broker server time, seconds since 1970, as MT5 takes it.

orderinteger

MT5 · order

The pending order the request is about (modify, remove).

positioninteger

MT5 · position

The position the request is about (close, stops, close by).

position_byinteger

MT5 · position_by

The opposite position, for close by.

magicinteger

MT5 · magic

Your own number, kept by MT5 on the order, its deals and its position.

commentstring

MT5 · comment

Up to 31 characters, kept by MT5 on the order.

resultobjector null

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

retcodeinteger

MT5 · retcode

MT5's return code: see Errors and retcodes.

retcode_nameenum

The return code's name; UNKNOWN for a code MT5 doesn't document.

OKTRADE_RETCODE_REQUOTETRADE_RETCODE_REJECTTRADE_RETCODE_CANCELTRADE_RETCODE_PLACEDTRADE_RETCODE_DONETRADE_RETCODE_DONE_PARTIALTRADE_RETCODE_ERRORTRADE_RETCODE_TIMEOUTTRADE_RETCODE_INVALIDTRADE_RETCODE_INVALID_VOLUMETRADE_RETCODE_INVALID_PRICETRADE_RETCODE_INVALID_STOPSTRADE_RETCODE_TRADE_DISABLEDTRADE_RETCODE_MARKET_CLOSEDTRADE_RETCODE_NO_MONEYTRADE_RETCODE_PRICE_CHANGEDTRADE_RETCODE_PRICE_OFFTRADE_RETCODE_INVALID_EXPIRATIONTRADE_RETCODE_ORDER_CHANGEDTRADE_RETCODE_TOO_MANY_REQUESTSTRADE_RETCODE_NO_CHANGESTRADE_RETCODE_SERVER_DISABLES_ATTRADE_RETCODE_CLIENT_DISABLES_ATTRADE_RETCODE_LOCKEDTRADE_RETCODE_FROZENTRADE_RETCODE_INVALID_FILLTRADE_RETCODE_CONNECTIONTRADE_RETCODE_ONLY_REALTRADE_RETCODE_LIMIT_ORDERSTRADE_RETCODE_LIMIT_VOLUMETRADE_RETCODE_INVALID_ORDERTRADE_RETCODE_POSITION_CLOSEDTRADE_RETCODE_INVALID_CLOSE_VOLUMETRADE_RETCODE_CLOSE_ORDER_EXISTTRADE_RETCODE_LIMIT_POSITIONSTRADE_RETCODE_REJECT_CANCELTRADE_RETCODE_LONG_ONLYTRADE_RETCODE_SHORT_ONLYTRADE_RETCODE_CLOSE_ONLYTRADE_RETCODE_FIFO_CLOSETRADE_RETCODE_HEDGE_PROHIBITEDUNKNOWN

commentstring

MT5 · comment

The broker's comment on the answer.

orderinteger

MT5 · order

The order's ticket, if one was placed.

dealinteger

MT5 · deal

The deal's ticket, if one was made.

positioninteger

The position's ticket, where the trade server gives it.

volumenumber

MT5 · volume

The volume dealt.

pricenumber

MT5 · price

The price dealt.

bidnumber

MT5 · bid

The bid when the request was handled (requotes).

asknumber

MT5 · ask

The ask when the request was handled (requotes).

retcode_externalinteger

MT5 · retcode_external

The external trading system's code, if the broker routes to one.

A refusal: fields

errorstring

What went wrong, as a stable code.

messagestring

What went wrong, for people. Its wording may change.

messagestring

What the answer means, in a sentence.

Errors

400		The ticket in the path is not a whole number. No body.
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 `Authorization: Bearer <key>`.
404	no_such_account	No such account, or one the key's workspace doesn't have: the two look the same.
404	no_such_order	The account has no pending order with that ticket (read fresh from the terminal).
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 (`state: refused`); `result` says why.
504	engine_timeout	The account's engine did not answer within 30 seconds.
504	terminal_timeout	The account's terminal did not answer within 5 seconds.

# A new key for each new trade; send the same one to retry it.
IDEMPOTENCY_KEY=$(uuidgen)

curl -X PATCH "https://api.pipsocket.com/v1/accounts/acc_01m6tx3k9f2qw8r7bznd5yvh4c/orders/881402377" \
  -H "Authorization: Bearer $PIPSOCKET_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 1.074,
    "sl": 1.069,
    "tp": 1.09,
    "type_time": "gtc"
  }'

{
  "message": "The request was completed.",
  "request": "req_5f0c2a9e41d7b3a8c6e2f190",
  "result": {
    "ask": 1.08412,
    "bid": 1.0841,
    "comment": "Request executed",
    "deal": 0,
    "order": 881402377,
    "position": 0,
    "price": 0,
    "retcode": 10009,
    "retcode_external": 0,
    "retcode_name": "TRADE_RETCODE_DONE",
    "volume": 0
  },
  "sent": {
    "action": "modify",
    "comment": "",
    "deviation": 0,
    "expiration": 0,
    "magic": 0,
    "order": 881402377,
    "position": 0,
    "position_by": 0,
    "price": 1.074,
    "sl": 1.069,
    "stoplimit": 0,
    "symbol": "EURUSD",
    "tp": 1.09,
    "type": "buy",
    "type_filling": "fok",
    "type_time": "gtc",
    "volume": 0
  },
  "state": "done"
}

MT5

sent is the exact MqlTradeRequest recorded for the terminal, so you can compare it with MT5's own logs. state and result say whether it reached MT5.