回测快速上手

端到端实操：提交回测、轮询完成状态、读取指标。所有请求均按鉴权进行签名。

1. 提交任务

POST 一个策略模板、交易对、时间周期和日期区间。响应中会包含后续轮询所需的任务 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 '{
    "template_id": "tpl_grid",
    "params": {
      "grid_levels": 8,
      "upper_price": "72000",
      "lower_price": "60000"
    },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-03-31T23:59:59Z",
    "capital": "10000.00",
    "leverage": 1,
    "fee_model": "fixed_bps",
    "fee_bps": "5"
  }'

响应示例：

{
  "id": "bt_3c91ef",
  "status": "queued",
  "config": {
    "template_id": "tpl_grid",
    "params": { "grid_levels": 8, "upper_price": "72000", "lower_price": "60000" },
    "symbols": ["BTCUSDT"],
    "timeframe": "1h",
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-03-31T23:59:59Z",
    "capital": "10000.00",
    "leverage": 1,
    "fee_model": "fixed_bps",
    "fee_bps": "5"
  },
  "submitted_at": "2026-04-29T10:15:00Z",
  "started_at": null,
  "finished_at": null,
  "progress": 0,
  "result": null,
  "error": null
}

完整字段说明请参见创建任务。

2. 轮询完成状态

按 ID 获取任务。轮询频率不得高于每 5 秒一次。当 status 进入终止值（done、failed 或 cancelled）时停止轮询。

curl -X GET https://api.pipai.example/v1/backtest/jobs/bt_3c91ef \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG"

任务运行期间，progress 从 0 推进到 1，result 为 null：

{
  "id": "bt_3c91ef",
  "status": "running",
  "submitted_at": "2026-04-29T10:15:00Z",
  "started_at": "2026-04-29T10:15:08Z",
  "finished_at": null,
  "progress": 0.45,
  "result": null,
  "error": null
}

完成后，status 为 done，result 被填充：

{
  "id": "bt_3c91ef",
  "status": "done",
  "submitted_at": "2026-04-29T10:15:00Z",
  "started_at": "2026-04-29T10:15:08Z",
  "finished_at": "2026-04-29T10:17:42Z",
  "progress": 1.0,
  "result": {
    "metrics": {
      "sharpe": "1.84",
      "sortino": "2.31",
      "calmar": "1.12",
      "max_drawdown": "-0.142",
      "win_rate": "0.638",
      "profit_factor": "1.92",
      "cagr": "0.187",
      "expected_value": "12.43",
      "total_trades": 247,
      "avg_trade_duration_seconds": 14820
    },
    "equity_curve": [ ["2025-01-01T00:00:00Z", "10000.00"], ["2025-01-02T00:00:00Z", "10031.50"] ],
    "trades": [ /* ... */ ]
  },
  "error": null
}

完整响应结构请参见获取结果。

3. 读取指标

返回的 result.metrics 对象汇总了本次回测。通常优先关注的字段：

字段	快速解读
`sharpe`	风险调整后收益。`> 1` 较好，`> 2` 优秀。
`sortino`	类似 Sharpe，但只惩罚下行波动。
`max_drawdown`	最严重的峰值到谷底回撤。越接近 0 越好。
`win_rate`	盈利成交占比。
`profit_factor`	总盈利 / 总亏损。`> 1.5` 较为健康。
`cagr`	权益曲线的年化复合增长率。
`expected_value`	每笔成交在计价货币下的平均盈亏。

例如，使用 jq：

curl -s -X GET https://api.pipai.example/v1/backtest/jobs/bt_3c91ef \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  | jq '.result.metrics | {sharpe, max_drawdown, win_rate, cagr}'

完整定义、公式与取值范围请参见指标。

提示

从小处入手。 在扩展到多交易对、多年回测之前，先在单一交易对、几个月的窗口上跑通流程。这样迭代更快，配置错误也能更早暴露。
及时取消失控的任务。 如果任务耗时远超预期，请取消它，而不是让它一直占用槽位。
关注并发上限。 单用户处于运行中的任务最多 5 个。超额提交会返回 RATE_LIMITED，直到有槽位释放。
在 90 天内导出结果。 权益曲线与成交记录在保留期之后会被回收；指标摘要会无限期保留。

1. 提交任务​

2. 轮询完成状态​

3. 读取指标​

提示​

1. 提交任务

2. 轮询完成状态

3. 读取指标

提示