mt5api 0.0.2__tar.gz → 0.0.3__tar.gz

mt5api-0.0.3/.agents/skills/local-qa/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: local-qa
+description: Run local QA including formatting, linting, and testing for the repository. Use whenever any file has been updated.
+disable-model-invocation: true
+---
+
+# Local QA (format, lint, and test)
+
+Run the local QA script `scripts/qa.sh` in this skill.
+
+## Procedure
+
+- Execute the script exactly as shown above when this skill is triggered.
+- Capture and summarize key output (success/failure, major warnings, and any files modified).
+- If the script fails due to missing tooling (`command not found`, missing executable, or equivalent), install the missing tool(s) and rerun `./scripts/qa.sh`.
+- Install tools using this order of preference:
+  1. Use the project's package manager when applicable (`uv`/`poetry` for Python, package manager scripts/dependencies for Node.js).
+  2. Use a system package manager (`brew` on macOS, `apt` on Debian/Ubuntu) when project-local install is not applicable.
+  3. Use language-specific installers as fallback (`pipx`/`pip`, `npm`, `go install`, etc.).
+- If multiple tools are missing, repeat install -> rerun until QA completes or you hit a blocker.
+- If installation fails or requires unavailable privileges, report what was attempted, the exact failure, and stop.
+- Do not run unrelated commands; only run commands needed for QA and missing-tool installation.

mt5api-0.0.3/.agents/skills/mt5api/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: mt5api
+description: >-
+  Query the MT5 API for account info, terminal status, health checks, symbol
+  data, market data (OHLCV rates, ticks, market depth), open positions, pending
+  orders, and trade history. Use when the user wants to interact with any mt5api
+  endpoint.
+allowed-tools: Bash
+---
+
+# MT5 API
+
+Query all mt5api endpoints: health, version, account, terminal, symbols, market
+data, positions, orders, and trade history.
+
+## Configuration
+
+The API base URL defaults to `http://localhost:8000`. Set `MT5API_URL` to
+override. When the server is configured with `MT5API_SECRET_KEY`, send the same value
+in the `X-API-Key` header. When server-side auth is disabled, omit the header
+instead of sending an empty `X-API-Key`.
+
+Use these shell helpers in examples:
+
+```bash
+MT5API_URL="${MT5API_URL:-http://localhost:8000}"
+AUTH_HEADER=()
+if [ -n "${MT5API_SECRET_KEY:-}" ]; then
+  AUTH_HEADER=(-H "X-API-Key: ${MT5API_SECRET_KEY}")
+fi
+```
+
+## Response Formats
+
+All endpoints (except `/health`) return JSON by default. Request Parquet with
+`format=parquet` or `Accept: application/parquet`.
+
+## Operational Notes
+
+- Start `ticks/range` with a narrow window. Large ranges can be slow; use
+  `ticks/from` when the user only needs the latest `N` ticks.
+- `/market-book/{symbol}` may return `503` when MT5 depth-of-market data is not
+  available for the symbol. Report the exact MT5 error and suggest another
+  symbol or skipping DOM data.
+- Empty arrays from `/positions`, `/orders`, `/history/orders`, or
+  `/history/deals` are valid results.
+
+---
+
+## Health & Version
+
+### Health Check (public, no auth required)
+
+```bash
+curl -s "${MT5API_URL}/health" | python -m json.tool
+```
+
+Returns:
+
+| Field         | Type    | Description                    |
+| ------------- | ------- | ------------------------------ |
+| status        | string  | `healthy` or `unhealthy`       |
+| mt5_connected | bool    | MT5 terminal connection status |
+| mt5_version   | string? | MT5 terminal version string    |
+| api_version   | string  | API version (e.g., `1.0.0`)    |
+
+### MT5 Version
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/version" | python -m json.tool
+```
+
+| Parameter | Type   | Required | Description              |
+| --------- | ------ | -------- | ------------------------ |
+| format    | string | no       | Response format override |
+
+---
+
+## Account & Terminal
+
+### Account Info
+
+Get current trading account details (balance, equity, margin, leverage, etc.).
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/account" | python -m json.tool
+```
+
+Key fields: `login`, `balance`, `equity`, `margin`, `margin_free`,
+`margin_level`, `leverage`, `currency`, `server`, `name`.
+
+| Parameter | Type   | Required | Description              |
+| --------- | ------ | -------- | ------------------------ |
+| format    | string | no       | Response format override |
+
+### Terminal Info
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/terminal" | python -m json.tool
+```
+
+| Parameter | Type   | Required | Description              |
+| --------- | ------ | -------- | ------------------------ |
+| format    | string | no       | Response format override |
+
+---
+
+## Symbols
+
+### List Symbols
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/symbols" | python -m json.tool
+```
+
+| Parameter | Type   | Required | Description                                   |
+| --------- | ------ | -------- | --------------------------------------------- |
+| group     | string | no       | Symbol group filter (e.g., `*USD*`, `Forex*`) |
+| format    | string | no       | Response format override                      |
+
+### Get Symbol Info
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/symbols/EURUSD" | python -m json.tool
+```
+
+### Get Latest Tick
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/symbols/EURUSD/tick" | python -m json.tool
+```
+
+---
+
+## Market Data
+
+`timeframe` and `flags` accept either the official MetaTrader 5 constant name
+(e.g., `TIMEFRAME_H1`, `COPY_TICKS_ALL`) or the equivalent integer value.
+
+### Rates from Date
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/rates/from?symbol=EURUSD&timeframe=TIMEFRAME_H1&date_from=2024-01-01T00:00:00Z&count=100" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Description                                  |
+| --------- | -------- | -------- | -------------------------------------------- |
+| symbol    | string   | yes      | Symbol name                                  |
+| timeframe | int/str  | yes      | MT5 timeframe constant or equivalent integer |
+| date_from | datetime | yes      | Start date (ISO 8601)                        |
+| count     | int      | yes      | Number of candles (1–100000)                 |
+| format    | string   | no       | Response format override                     |
+
+### Rates from Position
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/rates/from-pos?symbol=EURUSD&timeframe=TIMEFRAME_H1&start_pos=0&count=100" \
+  | python -m json.tool
+```
+
+| Parameter | Type    | Required | Description                       |
+| --------- | ------- | -------- | --------------------------------- |
+| symbol    | str     | yes      | Symbol name                       |
+| timeframe | str/int | yes      | MT5 timeframe constant or integer |
+| start_pos | int     | yes      | Start position (0 = current bar)  |
+| count     | int     | yes      | Number of candles (1–100000)      |
+| format    | string  | no       | Response format override          |
+
+### Rates in Range
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/rates/range?symbol=EURUSD&timeframe=TIMEFRAME_H1&date_from=2024-01-01T00:00:00Z&date_to=2024-01-31T23:59:59Z" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Description                       |
+| --------- | -------- | -------- | --------------------------------- |
+| symbol    | string   | yes      | Symbol name                       |
+| timeframe | int/str  | yes      | MT5 timeframe constant or integer |
+| date_from | datetime | yes      | Start date (ISO 8601)             |
+| date_to   | datetime | yes      | End date (ISO 8601)               |
+| format    | string   | no       | Response format override          |
+
+### Ticks from Date
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/ticks/from?symbol=EURUSD&date_from=2024-01-02T10:00:00Z&count=500" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Default        | Description                       |
+| --------- | -------- | -------- | -------------- | --------------------------------- |
+| symbol    | string   | yes      |                | Symbol name                       |
+| date_from | datetime | yes      |                | Start date (ISO 8601)             |
+| count     | int      | yes      |                | Number of ticks (1–100000)        |
+| flags     | int/str  | no       | COPY_TICKS_ALL | MT5 tick flag constant or integer |
+| format    | string   | no       |                | Response format override          |
+
+### Ticks in Range
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/ticks/range?symbol=EURUSD&date_from=2024-01-02T10:00:00Z&date_to=2024-01-02T11:00:00Z" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Default        | Description                       |
+| --------- | -------- | -------- | -------------- | --------------------------------- |
+| symbol    | string   | yes      |                | Symbol name                       |
+| date_from | datetime | yes      |                | Start date (ISO 8601)             |
+| date_to   | datetime | yes      |                | End date (ISO 8601)               |
+| flags     | int/str  | no       | COPY_TICKS_ALL | MT5 tick flag constant or integer |
+| format    | string   | no       |                | Response format override          |
+
+### Market Book (DOM)
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/market-book/EURUSD" | python -m json.tool
+```
+
+If this returns `503`, explain that MT5 did not provide DOM data for the
+requested symbol and include the server's error text.
+
+---
+
+## Positions, Orders & History
+
+### Open Positions
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/positions" | python -m json.tool
+```
+
+| Parameter | Type   | Required | Description               |
+| --------- | ------ | -------- | ------------------------- |
+| symbol    | string | no       | Filter by symbol          |
+| group     | string | no       | Filter by group pattern   |
+| ticket    | int    | no       | Filter by position ticket |
+| format    | string | no       | Response format override  |
+
+### Pending Orders
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/orders" | python -m json.tool
+```
+
+| Parameter | Type   | Required | Description              |
+| --------- | ------ | -------- | ------------------------ |
+| symbol    | string | no       | Filter by symbol         |
+| group     | string | no       | Filter by group pattern  |
+| ticket    | int    | no       | Filter by order ticket   |
+| format    | string | no       | Response format override |
+
+### Historical Orders
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/history/orders?date_from=2024-01-01T00:00:00Z&date_to=2024-01-31T23:59:59Z" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Description                                       |
+| --------- | -------- | -------- | ------------------------------------------------- |
+| date_from | datetime | cond.    | Start date (required if no ticket/position)       |
+| date_to   | datetime | cond.    | End date (required if no ticket/position)         |
+| ticket    | int      | cond.    | Filter by ticket (alternative to date range)      |
+| position  | int      | cond.    | Filter by position ID (alternative to date range) |
+| symbol    | string   | no       | Filter by symbol                                  |
+| group     | string   | no       | Filter by group pattern                           |
+| format    | string   | no       | Response format override                          |
+
+Either `(date_from AND date_to)` or `(ticket OR position)` must be provided.
+
+### Historical Deals
+
+```bash
+curl -s "${AUTH_HEADER[@]}" \
+  "${MT5API_URL}/history/deals?date_from=2024-01-01T00:00:00Z&date_to=2024-01-31T23:59:59Z" \
+  | python -m json.tool
+```
+
+| Parameter | Type     | Required | Description                                       |
+| --------- | -------- | -------- | ------------------------------------------------- |
+| date_from | datetime | cond.    | Start date (required if no ticket/position)       |
+| date_to   | datetime | cond.    | End date (required if no ticket/position)         |
+| ticket    | int      | cond.    | Filter by ticket (alternative to date range)      |
+| position  | int      | cond.    | Filter by position ID (alternative to date range) |
+| symbol    | string   | no       | Filter by symbol                                  |
+| group     | string   | no       | Filter by group pattern                           |
+| format    | string   | no       | Response format override                          |
+
+Either `(date_from AND date_to)` or `(ticket OR position)` must be provided.
+
+---
+
+## Procedure
+
+1. Identify which endpoint(s) the user needs from the sections above.
+2. Gather required parameters (symbol, timeframe, dates, count, filters).
+3. Decide whether the caller needs JSON or Parquet output.
+4. Build `AUTH_HEADER` only when `MT5API_SECRET_KEY` is set, then construct and run
+   the appropriate `curl` command(s).
+5. For `ticks/range`, start with a narrow interval and widen only if needed.
+6. Parse the JSON response and summarize the results, or note when the API
+   returned Parquet data.
+7. If `/market-book/{symbol}` returns `503`, explain that MT5 did not provide
+   DOM data for that symbol and include the error text.
+8. If the health status is `unhealthy`, note that the MT5 terminal may not be
+   running or reachable.
+9. For historical queries, remind the user that either a date range or a
+   ticket/position filter is required.

{mt5api-0.0.2 → mt5api-0.0.3}/AGENTS.md

@@ -41,7 +41,7 @@ Use `uv` for local work:
 ## Security & Configuration Tips
 
 - Do not commit real MT5 credentials or API keys.
-- Configure `MT5_API_KEY`, `API_RATE_LIMIT`, `API_CORS_ORIGINS`, and `API_LOG_LEVEL` through environment variables.
+- Configure `MT5API_SECRET_KEY`, `API_RATE_LIMIT`, `API_CORS_ORIGINS`, and `API_LOG_LEVEL` through environment variables.
 - The API server must run on Windows with a logged-in MetaTrader 5 terminal.
 - Linux and macOS are for HTTP clients and local non-runtime work only.
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5api
-Version: 0.0.2
+Version: 0.0.3
 Summary: MetaTrader 5 REST API
 Project-URL: Repository, https://github.com/dceoy/mt5api.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 # mt5api
 
-MetaTrader 5 REST API using FastAPI
+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)
 
@@ -71,7 +71,8 @@ uv sync
 ## Running the API on Windows
 
 ```powershell
-$env:MT5_API_KEY = "your-secret-api-key"  # Optional: omit to disable auth
+$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
 uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
 ```
 
@@ -80,6 +81,11 @@ 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
+`/symbols` at the root. `"/api/v1"`, `"api/v1"`, and `"/api/v1/"` are treated
+the same.
+
 ## Example Requests with curl
 
 Replace `windows-host` with the DNS name or IP address of the Windows machine
@@ -88,27 +94,32 @@ works. In PowerShell, use `curl.exe` if `curl` resolves to
 `Invoke-WebRequest`.
 
 ```console
-curl "http://windows-host:8000/api/v1/health"
+curl "http://windows-host:8000/health"
 ```
 
 ```console
-# Include X-API-Key only when MT5_API_KEY is configured on the server.
-curl -H "X-API-Key: your-secret-api-key" "http://windows-host:8000/api/v1/symbols?group=*USD*"
+# 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/api/v1/rates/from?symbol=EURUSD&timeframe=1&date_from=2024-01-01T00:00:00Z&count=100"
+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.
+
 ## Endpoints (Read-Only)
 
-- Health: `/api/v1/health`, `/api/v1/version`
-- Symbols: `/api/v1/symbols`, `/api/v1/symbols/{symbol}`, `/api/v1/symbols/{symbol}/tick`
-- Market data: `/api/v1/rates/from`, `/api/v1/rates/from-pos`, `/api/v1/rates/range`,
-  `/api/v1/ticks/from`, `/api/v1/ticks/range`, `/api/v1/market-book/{symbol}`
-- Account: `/api/v1/account`, `/api/v1/terminal`
-- Trading state: `/api/v1/positions`, `/api/v1/orders`
-- History: `/api/v1/history/orders`, `/api/v1/history/deals`
+- 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`
+
+If `API_ROUTER_PREFIX` is set, prepend that value to every API route above.
 
 ## License
 

{mt5api-0.0.2 → mt5api-0.0.3}/README.md

@@ -1,6 +1,6 @@
 # mt5api
 
-MetaTrader 5 REST API using FastAPI
+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)
 
@@ -41,7 +41,8 @@ uv sync
 ## Running the API on Windows
 
 ```powershell
-$env:MT5_API_KEY = "your-secret-api-key"  # Optional: omit to disable auth
+$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
 uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
 ```
 
@@ -50,6 +51,11 @@ 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
+`/symbols` at the root. `"/api/v1"`, `"api/v1"`, and `"/api/v1/"` are treated
+the same.
+
 ## Example Requests with curl
 
 Replace `windows-host` with the DNS name or IP address of the Windows machine
@@ -58,27 +64,32 @@ works. In PowerShell, use `curl.exe` if `curl` resolves to
 `Invoke-WebRequest`.
 
 ```console
-curl "http://windows-host:8000/api/v1/health"
+curl "http://windows-host:8000/health"
 ```
 
 ```console
-# Include X-API-Key only when MT5_API_KEY is configured on the server.
-curl -H "X-API-Key: your-secret-api-key" "http://windows-host:8000/api/v1/symbols?group=*USD*"
+# 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/api/v1/rates/from?symbol=EURUSD&timeframe=1&date_from=2024-01-01T00:00:00Z&count=100"
+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.
+
 ## Endpoints (Read-Only)
 
-- Health: `/api/v1/health`, `/api/v1/version`
-- Symbols: `/api/v1/symbols`, `/api/v1/symbols/{symbol}`, `/api/v1/symbols/{symbol}/tick`
-- Market data: `/api/v1/rates/from`, `/api/v1/rates/from-pos`, `/api/v1/rates/range`,
-  `/api/v1/ticks/from`, `/api/v1/ticks/range`, `/api/v1/market-book/{symbol}`
-- Account: `/api/v1/account`, `/api/v1/terminal`
-- Trading state: `/api/v1/positions`, `/api/v1/orders`
-- History: `/api/v1/history/orders`, `/api/v1/history/deals`
+- 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`
+
+If `API_ROUTER_PREFIX` is set, prepend that value to every API route above.
 
 ## License
 

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

@@ -33,11 +33,12 @@ nssm install mt5api
 5. Set environment variables in the NSSM GUI:
 
 ```
-# Optional: set MT5_API_KEY only when you want to require X-API-Key headers.
-MT5_API_KEY=your-secret-api-key
+# 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
 ```
 
 6. Start the service:
@@ -51,7 +52,7 @@ nssm start mt5api
 In PowerShell, use `curl.exe` if `curl` resolves to `Invoke-WebRequest`.
 
 ```console
-curl "http://localhost:8000/api/v1/health"
+curl "http://localhost:8000/health"
 ```
 
 Expected status: `healthy` (or `unhealthy` if MT5 is not connected).

mt5api-0.0.3/docs/api/index.md

@@ -0,0 +1,57 @@
+# API Reference
+
+This section contains the public documentation for mt5api.
+
+The API server must run on Windows because the `MetaTrader5` Python package is
+Windows-only. Run `mt5api` on a Windows host with MetaTrader 5 installed and
+logged in. Clients can call the HTTP API from any operating system.
+
+## Guides
+
+### [REST API](rest-api.md)
+
+FastAPI-based REST API that exposes read-only MT5 data over HTTP with JSON and
+Parquet support.
+
+### [Deployment](deployment.md)
+
+Windows service deployment guide for hosting the REST API alongside MetaTrader 5.
+
+## Architecture Overview
+
+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
+
+## Usage Guidelines
+
+- **Type Safety**: All endpoints and helpers include comprehensive type hints
+- **Error Handling**: Centralized through RFC 7807 responses (see REST API docs)
+- **Documentation**: Google-style docstrings with examples
+- **Validation**: Pydantic models for requests and responses
+- **Data Formats**: JSON and Parquet via content negotiation
+
+## Quick Start
+
+```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
+uv run uvicorn mt5api.main:app --host 0.0.0.0 --port 8000
+```
+
+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
+# 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/rates/from?symbol=EURUSD&timeframe=TIMEFRAME_M1&date_from=2024-01-01T00:00:00Z&count=100"
+```
+
+## Examples
+
+See the [REST API](rest-api.md) guide for endpoint examples and request syntax.