策略状态流

实时推送策略生命周期事件的 WebSocket 流：部署、暂停、开仓/平仓、订单提交与成交，以及不可恢复的错误。可使用此流驱动仪表盘、审计日志或下游自动化流程。

鉴权

WebSocket 连接必须使用与 REST 相同的 HMAC-SHA256 方案进行鉴权。可任选其一：

对连接 URL 进行签名 —— 将 api_key、timestamp 和 signature 作为查询参数传递，规范字符串为 timestamp + "GET" + path。示例：wss://stream.pipai.example/v1/ws?api_key=...&timestamp=...&signature=...。

在连接后发送一个 auth 帧作为第一条消息：

{ "op": "auth", "api_key": "...", "timestamp": 1761739200000, "signature": "..." }

5 秒内未完成鉴权的连接会被关闭。完整签名方案参见鉴权。

事件类型

事件	触发时机
`deployed`	策略转为 `deployed`。
`paused`	策略转为 `paused`。
`position_opened`	策略开了一个新持仓。
`position_closed`	一个持仓被平掉（由出场规则、手动暂停并平仓或止损触发）。
`order_placed`	一个订单被提交到交易所。
`order_filled`	一个订单完全或部分成交。
`order_cancelled`	一个订单被引擎或交易所取消。
`error`	引擎因不可恢复的错误而停止，策略转为 `error` 状态。

负载 schema

每个事件都使用相同的信封：

{
  "channel": "strategy.status",
  "event": "position_opened",
  "strategy_id": "strat_8f2a1b",
  "seq": 12483,
  "ts": "2026-04-29T12:00:00.000Z",
  "data": { }
}

信封字段	类型	说明
`channel`	string	始终为 `"strategy.status"`。
`event`	string	上面列出的事件类型之一。
`strategy_id`	string	发出该事件的策略。
`seq`	integer	每个频道单调递增的序号，可用于检测丢失并在重连后恢复。
`ts`	string	毫秒精度的 ISO 8601 UTC 时间戳。
`data`	object	事件特有的负载，schema 见下文。

`position_opened`

{
  "channel": "strategy.status",
  "event": "position_opened",
  "strategy_id": "strat_8f2a1b",
  "seq": 12483,
  "ts": "2026-04-29T12:00:00.000Z",
  "data": {
    "position_id": "pos_4ab9c0",
    "symbol": "BTCUSDT",
    "side": "long",
    "entry_price": "67234.50",
    "quantity": "0.0150",
    "leverage": 3,
    "notional": "1008.52"
  }
}

`position_closed`

{
  "channel": "strategy.status",
  "event": "position_closed",
  "strategy_id": "strat_8f2a1b",
  "seq": 12519,
  "ts": "2026-04-29T13:42:11.250Z",
  "data": {
    "position_id": "pos_4ab9c0",
    "symbol": "BTCUSDT",
    "side": "long",
    "entry_price": "67234.50",
    "exit_price": "67890.10",
    "quantity": "0.0150",
    "realized_pnl": "9.83",
    "reason": "exit_rule"
  }
}

reason 取值之一：exit_rule、stop_loss、take_profit、manual_pause_close、liquidation。

`order_filled`

{
  "channel": "strategy.status",
  "event": "order_filled",
  "strategy_id": "strat_8f2a1b",
  "seq": 12491,
  "ts": "2026-04-29T12:00:00.412Z",
  "data": {
    "order_id": "ord_77e2b1",
    "position_id": "pos_4ab9c0",
    "symbol": "BTCUSDT",
    "side": "buy",
    "type": "limit",
    "price": "67234.50",
    "quantity": "0.0150",
    "filled_quantity": "0.0150",
    "fee": "0.5039",
    "fee_currency": "USDT"
  }
}

部分成交时每次成交都会发出一个事件；filled_quantity 是该订单的累计成交数量。

`error`

{
  "channel": "strategy.status",
  "event": "error",
  "strategy_id": "strat_8f2a1b",
  "seq": 12604,
  "ts": "2026-04-29T14:05:33.001Z",
  "data": {
    "code": "EXCHANGE_AUTH_FAILED",
    "message": "Exchange API key rejected by Binance",
    "fatal": true
  }
}

当 fatal 为 true 时，策略已转为 error 状态，且不会自动恢复 —— 请排查、修复后重新部署。非致命错误也会发出，便于观察，但不会改变策略状态。

重连

连接可能因多种原因断开（网络、服务器维护、空闲超时）。客户端应使用指数退避进行重连：

起始延迟 1 秒。
每次连续失败后翻倍，并加入 ±25% 抖动。
上限为 30 秒。
在保持连接 60 秒的成功连接之后重置为 1 秒。

要无缝恢复，可在订阅帧中带上最后接收到的 seq：

{ "op": "subscribe", "channel": "strategy.status", "id": "strat_8f2a1b", "since_seq": 12483 }

服务器会重放缓冲中 seq > since_seq 的事件。重放是尽力而为：事件最长缓冲 5 分钟。如果 since_seq 早于缓冲范围，服务器会回复 { "op": "ack", "ok": false, "code": "REPLAY_UNAVAILABLE" }，此时应通过获取策略来对账状态。

订阅​

鉴权​

事件类型​

负载 schema​

position_opened​

position_closed​

order_filled​

error​

重连​

订阅

鉴权