YBX Trading API

API Description

Opens a market position or places a pending order.

HTTP Request

HTTP

POST /v1/order

Request Weight

1 (1 against ORDERS)

Request Parameters

Name	Type	Mandatory	Description
`login`	LONG	YES	MT5 account.
`symbol`	STRING	YES	Exact, case-sensitive.
`type`	ENUM	YES	`MARKET`, `BUY_LIMIT`, `SELL_LIMIT`, `BUY_STOP`, `SELL_STOP`, `BUY_STOP_LIMIT`, `SELL_STOP_LIMIT`.
`side`	ENUM	conditional	`BUY` or `SELL`. Mandatory for `MARKET`. For every pending type the side is implied by the type; if sent it must agree, otherwise `-1117`.
`volume`	DECIMAL	YES	Lots. Must be greater than `0` (`-4003`) and satisfy `volumeMin` (`-4006`), `volumeMax` (`-4005`) and `volumeStep` (`-4007`).
`price`	DECIMAL	conditional	Mandatory for every pending type, greater than `0` (`-4001`). Ignored for `MARKET` — a market order always fills at the server's price.
`stopLimitPrice`	DECIMAL	conditional	Mandatory for `BUY_STOP_LIMIT` and `SELL_STOP_LIMIT`: the limit price the order is placed at once `price` is touched. Sending it with any other `type` is `-1106`.
`sl`	DECIMAL	NO	Stop loss. `0` or omitted means none. Negative is `-4001`.
`tp`	DECIMAL	NO	Take profit. `0` or omitted means none. Negative is `-4001`.
`timeInForce`	ENUM	NO	Pending orders only — sending it on `MARKET` is `-1106`. `GTC` (default), `DAY`, `GTD`, `GTD_DAY`. Must be in the symbol's `expirationModes` (`-4012`).
`expiration`	LONG	conditional	Mandatory for `GTD` and `GTD_DAY` (`-1102`). Unix ms, greater than `0` (`-4012`).
`newClientOrderId`	STRING	NO	Idempotency key. Up to 36 characters, `[A-Za-z0-9-_.]` (`-1119` otherwise), unique per key. Strongly recommended.
`newOrderRespType`	ENUM	NO	`ACK` (default) or `RESULT`.
`comment`	STRING	NO	Up to 24 characters (`-1130` if longer). Stored on the MT5 order and deal and visible to the broker and the account holder. The service appends a short correlation tag of its own, so the comment you see back on a deal is longer than the one you sent — see Comments and deal attribution. Not a substitute for `newClientOrderId`.
`recvWindow`	LONG	NO	Default `5000`, max `60000`.
`timestamp`	LONG	YES
`signature`	STRING	YES

Mandatory parameters by type

`type`	Mandatory
`MARKET`	`login`, `symbol`, `type`, `side`, `volume`
`BUY_LIMIT`, `SELL_LIMIT`	`login`, `symbol`, `type`, `volume`, `price`
`BUY_STOP`, `SELL_STOP`	`login`, `symbol`, `type`, `volume`, `price`
`BUY_STOP_LIMIT`, `SELL_STOP_LIMIT`	`login`, `symbol`, `type`, `volume`, `price`, `stopLimitPrice`

Additionally, expiration is mandatory whenever timeInForce is GTD or GTD_DAY.

Price rules

Type	`price` must be
`BUY_LIMIT`	below the current ask
`SELL_LIMIT`	above the current bid
`BUY_STOP`	above the current ask
`SELL_STOP`	below the current bid
`BUY_STOP_LIMIT`	above the current ask; `stopLimitPrice` is the resulting buy-limit price
`SELL_STOP_LIMIT`	below the current bid; `stopLimitPrice` is the resulting sell-limit price

Violating these is -2021. Every price (price, stopLimitPrice, sl, tp) must be a multiple of tickSize (-4008), and must keep stopsLevel points of distance (-4009) from the price MT5 measures it against:

a pending order's price — from the market on its opening side (ask for a buy, bid for a sell);
sl / tp on a market order — from the market on its closing side (bid for a buy, ask for a sell);
sl / tp on a pending order — from the price the order will open at (stopLimitPrice for a stop-limit, price otherwise), not from the market.

These pre-flight checks need a fresh quote; when the service has none, the trade server performs them instead and the error carries its mt5RetCode.

The symbol's rules are checked too: tradeMode (-4011 disabled, -4013 long only, -4014 short only, -4015 close only), orderModes (-4016 for a type — or an sl / tp — the symbol does not allow) and expirationModes (-4012). An unknown symbol is -1121.

A retry with a newClientOrderId this key already used skips all of this and returns the stored outcome — see Idempotency.

Response Example

Response — ACK (default)

JSON

{
  "login": 100123,
  "clientOrderId": "bot-001",
  "symbol": "XAUUSD",
  "side": "BUY",
  "type": "MARKET",
  "volume": "0.10",
  "status": "ACCEPTED",
  "transactTime": 1789012345690
}

Response — RESULT, market order filled

JSON

{
  "login": 100123,
  "clientOrderId": "bot-001",
  "symbol": "XAUUSD",
  "side": "BUY",
  "type": "MARKET",
  "volume": "0.10",
  "status": "FILLED",
  "orderId": 44412345,
  "dealId": 55512345,
  "positionId": 44412345,
  "price": "2331.42",
  "executedVolume": "0.10",
  "sl": "2320.00",
  "tp": "2350.00",
  "mt5RetCode": 10009,
  "transactTime": 1789012345812
}

Response — pending order placed (RESULT)

JSON

{
  "login": 100123,
  "clientOrderId": "bot-002",
  "symbol": "XAUUSD",
  "side": "BUY",
  "type": "BUY_LIMIT",
  "volume": "0.10",
  "status": "NEW",
  "orderId": 44412350,
  "price": "2325.00",
  "timeInForce": "GTC",
  "mt5RetCode": 10008,
  "transactTime": 1789012345812
}

Response — rejected (HTTP 400)

JSON

{
  "code": -2018,
  "msg": "Insufficient margin on the trading account.",
  "mt5RetCode": 10019,
  "status": "REJECTED",
  "clientOrderId": "bot-003",
  "login": 100123
}

When the order was recorded and then rejected, the error body carries status, clientOrderId and login in addition to the standard envelope, so the rejection can be correlated without a second lookup. A request refused before it was recorded — a validation error such as -1102, -4007 or -2022 — returns the plain {"code","msg"} envelope.

Fields whose value is unknown or does not apply are omitted, not sent as null: an ACK response carries no orderId, dealId, positionId, price or executedVolume, and sl, tp and expiration are absent when the order has none.

Response fields

Field	Type	Description
`login`	LONG
`clientOrderId`	STRING	Yours if you sent one, otherwise generated.
`symbol`	STRING
`side`	ENUM	`BUY` / `SELL`. Derived from `type` for pending orders.
`type`	ENUM	As sent.
`volume`	DECIMAL	Requested volume, lots.
`status`	ENUM	See Status values.
`orderId`	LONG	MT5 order ticket. Absent until the server assigns one.
`dealId`	LONG	MT5 deal ticket. Market fills only.
`positionId`	LONG	MT5 position ticket. Market fills only. Under hedging it is typically equal to `orderId` for a newly opened position, but do not rely on that — use the value returned.
`price`	DECIMAL	Fill price for a market order; order price for a pending order.
`executedVolume`	DECIMAL	Filled volume, lots. May be less than `volume` on a partial fill.
`sl` / `tp`	DECIMAL	As sent. Absent when none was set.
`timeInForce`	ENUM	Pending orders only.
`expiration`	LONG	Pending orders only, Unix ms. Absent when none was set.
`mt5RetCode`	INT	The trade server's raw return code, when it answered.
`transactTime`	LONG	When the API produced this response, Unix ms.

POSTNew order (TRADE)

API Description

HTTP Request

Request Weight

Request Parameters

Response Example