跳到主要内容

回测 API 概览

针对历史行情数据运行策略模板，并获取性能指标。回测以异步任务方式执行——提交任务、轮询完成状态，然后下载结果。

本模块涵盖：

  • 提交并跟踪回测任务。
  • 解读结果格式。
  • Primit 计算的各项指标（Sharpe、最大回撤、胜率等）。

任务生命周期​

每个回测任务都会在一个简洁的状态机中流转。终止状态为 done、failed 和 cancelled。

            ┌──────────┐    slot free    ┌──────────┐
submit ───▶│  queued  │ ───────────────▶│ running  │
            └──────────┘                  └────┬─────┘
                  │                            │
                  │                            ├── success ──▶  done
              cancel                           │
                  │                            ├── error   ──▶  failed
                  ▼                            │
            cancelled                          └── cancel  ──▶  cancelled
状态说明
queued任务已被接受，正在等待执行槽位。
runningWorker 正在回放历史数据。progress 从 0 推进到 1。
done任务成功完成。result 已填充。
failed任务因错误中止。error 描述具体原因。
cancelled用户在任务结束前取消。

时间处理​

  • 所有 start 与 end 时间戳均为 UTC 下的 ISO 8601 字符串（例如 2025-01-01T00:00:00Z）。
  • 时间区间为双端闭区间——位于 start 与 end 上的 K 线都会参与模拟。
  • start 必须严格小于 end。
  • 最大跨度为 5 年。更长的区间会以 INVALID_PARAMETER 拒绝。
  • end 可以位于过去或当前时刻；未来时间戳会被拒绝。

费用模型​

Primit 在模拟过程中会按照任务上配置的 fee_model 计算交易费用。

模式行为
none不计费。便于做合理性检查；不具备真实性。
fixed_bps对每笔成交按名义本金应用一个统一的基点费率。通过 fee_bps 配置（默认 "5"，即 0.05%）。
tiered_maker_taker基于模拟得到的近 30 日成交量，使用平台默认的分层 maker/taker 费率。Maker 与 taker 费率不同。
match_exchange回放该交易对在所属交易所于模拟时间点的真实费率表，包含历史变更。最贴近真实情况，但计算最慢。

无论 fee_model 取何值，永续合约的币安资金费率始终会被应用。

结果保留期​

  • 完整结果（权益曲线与成交记录）在 finished_at 之后会保留 90 天。
  • 90 天后会回收较大的负载。任务摘要（配置、状态、时间戳和指标）会无限期保留，便于审计已运行的回测。
  • 如需长期保存，请在保留期结束前导出结果。

并发上限​

  • 每个用户处于 queued 或 running 状态的并发任务最多为 5 个。
  • 提交第 6 个任务会返回 429 RATE_LIMITED。
  • 排队中的任务会在槽位释放时自动启动。同一用户内按 FIFO 顺序执行。