panda-trade 0.1.0__tar.gz

panda_trade-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: panda-trade
+Version: 0.1.0
+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`。
+
+## 安装
+
+```bash
+pip install panda-trade
+```
+
+## 登录
+
+```python
+from panda_trade import login
+
+login()
+```
+
+SDK 使用 OAuth + PKCE 打开官网授权页，不需要 API Key，也不会保存官网密码。凭证保存在
+用户目录的 `.panda-trade/credentials.json`。
+
+也可以使用命令行：
+
+```bash
+panda-trade login
+panda-trade whoami
+panda-trade doctor
+```
+
+## 交易示例
+
+```python
+from panda_trade import Client
+
+client = Client()
+
+print(client.snapshot())
+print(client.quote("rb2610"))
+
+# 发布策略前先使用 dry_run 验证
+result = client.buy_open("rb2610", 1, price=3000, dry_run=True)
+print(result)
+```
+
+通过环境变量覆盖服务地址或 OAuth client：
+
+```text
+PANDA_TRADE_BASE_URL
+PANDA_TRADE_CLIENT_ID
+PANDA_TRADE_HOME
+```

panda_trade-0.1.0/README.md

@@ -0,0 +1,52 @@
+# panda-trade
+
+PandaAI 期货仿真交易大赛 Python SDK。默认连接：
+`https://www.pandaaiquant.com/openapi/v1`。
+
+## 安装
+
+```bash
+pip install panda-trade
+```
+
+## 登录
+
+```python
+from panda_trade import login
+
+login()
+```
+
+SDK 使用 OAuth + PKCE 打开官网授权页，不需要 API Key，也不会保存官网密码。凭证保存在
+用户目录的 `.panda-trade/credentials.json`。
+
+也可以使用命令行：
+
+```bash
+panda-trade login
+panda-trade whoami
+panda-trade doctor
+```
+
+## 交易示例
+
+```python
+from panda_trade import Client
+
+client = Client()
+
+print(client.snapshot())
+print(client.quote("rb2610"))
+
+# 发布策略前先使用 dry_run 验证
+result = client.buy_open("rb2610", 1, price=3000, dry_run=True)
+print(result)
+```
+
+通过环境变量覆盖服务地址或 OAuth client：
+
+```text
+PANDA_TRADE_BASE_URL
+PANDA_TRADE_CLIENT_ID
+PANDA_TRADE_HOME
+```

panda_trade-0.1.0/panda_trade/__init__.py

@@ -0,0 +1,34 @@
+"""PandaAI 期货仿真大赛 SDK（skills 赛道）。
+
+快速开始：
+
+    from panda_trade import login, Client
+
+    login()                                    # 浏览器授权，一次即可
+    c = Client()                               # 自动续期，过期无感
+
+    c.snapshot()                               # 资金 + 持仓 + 挂单
+    c.buy_open("rb2510", 1, price=3200)        # 限价开多
+    c.sell_close("rb2510", 1)                  # 市价平多
+    c.cancel_all()                             # 撤掉全部挂单
+
+先用 dry_run 验证逻辑，确认无误再真下单：
+
+    c.buy_open("rb2510", 3, dry_run=True)
+"""
+
+from panda_trade.auth import Credentials, login, logout, refresh
+from panda_trade.client import Client
+from panda_trade.errors import (
+    AuthError,
+    ContestApiError,
+    OrderTimeout,
+    PandaContestError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "login", "logout", "refresh", "Credentials", "Client",
+    "PandaContestError", "AuthError", "ContestApiError", "OrderTimeout",
+]

panda_trade-0.1.0/panda_trade/auth.py

@@ -0,0 +1,269 @@
+"""登录与凭证管理。
+
+选手只需要 `login()` —— 其余（PKCE、本地回调 server、开浏览器、换 token、落盘）
+全部在这里完成。凭证存 ~/.panda-trade/credentials.json（权限 0600）。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import os
+import secrets
+import socket
+import stat
+import threading
+import time
+import urllib.parse
+import webbrowser
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import httpx
+
+from panda_trade.errors import AuthError, ContestApiError
+
+DEFAULT_BASE_URL = os.getenv("PANDA_TRADE_BASE_URL", "https://www.pandaaiquant.com")
+DEFAULT_CLIENT_ID = os.getenv("PANDA_TRADE_CLIENT_ID", "panda-contest-cli")
+API_PREFIX = "/openapi/v1"
+
+CRED_DIR = Path(os.getenv("PANDA_TRADE_HOME", Path.home() / ".panda-trade"))
+CRED_FILE = CRED_DIR / "credentials.json"
+
+# 提前多久刷新（避免请求发出时正好过期）
+_REFRESH_SKEW = 120
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str
+    expires_at: float
+    account_id: str = ""
+    contest_id: str = ""
+    scope: str = ""
+    base_url: str = DEFAULT_BASE_URL
+    client_id: str = DEFAULT_CLIENT_ID
+
+    @property
+    def expired(self) -> bool:
+        return time.time() >= self.expires_at - _REFRESH_SKEW
+
+    def save(self) -> None:
+        CRED_DIR.mkdir(parents=True, exist_ok=True)
+        tmp = CRED_FILE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(asdict(self), ensure_ascii=False, indent=2), encoding="utf-8")
+        tmp.replace(CRED_FILE)
+        try:
+            # 凭证不能让同机其它用户读到
+            os.chmod(CRED_FILE, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass       # Windows 上 chmod 语义有限，忽略
+
+    @classmethod
+    def load(cls) -> "Credentials | None":
+        if not CRED_FILE.exists():
+            return None
+        try:
+            return cls(**json.loads(CRED_FILE.read_text(encoding="utf-8")))
+        except (json.JSONDecodeError, TypeError):
+            return None
+
+    @classmethod
+    def clear(cls) -> None:
+        CRED_FILE.unlink(missing_ok=True)
+
+
+# ══════════ PKCE ══════════
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(48)).decode().rstrip("=")
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode("ascii")).digest()
+    ).decode().rstrip("=")
+    return verifier, challenge
+
+
+# ══════════ 本地回调 ══════════
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    result: dict = {}
+
+    def do_GET(self):                                   # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self.send_response(404)
+            self.end_headers()
+            return
+        params = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+        _CallbackHandler.result = params
+
+        ok = "code" in params
+        title = "授权成功" if ok else "授权未完成"
+        detail = "可以关闭本页面，回到命令行继续。" if ok else (
+            f"原因：{params.get('error', '未知')}")
+        body = f"""<!doctype html><html><head><meta charset="utf-8">
+<title>{title}</title></head>
+<body style="font-family:system-ui,-apple-system,'Microsoft YaHei';
+             display:flex;align-items:center;justify-content:center;height:100vh;margin:0">
+<div style="text-align:center">
+  <div style="font-size:48px">{'✅' if ok else '⚠️'}</div>
+  <h2 style="margin:12px 0">{title}</h2>
+  <p style="color:#666">{detail}</p>
+</div></body></html>"""
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    def log_message(self, *args):                       # 静音：别把 HTTP 日志打给选手
+        pass
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+# ══════════ 登录 ══════════
+
+def login(
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    client_id: str = DEFAULT_CLIENT_ID,
+    scope: str = "futures:read futures:trade",
+    timeout: int = 300,
+    force: bool = False,
+    open_browser: bool = True,
+) -> Credentials:
+    """浏览器授权登录。已登录且凭证有效时直接返回（除非 force=True）。
+
+    整个过程选手只需要在浏览器里点一下「同意」。
+    """
+    if not force:
+        cred = Credentials.load()
+        if cred and not cred.expired:
+            return cred
+        if cred:
+            try:
+                return refresh(cred)
+            except (AuthError, ContestApiError):
+                pass          # refresh 失效，走完整登录
+
+    verifier, challenge = _pkce_pair()
+    state = secrets.token_urlsafe(16)
+    port = _free_port()
+    redirect_uri = f"http://127.0.0.1:{port}/callback"
+
+    authorize_url = f"{base_url}{API_PREFIX}/oauth/authorize?" + urllib.parse.urlencode({
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "scope": scope,
+        "state": state,
+    })
+
+    _CallbackHandler.result = {}
+    server = http.server.HTTPServer(("127.0.0.1", port), _CallbackHandler)
+    server.timeout = 1
+    thread = threading.Thread(target=_serve_until_result, args=(server, timeout), daemon=True)
+    thread.start()
+
+    print("正在打开浏览器完成授权…")
+    print(f"如果没有自动打开，请手动访问：\n  {authorize_url}\n")
+    if open_browser:
+        try:
+            webbrowser.open(authorize_url)
+        except Exception:
+            pass
+
+    thread.join(timeout + 2)
+    server.server_close()
+    params = _CallbackHandler.result
+
+    if not params:
+        raise AuthError(f"等待授权超时（{timeout}s）。请重新执行登录。")
+    if params.get("error"):
+        raise AuthError(f"授权未通过：{params['error']}")
+    if params.get("state") != state:
+        raise AuthError("state 校验失败，可能遭遇 CSRF，请重新登录")
+    code = params.get("code")
+    if not code:
+        raise AuthError("回调未带授权码，请重新登录")
+
+    data = _post_token(base_url, {
+        "grant_type": "authorization_code",
+        "client_id": client_id,
+        "code": code,
+        "code_verifier": verifier,
+        "redirect_uri": redirect_uri,
+    })
+    cred = _to_credentials(data, base_url, client_id)
+    cred.save()
+    print(f"✅ 登录成功，已绑定参赛账户 {cred.account_id}")
+    return cred
+
+
+def _serve_until_result(server: http.server.HTTPServer, timeout: int) -> None:
+    deadline = time.time() + timeout
+    while time.time() < deadline and not _CallbackHandler.result:
+        server.handle_request()
+
+
+def refresh(cred: Credentials) -> Credentials:
+    """用 refresh_token 换新凭证。服务端会轮转，旧的立即作废。"""
+    data = _post_token(cred.base_url, {
+        "grant_type": "refresh_token",
+        "client_id": cred.client_id,
+        "refresh_token": cred.refresh_token,
+    })
+    new = _to_credentials(data, cred.base_url, cred.client_id)
+    new.save()
+    return new
+
+
+def logout() -> None:
+    """撤销当前 access token 并删除本地凭证。"""
+    cred = Credentials.load()
+    if cred:
+        try:
+            httpx.post(
+                f"{cred.base_url}{API_PREFIX}/oauth/revoke",
+                headers={"Authorization": f"Bearer {cred.access_token}"},
+                timeout=10,
+            )
+        except httpx.HTTPError:
+            pass          # 网络问题不该阻止本地清理
+    Credentials.clear()
+
+
+def _post_token(base_url: str, form: dict) -> dict:
+    try:
+        resp = httpx.post(f"{base_url}{API_PREFIX}/oauth/token", data=form, timeout=20)
+    except httpx.HTTPError as e:
+        raise AuthError(f"连接授权服务失败：{e}") from e
+    try:
+        body = resp.json()
+    except ValueError:
+        raise AuthError(f"授权服务返回异常（HTTP {resp.status_code}）") from None
+    if resp.status_code != 200 or body.get("code") != "0":
+        raise AuthError(body.get("message") or f"换取凭证失败（HTTP {resp.status_code}）")
+    return body["data"]
+
+
+def _to_credentials(data: dict, base_url: str, client_id: str) -> Credentials:
+    return Credentials(
+        access_token=data["access_token"],
+        refresh_token=data["refresh_token"],
+        expires_at=time.time() + int(data.get("expires_in", 7200)),
+        account_id=data.get("account_id", ""),
+        contest_id=data.get("contest_id", ""),
+        scope=data.get("scope", ""),
+        base_url=base_url,
+        client_id=client_id,
+    )

panda_trade-0.1.0/panda_trade/cli.py

@@ -0,0 +1,144 @@
+"""命令行：panda-trade login / logout / whoami / doctor / positions / orders"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from panda_trade import auth
+from panda_trade.client import Client
+from panda_trade.errors import PandaContestError
+
+
+def _fmt(v: float) -> str:
+    return f"{v:,.2f}"
+
+
+def cmd_login(args) -> int:
+    cred = auth.login(force=args.force, open_browser=not args.no_browser)
+    print(f"账户 {cred.account_id} | 赛事 {cred.contest_id} | 权限 {cred.scope}")
+    return 0
+
+
+def cmd_logout(_args) -> int:
+    auth.logout()
+    print("已登出，本地凭证已清除")
+    return 0
+
+
+def cmd_whoami(_args) -> int:
+    cred = auth.Credentials.load()
+    if not cred:
+        print("尚未登录。执行：panda-trade login")
+        return 1
+    try:
+        me = Client(cred).user_info()
+    except PandaContestError as e:
+        print(f"✗ 无法读取用户信息：{e}")
+        return 1
+    user = me.get("user", {})
+    binding = me.get("binding", {})
+    import time
+    remain = int(cred.expires_at - time.time())
+    print(f"用户 ID  : {user.get('id', '-')}")
+    print(f"用户名   : {user.get('username') or '-'}")
+    print(f"手机号   : {user.get('phone') or '-'}")
+    print(f"参赛账户 : {binding.get('accountId') or cred.account_id}")
+    print(f"赛事     : {binding.get('contestId') or cred.contest_id}")
+    print(f"权限     : {' '.join(me.get('scopes') or []) or cred.scope}")
+    print(f"凭证     : {'有效，剩余 %ds' % remain if remain > 0 else '已过期（下次调用会自动续期）'}")
+    print(f"服务地址 : {cred.base_url}")
+    return 0
+
+
+def cmd_doctor(_args) -> int:
+    """自检。凭证过期 / 监控未就绪 / 非交易时段是最常见的三类问题。"""
+    try:
+        report = Client().doctor()
+    except PandaContestError as e:
+        print(f"✗ {e}")
+        return 1
+    for c in report["checks"]:
+        mark = "✓" if c["ok"] else "✗"
+        print(f"  {mark} {c['name']:12} {c['detail']}")
+    print()
+    print("整体状态：" + ("正常" if report["ok"] else "有问题，见上方 ✗ 项"))
+    return 0 if report["ok"] else 1
+
+
+def cmd_account(_args) -> int:
+    a = Client().account()
+    if not a.get("ready"):
+        print("账户资金快照尚未生成（监控可能刚拉起），请稍后重试")
+        return 1
+    print(f"动态权益 : {_fmt(a['totalProfit'])}")
+    print(f"可用资金 : {_fmt(a['availableFunds'])}")
+    print(f"占用保证金: {_fmt(a['margin'])}   风险度 {a['riskRate'] * 100:.2f}%")
+    print(f"持仓盈亏 : {_fmt(a['holdingPnl'])}   当日盈亏 {_fmt(a['dailyPnl'])}")
+    print(f"手续费   : {_fmt(a['cost'])}")
+    return 0
+
+
+def cmd_positions(_args) -> int:
+    rows = Client().positions()
+    if not rows:
+        print("（无持仓）")
+        return 0
+    print(f"{'合约':<12}{'方向':<6}{'持仓':>5}{'今/昨':>9}{'可平':>5}"
+          f"{'持仓均价':>10}{'最新价':>10}{'浮盈':>12}")
+    for p in rows:
+        print(f"{p['contractCode']:<12}{p['directionText']:<6}{p['position']:>5}"
+              f"{str(p['tdPosition']) + '/' + str(p['ydPosition']):>9}{p['closable']:>5}"
+              f"{p['holdPrice']:>10.2f}{p['lastPrice']:>10.2f}{p['holdingPnl']:>12,.2f}")
+    return 0
+
+
+def cmd_orders(args) -> int:
+    rows = Client().orders(status=args.status)
+    if not rows:
+        print("（无委托）")
+        return 0
+    print(f"{'委托号':<16}{'合约':<10}{'买卖':<6}{'开平':<6}{'类型':<6}"
+          f"{'价格':>9}{'数量':>5}{'已成':>5}{'状态':<10}")
+    for o in rows:
+        print(f"{o['orderId']:<16}{o['contractCode']:<10}{o['sideText']:<6}{o['offsetText']:<6}"
+              f"{o['orderTypeText']:<6}{o['price']:>9.2f}{o['quantity']:>5}"
+              f"{o['filledQuantity']:>5}{o['statusText']:<10}")
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="panda-trade", description="期货仿真大赛 CLI（skills 赛道）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("login", help="浏览器授权登录")
+    p.add_argument("--force", action="store_true", help="忽略已有凭证，强制重新登录")
+    p.add_argument("--no-browser", action="store_true", help="不自动开浏览器，只打印链接")
+    p.set_defaults(func=cmd_login)
+
+    sub.add_parser("logout", help="登出并清除本地凭证").set_defaults(func=cmd_logout)
+    sub.add_parser("whoami", help="查看当前登录状态").set_defaults(func=cmd_whoami)
+    sub.add_parser("doctor", help="连通性与状态自检").set_defaults(func=cmd_doctor)
+    sub.add_parser("account", help="账户资金").set_defaults(func=cmd_account)
+    sub.add_parser("positions", help="持仓").set_defaults(func=cmd_positions)
+
+    p = sub.add_parser("orders", help="委托查询")
+    p.add_argument("--status", default=None,
+                   help="open=挂单 / done=已完结 / filled / cancelled ...")
+    p.set_defaults(func=cmd_orders)
+
+    args = ap.parse_args(argv)
+    try:
+        return args.func(args)
+    except PandaContestError as e:
+        print(f"✗ {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\n已取消", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

panda_trade-0.1.0/panda_trade/client.py

@@ -0,0 +1,262 @@
+"""交易客户端。
+
+设计原则（渐进式披露）：常见操作一行搞定，高级参数按需再加。
+
+    c = Client()
+    c.buy_open("rb2510", 1)                       # 市价开多 1 手
+    c.buy_open("rb2510", 1, price=3200)           # 限价
+    c.buy_open("rb2510", 1, price=3200, tif="ioc")
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import httpx
+
+from panda_trade.auth import API_PREFIX, Credentials, login, refresh
+from panda_trade.errors import ContestApiError, OrderTimeout, PandaContestError
+
+
+class Client:
+    """大赛交易客户端。凭证过期会自动续期，选手无感。"""
+
+    def __init__(self, credentials: Credentials | None = None, *, timeout: float = 30.0):
+        cred = credentials or Credentials.load()
+        if cred is None:
+            raise PandaContestError(
+                "尚未登录。请先执行：\n"
+                "    from panda_trade import login\n"
+                "    login()\n"
+                "或命令行：panda-trade login"
+            )
+        self._cred = cred
+        self._http = httpx.Client(timeout=timeout)
+
+    # ── 账户信息 ──
+    @property
+    def account_id(self) -> str:
+        return self._cred.account_id
+
+    @property
+    def contest_id(self) -> str:
+        return self._cred.contest_id
+
+    # ══════════ 查询 ══════════
+
+    def account(self) -> dict:
+        """账户资金：权益/可用/保证金/浮盈/风险度。"""
+        return self._get("/futures/account")
+
+    def user_info(self) -> dict:
+        """当前官网登录用户资料及本次 OAuth 账户绑定。"""
+        return self._get("/oauth/me")
+
+    def positions(self) -> list[dict]:
+        """持仓（多空分开，含今昨仓）。"""
+        return self._get("/futures/positions")
+
+    def orders(self, *, status: str | None = None, trade_date: str | None = None,
+               count: int = 50) -> list[dict]:
+        """委托查询。status: open=挂单 / done=已完结 / filled / cancelled ..."""
+        return self._get("/futures/orders", params={
+            "status": status, "tradeDate": trade_date, "count": count})
+
+    def open_orders(self) -> list[dict]:
+        """挂单（在途委托）—— 最常用的查询。"""
+        return self._get("/futures/orders/open")
+
+    def order(self, order_id: str) -> dict:
+        """单笔委托详情。"""
+        return self._get(f"/futures/orders/{order_id}")
+
+    def trades(self, *, trade_date: str | None = None, count: int = 50) -> list[dict]:
+        """成交记录。"""
+        return self._get("/futures/trades", params={"tradeDate": trade_date, "count": count})
+
+    def snapshot(self) -> dict:
+        """一次拿齐资金 + 持仓 + 挂单。
+
+        大多数 skill 开头都要这三样，一次调用省三次往返，也避免三次之间状态不一致。
+        """
+        return self._get("/futures/snapshot")
+
+    def settlement(self) -> dict:
+        """结算单（CTP 原文）。"""
+        return self._get("/futures/settlement")
+
+    def quote(self, contract: str) -> dict:
+        """实时行情快照：最新价、买卖一档、涨跌停、持仓量。
+
+        报限价单前先看这个 —— 否则价格只能靠猜。
+        历史 K 线用 panda_data（get_future_daily / get_future_min），本方法只给实时。
+        """
+        return self._get("/futures/quote", params={"contractCode": contract})
+
+    def quotes(self, contracts: list[str]) -> list[dict]:
+        """批量实时行情（最多 50 个）。"""
+        return self._get("/futures/quotes", params={"contractCodes": ",".join(contracts)})
+
+    def contracts(self, keyword: str | None = None) -> list[dict]:
+        """可交易合约列表。"""
+        return self._get("/futures/contracts", params={"keyword": keyword})
+
+    # ══════════ 下单 ══════════
+
+    def place_order(
+        self, contract: str, side: str, offset: str, volume: int, *,
+        price: float | None = None, tif: str | None = None,
+        client_order_id: str | None = None, dry_run: bool = False,
+    ) -> dict:
+        """通用下单。price 不传 = 市价。
+
+        - 市价单会被服务端转成「涨跌停价 + IOC 限价单」（CTP 的真市价单只有中金所支持），
+          响应里的 executedAs / protectionPrice 会告知实际报单方式
+        - client_order_id 不传则自动生成 —— **幂等默认开启**，网络重试不会重复下单
+        - 超时抛 OrderTimeout（状态未知，**不要重试**，用 client_order_id 查询确认）
+        """
+        cid = client_order_id or uuid.uuid4().hex
+        body = {
+            "contractCode": contract, "side": side, "offset": offset,
+            "orderType": "limit" if price is not None else "market",
+            "volume": volume, "clientOrderId": cid, "dryRun": dry_run,
+        }
+        if price is not None:
+            body["price"] = price
+        if tif:
+            body["timeInForce"] = tif
+
+        data = self._post("/futures/orders", body)
+        if data.get("status") == "unknown":
+            raise OrderTimeout(cid, data.get("message", "下单回执超时"))
+        return data
+
+    # 四个语义化快捷方法：期货的开平方向容易写反，用名字固定下来
+    def buy_open(self, contract: str, volume: int, **kw) -> dict:
+        """买入开仓（做多）。"""
+        return self.place_order(contract, "buy", "open", volume, **kw)
+
+    def sell_open(self, contract: str, volume: int, **kw) -> dict:
+        """卖出开仓（做空）。"""
+        return self.place_order(contract, "sell", "open", volume, **kw)
+
+    def buy_close(self, contract: str, volume: int, **kw) -> dict:
+        """买入平仓（平空头）。"""
+        return self.place_order(contract, "buy", "close", volume, **kw)
+
+    def sell_close(self, contract: str, volume: int, **kw) -> dict:
+        """卖出平仓（平多头）。"""
+        return self.place_order(contract, "sell", "close", volume, **kw)
+
+    def cancel(self, order_id: str) -> dict:
+        """撤单。"""
+        return self._delete(f"/futures/orders/{order_id}")
+
+    # ══════════ 组合操作（服务端逐笔执行，避免选手自己循环出半成品状态）══════════
+
+    def cancel_all(self, contract: str | None = None) -> list[dict]:
+        """撤掉全部挂单（可按合约过滤）。返回每笔的结果。"""
+        out = []
+        for o in self.open_orders():
+            if contract and o["contractCode"].split(".")[0].lower() != contract.split(".")[0].lower():
+                continue
+            try:
+                out.append({"orderId": o["orderId"], "result": self.cancel(o["orderId"])})
+            except PandaContestError as e:
+                out.append({"orderId": o["orderId"], "error": str(e)})
+        return out
+
+    def close_all(self, contract: str | None = None, **kw) -> list[dict]:
+        """平掉全部持仓（可按合约过滤）。市价平，逐笔返回结果。
+
+        ⚠️ 逐笔执行，中途失败会留下部分平仓状态 —— 返回值里每笔的成败都在，
+        请检查后再决定是否重试剩余的。
+        """
+        out = []
+        for p in self.positions():
+            if contract and p["contractCode"].split(".")[0].lower() != contract.split(".")[0].lower():
+                continue
+            closable = int(p.get("closable") or 0)
+            if closable <= 0:
+                continue
+            # 平多用 sell_close，平空用 buy_close
+            fn = self.sell_close if p["direction"] == "long" else self.buy_close
+            try:
+                out.append({"contractCode": p["contractCode"], "direction": p["direction"],
+                            "volume": closable, "result": fn(p["contractCode"], closable, **kw)})
+            except PandaContestError as e:
+                out.append({"contractCode": p["contractCode"], "error": str(e)})
+        return out
+
+    # ══════════ 自检 ══════════
+
+    def doctor(self) -> dict:
+        """连通性与状态自检。凭证过期 / 监控未就绪 / 非交易时段是最常见的三类问题。"""
+        report: dict[str, Any] = {"ok": True, "checks": []}
+
+        def add(name, ok, detail=""):
+            report["checks"].append({"name": name, "ok": ok, "detail": detail})
+            if not ok:
+                report["ok"] = False
+
+        import time as _t
+        remain = int(self._cred.expires_at - _t.time())
+        add("凭证有效", remain > 0,
+            f"access 剩余 {max(remain, 0)}s；scope={self._cred.scope}")
+        add("账户绑定", bool(self._cred.account_id),
+            f"账户 {self._cred.account_id}（赛事 {self._cred.contest_id}）")
+        try:
+            acc = self.account()
+            add("账户数据可读", bool(acc.get("ready")),
+                "资金快照就绪" if acc.get("ready") else "快照未生成，账户监控可能刚拉起")
+            add("资金状况", True,
+                f"权益 {acc.get('totalProfit', 0):,.2f} / 可用 {acc.get('availableFunds', 0):,.2f}")
+        except ContestApiError as e:
+            add("账户数据可读", False, str(e))
+        try:
+            add("挂单查询", True, f"当前挂单 {len(self.open_orders())} 笔")
+        except ContestApiError as e:
+            add("挂单查询", False, str(e))
+        return report
+
+    # ══════════ HTTP ══════════
+
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        return self._request("GET", path, params=_clean(params))
+
+    def _post(self, path: str, body: dict) -> Any:
+        return self._request("POST", path, json=body)
+
+    def _delete(self, path: str) -> Any:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, *, _retried: bool = False, **kw) -> Any:
+        url = f"{self._cred.base_url}{API_PREFIX}{path}"
+        headers = {"Authorization": f"Bearer {self._cred.access_token}"}
+        try:
+            resp = self._http.request(method, url, headers=headers, **kw)
+        except httpx.HTTPError as e:
+            raise PandaContestError(f"请求失败：{e}") from e
+
+        # access 过期 → 自动续期后重试一次（选手无感）
+        if resp.status_code == 401 and not _retried:
+            self._cred = refresh(self._cred)
+            return self._request(method, path, _retried=True, **kw)
+
+        try:
+            body = resp.json()
+        except ValueError:
+            raise PandaContestError(
+                f"服务返回非 JSON（HTTP {resp.status_code}）：{resp.text[:200]}") from None
+
+        if body.get("code") != "0":
+            raise ContestApiError(
+                body.get("code", "unknown"), body.get("message", ""), body.get("data"),
+                http_status=resp.status_code, request_id=body.get("request_id", ""),
+            )
+        return body.get("data")
+
+
+def _clean(params: dict | None) -> dict | None:
+    return {k: v for k, v in (params or {}).items() if v is not None} or None

panda_trade-0.1.0/panda_trade/errors.py

@@ -0,0 +1,54 @@
+"""SDK 异常。
+
+服务端每个业务错误都带 suggestion / 可操作数据，这里原样透出——
+选手（和 AI）读 str(e) 就能知道下一步该做什么。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class PandaContestError(Exception):
+    """SDK 基类异常。"""
+
+
+class AuthError(PandaContestError):
+    """登录/授权失败。"""
+
+
+class ContestApiError(PandaContestError):
+    """服务端返回的业务错误。"""
+
+    def __init__(self, code: str, message: str, data: dict[str, Any] | None = None,
+                 *, http_status: int = 0, request_id: str = "") -> None:
+        self.code = code
+        self.message = message
+        self.data = data or {}
+        self.http_status = http_status
+        self.request_id = request_id
+        # suggestion 是排查的关键，直接拼进异常信息里
+        suggestion = self.data.get("suggestion")
+        text = f"[{code}] {message}"
+        if suggestion:
+            text += f"\n建议：{suggestion}"
+        if request_id:
+            text += f"\n(request_id: {request_id})"
+        super().__init__(text)
+
+
+class OrderTimeout(PandaContestError):
+    """下单等回执超时 —— 状态未知，**不是失败**。
+
+    柜台可能已受理。切勿直接重试，否则可能重复下单；
+    请用 client_order_id 查询委托确认结果。
+    """
+
+    def __init__(self, client_order_id: str, message: str) -> None:
+        self.client_order_id = client_order_id
+        super().__init__(
+            f"{message}\n"
+            f"⚠️ 委托状态未知，请勿直接重试。用以下方式确认后再决定：\n"
+            f"    c.orders(status='open')   # 看是否已挂上\n"
+            f"    clientOrderId = {client_order_id!r}"
+        )

panda_trade-0.1.0/panda_trade.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: panda-trade
+Version: 0.1.0
+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`。
+
+## 安装
+
+```bash
+pip install panda-trade
+```
+
+## 登录
+
+```python
+from panda_trade import login
+
+login()
+```
+
+SDK 使用 OAuth + PKCE 打开官网授权页，不需要 API Key，也不会保存官网密码。凭证保存在
+用户目录的 `.panda-trade/credentials.json`。
+
+也可以使用命令行：
+
+```bash
+panda-trade login
+panda-trade whoami
+panda-trade doctor
+```
+
+## 交易示例
+
+```python
+from panda_trade import Client
+
+client = Client()
+
+print(client.snapshot())
+print(client.quote("rb2610"))
+
+# 发布策略前先使用 dry_run 验证
+result = client.buy_open("rb2610", 1, price=3000, dry_run=True)
+print(result)
+```
+
+通过环境变量覆盖服务地址或 OAuth client：
+
+```text
+PANDA_TRADE_BASE_URL
+PANDA_TRADE_CLIENT_ID
+PANDA_TRADE_HOME
+```

panda_trade-0.1.0/panda_trade.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+panda_trade/__init__.py
+panda_trade/auth.py
+panda_trade/cli.py
+panda_trade/client.py
+panda_trade/errors.py
+panda_trade.egg-info/PKG-INFO
+panda_trade.egg-info/SOURCES.txt
+panda_trade.egg-info/dependency_links.txt
+panda_trade.egg-info/entry_points.txt
+panda_trade.egg-info/requires.txt
+panda_trade.egg-info/top_level.txt

panda_trade-0.1.0/panda_trade.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

panda_trade-0.1.0/panda_trade.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+panda-trade = panda_trade.cli:main

panda_trade-0.1.0/panda_trade.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24

panda_trade-0.1.0/panda_trade.egg-info/top_level.txt

@@ -0,0 +1 @@
+panda_trade

panda_trade-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "panda-trade"
+version = "0.1.0"
+description = "PandaAI 交易开放 API 的 Python SDK / CLI（OAuth 登录，无需 API Key）"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24"]
+keywords = ["pandaai", "futures", "trading", "contest", "oauth"]
+
+[project.urls]
+Homepage = "https://www.pandaaiquant.com"
+
+[project.scripts]
+panda-trade = "panda_trade.cli:main"
+
+[tool.setuptools]
+packages = ["panda_trade"]

panda_trade-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+