Metadata-Version: 2.4
Name: panda-trade
Version: 0.1.7
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.7`。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，也不能把两种时效混用。

# 订单/成交用游标惰性遍历，不一次性加载全量历史
print(client.orders())                         # 默认最近 20 条
print(client.orders(trade_date="today"))       # 今天订单
print(client.trades(trade_date="today"))       # 今天成交
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)
# 批量撤单默认先预演
cancel_plan = client.cancel_all(dry_run=True)
print(cancel_plan)
# 目标仓位默认先预演
target_plan = client.target_position([
    {"symbol": "黄金", "direction": "long", "volume": 5},
    {"symbol": "白银", "direction": "short", "volume": 5},
])
print(target_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
```

## AI 安全客户端

AI 集成优先使用 `AgentClient`。它先生成短时有效的冻结计划，用户确认后只按 `planId` 执行，确认阶段不能改变交易参数：

```python
from panda_trade import AgentClient

agent = AgentClient()
spec = agent.capabilities()  # 启动时读取统一语义和安全规则
plan = agent.prepare_order("au2610", "buy", "open", 5)
print(plan["planId"], plan["summary"])

# 将计划完整展示给用户并取得明确确认后：
operation = agent.execute_plan(plan["planId"], confirmed=True)
print(agent.operation(operation["operationId"]))
```
