创建回测任务

提交一个新的回测任务。返回新建的任务对象，状态为 queued；回测会异步执行。

接口

POST /v1/backtest/jobs

权重： 20

鉴权： 必需（已签名）

请求体

名称	类型	必填	说明
template_id	string	是	策略模板标识符（例如 tpl_grid）。可参见策略模块概览中的目录。
params	object	是	模板特定的参数。回测服务对其结构不作解析，由模板自行校验。
symbols	array<string>	是	大写的交易所风格交易对（例如 ["BTCUSDT"]）。多交易对回测仅在模板显式支持时可用。
timeframe	enum	是	K 线周期。取值之一：1m、5m、15m、1h、4h、1d。
start	string (ISO 8601 UTC)	是	模拟窗口的下界（含）。
end	string (ISO 8601 UTC)	是	上界（含）。必须 > start；总跨度 ≤ 5 年。
capital	string (decimal)	是	以计价货币计的初始账户权益。以字符串引用以保留精度。
leverage	integer	否	应用于持仓的最大杠杆。默认 1。
fee_model	enum	否	取值之一：none、fixed_bps、tiered_maker_taker、match_exchange。默认 fixed_bps。参见 概览 → 费用模型。
fee_bps	string (decimal)	否	每笔成交的基点费率。仅在 fee_model = "fixed_bps" 时生效。默认 "5"。
strategy_id	string	否	若设置，则会将对应策略的存储配置作为基础载入；以上任何字段如同时在请求中提供，会覆盖该策略的值。便于在自定义窗口上重新跑现有策略。

响应

{
  "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-12-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
}

响应字段

字段	类型	说明
id	string	任务标识符，形如 bt_<6-8 位十六进制>。
status	enum	取值之一：queued、running、done、failed、cancelled。新任务返回 queued。
config	object	回显回测实际运行所用的解析后配置。若提供了 strategy_id，此处反映合并后的配置。
submitted_at	string (ISO 8601)	服务端接受请求的时间戳。
started_at	string (ISO 8601) | null	任务离开队列时设置。处于 queued 时为 null。
finished_at	string (ISO 8601) | null	任务进入终止状态时设置。
progress	number	位于 [0, 1] 的进度比例。新排队的任务为 0。
result	object | null	在状态变为 done 之前为 null；参见 获取结果。
error	object | null	仅当状态为 failed 时不为 null；包含 { "code", "message" }。

错误

HTTP	错误码	原因
400	INVALID_PARAMETER	字段缺失、未知的 template_id、无效日期区间（例如 end <= start、跨度 > 5 年、end 在未来）、不受支持的 timeframe，或非数值的 capital。
409	INVALID_STATE	strategy_id 引用了已删除或当前不可用的策略。
429	RATE_LIMITED	用户处于 queued 或 running 状态的任务已达 5 个。请等待其中之一完成或先取消一个。

通用错误语义参见 错误。

示例

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-12-31T23:59:59Z",
    "capital": "10000.00",
    "leverage": 1,
    "fee_model": "fixed_bps",
    "fee_bps": "5"
  }'