auto_trade_sys/docs/common/WS交易接口实现说明.md

WebSocket 交易接口实现说明

概述

已实现通过 WebSocket API 创建 Algo 条件单（止损/止盈），优先于 REST，减少「请求超时」问题。

---

实现内容

1. 新增文件

• trading_system/ws_trade_client.py：WebSocket 交易客户端
  • 连接到 wss://ws-fapi.binance.com/ws-fapi/v1（正式）或 wss://testnet.binancefuture.com/ws-fapi/v1（测试）
  • 实现 algoOrder.place 方法，发送条件单请求
  • 处理请求-响应匹配（用 id 字段）
  • 自动重连、24h 主动重连、ping/pong 保活

2. 修改文件

• trading_system/binance_client.py：
  • __init__：添加 _ws_trade_client 属性
  • connect()：连接成功后启动 WS 交易客户端
  • futures_create_algo_order()：优先用 WS 发送条件单，失败回退 REST
  • disconnect()：停止 WS 交易客户端

---

工作流程

1. 启动时：BinanceClient.connect() 成功后，若 API 密钥有效，自动启动 WSTradeClient 并连接到 ws-fapi。
2. 下单时：
   • 若 WS 已连接 → 用 algoOrder.place 发送（带签名），等待响应（超时 20-25 秒）
   • WS 失败或未连接 → 回退到 REST POST /fapi/v1/algoOrder（原有逻辑，45 秒超时 + 重试）
3. 响应格式：WS 返回的 result 字段（含 algoId 等）直接返回，与 REST 格式兼容。

---

优势

• 减少超时：WS 长连接，无每次 HTTP 建连开销，响应通常更快
• 自动回退：WS 失败时自动用 REST，不影响现有逻辑
• 透明切换：调用方无需改动，futures_create_algo_order() 自动选择最优方式

---

配置

• 超时时间：WS 超时 = ALGO_ORDER_TIMEOUT_SEC - 5（最小 20 秒），REST 超时 = ALGO_ORDER_TIMEOUT_SEC（默认 45 秒）
• 连接管理：WS 连接自动重连、24h 主动重连、ping/pong 保活

---

日志

• WS 连接成功：✓ WebSocket 交易客户端已启动（条件单优先走 WS，失败回退 REST）
• WS 下单成功：{symbol} ✓ WS 条件单创建成功: algoId=...
• WS 失败回退：{symbol} WS 条件单失败（...），回退到 REST

---

注意事项

• WS 交易接口需要有效的 API 密钥（与 REST 相同）
• 签名计算方式与 REST 一致（HMAC-SHA256）
• 若 WS 连接失败，不影响 REST 下单功能