olza-api-mt5 0.1.0__tar.gz

olza_api_mt5-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: olza-api-mt5
+Version: 0.1.0
+Summary: REST and WebSocket API project for MetaTrader 5
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi<1.0.0,>=0.116.0
+Requires-Dist: MetaTrader5<6.0.0,>=5.0.0
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.35.0
+
+# python-api-mt5
+
+Starter project for a MetaTrader 5 API service with FastAPI.
+
+## 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:
+
+```powershell
+$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
+
+```bash
+olza-api-mt5
+```
+
+Optional flags:
+
+```bash
+olza-api-mt5 --port 9000
+olza-api-mt5 --host 0.0.0.0 --port 8000
+olza-api-mt5 --reload
+```
+
+Default port is `8000`.
+
+API docs:
+- Swagger UI: `http://127.0.0.1:8000/docs`
+- ReDoc: `http://127.0.0.1:8000/redoc`
+
+Health endpoint:
+- `GET http://127.0.0.1:8000/health`
+
+## Build and publish package
+
+1. Build distribution files:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+```
+
+2. Upload to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+3. Install from PyPI and run:
+
+```bash
+pip install olza-api-mt5
+olza-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:
+
+```bash
+python -m pip install pyinstaller
+pyinstaller --onefile --name olza-api-mt5 app/cli.py
+```
+
+The executable will be in `dist/olza-api-mt5.exe`.

olza_api_mt5-0.1.0/README.md

@@ -0,0 +1,85 @@
+# python-api-mt5
+
+Starter project for a MetaTrader 5 API service with FastAPI.
+
+## 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:
+
+```powershell
+$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
+
+```bash
+olza-api-mt5
+```
+
+Optional flags:
+
+```bash
+olza-api-mt5 --port 9000
+olza-api-mt5 --host 0.0.0.0 --port 8000
+olza-api-mt5 --reload
+```
+
+Default port is `8000`.
+
+API docs:
+- Swagger UI: `http://127.0.0.1:8000/docs`
+- ReDoc: `http://127.0.0.1:8000/redoc`
+
+Health endpoint:
+- `GET http://127.0.0.1:8000/health`
+
+## Build and publish package
+
+1. Build distribution files:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+```
+
+2. Upload to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+3. Install from PyPI and run:
+
+```bash
+pip install olza-api-mt5
+olza-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:
+
+```bash
+python -m pip install pyinstaller
+pyinstaller --onefile --name olza-api-mt5 app/cli.py
+```
+
+The executable will be in `dist/olza-api-mt5.exe`.

olza_api_mt5-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+"""OLZA MT5 API package."""

olza_api_mt5-0.1.0/app/cli.py

@@ -0,0 +1,14 @@
+import argparse
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the OLZA MT5 API server.")
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host. Default: 127.0.0.1")
+    parser.add_argument("--port", type=int, default=int(os.getenv("PORT", "8000")), help="Bind port. Default: 8000")
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload for development")
+    args = parser.parse_args()
+
+    uvicorn.run("app.main:app", host=args.host, port=args.port, reload=args.reload)

olza_api_mt5-0.1.0/app/main.py

@@ -0,0 +1,268 @@
+import os
+import asyncio
+from contextlib import asynccontextmanager
+
+import MetaTrader5 as mt5
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from app.services.account_service import get_account_info
+from app.services.bar_service import get_last_ohlc_bars
+from app.services.symbol_service import get_symbol_details, search_symbols
+from app.services.ticket_service import get_all_tickets
+from app.services.trade_service import close_by_ticket, create_market_order, list_open_positions, list_pending_orders
+
+
+class CreateOrderRequest(BaseModel):
+    symbol: str
+    side: str
+    volume: float
+    orderType: str = "market"
+    price: float | None = None
+    stopLimit: float | None = None
+    deviation: int = 20
+    sl: float | None = None
+    tp: float | None = None
+    magic: int = 0
+    comment: str = "api-order"
+
+
+class CloseOrderRequest(BaseModel):
+    ticket: int
+    volume: float | None = None
+    deviation: int = 20
+    comment: str = "api-close"
+
+
+def _initialize_mt5() -> tuple[bool, str]:
+    terminal_path = os.getenv("MT5_PATH")
+    login_raw = os.getenv("MT5_LOGIN")
+    password = os.getenv("MT5_PASSWORD")
+    server = os.getenv("MT5_SERVER")
+
+    init_kwargs: dict[str, object] = {}
+    if terminal_path:
+        init_kwargs["path"] = terminal_path
+    if login_raw:
+        try:
+            init_kwargs["login"] = int(login_raw)
+        except ValueError:
+            return False, "failed: MT5_LOGIN must be a number"
+    if password:
+        init_kwargs["password"] = password
+    if server:
+        init_kwargs["server"] = server
+
+    initialized = mt5.initialize(**init_kwargs)
+    if initialized:
+        return True, "connected"
+
+    last_error = mt5.last_error()
+    return False, f"failed: {last_error}"
+
+
+def _check_mt5_connection() -> tuple[bool, str]:
+    terminal_info = mt5.terminal_info()
+    if terminal_info is None:
+        return False, "disconnected"
+    return True, "connected"
+
+
+async def _mt5_monitor_loop(app_instance: FastAPI, interval_seconds: int = 5) -> None:
+    while True:
+        connected, message = _check_mt5_connection()
+        if not connected:
+            mt5_ok, mt5_message = _initialize_mt5()
+            app_instance.state.mt5_ok = mt5_ok
+            app_instance.state.mt5_message = mt5_message
+        else:
+            app_instance.state.mt5_ok = True
+            app_instance.state.mt5_message = message
+
+        await asyncio.sleep(interval_seconds)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    mt5_ok, mt5_message = _initialize_mt5()
+    app.state.mt5_ok = mt5_ok
+    app.state.mt5_message = mt5_message
+    monitor_task = asyncio.create_task(_mt5_monitor_loop(app))
+    try:
+        yield
+    finally:
+        monitor_task.cancel()
+        try:
+            await monitor_task
+        except asyncio.CancelledError:
+            pass
+        mt5.shutdown()
+
+app = FastAPI(
+    title="MT5 API",
+    version="0.1.0",
+    description="Starter FastAPI service for MetaTrader 5 integration.",
+    lifespan=lifespan,
+)
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {
+        "status": "ok",
+        "mt5": "connected" if app.state.mt5_ok else app.state.mt5_message,
+    }
+
+
+@app.get("/account")
+def account() -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = get_account_info()
+    if not ok:
+        raise HTTPException(status_code=500, detail=str(data))
+
+    return {"account": data}
+
+
+@app.get("/tickets")
+def tickets() -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = get_all_tickets()
+    if not ok:
+        raise HTTPException(status_code=500, detail=str(data))
+
+    return data
+
+
+@app.get("/symbols")
+def symbols(query: str | None = None) -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = search_symbols(query=query)
+    if not ok:
+        raise HTTPException(status_code=500, detail=str(data))
+
+    return data
+
+
+@app.get("/symbols/{name}")
+def symbol_details(name: str) -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = get_symbol_details(name=name)
+    if not ok:
+        raise HTTPException(status_code=404, detail=str(data))
+
+    return {"symbol": data}
+
+
+@app.get("/bars/{symbol}")
+def bars(symbol: str, timeframe: str = "M1", n: int = 100, include_volume: bool = False) -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    if n <= 0:
+        raise HTTPException(status_code=400, detail="n must be greater than 0")
+    if n > 10_000:
+        raise HTTPException(status_code=400, detail="n must be less than or equal to 10000")
+
+    ok, data = get_last_ohlc_bars(
+        symbol=symbol,
+        timeframe=timeframe,
+        count=n,
+        include_volume=include_volume,
+    )
+    if not ok:
+        error_message = str(data)
+        if "unsupported timeframe" in error_message:
+            raise HTTPException(status_code=400, detail=error_message)
+        if "symbol not found" in error_message:
+            raise HTTPException(status_code=404, detail=error_message)
+        raise HTTPException(status_code=500, detail=error_message)
+
+    return data
+
+
+@app.post("/orders")
+def create_order(payload: CreateOrderRequest) -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = create_market_order(
+        symbol=payload.symbol,
+        side=payload.side,
+        volume=payload.volume,
+        orderType=payload.orderType,
+        price=payload.price,
+        stopLimit=payload.stopLimit,
+        deviation=payload.deviation,
+        sl=payload.sl,
+        tp=payload.tp,
+        magic=payload.magic,
+        comment=payload.comment,
+    )
+    if not ok:
+        error_message = str(data)
+        if (
+            "side must be" in error_message
+            or "volume must be" in error_message
+            or "orderType must be" in error_message
+            or "required for" in error_message
+        ):
+            raise HTTPException(status_code=400, detail=error_message)
+        if "symbol not found" in error_message:
+            raise HTTPException(status_code=404, detail=error_message)
+        raise HTTPException(status_code=500, detail=error_message)
+
+    return data
+
+
+@app.get("/positions/open")
+def open_positions() -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = list_open_positions()
+    if not ok:
+        raise HTTPException(status_code=500, detail=str(data))
+
+    return data
+
+
+@app.get("/orders/pending")
+def pending_orders() -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = list_pending_orders()
+    if not ok:
+        raise HTTPException(status_code=500, detail=str(data))
+
+    return data
+
+
+@app.post("/orders/close")
+def close_order(payload: CloseOrderRequest) -> dict:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = close_by_ticket(
+        ticket=payload.ticket,
+        volume=payload.volume,
+        deviation=payload.deviation,
+        comment=payload.comment,
+    )
+    if not ok:
+        error_message = str(data)
+        if "ticket must be" in error_message or "volume " in error_message:
+            raise HTTPException(status_code=400, detail=error_message)
+        if "ticket not found" in error_message:
+            raise HTTPException(status_code=404, detail=error_message)
+        raise HTTPException(status_code=500, detail=error_message)
+
+    return data

olza_api_mt5-0.1.0/app/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer for OLZA MT5 API."""

olza_api_mt5-0.1.0/app/services/account_service.py

@@ -0,0 +1,18 @@
+from typing import Any
+
+import MetaTrader5 as mt5
+
+
+def get_account_info() -> tuple[bool, dict[str, Any] | str]:
+    """
+    Fetch account information from the active MT5 session.
+
+    Returns:
+        (True, account_info_dict) on success
+        (False, error_message) on failure
+    """
+    account_info = mt5.account_info()
+    if account_info is None:
+        return False, f"failed to fetch account info: {mt5.last_error()}"
+
+    return True, account_info._asdict()

olza_api_mt5-0.1.0/app/services/bar_service.py

@@ -0,0 +1,79 @@
+from datetime import datetime, timezone
+from typing import Any
+
+import MetaTrader5 as mt5
+
+
+_TIMEFRAME_MAP: dict[str, int] = {
+    "M1": mt5.TIMEFRAME_M1,
+    "M2": mt5.TIMEFRAME_M2,
+    "M3": mt5.TIMEFRAME_M3,
+    "M4": mt5.TIMEFRAME_M4,
+    "M5": mt5.TIMEFRAME_M5,
+    "M6": mt5.TIMEFRAME_M6,
+    "M10": mt5.TIMEFRAME_M10,
+    "M12": mt5.TIMEFRAME_M12,
+    "M15": mt5.TIMEFRAME_M15,
+    "M20": mt5.TIMEFRAME_M20,
+    "M30": mt5.TIMEFRAME_M30,
+    "H1": mt5.TIMEFRAME_H1,
+    "H2": mt5.TIMEFRAME_H2,
+    "H3": mt5.TIMEFRAME_H3,
+    "H4": mt5.TIMEFRAME_H4,
+    "H6": mt5.TIMEFRAME_H6,
+    "H8": mt5.TIMEFRAME_H8,
+    "H12": mt5.TIMEFRAME_H12,
+    "D1": mt5.TIMEFRAME_D1,
+    "W1": mt5.TIMEFRAME_W1,
+    "MN1": mt5.TIMEFRAME_MN1,
+}
+
+
+def get_last_ohlc_bars(
+    symbol: str,
+    timeframe: str,
+    count: int,
+    include_volume: bool = False,
+) -> tuple[bool, dict[str, Any] | str]:
+    """
+    Fetch the last N OHLC bars for a symbol and timeframe.
+
+    Returns:
+        (True, payload) on success
+        (False, error_message) on failure
+    """
+    timeframe_value = _TIMEFRAME_MAP.get(timeframe.upper())
+    if timeframe_value is None:
+        supported = ", ".join(_TIMEFRAME_MAP.keys())
+        return False, f"unsupported timeframe '{timeframe}'. supported: {supported}"
+
+    symbol_info = mt5.symbol_info(symbol)
+    if symbol_info is None:
+        return False, f"symbol not found or unavailable: {symbol}"
+
+    if not symbol_info.visible and not mt5.symbol_select(symbol, True):
+        return False, f"failed to select symbol '{symbol}': {mt5.last_error()}"
+
+    rates = mt5.copy_rates_from_pos(symbol, timeframe_value, 0, count)
+    if rates is None:
+        return False, f"failed to fetch bars: {mt5.last_error()}"
+
+    bars: list[dict[str, Any]] = []
+    for rate in rates:
+        bar = {
+            "time": datetime.fromtimestamp(int(rate["time"]), tz=timezone.utc).isoformat(),
+            "open": float(rate["open"]),
+            "high": float(rate["high"]),
+            "low": float(rate["low"]),
+            "close": float(rate["close"]),
+        }
+        if include_volume:
+            bar["volume"] = int(rate["tick_volume"])
+        bars.append(bar)
+
+    return True, {
+        "symbol": symbol,
+        "timeframe": timeframe.upper(),
+        "count": len(bars),
+        "bars": bars,
+    }

olza_api_mt5-0.1.0/app/services/symbol_service.py

@@ -0,0 +1,43 @@
+from typing import Any
+
+import MetaTrader5 as mt5
+
+
+def search_symbols(query: str | None = None) -> tuple[bool, dict[str, Any] | str]:
+    """
+    Fetch all available symbols, optionally filtered by substring.
+
+    Returns:
+        (True, payload) on success
+        (False, error_message) on failure
+    """
+    symbols = mt5.symbols_get()
+    if symbols is None:
+        return False, f"failed to fetch symbols: {mt5.last_error()}"
+
+    if query:
+        lowered_query = query.lower()
+        filtered_symbols = [symbol.name for symbol in symbols if lowered_query in symbol.name.lower()]
+    else:
+        filtered_symbols = [symbol.name for symbol in symbols]
+
+    return True, {
+        "query": query,
+        "count": len(filtered_symbols),
+        "symbols": filtered_symbols,
+    }
+
+
+def get_symbol_details(name: str) -> tuple[bool, dict[str, Any] | str]:
+    """
+    Fetch details for a single symbol by its exact name.
+
+    Returns:
+        (True, payload) on success
+        (False, error_message) on failure
+    """
+    symbol_info = mt5.symbol_info(name)
+    if symbol_info is None:
+        return False, f"symbol not found or unavailable: {name}"
+
+    return True, symbol_info._asdict()

olza_api_mt5-0.1.0/app/services/ticket_service.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+import MetaTrader5 as mt5
+
+
+def get_all_tickets() -> tuple[bool, dict[str, Any] | str]:
+    """
+    Fetch currently available MT5 tickets from open positions and active orders.
+
+    Returns:
+        (True, payload) on success
+        (False, error_message) on failure
+    """
+    positions = mt5.positions_get()
+    if positions is None:
+        return False, f"failed to fetch positions: {mt5.last_error()}"
+
+    orders = mt5.orders_get()
+    if orders is None:
+        return False, f"failed to fetch orders: {mt5.last_error()}"
+
+    position_tickets = [int(position.ticket) for position in positions]
+    order_tickets = [int(order.ticket) for order in orders]
+
+    return True, {
+        "position_tickets": position_tickets,
+        "order_tickets": order_tickets,
+        "total": len(position_tickets) + len(order_tickets),
+    }

olza_api_mt5-0.1.0/app/services/trade_service.py

@@ -0,0 +1,265 @@
+from typing import Any
+
+import MetaTrader5 as mt5
+
+
+def _to_jsonable(value: Any) -> Any:
+    if hasattr(value, "_asdict"):
+        return {k: _to_jsonable(v) for k, v in value._asdict().items()}
+    if isinstance(value, dict):
+        return {k: _to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_to_jsonable(item) for item in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def _ensure_symbol(symbol: str) -> tuple[bool, str | Any]:
+    info = mt5.symbol_info(symbol)
+    if info is None:
+        return False, f"symbol not found or unavailable: {symbol}"
+
+    if not info.visible and not mt5.symbol_select(symbol, True):
+        return False, f"failed to select symbol '{symbol}': {mt5.last_error()}"
+
+    return True, info
+
+
+def _resolve_filling_mode(info: Any) -> int:
+    mode = int(info.filling_mode)
+    allowed = {mt5.ORDER_FILLING_FOK, mt5.ORDER_FILLING_IOC, mt5.ORDER_FILLING_RETURN}
+    if mode in allowed:
+        return mode
+    return mt5.ORDER_FILLING_RETURN
+
+
+def _filling_candidates(info: Any) -> list[int]:
+    primary = _resolve_filling_mode(info)
+    fallback_order = [primary, mt5.ORDER_FILLING_RETURN, mt5.ORDER_FILLING_IOC, mt5.ORDER_FILLING_FOK]
+    candidates: list[int] = []
+    for filling in fallback_order:
+        if filling not in candidates:
+            candidates.append(filling)
+    return candidates
+
+
+def _send_with_filling_fallback(request: dict[str, Any], info: Any) -> Any:
+    last_result = None
+    for filling in _filling_candidates(info):
+        req = dict(request)
+        req["type_filling"] = filling
+        result = mt5.order_send(req)
+        if result is None:
+            last_result = None
+            continue
+        last_result = result
+        if int(getattr(result, "retcode", -1)) != mt5.TRADE_RETCODE_INVALID_FILL:
+            return result
+    return last_result
+
+
+def create_market_order(
+    symbol: str,
+    side: str,
+    volume: float,
+    orderType: str = "market",
+    price: float | None = None,
+    stopLimit: float | None = None,
+    deviation: int = 20,
+    sl: float | None = None,
+    tp: float | None = None,
+    magic: int = 0,
+    comment: str = "api-order",
+) -> tuple[bool, dict[str, Any] | str]:
+    normalized_side = side.lower()
+    if normalized_side not in {"buy", "sell"}:
+        return False, "side must be 'buy' or 'sell'"
+    if volume <= 0:
+        return False, "volume must be greater than 0"
+
+    orderTypeKey = orderType.replace("_", "").lower()
+    orderTypeMap = {
+        "market": "market",
+        "limit": "limit",
+        "stop": "stop",
+        "stoplimit": "stopLimit",
+    }
+    normalized_order_type = orderTypeMap.get(orderTypeKey)
+    supportedKinds = {"market", "limit", "stop", "stopLimit"}
+    if normalized_order_type not in supportedKinds:
+        return False, "orderType must be one of: market, limit, stop, stopLimit"
+
+    ok, info_or_error = _ensure_symbol(symbol)
+    if not ok:
+        return False, str(info_or_error)
+    symbol_info = info_or_error
+
+    tick = mt5.symbol_info_tick(symbol)
+    if tick is None:
+        return False, f"failed to fetch tick for symbol '{symbol}': {mt5.last_error()}"
+
+    is_buy = normalized_side == "buy"
+
+    if normalized_order_type == "market":
+        action = mt5.TRADE_ACTION_DEAL
+        orderTypeValue = mt5.ORDER_TYPE_BUY if is_buy else mt5.ORDER_TYPE_SELL
+        order_price = float(tick.ask if is_buy else tick.bid)
+    elif normalized_order_type == "limit":
+        if price is None:
+            return False, "price is required for limit orders"
+        action = mt5.TRADE_ACTION_PENDING
+        orderTypeValue = mt5.ORDER_TYPE_BUY_LIMIT if is_buy else mt5.ORDER_TYPE_SELL_LIMIT
+        order_price = float(price)
+    elif normalized_order_type == "stop":
+        if price is None:
+            return False, "price is required for stop orders"
+        action = mt5.TRADE_ACTION_PENDING
+        orderTypeValue = mt5.ORDER_TYPE_BUY_STOP if is_buy else mt5.ORDER_TYPE_SELL_STOP
+        order_price = float(price)
+    else:
+        if price is None:
+            return False, "price is required for stopLimit orders"
+        if stopLimit is None:
+            return False, "stopLimit is required for stopLimit orders"
+        action = mt5.TRADE_ACTION_PENDING
+        orderTypeValue = mt5.ORDER_TYPE_BUY_STOP_LIMIT if is_buy else mt5.ORDER_TYPE_SELL_STOP_LIMIT
+        order_price = float(price)
+
+    request: dict[str, Any] = {
+        "action": action,
+        "symbol": symbol,
+        "volume": float(volume),
+        "type": orderTypeValue,
+        "price": order_price,
+        "deviation": int(deviation),
+        "magic": int(magic),
+        "comment": comment,
+        "type_time": mt5.ORDER_TIME_GTC,
+    }
+    if normalized_order_type == "stopLimit":
+        request["stoplimit"] = float(stopLimit)
+    if sl is not None:
+        request["sl"] = float(sl)
+    if tp is not None:
+        request["tp"] = float(tp)
+
+    result = _send_with_filling_fallback(request, symbol_info)
+    if result is None:
+        return False, f"order_send failed: {mt5.last_error()}"
+
+    result_dict = _to_jsonable(result)
+    result_comment = str(getattr(result, "comment", ""))
+    return True, {
+        "retcode": result.retcode,
+        "success": result.retcode == mt5.TRADE_RETCODE_DONE,
+        "message": result_comment,
+        "hint": (
+            "Enable AutoTrading in the MT5 terminal and allow algorithmic trading."
+            if "AutoTrading disabled by client" in result_comment
+            else None
+        ),
+        "result": result_dict,
+    }
+
+
+def list_open_positions() -> tuple[bool, dict[str, Any] | str]:
+    positions = mt5.positions_get()
+    if positions is None:
+        return False, f"failed to fetch positions: {mt5.last_error()}"
+
+    payload = [_to_jsonable(position) for position in positions]
+    return True, {
+        "count": len(payload),
+        "positions": payload,
+    }
+
+
+def list_pending_orders() -> tuple[bool, dict[str, Any] | str]:
+    orders = mt5.orders_get()
+    if orders is None:
+        return False, f"failed to fetch pending orders: {mt5.last_error()}"
+
+    payload = [_to_jsonable(order) for order in orders]
+    return True, {
+        "count": len(payload),
+        "orders": payload,
+    }
+
+
+def close_by_ticket(
+    ticket: int,
+    volume: float | None = None,
+    deviation: int = 20,
+    comment: str = "api-close",
+) -> tuple[bool, dict[str, Any] | str]:
+    if ticket <= 0:
+        return False, "ticket must be greater than 0"
+
+    pending_orders = mt5.orders_get(ticket=ticket)
+    if pending_orders is not None and len(pending_orders) > 0:
+        remove_request = {
+            "action": mt5.TRADE_ACTION_REMOVE,
+            "order": int(ticket),
+            "comment": comment,
+        }
+        remove_result = mt5.order_send(remove_request)
+        if remove_result is None:
+            return False, f"failed to cancel order: {mt5.last_error()}"
+        return True, {
+            "operation": "cancel_pending_order",
+            "retcode": remove_result.retcode,
+            "success": remove_result.retcode == mt5.TRADE_RETCODE_DONE,
+            "result": _to_jsonable(remove_result),
+        }
+
+    positions = mt5.positions_get(ticket=ticket)
+    if positions is None:
+        return False, f"failed to fetch ticket {ticket}: {mt5.last_error()}"
+    if len(positions) == 0:
+        return False, f"ticket not found in open positions or pending orders: {ticket}"
+
+    position = positions[0]
+    close_volume = float(volume) if volume is not None else float(position.volume)
+    if close_volume <= 0:
+        return False, "volume must be greater than 0"
+    if close_volume > float(position.volume):
+        return False, f"volume exceeds position volume ({position.volume})"
+
+    symbol = str(position.symbol)
+    ok, info_or_error = _ensure_symbol(symbol)
+    if not ok:
+        return False, str(info_or_error)
+    symbol_info = info_or_error
+
+    tick = mt5.symbol_info_tick(symbol)
+    if tick is None:
+        return False, f"failed to fetch tick for symbol '{symbol}': {mt5.last_error()}"
+
+    is_buy_position = int(position.type) == mt5.POSITION_TYPE_BUY
+    close_type = mt5.ORDER_TYPE_SELL if is_buy_position else mt5.ORDER_TYPE_BUY
+    close_price = float(tick.bid if is_buy_position else tick.ask)
+
+    close_request: dict[str, Any] = {
+        "action": mt5.TRADE_ACTION_DEAL,
+        "position": int(position.ticket),
+        "symbol": symbol,
+        "volume": close_volume,
+        "type": close_type,
+        "price": close_price,
+        "deviation": int(deviation),
+        "magic": int(position.magic),
+        "comment": comment,
+        "type_time": mt5.ORDER_TIME_GTC,
+    }
+
+    close_result = _send_with_filling_fallback(close_request, symbol_info)
+    if close_result is None:
+        return False, f"failed to close position: {mt5.last_error()}"
+
+    return True, {
+        "operation": "close_position",
+        "retcode": close_result.retcode,
+        "success": close_result.retcode == mt5.TRADE_RETCODE_DONE,
+        "result": _to_jsonable(close_result),
+    }

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: olza-api-mt5
+Version: 0.1.0
+Summary: REST and WebSocket API project for MetaTrader 5
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi<1.0.0,>=0.116.0
+Requires-Dist: MetaTrader5<6.0.0,>=5.0.0
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.35.0
+
+# python-api-mt5
+
+Starter project for a MetaTrader 5 API service with FastAPI.
+
+## 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:
+
+```powershell
+$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
+
+```bash
+olza-api-mt5
+```
+
+Optional flags:
+
+```bash
+olza-api-mt5 --port 9000
+olza-api-mt5 --host 0.0.0.0 --port 8000
+olza-api-mt5 --reload
+```
+
+Default port is `8000`.
+
+API docs:
+- Swagger UI: `http://127.0.0.1:8000/docs`
+- ReDoc: `http://127.0.0.1:8000/redoc`
+
+Health endpoint:
+- `GET http://127.0.0.1:8000/health`
+
+## Build and publish package
+
+1. Build distribution files:
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+```
+
+2. Upload to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+3. Install from PyPI and run:
+
+```bash
+pip install olza-api-mt5
+olza-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:
+
+```bash
+python -m pip install pyinstaller
+pyinstaller --onefile --name olza-api-mt5 app/cli.py
+```
+
+The executable will be in `dist/olza-api-mt5.exe`.

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+app/__init__.py
+app/cli.py
+app/main.py
+app/services/__init__.py
+app/services/account_service.py
+app/services/bar_service.py
+app/services/symbol_service.py
+app/services/ticket_service.py
+app/services/trade_service.py
+olza_api_mt5.egg-info/PKG-INFO
+olza_api_mt5.egg-info/SOURCES.txt
+olza_api_mt5.egg-info/dependency_links.txt
+olza_api_mt5.egg-info/entry_points.txt
+olza_api_mt5.egg-info/requires.txt
+olza_api_mt5.egg-info/top_level.txt

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+olza-api-mt5 = app.cli:main

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/requires.txt

@@ -0,0 +1,3 @@
+fastapi<1.0.0,>=0.116.0
+MetaTrader5<6.0.0,>=5.0.0
+uvicorn[standard]<1.0.0,>=0.35.0

olza_api_mt5-0.1.0/olza_api_mt5.egg-info/top_level.txt

@@ -0,0 +1 @@
+app

olza_api_mt5-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "olza-api-mt5"
+version = "0.1.0"
+description = "REST and WebSocket API project for MetaTrader 5"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.116.0,<1.0.0",
+    "MetaTrader5>=5.0.0,<6.0.0",
+    "uvicorn[standard]>=0.35.0,<1.0.0",
+]
+
+[project.scripts]
+olza-api-mt5 = "app.cli:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

olza_api_mt5-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+