Backtests

Prepare historical data, execute a strategy, poll its result, and inspect its equity curve.

Prepare historical data, run a compiled strategy against it once, poll the result, and plot the equity curve. For running the same strategy across a parameter grid instead, see docs/backtest_sweep.md.

{type} is the DataSourceType — ticker today.

Preparing data

POST .../prepare

Enqueues a prepare task over a date range and returns a jobId immediately; poll the GET below for completion. Same params → same jobId (idempotent) — repeated calls reuse the existing job instead of enqueueing duplicate work.

Request body — PrepareRequest

Two shapes, chosen by the exchangeId path segment:

exchangeId: user is reserved for your own uploaded data — see docs/datasets.md.

Example

curl -X POST https://api.qtsurfer.net/v1/backtest/binance/ticker/prepare 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"instrument":"BTC/USDT","from":"2026-03-14","to":"2026-03-15"}'
# → 202 {"jobId": "5ikYAMIO..."}

Errors: 400 invalid request, from older than the lookback window, to in the future, or (for exchangeId: user) the dataset’s upload hasn’t finished ingesting / cadence finer than the dataset’s discovered cadence / range exceeds your tier’s limit · 404 exchange/type not found, or (for exchangeId: user) datasetId/datasetVersionId doesn’t exist or isn’t yours · 429 global queue at capacity or too many active backtests — doesn’t apply to exchangeId: user, which reads an already-ingested file rather than claiming worker capacity.

Polling prepare status

GET .../prepare/{jobId}

A single-instrument prepare is always terminal (status: Completed) — decide from coverageRatio (e.g. execute once it clears a chosen threshold) rather than polling for missing hours that may never arrive. A missing hour usually means low activity, not missing data.

Response — PrepareJobState

The JobState shape (contextId, status, statusDetail, size, completed, startTime, endTime) plus a coverage summary. Two coverage shapes, by exchange vs. dataset:

Example

curl https://api.qtsurfer.net/v1/backtest/binance/ticker/prepare/$PREPARE_JOB_ID 
  -H "Authorization: Bearer $TOKEN"

{
  "contextId": "ctx_0bjmoxd4vahkgc0hnvdldh",
  "status": "Completed",
  "size": 0,
  "completed": 24,
  "startTime": "2026-04-14T15:00:00Z",
  "endTime": "2026-04-14T15:00:01Z",
  "dataFrom": "2026-04-14T13:00:00Z",
  "dataTo": "2026-04-14T15:30:05Z",
  "coverageRatio": 0.994,
  "totalHours": 168,
  "hoursWithData": 167,
  "hoursWithoutData": [
    {"hour": "2026-04-14T02:00:00Z", "expected": 0, "rationale": "low_activity"}
  ]
}

Executing a backtest

POST .../execute

Runs the strategy identified by strategyId over the data from prepareJobId; instrument and date range are recovered from the prepare job, not sent again. Works unchanged for a dataset-backed prepare. Same (prepareJobId, strategyId, storeSignals, equityCurve) → same jobId (idempotent) — a request that omits equityCurve dedupes exactly as it did before that field existed.

Request body

Example

curl -X POST https://api.qtsurfer.net/v1/backtest/binance/ticker/execute 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"prepareJobId":"5ikYAMIO...","strategyId":"2ul144qe9tlwzu5anhwvc6"}'
# → 202 {"jobId": "4GmNN0i9..."}

Errors: 400 invalid request · 404 prepare job not found or expired · 429 rate limited.

Polling the result

GET .../execute/{jobId}

A 202 (empty body, {}) means the result isn’t readable yet — keep polling under your existing timeout, and never treat it as terminal. It’s returned both while the job is still running and when a terminal job’s stored result couldn’t be read back, so a poll loop should key off 200 plus state.status, not off “not 202 anymore”.

Response — BacktestJobResult

state (JobState) plus results (ResultMap):

Example

curl https://api.qtsurfer.net/v1/backtest/binance/ticker/execute/$EXECUTE_JOB_ID 
  -H "Authorization: Bearer $TOKEN"

{
  "state": {"status": "Completed", "completed": 85058},
  "results": {
    "pnlTotal": 42.75, "pnlTotalPercent": 2.25, "totalTrades": 156, "winRate": 58.33,
    "sharpeRatio": 1.245, "sortinoRatio": 1.872, "cagr": 0.1534,
    "maxDrawdown": 12.50, "maxDrawdownPercent": 8.75, "iops": 123956.53,
    "equityCurve": {
      "points": [
        {"timestamp": 1700000000000, "equity": 100.0},
        {"timestamp": 1700000060000, "equity": 110.5},
        {"timestamp": 1700000120000, "equity": 90.25}
      ],
      "meta": {
        "inputPointCount": 3, "outputPointCount": 3,
        "resampled": false, "differential": false, "outMode": "ARRAY"
      }
    }
  }
}

Errors: 400 invalid request · 404 execution job not found.

Cancelling

DELETE .../execute/{jobId}

Requests cancellation; status transitions to Aborted once processed — asynchronous, so poll GET to confirm. 200 {"status": "cancelling", "jobId": "..."} · 404 not found.

Visualizing the equity curve

The shared equity-curve guide covers plotting, percentage normalization, ARRAY and SHORT shapes, resampling, differential encoding, metadata, size guards, and the different submit/read semantics for plain backtests and retained sweep trials.