> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novosky.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MT5 REST API

> Overview of the self-hosted MetaTrader 5 REST API used by NOVOSKY. All bot-to-broker communication goes through this API.

## Overview

NOVOSKY does not use the MetaTrader5 Python package. All broker communication goes through a self-hosted HTTP API running on your MT5 server.

**Base URL:** `https://novosky.app/terminal/` (or your own self-hosted instance)

**OpenAPI spec:** [`/openapi.json`](https://novosky.app/terminal/openapi.json)

**Authentication:** Bearer token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer <API_TOKEN>" https://novosky.app/terminal/ping
```

Set `API_TOKEN` in your `.env` to match the token configured on the server. The `/ping` endpoint is the only one that skips authentication.

***

## Endpoint groups

The API is organized into seven tag groups — all auto-generated in the sidebar:

| Group     | Endpoints                                                                | Description                                           |
| --------- | ------------------------------------------------------------------------ | ----------------------------------------------------- |
| System    | `/ping`, `/ping/broker`, `/error`                                        | Health, broker latency, last error                    |
| Terminal  | `/terminal`, `/terminal/init`, `/terminal/restart`, `/terminal/shutdown` | MT5 terminal lifecycle                                |
| Time      | `/time`                                                                  | Broker server time vs UTC — detects server UTC offset |
| Account   | `/account`                                                               | Live balance, equity, margin                          |
| Symbols   | `/symbols`, `/symbols/{symbol}`, `/tick`, `/ticks`, `/rates`             | Symbol specs and market data                          |
| Positions | `/positions`, `/positions/{ticket}`                                      | Open position management                              |
| Orders    | `/orders`, `/orders/{ticket}`                                            | Order placement and management                        |
| History   | `/history/deals`, `/history/orders`                                      | Closed deals and orders                               |

***

## Response format

All endpoints return JSON. HTTP helpers in `trading/bot.py` parse responses into `SimpleNamespace` objects:

```python theme={null}
account = api_get("/account")
print(account.balance, account.equity)

tick = api_get("/symbols/BTCUSD/tick")
print(tick.bid, tick.ask)
```

***

## Error handling

Non-2xx responses include a `retcode` field with the MT5 error code. The bot logs errors and sends a Telegram alert automatically.

```json theme={null}
{ "retcode": 10014, "message": "Invalid stops" }
```

Common retcodes:

| Code  | Meaning                                  |
| ----- | ---------------------------------------- |
| 10009 | Success                                  |
| 10014 | Invalid stops (SL/TP too close to price) |
| 10018 | Market is closed                         |
| 10019 | Insufficient funds                       |
| 10024 | Too many requests                        |

***

## Broker server time

`GET /time` returns the broker's server timestamp alongside machine UTC, so you can verify the detected UTC offset. Optionally pass `?symbol=BTCUSD` to pin which symbol's tick is used.

```json theme={null}
{
  "utc_epoch": 1777879028,
  "utc_iso": "2026-05-04T07:17:08+00:00",
  "server_epoch": 1777879029,
  "server_iso": "2026-05-04T07:17:09+00:00",
  "utc_offset_hours": 0,
  "utc_offset_seconds": 0,
  "used_symbol": "BTCUSD"
}
```

The bot auto-detects this offset at startup and uses it to normalise broker candle timestamps to UTC. If the market is closed and no tick is available, `server_epoch` will be `null` and the bot falls back to `broker_utc_offset_fallback_hours` in `config.json`.

***

## Spread conversion

`GET /symbols/{symbol}/rates` returns `spread` in raw points. For BTCUSD on RoboForex:

```
1400 pts × $0.01 = $14.00 round-turn spread
```

`trading.py` handles this automatically.

***

## Order types

`POST /orders` accepts the following `type` values:

```
BUY, SELL
BUY_LIMIT, SELL_LIMIT
BUY_STOP, SELL_STOP
BUY_STOP_LIMIT, SELL_STOP_LIMIT
```

The NOVOSKY bot only places `BUY` and `SELL` market orders. The other types are available for manual use.