Getting Started

MT5 Trader is a Python service. Production must run on 64-bit Windows beside a running MetaTrader 5 terminal, because the official MetaTrader5 package is Windows-only. Development, testing, and linting work on any platform thanks to the adapter abstraction and a fake terminal.

Requirements

Python 3.11–3.14.
Production: 64-bit Windows with the MetaTrader 5 desktop terminal installed, logged in to the target account.
Development: any OS (the real MT5 dependency is only installed on Windows).

Install


# From the repo root
cd mt5-trader
 
# Install the package with dev extras
pip install -e ".[dev]"

Configure

On Windows (production), copy a profile template:


Copy-Item .env.example.forex .env
# or for a second broker:
Copy-Item .env.example.deriv .env.deriv

On any OS for local packaging checks:


cp .env.example.forex .env

Key settings (full list on the Architecture page):

Variable	Purpose
`MT5_TERMINAL_PATH`, `MT5_LOGIN`, `MT5_PASSWORD`, `MT5_SERVER`	Terminal path and broker account credentials.
`API_KEY`	Auth key (min 16 chars) required on every request via `X-API-Key`.
`ALLOWED_SYMBOLS`, `ALLOWED_SIGNAL_SOURCES`, `MAXIMUM_VOLUME`, `MAGIC_NUMBER`	Core guardrails, accepted signal providers, and order tagging.
`TRADING_ENABLED`	Fail-safe, default `false`. Readiness returns 503 until this is `true`.
`DATABASE_PATH`	SQLite idempotency ledger (use an absolute path in production).
`NOTIFICATIONS_ENABLED`	Optional fan-out to notification-service after each new signal outcome and after failed inbound requests.

Passwords and the API key are handled as secrets and excluded from logs. Keep .env out of version control.

Run


# Console script (installed by pip)
mt5-signal-service
 
# Profile-scoped (separate env file + port)
mt5-signal-service --profile forex
mt5-signal-service --profile deriv
 
# …or as a module
python -m mt5_signal_service.main

The service binds to HOST:PORT (default 127.0.0.1:8000) with a single worker. Verify it:

GET /health/live — process is up.
GET /health/ready — terminal connected and TRADING_ENABLED=true.
GET /docs — interactive OpenAPI documentation.
Console market_data_probe_completed — every ALLOWED_SYMBOLS entry should report ok before enabling trading.

Do not expose Uvicorn directly. Terminate TLS and network restrictions at a reverse proxy in front of the service. On Windows you can auto-start it via Task Scheduler under the interactive user that owns the terminal — with parallel instances disabled (one task per profile).

Develop & test


pip install -e ".[dev]"
 
pytest                 # full suite (uses a fake MT5 adapter — no Windows needed)
ruff check .           # lint
ruff format --check .  # format check

The MT5-terminal integration test is opt-in and refuses to run against anything but a demo server:


RUN_MT5_DEMO_INTEGRATION=1 pytest -m integration

Next steps

API Reference — the request/response contract.
Architecture — how signals are executed safely.