open-api-mt5 0.3.0__tar.gz

open_api_mt5-0.3.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: open-api-mt5
+Version: 0.3.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
+
+# 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:
+
+```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
+open-api-mt5
+```
+
+Optional flags:
+
+```bash
+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:
+    ```json
+    {
+      "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:
+
+```javascript
+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:
+
+```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 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:
+
+```bash
+python -m pip install pyinstaller
+pyinstaller --onefile --name open-api-mt5 app/cli.py
+```
+
+The executable will be in `dist/open-api-mt5.exe`.

open_api_mt5-0.3.0/README.md

@@ -0,0 +1,141 @@
+# 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:
+
+```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
+open-api-mt5
+```
+
+Optional flags:
+
+```bash
+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:
+    ```json
+    {
+      "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:
+
+```javascript
+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:
+
+```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 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:
+
+```bash
+python -m pip install pyinstaller
+pyinstaller --onefile --name open-api-mt5 app/cli.py
+```
+
+The executable will be in `dist/open-api-mt5.exe`.

open_api_mt5-0.3.0/app/__init__.py

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

open_api_mt5-0.3.0/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)