open-api-mt5 0.3.0

REST and WebSocket API project for MetaTrader 5

open-api-mt5

MetaTrader 5 API service with FastAPI.

Important limitation

This API controls a single MT5 terminal/session instance per running service process.

• A single API instance can be connected to only one account at a time.
• /account/connect switches that single active session.
• If you run multiple API services, use separate MT5 terminal instances/data folders for reliable isolation.

Setup

1. Create a virtual environment:
   • Windows PowerShell: python -m venv .venv
2. Activate it:
   • .\.venv\Scripts\Activate.ps1
3. Install dependencies:
   • python -m pip install -U pip
   • pip install -e .

MT5 startup config

The API initializes MetaTrader 5 when FastAPI starts and closes it when FastAPI stops. It also checks MT5 connection every 5 seconds and tries to reconnect automatically if disconnected.

Set these environment variables in PowerShell before running:

$env:MT5_PATH = "C:\Program Files\MetaTrader 5\terminal64.exe"
$env:MT5_LOGIN = "12345678"
$env:MT5_PASSWORD = "your-password"
$env:MT5_SERVER = "YourBroker-Server"

MT5_PATH is optional if MT5 is already discoverable, but setting it is recommended.

Run

open-api-mt5

Optional flags:

open-api-mt5 --port 9000
open-api-mt5 --host 0.0.0.0 --port 8000
open-api-mt5 --reload

Default port is 8000.

API docs:

• Swagger UI: http://127.0.0.1:8000/docs
• WebSocket docs in Swagger:
  • GET /ws/positions/open/docs

Health endpoint:

• GET http://127.0.0.1:8000/health

Account connection endpoints:

• POST http://127.0.0.1:8000/account/connect
  • Body: username, password, server, optional path
  • Example body:

    {
      "username": "12345678",
      "password": "your-password",
      "server": "YourBroker-Server",
      "path": "C:\\Program Files\\MetaTrader 5\\terminal64.exe"
    }
    

• POST http://127.0.0.1:8000/account/disconnect

Trade history endpoint:

• GET http://127.0.0.1:8000/trades/history
• Optional query params: fromDate, toDate (ISO datetime, UTC recommended)
• If omitted, it returns the last 7 days by default

Calendar events endpoint:

• GET http://127.0.0.1:8000/calendar/events
• Optional query params: fromDate, toDate (ISO datetime), country (example: US), currency (example: USD)
• Default range when omitted: last 7 days to next 7 days

WebSocket streams

Open positions stream:

• ws://127.0.0.1:8000/ws/positions/open
• Optional query param: intervalSeconds (poll interval, bounded to 0.2..60)
• Events:
  • subscribed
  • positionsSnapshot
  • error
• positionsSnapshot includes:
  • positions[].pnl (position PnL, sourced from MT5 profit)
  • totalPnl (sum of all open positions PnL)

Example JavaScript client:

const ws = new WebSocket("ws://127.0.0.1:8000/ws/positions/open?intervalSeconds=1");
ws.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  console.log(payload.event, payload);
};

Build and publish package

1. Build distribution files:

python -m pip install --upgrade build twine
python -m build

2. Upload to PyPI:

python -m twine upload dist/*

3. Install from PyPI and run:

pip install open-api-mt5
open-api-mt5 --port 8000

Optional: standalone executable (no Python required on target machine)

If you want users to run it without installing Python, build an executable:

python -m pip install pyinstaller
pyinstaller --onefile --name open-api-mt5 app/cli.py

The executable will be in dist/open-api-mt5.exe.