策略快速上手

本指南将创建一个策略，通过回测验证它，先以模拟运行再以实盘方式部署，订阅状态更新，并在完成后干净地暂停它。

所有请求都必须签名 —— 参见 鉴权。示例假设 $API_KEY、$TS 和 $SIG 已按签名方案设置好。

1. 创建策略

发送 POST /v1/strategies 请求，附上模板、参数和执行上下文。策略会以 draft 状态创建。

curl -X POST "https://api.pipai.example/v1/strategies" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BTC grid 1h",
    "template_id": "tpl_grid",
    "params": {
      "grid_levels": 8,
      "upper_price": "72000",
      "lower_price": "60000",
      "rebalance_threshold": "0.02"
    },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "capital": "10000.00",
    "leverage": 3
  }'

响应中包含新策略的 id（例如 strat_8f2a1b）以及 status: "draft"。完整 schema 参见 创建策略。

2. 部署前先回测

在投入资金之前，先用历史数据进行回测以验证参数。提交一个引用 strategy_id 的回测任务：

curl -X POST "https://api.pipai.example/v1/backtest/jobs" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": "strat_8f2a1b",
    "from": "2025-10-01T00:00:00Z",
    "to":   "2026-04-01T00:00:00Z"
  }'

轮询任务直至完成并查看报告。完整细节参见 Backtesting 模块。

3. 部署（先 dry-run，后实盘）

回测结果良好后即可部署。建议先做模拟运行 —— 引擎会消费实时行情并发出相同的事件，但不会下达真实订单。

# 步骤 3a：模拟运行
curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/deploy" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": true }'

# 步骤 3b：暂停模拟运行，然后以实盘方式重新部署
curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/pause" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/deploy" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": false }'

参见 部署策略。

4. 订阅状态更新

打开一个 WebSocket 连接（按鉴权文档进行签名），并发送订阅帧：

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

随着事件发生，你会陆续收到 deployed、position_opened、order_filled、position_closed 等事件。完整事件列表参见 策略状态 WebSocket。

5. 暂停并清理

完成后请暂停策略。将 close_positions: true 设为真可以按市价平掉所有未平仓的持仓。

curl -X POST "https://api.pipai.example/v1/strategies/strat_8f2a1b/pause" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{ "close_positions": true }'

如果不再需要该策略，可以将其删除（仅在 draft、paused 或 stopped 状态下允许）：

curl -X DELETE "https://api.pipai.example/v1/strategies/strat_8f2a1b" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG"