Metadata-Version: 2.4
Name: qmtlink
Version: 0.1.0a4
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: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: fastapi>=0.141.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: typer>=0.27.1
Requires-Dist: uvicorn[standard]>=0.52.1
Requires-Dist: xtquant>=250807.1.2 ; sys_platform == 'win32'
Requires-Python: >=3.11, <3.14
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
Description-Content-Type: text/markdown

# QmtLink

QmtLink 是一个面向 A 股 miniQMT/xtquant 的非官方中转工具，让 Windows 交易机、AI
命令行工具和 Python 量化项目使用同一套交易接口。

主要功能：

- 一条命令启动 Windows miniQMT 中转服务
- 提供默认输出 JSON 的 `qmt` 命令，方便 AI 和自动化脚本调用
- 提供 Python SDK，方便量化项目接入实盘
- 提供 HTTP 接口，隔离策略代码与 Windows miniQMT 环境
- 支持行情、资产、持仓、委托、成交、下单、查单和撤单
- 使用 SQLite 持久化下单幂等记录，降低重复下单风险

> 当前仍是开发预览版。模拟模式、HTTP 接口、命令行和 SDK 已可用；真实交易适配尚未在
> 你的券商 miniQMT 环境验证，请先使用模拟模式，切勿直接用于实盘。

## 安装

全局安装 `qmt` 命令：

```bash
uv tool install qmtlink
```

安装到自己的 Python 量化项目：

```bash
uv add qmtlink
```

不需要填写 `[server]`，也不需要手动追加 xtquant。Windows 会自动安装 xtquant，
Linux 和 macOS 只安装跨平台组件。

## 快速体验

启动不连接真实 miniQMT 的模拟中转服务：

```bash
qmt bridge run --mock
```

在另一个终端执行：

```bash
qmt health
qmt capabilities
qmt market quote --symbol 000001.SZ --symbol 600519.SH
qmt account asset
qmt account positions
qmt order preview --symbol 000001.SZ --side buy --quantity 100 --price 10.50
```

第一次运行时会自动生成配置文件和随机 API 密钥。所有命令默认输出 JSON。
`qmtlink` 也可以作为 `qmt` 的备用命令。

## 连接 Windows miniQMT

直接运行：

```powershell
qmt bridge run
```

QmtLink 第一次运行会自动生成配置文件，并在输出中显示文件位置。打开文件，只需填写：

```toml
qmt_path = 'C:\miniQMT安装目录\userdata_mini'
account_id = "你的资金账号"
```

保存后再次运行：

```powershell
qmt bridge run
```

不需要自己生成 API 密钥，也不需要设置环境变量。可使用 `qmt bridge doctor` 检查当前配置和
运行环境。

QmtLink 会启动唯一的 XtQuantTrader 运行实例，连接 miniQMT 并订阅账户。真实中转服务建议
使用 Python 3.11～3.13，并先在模拟盘或券商测试环境中验证。

## Python SDK

```python
from qmtlink import QMTClient

with QMTClient() as client:
    print(client.health())
    print(client.get_quotes(["000001.SZ"]))
    print(client.get_positions())
```

量化项目与 bridge 在同一台机器时，SDK 会自动读取同一份配置。分开部署时，在量化项目机器
的配置文件中设置 `url`，并使用与 bridge 相同的 `api_key`。

## 交易安全

- 真实下单和撤单默认关闭。
- 配置文件必须增加 `allow_live_orders = true` 才允许提交。
- 命令行还必须显式提供 `--live`。
- 每笔订单必须携带唯一的 `client_order_id`。
- `client_order_id` 会写入 SQLite，重启后仍会阻止重复提交。
- 下单超时后必须先查询订单状态，不能直接重试。
- API 密钥由 QmtLink 自动生成并保存在本地配置中，不要提交到 Git 仓库。

## 配置项

默认配置文件位置：

- Windows：`%APPDATA%\qmtlink\config.toml`
- Linux/macOS：`~/.config/qmtlink/config.toml`

常用配置：

| 配置 | 默认值 | 用途 |
|---|---|---|
| `api_key` | 自动生成 | CLI、SDK 和 bridge 共用的访问密钥 |
| `qmt_path` | 空 | Windows `userdata_mini` 完整路径 |
| `account_id` | 空 | miniQMT 资金账号 |

其他参数都有内置默认值。只有需要远程访问或开启实盘下单时，才需要手动增加 `url`、
`host`、`port` 或 `allow_live_orders`。

配置示例见 [qmtlink.toml.example](qmtlink.toml.example)。如需把配置放到其他位置，可设置
`QMTLINK_CONFIG` 指向该文件。

## 参与开发

```bash
uv sync --dev
uv run pytest
uv run ruff check .
uv build --no-sources
```

后续计划见 [ROADMAP.md](ROADMAP.md)，发版说明见
[docs/RELEASING.md](docs/RELEASING.md)。

## 许可证

本项目使用 MIT 许可证。QmtLink 与 miniQMT、QMT、xtquant 及其权利方不存在官方隶属或
背书关系。
