Metadata-Version: 2.4
Name: panda-trade
Version: 0.1.6
Summary: PandaAI 交易开放 API 的 Python SDK / CLI（OAuth 登录，无需 API Key）
Project-URL: Homepage, https://www.pandaaiquant.com
Keywords: pandaai,futures,trading,contest,oauth
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24

# panda-trade

PandaAI 期货仿真交易大赛 Python SDK。默认连接：
`https://www.pandaaiquant.com/openapi/v1`。

SDK 只提供账户查询和交易能力：资金、持仓、委托、挂单、成交、排名、下单、撤单和
服务端清仓和移仓换月。不提供行情、K 线、主力合约、品种搜索或 `panda_data` 数据代理；下单时
必须使用赛事提供的实际可交易合约代码。

## 安装

```bash
pip install -U panda-trade
```

## 登录

```python
from panda_trade import login

login()
```

SDK 使用 OAuth + PKCE 打开 PandaAI 官网统一登录页，不需要 API Key，也不会保存官网密码。
浏览器已经登录官网时会直接完成赛事账户授权；未登录时在官网登录，登录后自动回到
Python 本地回调。凭证保存在用户目录的 `.panda-trade/credentials.json`。

也可以使用命令行：

```bash
panda-trade login
panda-trade whoami
panda-trade doctor
```

当前版本：`0.1.6`。SDK 使用的登录账号是 PandaAI 官网账号，不能把密码写入代码或提交到仓库。

服务器没有图形界面时，请在有浏览器的设备打开 CLI 输出的设备验证地址；官网登录态确认后
会自动完成授权，Python 客户端无需接收或保存官网账号密码。

## 交易示例

```python
from panda_trade import Client

client = Client()

print(client.snapshot())

# 发布策略前先使用 dry_run 验证
result = client.buy_open("rb2610", 1, price=3000, dry_run=True)
print(result)
# 不传 price 时自动按市价 IOC；传 price 时自动按 GFD 限价（当日有效）。
# 不需要设置 tif，也不能把两种时效混用。

# 订单/成交用游标惰性遍历，不一次性加载全量历史
for order in client.iter_orders(count=200):
    print(order["orderId"], order["status"])
for trade in client.iter_trades(count=200):
    print(trade["tradeId"], trade["price"])

# 排名与服务端清仓（清仓先预演，确认后再执行）
print(client.ranking_me())
plan = client.close_all(dry_run=True)
print(plan)
# client.close_all(client_request_id="close-batch-20260818", dry_run=False)

# 移仓默认只预演：旧合约月份必须小于当前主力月份
roll_plan = client.rollover("黄金", 2, direction="long", from_contract="au2508")
print(roll_plan)
# 明确确认后复用批次号执行：
# client.rollover("黄金", 2, direction="long", from_contract="au2508",
#                 dry_run=False, client_request_id="roll-20260819-01")
```

通过环境变量覆盖服务地址或 OAuth client：

```text
PANDA_TRADE_BASE_URL
PANDA_TRADE_CLIENT_ID
PANDA_TRADE_HOME
```
