Add calculation and MT5 utility endpoints

AGENTS.md

@@ -22,15 +22,11 @@
 
 - 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.
-- The service is intentionally read-only: expose account, terminal, symbol, market, order, and history data without adding trading actions.
 
 ### Key Dependencies
 
 - `pdmt5`: Underlying MetaTrader 5 client integration used by the API layer.
 - `fastapi`: HTTP application framework and OpenAPI generation.
-- `pyarrow`: Apache Parquet response support.
-- `slowapi`: Request rate limiting.
-- `httpx`: HTTP client support used in testing and API interaction.
 
 ### Package Structure
 
@@ -44,19 +40,16 @@
   - `models.py`: Pydantic API models.
   - `middleware.py`: Request logging and error handling.
   - `constants.py`: Shared constants and environment variable names.
-  - `routers/`: Read-only endpoint groups: `health.py`, `symbols.py`, `market.py`, `account.py`, and `history.py`.
+  - `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
 
-- Target Python 3.11+ with 4-space indentation and an 88-character line limit.
-- Keep modules and functions in `snake_case`, classes in `PascalCase`, and constants in `UPPER_SNAKE_CASE`.
-- Type annotations are expected; Pyright runs in strict mode.
-- Ruff is configured with broad lint coverage; docstrings should follow the Google convention.
-- Test coverage is enforced at 100%; update or add tests with every behavior change.
-- Keep endpoint code grouped by domain under `mt5api/routers/`.
-- Use `pytest.mark.parametrize` for input/result matrices.
+- 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
 
@@ -67,8 +60,6 @@
 ## Commit & Pull Request Guidelines
 
 - Run QA using `local-qa` skill before committing or creating a PR.
-- Include request/response examples or screenshots when docs or OpenAPI-visible behavior changes.
-- Keep PRs focused and include: concise summary, affected workflow paths, linked issue/context, and regenerated `README.md` when workflow inventory changes.
 - 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.
 

README.md

@@ -4,9 +4,10 @@ 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`](https://github.com/dceoy/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
@@ -15,7 +16,8 @@ any operating system.
 
 ## 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
@@ -51,10 +53,13 @@ Docs:
 - Swagger UI: `http://localhost:8000/docs`
 - OpenAPI JSON: `http://localhost:8000/openapi.json`
 
-Set `MT5API_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 `/symbols` at the root. `"/api/v1"`, `"api/v1"`, and `"/api/v1/"` are
-treated the same.
+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
 
@@ -76,20 +81,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 `MT5API_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
 

docs/api/deployment.md

@@ -37,6 +37,7 @@ nssm install mt5api
 MT5API_SECRET_KEY=your-secret-api-key
 MT5API_LOG_LEVEL=INFO
 MT5API_RATE_LIMIT=100
+MT5API_MAX_MARKET_BOOK_SUBSCRIPTIONS=100
 MT5API_CORS_ORIGINS=*
 MT5API_ROUTER_PREFIX=/api/v1
 ```

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