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, kline or funding.

Where a job’s status lives

The three job-polling endpoints answer “is it done, did it fail” at different places, because each returns its own result type. The status itself is the same JobState vocabulary (New, Started, Completed, Aborted, Failed) in all three:

A poller that serves all three can read (resp.get("state") or resp)["status"] (in Python): state when the response has one, the top level when it does not.

Data sources

A funding request to execute or executeSweep is rejected with 400 before anything is queued, and the message names what can be run: funding data can be prepared but not executed yet. Sources that can be executed: ticker, kline.

Kline: you choose the bar width

A kline run reads bars of exactly the cadence you prepared at — 1s (the default), 1m, 5m, 15m, 30m, 1h, 4h or 1d — whatever the strategy itself might suggest. The same strategy can therefore be run at several cadences by preparing the range once per cadence. Any other label (5s, 3m, 8h, …) is 400 at prepare, and the message lists the accepted ones.

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

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

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, a kline cadence that isn’t a kline cadence, 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; against an rt dataset, which has no ratio, from dataFrom/dataTo) 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, baseConfig, params) → same jobId (idempotent) — a request that omits equityCurve, baseConfig or params dedupes exactly as it did before those fields existed. Two different params vectors over one prepare are two different jobs, and 9 and 9.0 are the same one.

Optionally takes params: strategy properties for this one run, applied without recompiling. Use this to re-run a sweep row as an ordinary backtest result with a chosen parameter vector — for example, when you need the plain-backtest result alongside a sweep curve (see docs/backtest_sweep.md). Compile the strategy once, call this endpoint N times with different params, and each response includes the curve under the same conditions as any other plain backtest. This is an independent execution rather than a replay of the sweep trial, but the two paths are pinned to agree on every leaderboard metric for the same vector. Treat a difference as a bug worth reporting, not as expected behaviour.

Optionally takes baseConfig: capital/fee/position-size overrides, the same SweepBaseConfig shape executeSweep accepts — send the same object to either endpoint. This endpoint has one effective fee rate rather than a sweep’s independent buy/sell legs: a baseConfig that resolves to different buy/sell rates, or sets a non-default feeLeg, is rejected with 400 instead of silently collapsed to one side. Omit it to run at the platform defaults (initialFunding: 100, feeRate: 0.001).

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..."}

With a baseConfig override (capital and position size, instead of the platform defaults):

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","baseConfig":{"initialFunding":1000,"percentAmountToLock":10}}'
# → 202 {"jobId": "7pQx91Ab..."}

Re-running a sweep leaderboard row for its curve, with params:

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","params":{"ema.fast.period":9,"ema.slow.period":21}}'
# → 202 {"jobId": "9k2LpQi7..."}

Errors: 400 invalid request, or a type that can’t be executed yet (funding) · 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": 0.5833,
    "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.