open-api-mt5 0.3.0__py3-none-any.whl

app/__init__.py

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

app/cli.py

@@ -0,0 +1,14 @@
+import argparse
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the Open 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)

app/main.py

@@ -0,0 +1,560 @@
+import os
+import asyncio
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import Any
+
+import MetaTrader5 as mt5
+from fastapi import FastAPI, HTTPException, Query, WebSocket, WebSocketDisconnect
+from pydantic import BaseModel, Field
+from app.services.account_service import get_account_info
+from app.services.bar_service import get_last_ohlc_bars
+from app.services.calendar_service import list_calendar_events
+from app.services.connection_service import initialize_connection, shutdown_connection
+from app.services.stream_service import get_open_positions_snapshot
+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, list_trade_history
+
+
+class CreateOrderRequest(BaseModel):
+    symbol: str = Field(..., description="Trading symbol (example: EURUSD).")
+    side: str = Field(..., description="Order side. Allowed values: buy, sell.", examples=["buy"])
+    volume: float = Field(..., gt=0, description="Order lot size.")
+    orderType: str = Field(
+        "market",
+        description="Order type. Allowed values: market, limit, stop, stopLimit.",
+        examples=["market"],
+    )
+    price: float | None = Field(None, description="Trigger/entry price. Required for limit, stop, and stopLimit.")
+    stopLimit: float | None = Field(None, description="Stop-limit price. Required only when orderType is stopLimit.")
+    deviation: int = Field(20, ge=0, description="Maximum slippage in points.")
+    sl: float | None = Field(None, description="Stop loss price.")
+    tp: float | None = Field(None, description="Take profit price.")
+    magic: int = Field(0, description="Client strategy identifier (magic number).")
+    comment: str = Field("api-order", description="Comment attached to the order.")
+
+
+class CloseOrderRequest(BaseModel):
+    ticket: int = Field(..., gt=0, description="Position/order ticket to close or cancel.")
+    volume: float | None = Field(None, gt=0, description="Partial close volume. If omitted, closes full position size.")
+    deviation: int = Field(20, ge=0, description="Maximum slippage in points.")
+    comment: str = Field("api-close", description="Comment attached to close/cancel operation.")
+
+
+class HealthResponse(BaseModel):
+    status: str = Field(..., description="API health indicator.")
+    mt5: str = Field(..., description="MT5 connection status or error message.")
+
+
+class AccountResponse(BaseModel):
+    account: dict[str, Any] = Field(..., description="Account payload from MT5. Keys are camelCase.")
+
+
+class ConnectAccountRequest(BaseModel):
+    username: str = Field(..., description="MT5 account login/username (numeric).")
+    password: str = Field(..., description="MT5 account password.")
+    server: str = Field(..., description="MT5 broker server name.")
+    path: str | None = Field(None, description="Optional MT5 terminal executable path.")
+
+
+class ConnectionResponse(BaseModel):
+    success: bool = Field(..., description="True when MT5 connect/disconnect action succeeds.")
+    mt5: str = Field(..., description="Connection status or error message.")
+
+
+class TicketsResponse(BaseModel):
+    positionTickets: list[int] = Field(..., description="Open position ticket IDs.")
+    orderTickets: list[int] = Field(..., description="Pending order ticket IDs.")
+    total: int = Field(..., description="Total number of tickets.")
+
+
+class SymbolsResponse(BaseModel):
+    query: str | None = Field(None, description="Search filter used for symbols.")
+    count: int = Field(..., description="Number of symbols returned.")
+    symbols: list[str] = Field(..., description="List of symbol names.")
+
+
+class SymbolDetailsResponse(BaseModel):
+    symbol: dict[str, Any] = Field(..., description="Detailed symbol attributes from MT5. Keys are camelCase.")
+
+
+class BarItem(BaseModel):
+    time: str = Field(..., description="Bar timestamp in ISO-8601 format (UTC).")
+    open: float = Field(..., description="Open price.")
+    high: float = Field(..., description="High price.")
+    low: float = Field(..., description="Low price.")
+    close: float = Field(..., description="Close price.")
+    volume: int | None = Field(None, description="Tick volume when includeVolume=true.")
+
+
+class BarsResponse(BaseModel):
+    symbol: str = Field(..., description="Symbol used in the query.")
+    timeframe: str = Field(..., description="Requested timeframe.")
+    count: int = Field(..., description="Number of bars returned.")
+    bars: list[BarItem] = Field(..., description="OHLC bars.")
+
+
+class OrderExecutionResponse(BaseModel):
+    retcode: int = Field(..., description="MT5 return code.")
+    success: bool = Field(..., description="True when MT5 reports successful execution.")
+    message: str = Field(..., description="MT5 execution message.")
+    hint: str | None = Field(None, description="Actionable hint when available.")
+    result: dict[str, Any] = Field(..., description="Raw MT5 execution result. Keys are camelCase.")
+
+
+class OpenPositionsResponse(BaseModel):
+    count: int = Field(..., description="Number of open positions.")
+    positions: list[dict[str, Any]] = Field(..., description="Open positions payload. Keys are camelCase.")
+
+
+class PendingOrdersResponse(BaseModel):
+    count: int = Field(..., description="Number of pending orders.")
+    orders: list[dict[str, Any]] = Field(..., description="Pending orders payload. Keys are camelCase.")
+
+
+class TradeHistoryResponse(BaseModel):
+    fromDate: str = Field(..., description="Start datetime used for history query (ISO-8601, UTC).")
+    toDate: str = Field(..., description="End datetime used for history query (ISO-8601, UTC).")
+    count: int = Field(..., description="Number of trade records returned.")
+    trades: list[dict[str, Any]] = Field(..., description="Historical deal records from MT5. Keys are camelCase.")
+
+
+class CloseOrderResponse(BaseModel):
+    operation: str = Field(..., description="Executed operation type: closePosition or cancelPendingOrder.")
+    retcode: int = Field(..., description="MT5 return code.")
+    success: bool = Field(..., description="True when MT5 reports successful execution.")
+    result: dict[str, Any] = Field(..., description="Raw MT5 close/cancel result. Keys are camelCase.")
+
+
+class CalendarEventsResponse(BaseModel):
+    fromDate: str = Field(..., description="Start datetime used for calendar query (ISO-8601, UTC).")
+    toDate: str = Field(..., description="End datetime used for calendar query (ISO-8601, UTC).")
+    country: str | None = Field(None, description="Country filter used in query.")
+    currency: str | None = Field(None, description="Currency filter used in query.")
+    count: int = Field(..., description="Number of calendar events returned.")
+    events: list[dict[str, Any]] = Field(..., description="Calendar event/value entries from MT5. Keys are camelCase.")
+
+
+class WebSocketDocsResponse(BaseModel):
+    stream: str = Field(..., description="Logical stream name.")
+    websocketPath: str = Field(..., description="Relative WebSocket path.")
+    websocketExampleUrl: str = Field(..., description="Example URL to connect from a client.")
+    queryParams: dict[str, str] = Field(..., description="Supported query parameters and value constraints.")
+    events: list[str] = Field(..., description="Event types emitted by the stream.")
+    sampleMessages: list[dict[str, Any]] = Field(..., description="Sample messages sent by the server.")
+
+
+def _utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _bounded_interval(value: float, minimum: float = 0.2, maximum: float = 60.0) -> float:
+    return max(minimum, min(maximum, value))
+
+
+def _initialize_mt5() -> tuple[bool, str]:
+    connection_config = getattr(app.state, "mt5_connection_config", None)
+    if connection_config is None:
+        connection_config = {
+            "path": os.getenv("MT5_PATH"),
+            "username": os.getenv("MT5_LOGIN"),
+            "password": os.getenv("MT5_PASSWORD"),
+            "server": os.getenv("MT5_SERVER"),
+        }
+        app.state.mt5_connection_config = connection_config
+    return initialize_connection(
+        username=connection_config.get("username"),
+        password=connection_config.get("password"),
+        server=connection_config.get("server"),
+        path=connection_config.get("path"),
+    )
+
+
+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:
+            if getattr(app_instance.state, "auto_reconnect", True):
+                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 = False
+                app_instance.state.mt5_message = "disconnected"
+        else:
+            app_instance.state.mt5_ok = True
+            app_instance.state.mt5_message = message
+
+        await asyncio.sleep(interval_seconds)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    app.state.mt5_connection_config = {
+        "path": os.getenv("MT5_PATH"),
+        "username": os.getenv("MT5_LOGIN"),
+        "password": os.getenv("MT5_PASSWORD"),
+        "server": os.getenv("MT5_SERVER"),
+    }
+    app.state.auto_reconnect = True
+    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,
+    openapi_tags=[
+        {"name": "Health", "description": "Service and MT5 connection status."},
+        {"name": "Account", "description": "Account information endpoints."},
+        {"name": "Tickets", "description": "Active position and order tickets."},
+        {"name": "Symbols", "description": "Symbol search and metadata."},
+        {"name": "Market Data", "description": "Historical market bars."},
+        {"name": "Orders", "description": "Order creation, pending orders, and close/cancel."},
+        {"name": "Positions", "description": "Open position endpoints."},
+        {"name": "Trades", "description": "Trade history endpoints."},
+        {"name": "Calendar", "description": "Economic calendar endpoints."},
+        {"name": "WebSocket Docs", "description": "Swagger-visible docs for WebSocket streams."},
+    ],
+)
+
+
+@app.get("/health", response_model=HealthResponse, summary="Health check", tags=["Health"])
+def health() -> HealthResponse:
+    return {
+        "status": "ok",
+        "mt5": "connected" if app.state.mt5_ok else app.state.mt5_message,
+    }
+
+
+@app.get("/account", response_model=AccountResponse, summary="Get account information", tags=["Account"])
+def account() -> AccountResponse:
+    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.post("/account/connect", response_model=ConnectionResponse, summary="Connect to MT5 account", tags=["Account"])
+def connect_account(payload: ConnectAccountRequest) -> ConnectionResponse:
+    app.state.mt5_connection_config = {
+        "path": payload.path,
+        "username": payload.username,
+        "password": payload.password,
+        "server": payload.server,
+    }
+    app.state.auto_reconnect = True
+
+    mt5.shutdown()
+    ok, message = _initialize_mt5()
+    app.state.mt5_ok = ok
+    app.state.mt5_message = message
+    if not ok:
+        raise HTTPException(status_code=400, detail=message)
+    return {"success": True, "mt5": message}
+
+
+@app.post("/account/disconnect", response_model=ConnectionResponse, summary="Disconnect MT5 account", tags=["Account"])
+def disconnect_account() -> ConnectionResponse:
+    app.state.auto_reconnect = False
+    ok, message = shutdown_connection()
+    app.state.mt5_ok = False
+    app.state.mt5_message = message if ok else "failed to disconnect"
+    if not ok:
+        raise HTTPException(status_code=500, detail=message)
+    return {"success": True, "mt5": message}
+
+
+@app.get("/tickets", response_model=TicketsResponse, summary="Get all active tickets", tags=["Tickets"])
+def tickets() -> TicketsResponse:
+    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", response_model=SymbolsResponse, summary="Search symbols", tags=["Symbols"])
+def symbols(query: str | None = Query(None, description="Optional case-insensitive filter for symbol names.")) -> SymbolsResponse:
+    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}", response_model=SymbolDetailsResponse, summary="Get symbol details", tags=["Symbols"])
+def symbol_details(name: str) -> SymbolDetailsResponse:
+    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}", response_model=BarsResponse, summary="Get OHLC bars", tags=["Market Data"])
+def bars(
+    symbol: str,
+    timeframe: str = Query("M1", description="Timeframe code (example: M1, M5, H1, D1)."),
+    n: int = Query(100, ge=1, le=10_000, description="Number of bars to fetch (1..10000)."),
+    includeVolume: bool = Query(False, description="Include tick volume in each bar."),
+) -> BarsResponse:
+    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,
+        includeVolume=includeVolume,
+    )
+    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", response_model=OrderExecutionResponse, summary="Create an order", tags=["Orders"])
+def create_order(payload: CreateOrderRequest) -> OrderExecutionResponse:
+    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", response_model=OpenPositionsResponse, summary="List open positions", tags=["Positions"])
+def open_positions() -> OpenPositionsResponse:
+    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", response_model=PendingOrdersResponse, summary="List pending orders", tags=["Orders"])
+def pending_orders() -> PendingOrdersResponse:
+    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.get("/trades/history", response_model=TradeHistoryResponse, summary="Get trade history", tags=["Trades"])
+def trade_history(
+    fromDate: str | None = Query(None, description="Start ISO datetime (UTC recommended)."),
+    toDate: str | None = Query(None, description="End ISO datetime (UTC recommended)."),
+) -> TradeHistoryResponse:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = list_trade_history(fromDate=fromDate, toDate=toDate)
+    if not ok:
+        error_message = str(data)
+        if "must be a valid ISO datetime" in error_message or "must be earlier than" in error_message:
+            raise HTTPException(status_code=400, detail=error_message)
+        raise HTTPException(status_code=500, detail=error_message)
+
+    return data
+
+
+@app.get("/calendar/events", response_model=CalendarEventsResponse, summary="Get calendar events", tags=["Calendar"])
+def calendar_events(
+    fromDate: str | None = Query(None, description="Start ISO datetime (UTC recommended)."),
+    toDate: str | None = Query(None, description="End ISO datetime (UTC recommended)."),
+    country: str | None = Query(None, description="Optional country filter (example: US)."),
+    currency: str | None = Query(None, description="Optional currency filter (example: USD)."),
+) -> CalendarEventsResponse:
+    if not app.state.mt5_ok:
+        raise HTTPException(status_code=503, detail=app.state.mt5_message)
+
+    ok, data = list_calendar_events(
+        from_date=fromDate,
+        to_date=toDate,
+        country=country,
+        currency=currency,
+    )
+    if not ok:
+        error_message = str(data)
+        if "must be a valid ISO datetime" in error_message or "must be earlier than" in error_message:
+            raise HTTPException(status_code=400, detail=error_message)
+        if "not available" in error_message:
+            raise HTTPException(status_code=501, detail=error_message)
+        raise HTTPException(status_code=500, detail=error_message)
+
+    return data
+
+
+@app.post("/orders/close", response_model=CloseOrderResponse, summary="Close position or cancel pending order", tags=["Orders"])
+def close_order(payload: CloseOrderRequest) -> CloseOrderResponse:
+    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
+
+
+@app.websocket("/ws/positions/open")
+async def ws_open_positions(websocket: WebSocket, intervalSeconds: float = 1.0) -> None:
+    await websocket.accept()
+    interval = _bounded_interval(float(intervalSeconds))
+
+    try:
+        await websocket.send_json(
+            {
+                "event": "subscribed",
+                "timestamp": _utc_now_iso(),
+                "stream": "openPositions",
+                "intervalSeconds": interval,
+            }
+        )
+
+        while True:
+            ok, payload = get_open_positions_snapshot()
+            if ok:
+                await websocket.send_json(payload)
+            else:
+                await websocket.send_json(
+                    {
+                        "event": "error",
+                        "timestamp": _utc_now_iso(),
+                        "stream": "openPositions",
+                        "message": str(payload),
+                    }
+                )
+            await asyncio.sleep(interval)
+    except WebSocketDisconnect:
+        return
+
+
+@app.get(
+    "/ws/positions/open/docs",
+    response_model=WebSocketDocsResponse,
+    summary="WebSocket docs: open positions stream",
+    tags=["WebSocket Docs"],
+)
+def ws_positions_open_docs() -> WebSocketDocsResponse:
+    return {
+        "stream": "openPositions",
+        "websocketPath": "/ws/positions/open",
+        "websocketExampleUrl": "ws://127.0.0.1:8000/ws/positions/open?intervalSeconds=1",
+        "queryParams": {
+            "intervalSeconds": "float, optional, bounded to 0.2..60 (default 1.0)",
+        },
+        "events": [
+            "subscribed",
+            "positionsSnapshot",
+            "error",
+        ],
+        "sampleMessages": [
+            {
+                "event": "subscribed",
+                "timestamp": "2026-03-12T10:00:00+00:00",
+                "stream": "openPositions",
+                "intervalSeconds": 1.0,
+            },
+            {
+                "event": "positionsSnapshot",
+                "timestamp": "2026-03-12T10:00:01+00:00",
+                "count": 2,
+                "totalPnl": 42.7,
+                "positions": [
+                    {
+                        "ticket": 123456789,
+                        "symbol": "EURUSD",
+                        "volume": 0.1,
+                        "profit": 25.4,
+                        "pnl": 25.4,
+                    }
+                ],
+            },
+        ],
+    }

app/services/__init__.py

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

app/services/account_service.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+import MetaTrader5 as mt5
+from app.services.serialization import toJsonable
+
+
+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
+    """
+    accountInfo = mt5.account_info()
+    if accountInfo is None:
+        return False, f"failed to fetch account info: {mt5.last_error()}"
+
+    return True, toJsonable(accountInfo)

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,
+    includeVolume: 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
+    """
+    timeframeValue = _TIMEFRAME_MAP.get(timeframe.upper())
+    if timeframeValue is None:
+        supported = ", ".join(_TIMEFRAME_MAP.keys())
+        return False, f"unsupported timeframe '{timeframe}'. supported: {supported}"
+
+    symbolInfo = mt5.symbol_info(symbol)
+    if symbolInfo is None:
+        return False, f"symbol not found or unavailable: {symbol}"
+
+    if not symbolInfo.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, timeframeValue, 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 includeVolume:
+            bar["volume"] = int(rate["tick_volume"])
+        bars.append(bar)
+
+    return True, {
+        "symbol": symbol,
+        "timeframe": timeframe.upper(),
+        "count": len(bars),
+        "bars": bars,
+    }