# 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](/general-info.md) | 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](/market-data.md) | `ping`, `time`, `exchangeInfo`, tickers, klines, recent ticks |
| [Order Lifecycle](/trade.md) | **Order lifecycle** (read this first), place / modify / cancel orders, positions, batch orders |
| [Account Overview](/account.md) | Account state, the logins a key may trade, deal history |
| [User Data Streams Overview](/user-data-streams.md#listenkey-management) | `listenKey` create / keepalive / close |
| [WebSocket Market Streams Overview](/websocket-market-streams.md) | Connect, subscribe protocol, limits, every market stream |
| [User Data Streams Overview](/user-data-streams.md) | Connect with a `listenKey`, every account event, ordering and reconnect rules |
| [Common Definition](/common-definition.md) | Every enum, with its MT5 integer, and the `mt5RetCode` table |
| [Error Codes](/error-codes.md) | Every error code by family, with exact `msg` text |
| [Known Limitations](/known-limitations.md) | **Pre-release:** where the current trade server falls short of the contract, and what to do meanwhile |
| [Change Log](/changelog.md) | Version history |
| [openapi.yaml](/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](/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](/general-info.md#signed-endpoint-security-trade-and-user_data).

### 3. Read the account

```bash
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.

```bash
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](/trade.md#order-lifecycle).

### 5. Subscribe to prices

```
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

```bash
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](/user-data-streams.md).

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