Yellow BoxTrading APIv1 · pre-release

Introduction

REST and WebSocket API for programmatic trading on Yellow Box Markets MT5 accounts.

The conventions (authentication, signing, headers, error envelope, rate-limit model, WebSocket subscribe protocol) are deliberately modelled on the Binance USDⓈ-M Futures API, so an existing Binance client is mostly a matter of changing the base URL, the header name and the field names.

The semantics are MT5, not Binance:

MT5 semantics used here What this replaces
Volume is in lots not contracts or base-asset quantity
Bid / ask quotes, spread priced by the broker no mark price, no index price
Hedging only — many position tickets per symbol, each with its own ticket id no one-way/netting mode, no positionSide
SL/TP live on the position, modified in place no separate stop orders to manage
Swaps charged by the trade server no funding rate, no funding interval
Margin and stop-out are the trade server's no liquidation engine, no ADL, no insurance fund
Symbols are MT5 symbol names, case-sensitive, exact no upper/lower-casing anywhere

There is no wire compatibility with Binance. Field names, enum values and error codes are ours.

Pages

Page Contents
General Info Base URLs, authentication and signing (worked example), the login parameter model, rate limits, HTTP status codes, error shape, data conventions, versioning policy
Market Data Overview ping, time, exchangeInfo, tickers, klines, recent ticks
Order Lifecycle Order lifecycle (read this first), place / modify / cancel orders, positions, batch orders
Account Overview Account state, the logins a key may trade, deal history
User Data Streams Overview listenKey create / keepalive / close
WebSocket Market Streams Overview Connect, subscribe protocol, limits, every market stream
User Data Streams Overview Connect with a listenKey, every account event, ordering and reconnect rules
Common Definition Every enum, with its MT5 integer, and the mt5RetCode table
Error Codes Every error code by family, with exact msg text
Known Limitations Pre-release: where the current trade server falls short of the contract, and what to do meanwhile
Change Log Version history
openapi.yaml Machine-readable OpenAPI 3.1 contract for the REST surface

Quick start

1. Get credentials

The broker issues you an API key and an API secret, plus the list of MT5 logins the key may trade. The secret is shown once and is never recoverable — store it in your secret manager.

A key is bound to a set of logins. Every account-scoped call takes a mandatory login parameter, because one key normally trades many accounts. See general-info.md § The login parameter.

2. Sign a request

SIGNED endpoints take timestamp (Unix ms) and signature (hex HMAC-SHA256 of the request parameters with your secret). Full rules and a reproducible worked example: general-info.md § SIGNED endpoint security.

3. Read the account

cURL / shell
curl -H "X-YBX-APIKEY: <your key>" \
  "https://trade-api.yellowboxmarkets.com/v1/account?login=100123&recvWindow=5000&timestamp=1789012345678&signature=13c783f085a1ef46b6a0e1df8d59c70ab50a4f8e669ffa4a2bc49998c0a9255b"
JSON
{
  "login": 100123,
  "group": "real\\BOT\\ECN",
  "currency": "USD",
  "leverage": 100,
  "balance": "10000.0000",
  "credit": "0.0000",
  "equity": "10012.3400",
  "margin": "233.1200",
  "freeMargin": "9779.2200",
  "marginLevel": "4294.60",
  "profit": "12.3400",
  "tradeAllowed": true,
  "updateTime": 1789012345678
}

4. Place a market order

Default newOrderRespType is ACK — the order is durably queued and the call returns immediately. This is the recommended mode when you fan one signal out across many accounts.

cURL / shell
curl -X POST -H "X-YBX-APIKEY: <your key>" \
  -d "login=100123&symbol=XAUUSD&side=BUY&type=MARKET&volume=0.10&newClientOrderId=bot-001&recvWindow=5000&timestamp=1789012345678&signature=b7f6052aa37e7d6de935cce1c099f8103a2b0a0711b77fdf48becfc8b7d2c0e7" \
  "https://trade-api.yellowboxmarkets.com/v1/order"
JSON
{
  "login": 100123,
  "clientOrderId": "bot-001",
  "symbol": "XAUUSD",
  "side": "BUY",
  "type": "MARKET",
  "volume": "0.10",
  "status": "ACCEPTED",
  "transactTime": 1789012345690
}

newClientOrderId is the idempotency key. Always set it. Resending the same id never creates a second order — see rest-api/trade.md § Order lifecycle.

5. Subscribe to prices

Text
wss://trade-stream.yellowboxmarkets.com/ws
JSON
{"method":"SUBSCRIBE","params":["XAUUSD@tick"],"id":1}
JSON
{"result":null,"id":1}
JSON
{"e":"tick","E":1789012345678,"s":"XAUUSD","b":"2331.15","a":"2331.42","l":"2331.15","v":8,"bd":1,"ad":-1,"T":1789012345678}

6. Subscribe to your own executions

cURL / shell
curl -X POST -H "X-YBX-APIKEY: <your key>" "https://trade-api.yellowboxmarkets.com/v1/listenKey"
JSON
{"listenKey":"pqia91ma19a5s61cv6a81va65sdf19v8a65a1a5s61cv6a81va65sdf19v8a65a1"}

Then connect to wss://trade-stream.yellowboxmarkets.com/ws/<listenKey>. One connection carries events for every login the key may trade; each event carries L (the login). Keep the key alive with PUT /v1/listenKey every 30 minutes. See User Data Streams Overview.

Sandbox

There is no separate testnet host. Sandbox testing runs against the same base URLs with a key scoped to demo-group MT5 logins. Ask the broker for a demo-scoped key; GET /v1/accounts reports "demo": true for those logins. Demo accounts behave identically at the API layer — same signing, same rate limits, same streams.

Do not assume a key is demo-only because you asked for one. Check GET /v1/accounts before your first order. A demo-scoped key lists exactly its demo logins: the broker issues it with an explicit login list and nothing else, so accounts added to your production key never appear on it.

Support

Integration contact, key issuance and incident escalation: to be provided by the broker (placeholder — no public support channel is published for this API yet).

Report a suspected contract bug against a specific endpoint, request id and UTC timestamp. Every response carries the key's rate-limit headers, which help correlate.