Metadata-Version: 2.4
Name: qmt-api
Version: 0.4.1
Summary: Remote xtquant service based on a layered xqshare fork
Requires-Python: >=3.10
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rpyc>=6.0
Provides-Extra: server
Requires-Dist: numpy>=2.5.0; (python_version >= '3.12') and extra == 'server'
Requires-Dist: pandas>=3.0.3; (python_version >= '3.12') and extra == 'server'
Requires-Dist: pywin32>=306; (python_version >= '3.12' and sys_platform == 'win32') and extra == 'server'
Requires-Dist: xtquant; (python_version >= '3.12') and extra == 'server'
Description-Content-Type: text/markdown

# qmt-api

基于 fork xqshare 的远程 xtquant 服务，通过 RPyC 透明代理实现 Linux 策略机调用 Windows QMT 的完整链路。

## 架构

```
Linux 策略机                          Windows 服务机
┌─────────────────────┐              ┌──────────────────────┐
│  策略代码            │   RPyC      │  qmt-api Service      │
│  pip install qmt-api │ ◄──────────► │  → xtquant            │
│                     │   TCP/SSL    │  → QMT/miniQMT        │
│  adapter.get_tick() │              │  → 券商交易服务器      │
│  trader.order_stock()│              │                       │
└─────────────────────┘              └──────────────────────┘
```

## 快速开始

### Linux 客户端安装

```bash
# 从 GitHub 安装（不含 xtquant/pywin32）
pip install git+ssh://git@github.com/Judioljuse/qmt-api.git

# 或 HTTPS
pip install git+https://github.com/Judioljuse/qmt-api.git
```

### Windows 服务端部署

```powershell
# 克隆仓库
git clone git@github.com:Judioljuse/qmt-api.git
cd qmt-api

# 安装依赖（含 xtquant/pywin32/numpy/pandas）
uv sync --extra server

# 配置环境
Copy-Item deploy/env/.env.server.example .env
# 编辑 .env 填入 QMT 路径和账号

# 启动服务
uv run python -m qmt_api.upstream.xqshare_compat.server --port 18812
```

### 使用示例

```python
import os
from qmt_api import XtQuantRemote, XtDataAdapter, XtTraderAdapter

# 连接 Windows 服务端（host/port 从环境变量或参数传入）
remote = XtQuantRemote(
    host=os.environ.get('XQSHARE_REMOTE_HOST'),
    port=int(os.environ.get('XQSHARE_REMOTE_PORT', '18812')),
    client_id='client-standard',
    client_secret='xqshare-default-secret'
)

# 行情查询
xtdata = XtDataAdapter(remote)
tick = xtdata.get_full_tick(['000001.SZ'])

# 交易查询
trader = XtTraderAdapter(remote, userdata_path='/dummy')
positions = trader.query_stock_positions('YOUR_ACCOUNT_ID')

remote.close()
```

> 自 v0.4.0 起支持顶层快捷导入，无需再写内部模块路径。
> 客户端不安装 xtquant，所有调用通过 RPyC 透明代理到 Windows 服务端。

## 更新

### Linux 客户端更新

```bash
pip install --upgrade git+https://github.com/Judioljuse/qmt-api.git
```

### Windows 服务端更新

```powershell
git pull
uv sync --extra server
# 重启服务
```

## 文档

- [API 参考文档](docs/api-reference.md)
- [接口验收 Notebook](docs/DEMO.ipynb)
- [测试规范](docs/testing-conventions.md)
- [下单/撤单验收指南](docs/trading-verification-guide.md)
- [上游同步策略](docs/upstream-sync-strategy.md)
- [认证扩展指南](docs/auth-extension-guide.md)

## 版本

当前版本：0.4.1

详见 [CHANGELOG.md](CHANGELOG.md) 或 [GitHub Releases](https://github.com/Judioljuse/qmt-api/releases)
