qmtlink 0.1.0a1__tar.gz

qmtlink-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QmtLink Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qmtlink-0.1.0a1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: qmtlink
+Version: 0.1.0a1
+Summary: An unofficial CLI, Python SDK, and HTTP bridge for miniQMT/xtquant
+Keywords: miniqmt,qmt,xtquant,trading,cli
+Author: QmtLink Contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: typer>=0.27.1
+Requires-Dist: fastapi>=0.141.1 ; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.52.1 ; extra == 'server'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/ilwk/qmtlink
+Project-URL: Repository, https://github.com/ilwk/qmtlink
+Project-URL: Issues, https://github.com/ilwk/qmtlink/issues
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# QmtLink
+
+QmtLink 是一个非官方的 miniQMT/xtquant 跨平台中转项目，提供：
+
+- Windows Bridge 一键启动命令
+- 面向 AI 和自动化脚本的 JSON CLI
+- 面向 Python 量化项目的 SDK
+- HTTP API（实时 WebSocket 将在后续版本加入）
+
+> 当前版本是开发预览版。Mock Bridge、HTTP API、CLI 和 SDK 可用；真实 miniQMT
+> 交易尚未实现，请勿用于实盘。
+
+## 安装
+
+客户端和 CLI：
+
+```bash
+uv add qmtlink
+```
+
+Windows Bridge：
+
+```bash
+uv add "qmtlink[server]"
+```
+
+## 快速体验
+
+启动 Mock Bridge：
+
+```bash
+qmt bridge run --mock
+```
+
+另一个终端执行：
+
+```bash
+qmt health
+qmt capabilities
+qmt market quote --symbol 000001.SZ --symbol 600519.SH
+qmt order preview --symbol 000001.SZ --side buy --quantity 100 --price 10.50
+```
+
+所有 CLI 命令默认输出 JSON。`qmtlink` 是 `qmt` 的等价备用命令。
+
+## Python SDK
+
+```python
+from qmtlink import QMTClient
+
+with QMTClient("http://127.0.0.1:8000") as client:
+    print(client.health())
+    print(client.get_quotes(["000001.SZ"]))
+```
+
+## Bridge 诊断
+
+```bash
+qmt bridge doctor
+```
+
+真实模式会延迟导入 xtquant，基础客户端包在 Linux/macOS 上不会导入它：
+
+```bash
+qmt bridge run
+```
+
+## 安全原则
+
+- 真实交易默认关闭。
+- 交易请求必须携带唯一 `client_order_id`。
+- 下单请求不得在网络超时后盲目重试。
+- API Key 通过 `QMTLINK_API_KEY` 提供，不建议放入命令参数。
+
+## 环境变量
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `QMTLINK_URL` | `http://127.0.0.1:8000` | CLI/SDK 服务地址 |
+| `QMTLINK_API_KEY` | 空 | API Key |
+| `QMTLINK_HOST` | `127.0.0.1` | Bridge 监听地址 |
+| `QMTLINK_PORT` | `8000` | Bridge 监听端口 |
+| `QMTLINK_MODE` | `real` | `real` 或 `mock` |
+| `QMTLINK_ALLOW_LIVE_ORDERS` | `false` | 允许提交订单 |
+
+## 开发
+
+```bash
+uv sync --extra server
+uv run pytest
+uv run ruff check .
+uv build --no-sources
+```
+
+开发路线见 [ROADMAP.md](ROADMAP.md)。
+
+## License
+
+MIT。QmtLink 与 miniQMT、QMT、xtquant 及其权利方不存在官方隶属或背书关系。

qmtlink-0.1.0a1/README.md

@@ -0,0 +1,99 @@
+# QmtLink
+
+QmtLink 是一个非官方的 miniQMT/xtquant 跨平台中转项目，提供：
+
+- Windows Bridge 一键启动命令
+- 面向 AI 和自动化脚本的 JSON CLI
+- 面向 Python 量化项目的 SDK
+- HTTP API（实时 WebSocket 将在后续版本加入）
+
+> 当前版本是开发预览版。Mock Bridge、HTTP API、CLI 和 SDK 可用；真实 miniQMT
+> 交易尚未实现，请勿用于实盘。
+
+## 安装
+
+客户端和 CLI：
+
+```bash
+uv add qmtlink
+```
+
+Windows Bridge：
+
+```bash
+uv add "qmtlink[server]"
+```
+
+## 快速体验
+
+启动 Mock Bridge：
+
+```bash
+qmt bridge run --mock
+```
+
+另一个终端执行：
+
+```bash
+qmt health
+qmt capabilities
+qmt market quote --symbol 000001.SZ --symbol 600519.SH
+qmt order preview --symbol 000001.SZ --side buy --quantity 100 --price 10.50
+```
+
+所有 CLI 命令默认输出 JSON。`qmtlink` 是 `qmt` 的等价备用命令。
+
+## Python SDK
+
+```python
+from qmtlink import QMTClient
+
+with QMTClient("http://127.0.0.1:8000") as client:
+    print(client.health())
+    print(client.get_quotes(["000001.SZ"]))
+```
+
+## Bridge 诊断
+
+```bash
+qmt bridge doctor
+```
+
+真实模式会延迟导入 xtquant，基础客户端包在 Linux/macOS 上不会导入它：
+
+```bash
+qmt bridge run
+```
+
+## 安全原则
+
+- 真实交易默认关闭。
+- 交易请求必须携带唯一 `client_order_id`。
+- 下单请求不得在网络超时后盲目重试。
+- API Key 通过 `QMTLINK_API_KEY` 提供，不建议放入命令参数。
+
+## 环境变量
+
+| 变量 | 默认值 | 用途 |
+|---|---|---|
+| `QMTLINK_URL` | `http://127.0.0.1:8000` | CLI/SDK 服务地址 |
+| `QMTLINK_API_KEY` | 空 | API Key |
+| `QMTLINK_HOST` | `127.0.0.1` | Bridge 监听地址 |
+| `QMTLINK_PORT` | `8000` | Bridge 监听端口 |
+| `QMTLINK_MODE` | `real` | `real` 或 `mock` |
+| `QMTLINK_ALLOW_LIVE_ORDERS` | `false` | 允许提交订单 |
+
+## 开发
+
+```bash
+uv sync --extra server
+uv run pytest
+uv run ruff check .
+uv build --no-sources
+```
+
+开发路线见 [ROADMAP.md](ROADMAP.md)。
+
+## License
+
+MIT。QmtLink 与 miniQMT、QMT、xtquant 及其权利方不存在官方隶属或背书关系。

qmtlink-0.1.0a1/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "qmtlink"
+version = "0.1.0a1"
+description = "An unofficial CLI, Python SDK, and HTTP bridge for miniQMT/xtquant"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "miniqmt",
+    "qmt",
+    "xtquant",
+    "trading",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+    "typer>=0.27.1",
+]
+
+[[project.authors]]
+name = "QmtLink Contributors"
+
+[project.scripts]
+qmt = "qmtlink.cli.main:main"
+qmtlink = "qmtlink.cli.main:main"
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.141.1",
+    "uvicorn[standard]>=0.52.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ilwk/qmtlink"
+Repository = "https://github.com/ilwk/qmtlink"
+Issues = "https://github.com/ilwk/qmtlink/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.1",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qmtlink-0.1.0a1/pyproject.toml.orig

@@ -0,0 +1,58 @@
+[project]
+name = "qmtlink"
+version = "0.1.0a1"
+description = "An unofficial CLI, Python SDK, and HTTP bridge for miniQMT/xtquant"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "QmtLink Contributors" }]
+keywords = ["miniqmt", "qmt", "xtquant", "trading", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.4",
+    "typer>=0.27.1",
+]
+
+[project.scripts]
+qmt = "qmtlink.cli.main:main"
+qmtlink = "qmtlink.cli.main:main"
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.141.1",
+    "uvicorn[standard]>=0.52.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/ilwk/qmtlink"
+Repository = "https://github.com/ilwk/qmtlink"
+Issues = "https://github.com/ilwk/qmtlink/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.1",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qmtlink-0.1.0a1/src/qmtlink/__init__.py

@@ -0,0 +1,13 @@
+"""Public Python SDK for QmtLink."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import QMTClient
+from .models import OrderRequest, OrderSide, OrderType
+
+try:
+    __version__ = version("qmtlink")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0.0.0"
+
+__all__ = ["QMTClient", "OrderRequest", "OrderSide", "OrderType", "__version__"]

qmtlink-0.1.0a1/src/qmtlink/__main__.py

@@ -0,0 +1,4 @@
+from .cli.main import main
+
+if __name__ == "__main__":
+    main()

qmtlink-0.1.0a1/src/qmtlink/bridge/__init__.py

@@ -0,0 +1,4 @@
+from .base import Bridge
+from .factory import create_bridge
+
+__all__ = ["Bridge", "create_bridge"]

qmtlink-0.1.0a1/src/qmtlink/bridge/base.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from qmtlink.models import OrderPreview, OrderRequest, OrderResult, Quote
+
+
+class Bridge(Protocol):
+    mode: str
+
+    def health(self) -> dict[str, object]: ...
+
+    def capabilities(self) -> dict[str, object]: ...
+
+    def get_quotes(self, symbols: list[str]) -> list[Quote]: ...
+
+    def preview_order(self, order: OrderRequest) -> OrderPreview: ...
+
+    def place_order(self, order: OrderRequest) -> OrderResult: ...

qmtlink-0.1.0a1/src/qmtlink/bridge/factory.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from qmtlink.errors import QMTLinkError
+
+from .base import Bridge
+from .mock import MockBridge
+from .xtquant import XtQuantBridge
+
+
+def create_bridge(mode: str) -> Bridge:
+    normalized = mode.strip().lower()
+    if normalized == "mock":
+        return MockBridge()
+    if normalized == "real":
+        return XtQuantBridge()
+    raise QMTLinkError("INVALID_MODE", f"unsupported bridge mode: {mode}")

qmtlink-0.1.0a1/src/qmtlink/bridge/mock.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import time
+
+from qmtlink.models import OrderPreview, OrderRequest, OrderResult, Quote
+
+
+class MockBridge:
+    mode = "mock"
+
+    def health(self) -> dict[str, object]:
+        return {"mode": self.mode, "qmt_connected": False, "mock": True}
+
+    def capabilities(self) -> dict[str, object]:
+        return {
+            "mode": self.mode,
+            "market_data": True,
+            "realtime_stream": False,
+            "trading": True,
+            "real_trading": False,
+        }
+
+    def get_quotes(self, symbols: list[str]) -> list[Quote]:
+        now = int(time.time() * 1000)
+        return [
+            Quote(
+                symbol=symbol,
+                last_price=round(8 + (sum(map(ord, symbol)) % 5000) / 100, 2),
+                volume=0,
+                timestamp=now,
+            )
+            for symbol in symbols
+        ]
+
+    def preview_order(self, order: OrderRequest) -> OrderPreview:
+        estimated = None if order.price is None else round(order.price * order.quantity, 2)
+        return OrderPreview(
+            client_order_id=order.client_order_id,
+            symbol=order.symbol,
+            side=order.side,
+            quantity=order.quantity,
+            price=order.price,
+            order_type=order.order_type,
+            estimated_amount=estimated,
+            risk_checks={
+                "valid_quantity": True,
+                "valid_price": True,
+                "real_trading": False,
+            },
+        )
+
+    def place_order(self, order: OrderRequest) -> OrderResult:
+        return OrderResult(
+            client_order_id=order.client_order_id,
+            order_id=f"mock-{order.client_order_id}",
+            status="accepted",
+            submitted=True,
+        )

qmtlink-0.1.0a1/src/qmtlink/bridge/xtquant.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qmtlink.errors import QMTLinkError
+from qmtlink.models import OrderPreview, OrderRequest, OrderResult, Quote
+
+
+class XtQuantBridge:
+    """Thin, deliberately limited adapter for a locally installed xtquant."""
+
+    mode = "real"
+
+    def __init__(self) -> None:
+        try:
+            from xtquant import xtdata
+        except ImportError as exc:
+            raise QMTLinkError(
+                "XTQUANT_NOT_INSTALLED",
+                "xtquant is unavailable; run `qmt bridge doctor` on the miniQMT machine",
+            ) from exc
+        self._xtdata = xtdata
+
+    def health(self) -> dict[str, object]:
+        return {"mode": self.mode, "qmt_connected": True, "mock": False}
+
+    def capabilities(self) -> dict[str, object]:
+        return {
+            "mode": self.mode,
+            "market_data": True,
+            "realtime_stream": False,
+            "trading": False,
+            "real_trading": False,
+        }
+
+    @staticmethod
+    def _number(data: dict[str, Any], *keys: str) -> float | None:
+        for key in keys:
+            value = data.get(key)
+            if value is not None:
+                return float(value)
+        return None
+
+    def get_quotes(self, symbols: list[str]) -> list[Quote]:
+        raw = self._xtdata.get_full_tick(symbols)
+        quotes: list[Quote] = []
+        for symbol in symbols:
+            item = raw.get(symbol, {})
+            quotes.append(
+                Quote(
+                    symbol=symbol,
+                    last_price=self._number(item, "lastPrice", "last_price") or 0.0,
+                    open=self._number(item, "open"),
+                    high=self._number(item, "high"),
+                    low=self._number(item, "low"),
+                    volume=self._number(item, "volume"),
+                    timestamp=item.get("time") or item.get("timestamp"),
+                )
+            )
+        return quotes
+
+    def preview_order(self, order: OrderRequest) -> OrderPreview:
+        estimated = None if order.price is None else round(order.price * order.quantity, 2)
+        return OrderPreview(
+            client_order_id=order.client_order_id,
+            symbol=order.symbol,
+            side=order.side,
+            quantity=order.quantity,
+            price=order.price,
+            order_type=order.order_type,
+            estimated_amount=estimated,
+            risk_checks={"trading_implemented": False},
+        )
+
+    def place_order(self, order: OrderRequest) -> OrderResult:
+        raise QMTLinkError(
+            "TRADING_NOT_IMPLEMENTED",
+            "real xtquant trading is not implemented in this preview release",
+        )

qmtlink-0.1.0a1/src/qmtlink/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface."""

qmtlink-0.1.0a1/src/qmtlink/cli/main.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import platform
+import sys
+from typing import Annotated
+
+import typer
+
+from qmtlink.client import QMTClient
+from qmtlink.config import ClientSettings, ServerSettings
+from qmtlink.errors import QMTLinkError
+from qmtlink.models import OrderRequest, OrderSide, OrderType
+
+from .output import emit
+
+app = typer.Typer(help="CLI, SDK, and bridge for miniQMT/xtquant", no_args_is_help=True)
+bridge_app = typer.Typer(help="Manage the local Windows Bridge", no_args_is_help=True)
+market_app = typer.Typer(help="Query market data", no_args_is_help=True)
+order_app = typer.Typer(help="Preview and submit orders", no_args_is_help=True)
+app.add_typer(bridge_app, name="bridge")
+app.add_typer(market_app, name="market")
+app.add_typer(order_app, name="order")
+
+
+def _client() -> QMTClient:
+    settings = ClientSettings.from_env()
+    return QMTClient(settings.base_url, api_key=settings.api_key, timeout=settings.timeout)
+
+
+def _handle_error(exc: Exception) -> None:
+    if isinstance(exc, QMTLinkError):
+        emit(exc.as_dict(), ok=False)
+        raise typer.Exit(code=4 if exc.retryable else 5)
+    emit({"code": type(exc).__name__.upper(), "message": str(exc), "retryable": False}, ok=False)
+    raise typer.Exit(code=1)
+
+
+@bridge_app.command("doctor")
+def bridge_doctor(pretty: bool = typer.Option(False, "--pretty")) -> None:
+    xtquant_available = importlib.util.find_spec("xtquant") is not None
+    emit(
+        {
+            "platform": platform.system().lower(),
+            "python": platform.python_version(),
+            "xtquant_importable": xtquant_available,
+            "api_key_configured": bool(os.getenv("QMTLINK_API_KEY")),
+            "ready_for_mock": True,
+            "ready_for_real": sys.platform == "win32" and xtquant_available,
+        },
+        pretty=pretty,
+    )
+
+
+@bridge_app.command("run")
+def bridge_run(
+    mock: bool = typer.Option(False, "--mock", help="Run without miniQMT"),
+    host: str | None = typer.Option(None, "--host"),
+    port: int | None = typer.Option(None, "--port", min=1, max=65535),
+) -> None:
+    base = ServerSettings.from_env()
+    settings = ServerSettings(
+        host=host or base.host,
+        port=port or base.port,
+        mode="mock" if mock else base.mode,
+        api_key=base.api_key,
+        allow_live_orders=base.allow_live_orders,
+    )
+    try:
+        from qmtlink.server.runner import run_server
+
+        run_server(settings)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+@app.command("health")
+def health(pretty: bool = typer.Option(False, "--pretty")) -> None:
+    try:
+        with _client() as client:
+            emit(client.health(), pretty=pretty)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+@app.command("capabilities")
+def capabilities(pretty: bool = typer.Option(False, "--pretty")) -> None:
+    try:
+        with _client() as client:
+            emit(client.capabilities(), pretty=pretty)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+@market_app.command("quote")
+def market_quote(
+    symbols: Annotated[list[str], typer.Option("--symbol", help="Repeat for multiple symbols")],
+    pretty: bool = typer.Option(False, "--pretty"),
+) -> None:
+    try:
+        with _client() as client:
+            emit(client.get_quotes(symbols), pretty=pretty)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+def _order_request(
+    symbol: str,
+    side: OrderSide,
+    quantity: int,
+    price: float | None,
+    order_type: OrderType,
+    client_order_id: str | None,
+    live: bool,
+) -> OrderRequest:
+    values: dict[str, object] = {
+        "symbol": symbol,
+        "side": side,
+        "quantity": quantity,
+        "price": price,
+        "order_type": order_type,
+        "live": live,
+    }
+    if client_order_id:
+        values["client_order_id"] = client_order_id
+    return OrderRequest.model_validate(values)
+
+
+@order_app.command("preview")
+def order_preview(
+    symbol: Annotated[str, typer.Option("--symbol")],
+    side: Annotated[OrderSide, typer.Option("--side")],
+    quantity: Annotated[int, typer.Option("--quantity", min=1)],
+    price: Annotated[float | None, typer.Option("--price", min=0)] = None,
+    order_type: Annotated[OrderType, typer.Option("--order-type")] = OrderType.LIMIT,
+    client_order_id: Annotated[str | None, typer.Option("--client-order-id")] = None,
+    pretty: Annotated[bool, typer.Option("--pretty")] = False,
+) -> None:
+    try:
+        request = _order_request(symbol, side, quantity, price, order_type, client_order_id, False)
+        with _client() as client:
+            emit(client.preview_order(request), pretty=pretty)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+@order_app.command("place")
+def order_place(
+    symbol: Annotated[str, typer.Option("--symbol")],
+    side: Annotated[OrderSide, typer.Option("--side")],
+    quantity: Annotated[int, typer.Option("--quantity", min=1)],
+    price: Annotated[float | None, typer.Option("--price", min=0)] = None,
+    order_type: Annotated[OrderType, typer.Option("--order-type")] = OrderType.LIMIT,
+    client_order_id: Annotated[str | None, typer.Option("--client-order-id")] = None,
+    live: Annotated[bool, typer.Option("--live", help="Submit instead of preview")] = False,
+    pretty: Annotated[bool, typer.Option("--pretty")] = False,
+) -> None:
+    try:
+        request = _order_request(symbol, side, quantity, price, order_type, client_order_id, live)
+        with _client() as client:
+            result = client.place_order(request) if live else client.preview_order(request)
+            emit(result, pretty=pretty)
+    except Exception as exc:
+        _handle_error(exc)
+
+
+def main() -> None:
+    app()

qmtlink-0.1.0a1/src/qmtlink/cli/output.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {key: _jsonable(item) for key, item in value.items()}
+    return value
+
+
+def emit(data: Any, *, ok: bool = True, pretty: bool = False) -> None:
+    payload = {"ok": ok, "data": _jsonable(data)} if ok else {"ok": False, "error": data}
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2 if pretty else None)
+    sys.stdout.write("\n")

qmtlink-0.1.0a1/src/qmtlink/client/__init__.py

@@ -0,0 +1,3 @@
+from .client import QMTClient
+
+__all__ = ["QMTClient"]

qmtlink-0.1.0a1/src/qmtlink/client/client.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from qmtlink.config import ClientSettings
+from qmtlink.errors import QMTLinkError
+from qmtlink.models import OrderPreview, OrderRequest, OrderResult, Quote
+
+
+class QMTClient:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        settings = ClientSettings.from_env()
+        self._api_key = api_key if api_key is not None else settings.api_key
+        self._client = httpx.Client(
+            base_url=(base_url or settings.base_url).rstrip("/"),
+            timeout=timeout if timeout is not None else settings.timeout,
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        headers = dict(kwargs.pop("headers", {}))
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+        try:
+            response = self._client.request(method, path, headers=headers, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise QMTLinkError("REQUEST_TIMEOUT", str(exc), retryable=True) from exc
+        except httpx.HTTPError as exc:
+            raise QMTLinkError("NETWORK_ERROR", str(exc), retryable=True) from exc
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise QMTLinkError(
+                "INVALID_RESPONSE", f"server returned HTTP {response.status_code} without JSON"
+            ) from exc
+
+        if response.is_error or not payload.get("ok", False):
+            error = payload.get("error") or {}
+            raise QMTLinkError(
+                error.get("code", "HTTP_ERROR"),
+                error.get("message", f"HTTP {response.status_code}"),
+                retryable=bool(error.get("retryable", False)),
+                status_code=response.status_code,
+            )
+        return payload
+
+    def health(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/health")["data"]
+
+    def capabilities(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/capabilities")["data"]
+
+    def get_quotes(self, symbols: list[str]) -> list[Quote]:
+        data = self._request("POST", "/api/v1/market/quotes", json={"symbols": symbols})["data"]
+        return [Quote.model_validate(item) for item in data]
+
+    def preview_order(self, order: OrderRequest) -> OrderPreview:
+        data = self._request(
+            "POST",
+            "/api/v1/orders/preview",
+            json=order.model_dump(mode="json"),
+        )["data"]
+        return OrderPreview.model_validate(data)
+
+    def place_order(self, order: OrderRequest) -> OrderResult:
+        data = self._request("POST", "/api/v1/orders", json=order.model_dump(mode="json"))["data"]
+        return OrderResult.model_validate(data)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> QMTClient:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()

qmtlink-0.1.0a1/src/qmtlink/config.py

@@ -0,0 +1,49 @@
+"""Environment-backed settings shared by the CLI and server."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True, slots=True)
+class ClientSettings:
+    base_url: str = "http://127.0.0.1:8000"
+    api_key: str | None = None
+    timeout: float = 30.0
+
+    @classmethod
+    def from_env(cls) -> ClientSettings:
+        defaults = cls()
+        return cls(
+            base_url=os.getenv("QMTLINK_URL", defaults.base_url),
+            api_key=os.getenv("QMTLINK_API_KEY") or None,
+            timeout=float(os.getenv("QMTLINK_TIMEOUT", str(defaults.timeout))),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServerSettings:
+    host: str = "127.0.0.1"
+    port: int = 8000
+    mode: str = "real"
+    api_key: str | None = None
+    allow_live_orders: bool = False
+
+    @classmethod
+    def from_env(cls) -> ServerSettings:
+        defaults = cls()
+        return cls(
+            host=os.getenv("QMTLINK_HOST", defaults.host),
+            port=int(os.getenv("QMTLINK_PORT", str(defaults.port))),
+            mode=os.getenv("QMTLINK_MODE", defaults.mode),
+            api_key=os.getenv("QMTLINK_API_KEY") or None,
+            allow_live_orders=_env_bool("QMTLINK_ALLOW_LIVE_ORDERS"),
+        )

qmtlink-0.1.0a1/src/qmtlink/errors.py

@@ -0,0 +1,26 @@
+"""QmtLink exceptions."""
+
+from __future__ import annotations
+
+
+class QMTLinkError(RuntimeError):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        retryable: bool = False,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.status_code = status_code
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "retryable": self.retryable,
+        }

qmtlink-0.1.0a1/src/qmtlink/models/__init__.py

@@ -0,0 +1,12 @@
+from .market import Quote, QuoteRequest
+from .order import OrderPreview, OrderRequest, OrderResult, OrderSide, OrderType
+
+__all__ = [
+    "OrderPreview",
+    "OrderRequest",
+    "OrderResult",
+    "OrderSide",
+    "OrderType",
+    "Quote",
+    "QuoteRequest",
+]

qmtlink-0.1.0a1/src/qmtlink/models/market.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class QuoteRequest(BaseModel):
+    symbols: list[str] = Field(min_length=1, max_length=500)
+
+    @field_validator("symbols")
+    @classmethod
+    def normalize_symbols(cls, symbols: list[str]) -> list[str]:
+        normalized = [symbol.strip().upper() for symbol in symbols if symbol.strip()]
+        if not normalized:
+            raise ValueError("at least one symbol is required")
+        return list(dict.fromkeys(normalized))
+
+
+class Quote(BaseModel):
+    symbol: str
+    last_price: float
+    open: float | None = None
+    high: float | None = None
+    low: float | None = None
+    volume: float | None = None
+    timestamp: int | None = None

qmtlink-0.1.0a1/src/qmtlink/models/order.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class OrderSide(StrEnum):
+    BUY = "buy"
+    SELL = "sell"
+
+
+class OrderType(StrEnum):
+    LIMIT = "limit"
+    MARKET = "market"
+
+
+class OrderRequest(BaseModel):
+    symbol: str
+    side: OrderSide
+    quantity: int = Field(gt=0)
+    price: float | None = Field(default=None, gt=0)
+    order_type: OrderType = OrderType.LIMIT
+    client_order_id: str = Field(default_factory=lambda: uuid4().hex, min_length=8, max_length=128)
+    live: bool = False
+
+    @model_validator(mode="after")
+    def validate_order(self) -> OrderRequest:
+        self.symbol = self.symbol.strip().upper()
+        if not self.symbol:
+            raise ValueError("symbol is required")
+        if self.order_type == OrderType.LIMIT and self.price is None:
+            raise ValueError("price is required for a limit order")
+        return self
+
+
+class OrderPreview(BaseModel):
+    client_order_id: str
+    symbol: str
+    side: OrderSide
+    quantity: int
+    price: float | None
+    order_type: OrderType
+    estimated_amount: float | None
+    submitted: bool = False
+    risk_checks: dict[str, bool]
+
+
+class OrderResult(BaseModel):
+    client_order_id: str
+    order_id: str
+    status: str
+    submitted: bool

qmtlink-0.1.0a1/src/qmtlink/server/__init__.py

@@ -0,0 +1 @@
+"""Optional FastAPI server package."""

qmtlink-0.1.0a1/src/qmtlink/server/app.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import hmac
+import time
+from uuid import uuid4
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from qmtlink import __version__
+from qmtlink.bridge import Bridge, create_bridge
+from qmtlink.config import ServerSettings
+from qmtlink.errors import QMTLinkError
+from qmtlink.models import OrderRequest, QuoteRequest
+
+
+def _success(data: object, started: float) -> dict[str, object]:
+    return {
+        "ok": True,
+        "request_id": f"req_{uuid4().hex}",
+        "data": data,
+        "meta": {"elapsed_ms": round((time.perf_counter() - started) * 1000, 3)},
+    }
+
+
+def create_app(
+    bridge: Bridge | None = None,
+    settings: ServerSettings | None = None,
+) -> FastAPI:
+    settings = settings or ServerSettings.from_env()
+    backend = bridge or create_bridge(settings.mode)
+    app = FastAPI(title="QmtLink", version=__version__)
+    app.state.bridge = backend
+    app.state.settings = settings
+
+    @app.exception_handler(QMTLinkError)
+    async def handle_qmtlink_error(_request: Request, exc: QMTLinkError) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code or 500,
+            content={"ok": False, "error": exc.as_dict()},
+        )
+
+    def require_api_key(api_key: str | None) -> None:
+        expected = settings.api_key
+        if not expected:
+            raise HTTPException(
+                status_code=503,
+                detail={"code": "API_KEY_NOT_CONFIGURED", "message": "API key is required"},
+            )
+        if api_key is None or not hmac.compare_digest(api_key, expected):
+            raise HTTPException(
+                status_code=401,
+                detail={"code": "INVALID_API_KEY", "message": "invalid or missing API key"},
+            )
+
+    @app.exception_handler(HTTPException)
+    async def handle_http_error(_request: Request, exc: HTTPException) -> JSONResponse:
+        detail = exc.detail if isinstance(exc.detail, dict) else {"message": str(exc.detail)}
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "ok": False,
+                "error": {
+                    "code": detail.get("code", "HTTP_ERROR"),
+                    "message": detail.get("message", str(exc.detail)),
+                    "retryable": False,
+                },
+            },
+        )
+
+    @app.get("/api/v1/health")
+    async def health() -> dict[str, object]:
+        started = time.perf_counter()
+        data = {"version": __version__, **backend.health()}
+        return _success(data, started)
+
+    @app.get("/api/v1/capabilities")
+    async def capabilities() -> dict[str, object]:
+        started = time.perf_counter()
+        return _success(backend.capabilities(), started)
+
+    @app.post("/api/v1/market/quotes")
+    async def quotes(payload: QuoteRequest) -> dict[str, object]:
+        started = time.perf_counter()
+        data = [quote.model_dump(mode="json") for quote in backend.get_quotes(payload.symbols)]
+        return _success(data, started)
+
+    @app.post("/api/v1/orders/preview")
+    async def preview_order(
+        payload: OrderRequest,
+        x_api_key: str | None = Header(default=None),
+    ) -> dict[str, object]:
+        started = time.perf_counter()
+        require_api_key(x_api_key)
+        return _success(backend.preview_order(payload).model_dump(mode="json"), started)
+
+    @app.post("/api/v1/orders")
+    async def place_order(
+        payload: OrderRequest,
+        x_api_key: str | None = Header(default=None),
+    ) -> dict[str, object]:
+        started = time.perf_counter()
+        require_api_key(x_api_key)
+        if not payload.live:
+            raise HTTPException(
+                status_code=400,
+                detail={"code": "LIVE_FLAG_REQUIRED", "message": "set live=true to submit"},
+            )
+        if not settings.allow_live_orders:
+            raise HTTPException(
+                status_code=403,
+                detail={"code": "LIVE_ORDERS_DISABLED", "message": "live orders are disabled"},
+            )
+        return _success(backend.place_order(payload).model_dump(mode="json"), started)
+
+    return app

qmtlink-0.1.0a1/src/qmtlink/server/runner.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from qmtlink.config import ServerSettings
+
+
+def run_server(settings: ServerSettings) -> None:
+    try:
+        import uvicorn
+    except ImportError as exc:  # pragma: no cover - depends on installation extras
+        raise RuntimeError('server dependencies are missing; install "qmtlink[server]"') from exc
+
+    from .app import create_app
+
+    uvicorn.run(create_app(settings=settings), host=settings.host, port=settings.port, workers=1)