Metadata-Version: 2.4
Name: panda-trade
Version: 0.1.12
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` 数据代理；下单时
开仓可以传明确的中文品种名/品种码（例如“原油”或 `SC`），服务端会解析为当前主力实际合约；平仓必须使用持仓返回的实际合约代码，避免主力换月后误平。

## 安装

```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
```

当前版本以 `importlib.metadata.version('panda-trade')` 输出为准；安装命令始终跟随 PyPI `latest`。AI 或脚本可在开始使用前检查并更新：

```bash
python -m panda_trade.cli update --check
python -m panda_trade.cli update --yes
```

更新完成后重新启动当前 AI/进程；活动委托、未知回执或计划执行期间不要更新。SDK 使用的登录账号是 PandaAI 官网账号，不能把密码写入代码或提交到仓库。

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

## 交易示例

```python
from panda_trade import Client

client = Client()

print(client.snapshot())
print(client.quote("黄金"))  # 中文品种自动解析当前主力，返回最新价和完整行情时间

# 发布策略前先使用 dry_run 验证
result = client.buy_open("rb2610", 1, price=3000, dry_run=True)
print(result)
# 不传 price 时自动按市价 IOC；传 price 时自动按 GFD 限价（当日有效）。
# 不需要设置 tif，也不能把两种时效混用。
# 下单响应的 marketQuote 只用于展示，不能自动作为市价单委托价格。

# 订单/成交用游标惰性遍历，不一次性加载全量历史
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())
print(client.ranking(board_type="live"))       # 实时榜前十，含指标和得分
print(client.ranking(board_type="settled"))    # 结算榜前十
print(client.settlements())                     # 最近 5 个交易日
print(client.settlements(limit=30))             # 最多最近 30 个交易日
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"]))
```
