API Reference

This section contains the public documentation for mt5api.

The API server must run on Windows because the MetaTrader5 Python package is Windows-only. Run mt5api on a Windows host with MetaTrader 5 installed and logged in. Clients can call the HTTP API from any operating system.

Guides

REST API

FastAPI-based REST API that exposes MT5 market data, account info, trading history, calculations, and non-executing operational endpoints over HTTP with JSON and Parquet support.

Deployment

Windows service deployment guide for hosting the REST API alongside MetaTrader 5.

Architecture Overview

mt5api provides a FastAPI layer on top of the MetaTrader 5 terminal runtime:

  1. API Layer (mt5api.main, mt5api.routers): FastAPI app, routers, and response formatting. Routers are grouped by domain:
  2. health.py: health check, version, last error
  3. symbols.py: symbol listing, details, tick, and total
  4. market.py: OHLCV rates, tick data, and market depth
  5. calc.py: margin and profit calculations
  6. account.py: account and terminal info
  7. history.py: positions, orders, history with totals
  8. trading.py: order check, symbol selection, market book subscriptions
  9. Dependency Layer (mt5api.dependencies): MT5 client lifecycle and format negotiation
  10. Model Layer (mt5api.models): Response schemas and MT5 constant metadata helpers (TIMEFRAME, COPY_TICKS, ORDER_TYPE)
  11. Formatter Layer (mt5api.formatters): JSON and Parquet serialization helpers

Usage Guidelines

  • Type Safety: All endpoints and helpers include comprehensive type hints
  • Error Handling: Centralized through RFC 7807 responses (see REST API docs)
  • Documentation: Google-style docstrings with examples
  • Validation: Pydantic models for requests and responses
  • Data Formats: JSON and Parquet via content negotiation

Quick Start

$env:MT5API_SECRET_KEY = "your-secret-api-key"  # Optional: omit to disable auth
$env:MT5API_ROUTER_PREFIX = "/api/v1"     # Optional: omit for root-level routes
uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000

Replace windows-host with the DNS name or IP address of the Windows machine running mt5api. If you run the request on that Windows host, localhost also works. In PowerShell, use curl.exe if curl resolves to Invoke-WebRequest.

# Include X-API-Key only when MT5API_SECRET_KEY is configured on the server.
curl -H "X-API-Key: your-secret-api-key" "http://windows-host:8000/rates/from?symbol=EURUSD&timeframe=TIMEFRAME_M1&date_from=2024-01-01T00:00:00Z&count=100"

Examples

See the REST API guide for endpoint examples and request syntax.