mt5api 0.0.3__tar.gz → 0.0.4__tar.gz

mt5api-0.0.4/AGENTS.md

@@ -0,0 +1,90 @@
+# Repository Guidelines
+
+## Commands
+
+### Development Setup
+
+- `uv sync --dev` installs runtime and development dependencies.
+- `uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000` starts the API locally.
+- `uv run python -m mt5api` starts the app using `MT5API_HOST`, `MT5API_PORT`, and `MT5API_LOG_LEVEL`.
+- `uv run mkdocs serve` previews the documentation site.
+
+### Code Quality and Documentation
+
+**Important**: Run these before committing or creating a PR.
+
+1. **Format, lint, and test**: Use `local-qa` skill.
+2. **Documentation build**: Run `uv run mkdocs build` when documentation, configuration, or OpenAPI-visible behavior changes.
+
+## Architecture
+
+### Runtime Constraints
+
+- The API server must run on Windows with a logged-in MetaTrader 5 terminal.
+- Linux and macOS are for HTTP clients, documentation work, and local non-runtime development only.
+
+### Key Dependencies
+
+- `pdmt5`: Underlying MetaTrader 5 client integration used by the API layer.
+- `fastapi`: HTTP application framework and OpenAPI generation.
+
+### Package Structure
+
+- `mt5api/`: Main FastAPI package.
+  - `main.py`: App wiring, lifespan handling, middleware, CORS, and router registration.
+  - `__main__.py`: CLI entry point for launching the API from environment-backed configuration.
+  - `config.py`: Environment-backed configuration normalization and validation.
+  - `auth.py`: Optional API key authentication helpers.
+  - `dependencies.py`: Shared endpoint dependencies and MT5 accessors.
+  - `formatters.py`: JSON and Parquet response formatting helpers.
+  - `models.py`: Pydantic API models.
+  - `middleware.py`: Request logging and error handling.
+  - `constants.py`: Shared constants and environment variable names.
+  - `routers/`: Endpoint groups for operations: `health.py`, `symbols.py`, `market.py`, `account.py`, `history.py`, `calc.py`, and `trading.py`.
+- `tests/`: Pytest suite covering API behavior, configuration, middleware, and CLI entry points.
+- `docs/`: MkDocs documentation, including REST API and deployment guidance.
+
+## Quality Standards
+
+- Type hints required (pyright strict mode)
+- Comprehensive linting with 35+ rule categories (ruff)
+- Test coverage tracking with 100% (pytest-cov)
+- Parametrized tests for input/result matrices using `pytest.mark.parametrize` (pytest)
+
+## Documentation Workflow
+
+1. Update docstrings and docs when behavior, configuration, or OpenAPI-visible output changes.
+2. Local preview: `uv run mkdocs serve`
+3. Build validation: `uv run mkdocs build`
+
+## Commit & Pull Request Guidelines
+
+- Run QA using `local-qa` skill before committing or creating a PR.
+- Branch names use appropriate prefixes on creation (e.g., `feature/...`, `bugfix/...`, `refactor/...`, `docs/...`, `chore/...`).
+- When instructed to create a PR, create it as a draft with appropriate labels by default.
+
+## Security & Configuration Tips
+
+- Do not commit real MT5 credentials or API keys.
+- Configure `MT5API_SECRET_KEY`, `MT5API_RATE_LIMIT`, `MT5API_CORS_ORIGINS`, `MT5API_ROUTER_PREFIX`, and `MT5API_LOG_LEVEL` through environment variables.
+- Keep runtime configuration in the environment instead of hardcoding deployment values.
+- Authentication mode is fixed at process startup; cover both authenticated and unauthenticated behavior when changing auth-related code.
+
+## Code Design Principles
+
+Always prefer the simplest design that works.
+
+- **KISS**: Choose straightforward solutions and avoid unnecessary abstraction.
+- **DRY**: Remove duplication when it improves clarity and maintainability.
+- **YAGNI**: Do not add features, hooks, or flexibility until they are needed.
+- **SOLID/Clean Code**: Apply these as tools only when they keep the design simpler and easier to change.
+
+## Development Methodology
+
+Keep delivery incremental, test-backed, and easy to review.
+
+- Make small, safe, reversible changes.
+- Prefer `Red -> Green -> Refactor`.
+- Do not mix feature work and refactoring in the same commit.
+- Refactor when it improves clarity or removes real duplication (Rule of Three).
+- Keep tests fast, focused, and self-validating.

{mt5api-0.0.3 → mt5api-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 0.0.3
+Version: 0.0.4
 Summary: MetaTrader 5 REST API
 Project-URL: Repository, https://github.com/dceoy/mt5api.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -34,18 +34,46 @@ MetaTrader 5 REST API
 
 [![CI/CD](https://github.com/dceoy/mt5api/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/mt5api/actions/workflows/ci.yml)
 
-mt5api exposes read-only MT5 market data, account info, and trading history
-over HTTP. It uses the `pdmt5` client internally and adds optional API-key
-auth, rate limiting, and JSON/Parquet response formatting.
+mt5api exposes MT5 market data, account info, trading history, and trading
+operations over HTTP. It uses the [`pdmt5`](https://github.com/dceoy/pdmt5)
+client internally and adds optional API-key auth, rate limiting, and
+JSON/Parquet response formatting.
 
 The API server must run on Windows. The `MetaTrader5` Python package used by
 `pdmt5` is supported only on Windows, so you must host `mt5api` on a Windows
 machine with a logged-in MetaTrader 5 terminal. HTTP clients can connect from
 any operating system.
 
+## Architecture
+
+```mermaid
+graph TB
+    Client["HTTP Client<br/>(Any OS)"]
+
+    subgraph "Windows Host"
+        subgraph "FastAPI Application"
+            Middleware["Middleware Stack<br/>CORS · Logging · Error Handler · Rate Limiter"]
+            Routers["Routers<br/>health · symbols · market · account · history · calc · trading"]
+            Auth["API Key Security Dependency<br/>Security(api_key_header) · verify_api_key"]
+            Deps["FastAPI Dependencies<br/>MT5 Client Singleton · Format Negotiation"]
+            Formatters["Response Formatters<br/>JSON · Parquet"]
+            Middleware --> Routers --> Deps --> Formatters
+            Auth -.-> Routers
+            Formatters --> Middleware
+        end
+
+        Deps --> pdmt5["pdmt5<br/>MT5 Client Library"]
+        pdmt5 --> MT5["MetaTrader 5<br/>Terminal"]
+    end
+
+    Client -- "HTTP/REST" --> Middleware
+    Middleware -- "JSON / Parquet" --> Client
+```
+
 ## Features
 
-- Read-only REST endpoints for symbols, market data, account info, orders, and history
+- REST endpoints for symbols, market data, account info, orders, history,
+  calculations, and trading operations
 - JSON and Apache Parquet responses (content negotiation)
 - Optional API key authentication with per-minute rate limiting
 - Structured JSON logging and configurable CORS
@@ -72,7 +100,7 @@ uv sync
 
 ```powershell
 $env:MT5API_SECRET_KEY = "your-secret-api-key"  # Optional: omit to disable auth
-$env:API_ROUTER_PREFIX = "/api/v1"        # Optional: omit for root-level routes
+$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
 ```
 
@@ -81,11 +109,14 @@ Docs:
 - Swagger UI: `http://localhost:8000/docs`
 - OpenAPI JSON: `http://localhost:8000/openapi.json`
 
-Set `API_ROUTER_PREFIX` to mount the read-only API endpoints under a shared path
-such as `/api/v1`. The default is `""`, which keeps routes like `/health` and
+Set `MT5API_ROUTER_PREFIX` to mount the API endpoints under a shared path such
+as `/api/v1`. The default is `""`, which keeps routes like `/health` and
 `/symbols` at the root. `"/api/v1"`, `"api/v1"`, and `"/api/v1/"` are treated
 the same.
 
+Set `MT5API_MAX_MARKET_BOOK_SUBSCRIPTIONS` to cap active market-book
+subscriptions. The default limit is `100`.
+
 ## Example Requests with curl
 
 Replace `windows-host` with the DNS name or IP address of the Windows machine
@@ -106,20 +137,34 @@ curl -H "X-API-Key: your-secret-api-key" "http://windows-host:8000/symbols?group
 curl -H "X-API-Key: your-secret-api-key" -H "Accept: application/parquet" "http://windows-host:8000/rates/from?symbol=EURUSD&timeframe=TIMEFRAME_M1&date_from=2024-01-01T00:00:00Z&count=100"
 ```
 
-Market-data endpoints accept MetaTrader 5 constants either by official name
-(`TIMEFRAME_M1`, `COPY_TICKS_ALL`) or by their integer value.
+Market-data and calculation endpoints accept MetaTrader 5 constants either by
+official name (`TIMEFRAME_M1`, `COPY_TICKS_ALL`, `ORDER_TYPE_BUY`) or by their
+integer value.
+
+## Endpoints
+
+If `MT5API_ROUTER_PREFIX` is set, prepend that value to every API route below.
+
+### Read-Only Endpoints
 
-## Endpoints (Read-Only)
+- Health: `GET /health`, `GET /version`, `GET /last-error`
+- Symbols: `GET /symbols`, `GET /symbols/total`, `GET /symbols/{symbol}`,
+  `GET /symbols/{symbol}/tick`
+- Market data: `GET /rates/from`, `GET /rates/from-pos`, `GET /rates/range`,
+  `GET /ticks/from`, `GET /ticks/range`, `GET /market-book/{symbol}`
+- Calculations: `GET /calc/margin`, `GET /calc/profit`
+- Account: `GET /account`, `GET /terminal`
+- Trading state: `GET /positions`, `GET /positions/total`,
+  `GET /orders`, `GET /orders/total`
+- History: `GET /history/orders`, `GET /history/orders/total`,
+  `GET /history/deals`, `GET /history/deals/total`
 
-- Health: `/health`, `/version`
-- Symbols: `/symbols`, `/symbols/{symbol}`, `/symbols/{symbol}/tick`
-- Market data: `/rates/from`, `/rates/from-pos`, `/rates/range`,
-  `/ticks/from`, `/ticks/range`, `/market-book/{symbol}`
-- Account: `/account`, `/terminal`
-- Trading state: `/positions`, `/orders`
-- History: `/history/orders`, `/history/deals`
+### Operational Endpoints
 
-If `API_ROUTER_PREFIX` is set, prepend that value to every API route above.
+- `POST /symbols/{symbol}/select` — Show or hide symbol in MarketWatch
+- `POST /market-book/{symbol}/subscribe` — Subscribe to DOM events
+- `POST /market-book/{symbol}/unsubscribe` — Unsubscribe from DOM events
+- `POST /order/check` — Validate a trade request without execution
 
 ## License
 

mt5api-0.0.4/README.md

@@ -0,0 +1,141 @@
+# mt5api
+
+MetaTrader 5 REST API
+
+[![CI/CD](https://github.com/dceoy/mt5api/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/mt5api/actions/workflows/ci.yml)
+
+mt5api exposes MT5 market data, account info, trading history, and trading
+operations over HTTP. It uses the [`pdmt5`](https://github.com/dceoy/pdmt5)
+client internally and adds optional API-key auth, rate limiting, and
+JSON/Parquet response formatting.
+
+The API server must run on Windows. The `MetaTrader5` Python package used by
+`pdmt5` is supported only on Windows, so you must host `mt5api` on a Windows
+machine with a logged-in MetaTrader 5 terminal. HTTP clients can connect from
+any operating system.
+
+## Architecture
+
+```mermaid
+graph TB
+    Client["HTTP Client<br/>(Any OS)"]
+
+    subgraph "Windows Host"
+        subgraph "FastAPI Application"
+            Middleware["Middleware Stack<br/>CORS · Logging · Error Handler · Rate Limiter"]
+            Routers["Routers<br/>health · symbols · market · account · history · calc · trading"]
+            Auth["API Key Security Dependency<br/>Security(api_key_header) · verify_api_key"]
+            Deps["FastAPI Dependencies<br/>MT5 Client Singleton · Format Negotiation"]
+            Formatters["Response Formatters<br/>JSON · Parquet"]
+            Middleware --> Routers --> Deps --> Formatters
+            Auth -.-> Routers
+            Formatters --> Middleware
+        end
+
+        Deps --> pdmt5["pdmt5<br/>MT5 Client Library"]
+        pdmt5 --> MT5["MetaTrader 5<br/>Terminal"]
+    end
+
+    Client -- "HTTP/REST" --> Middleware
+    Middleware -- "JSON / Parquet" --> Client
+```
+
+## Features
+
+- REST endpoints for symbols, market data, account info, orders, history,
+  calculations, and trading operations
+- JSON and Apache Parquet responses (content negotiation)
+- Optional API key authentication with per-minute rate limiting
+- Structured JSON logging and configurable CORS
+- OpenAPI/Swagger docs built into the API
+
+## Requirements
+
+- Python 3.11+
+- Windows host with MetaTrader 5 terminal installed and logged in
+- Linux and macOS are not supported for the API server runtime, but they work
+  for HTTP clients
+
+## Installation
+
+Install and run the API on the Windows machine where MetaTrader 5 is installed.
+
+```powershell
+git clone https://github.com/dceoy/mt5api.git
+cd mt5api
+uv sync
+```
+
+## Running the API on Windows
+
+```powershell
+$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
+```
+
+Docs:
+
+- Swagger UI: `http://localhost:8000/docs`
+- OpenAPI JSON: `http://localhost:8000/openapi.json`
+
+Set `MT5API_ROUTER_PREFIX` to mount the API endpoints under a shared path such
+as `/api/v1`. The default is `""`, which keeps routes like `/health` and
+`/symbols` at the root. `"/api/v1"`, `"api/v1"`, and `"/api/v1/"` are treated
+the same.
+
+Set `MT5API_MAX_MARKET_BOOK_SUBSCRIPTIONS` to cap active market-book
+subscriptions. The default limit is `100`.
+
+## Example Requests with curl
+
+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`.
+
+```console
+curl "http://windows-host:8000/health"
+```
+
+```console
+# 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/symbols?group=*USD*"
+```
+
+```console
+curl -H "X-API-Key: your-secret-api-key" -H "Accept: application/parquet" "http://windows-host:8000/rates/from?symbol=EURUSD&timeframe=TIMEFRAME_M1&date_from=2024-01-01T00:00:00Z&count=100"
+```
+
+Market-data and calculation endpoints accept MetaTrader 5 constants either by
+official name (`TIMEFRAME_M1`, `COPY_TICKS_ALL`, `ORDER_TYPE_BUY`) or by their
+integer value.
+
+## Endpoints
+
+If `MT5API_ROUTER_PREFIX` is set, prepend that value to every API route below.
+
+### Read-Only Endpoints
+
+- Health: `GET /health`, `GET /version`, `GET /last-error`
+- Symbols: `GET /symbols`, `GET /symbols/total`, `GET /symbols/{symbol}`,
+  `GET /symbols/{symbol}/tick`
+- Market data: `GET /rates/from`, `GET /rates/from-pos`, `GET /rates/range`,
+  `GET /ticks/from`, `GET /ticks/range`, `GET /market-book/{symbol}`
+- Calculations: `GET /calc/margin`, `GET /calc/profit`
+- Account: `GET /account`, `GET /terminal`
+- Trading state: `GET /positions`, `GET /positions/total`,
+  `GET /orders`, `GET /orders/total`
+- History: `GET /history/orders`, `GET /history/orders/total`,
+  `GET /history/deals`, `GET /history/deals/total`
+
+### Operational Endpoints
+
+- `POST /symbols/{symbol}/select` — Show or hide symbol in MarketWatch
+- `POST /market-book/{symbol}/subscribe` — Subscribe to DOM events
+- `POST /market-book/{symbol}/unsubscribe` — Unsubscribe from DOM events
+- `POST /order/check` — Validate a trade request without execution
+
+## License
+
+MIT License - see [LICENSE](https://github.com/dceoy/mt5api/blob/main/LICENSE).

{mt5api-0.0.3 → mt5api-0.0.4}/docs/api/deployment.md

@@ -35,10 +35,11 @@ nssm install mt5api
 ```
 # Optional: set MT5API_SECRET_KEY only when you want to require X-API-Key headers.
 MT5API_SECRET_KEY=your-secret-api-key
-API_LOG_LEVEL=INFO
-API_RATE_LIMIT=100
-API_CORS_ORIGINS=*
-API_ROUTER_PREFIX=/api/v1
+MT5API_LOG_LEVEL=INFO
+MT5API_RATE_LIMIT=100
+MT5API_MAX_MARKET_BOOK_SUBSCRIPTIONS=100
+MT5API_CORS_ORIGINS=*
+MT5API_ROUTER_PREFIX=/api/v1
 ```
 
 6. Start the service:

{mt5api-0.0.3 → mt5api-0.0.4}/docs/api/index.md

@@ -10,8 +10,9 @@ logged in. Clients can call the HTTP API from any operating system.
 
 ### [REST API](rest-api.md)
 
-FastAPI-based REST API that exposes read-only MT5 data over HTTP with JSON and
-Parquet support.
+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](deployment.md)
 
@@ -21,10 +22,21 @@ Windows service deployment guide for hosting the REST API alongside MetaTrader 5
 
 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
-2. **Dependency Layer** (`mt5api.dependencies`): MT5 client lifecycle and format negotiation
-3. **Model Layer** (`mt5api.models`): Response schemas and MT5 constant metadata helpers
-4. **Formatter Layer** (`mt5api.formatters`): JSON and Parquet serialization helpers
+1. **API Layer** (`mt5api.main`, `mt5api.routers`): FastAPI app, routers, and
+   response formatting. Routers are grouped by domain:
+   - `health.py`: health check, version, last error
+   - `symbols.py`: symbol listing, details, tick, and total
+   - `market.py`: OHLCV rates, tick data, and market depth
+   - `calc.py`: margin and profit calculations
+   - `account.py`: account and terminal info
+   - `history.py`: positions, orders, history with totals
+   - `trading.py`: order check, symbol selection, market book subscriptions
+2. **Dependency Layer** (`mt5api.dependencies`): MT5 client lifecycle and
+   format negotiation
+3. **Model Layer** (`mt5api.models`): Response schemas and MT5 constant
+   metadata helpers (TIMEFRAME, COPY_TICKS, ORDER_TYPE)
+4. **Formatter Layer** (`mt5api.formatters`): JSON and Parquet serialization
+   helpers
 
 ## Usage Guidelines
 
@@ -38,7 +50,7 @@ mt5api provides a FastAPI layer on top of the MetaTrader 5 terminal runtime:
 
 ```powershell
 $env:MT5API_SECRET_KEY = "your-secret-api-key"  # Optional: omit to disable auth
-$env:API_ROUTER_PREFIX = "/api/v1"        # Optional: omit for root-level routes
+$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
 ```