Backtests

Prepara datos históricos, ejecuta una estrategia, sondea su resultado e inspecciona su curva de equity.

Prepara datos históricos, ejecuta una estrategia compilada contra ellos una vez, sondea el resultado y traza la curva de equity. Para ejecutar la misma estrategia sobre una cuadrícula de parámetros en su lugar, consulta docs/backtest_sweep.md.

{type} es el DataSourceType: ticker, kline o funding.

Dónde vive el estado de un job

Los tres endpoints de sondeo de jobs responden “¿ha terminado?, ¿ha fallado?” en sitios distintos, porque cada uno devuelve su propio tipo de resultado. El estado en sí es el mismo vocabulario de JobState (New, Started, Completed, Aborted, Failed) en los tres:

Un sondeador que sirva a los tres puede leer (resp.get("state") or resp)["status"] (en Python): state cuando la respuesta lo tiene, el primer nivel cuando no.

Fuentes de datos

Una petición funding a execute o executeSweep se rechaza con 400 antes de encolar nada, y el mensaje nombra qué se puede ejecutar: funding data can be prepared but not executed yet. Sources that can be executed: ticker, kline.

Kline: tú eliges el ancho de la barra

Una ejecución kline lee barras exactamente de la cadence con la que preparaste — 1s (por defecto), 1m, 5m, 15m, 30m, 1h, 4h u 1d — sea lo que sea que sugiera la propia estrategia. Por eso la misma estrategia se puede ejecutar a varias cadencias preparando el rango una vez por cadencia. Cualquier otra etiqueta (5s, 3m, 8h, …) es 400 al preparar, y el mensaje enumera las aceptadas.

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

Preparar datos

POST .../prepare

Encola una tarea de preparación sobre un rango de fechas y devuelve un jobId de inmediato; sondea el GET de abajo hasta que termine. Los mismos parámetros → el mismo jobId (idempotente) — las llamadas repetidas reutilizan el job existente en lugar de encolar trabajo duplicado.

Cuerpo de la petición — PrepareRequest

Dos formas, según el segmento de ruta exchangeId:

exchangeId: user está reservado para tus propios datos subidos — consulta docs/datasets.md.

Ejemplo

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

Errores: 400 petición inválida, from anterior a la ventana de retención, to en el futuro, una cadence de kline que no es una cadencia de kline, o (para exchangeId: user) la subida del conjunto de datos no ha terminado de ingerirse / cadence más fina que la cadencia descubierta del conjunto de datos / el rango excede el límite de tu plan · 404 exchange/tipo no encontrado, o (para exchangeId: user) datasetId/ datasetVersionId no existe o no es tuyo · 429 cola global al límite o demasiados backtests activos — no aplica a exchangeId: user, que lee un fichero ya ingerido en lugar de reclamar capacidad de worker.

Sondear el estado de la preparación

GET .../prepare/{jobId}

Una preparación de un solo instrumento siempre es terminal (status: Completed) — decide a partir de coverageRatio (por ejemplo, ejecuta en cuanto supere un umbral elegido; contra un conjunto de datos rt, que no tiene ratio, a partir de dataFrom/dataTo) en lugar de sondear a la espera de horas ausentes que quizá nunca lleguen. Una hora ausente normalmente significa baja actividad, no datos perdidos.

Respuesta — PrepareJobState

La forma JobState (contextId, status, statusDetail, size, completed, startTime, endTime) más un resumen de cobertura. Dos formas de cobertura, según sea exchange o conjunto de datos:

Ejemplo

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

Ejecutar un backtest

POST .../execute

Ejecuta la estrategia identificada por strategyId sobre los datos de prepareJobId; el instrumento y el rango de fechas se recuperan del job de preparación, no se vuelven a enviar. Funciona igual para una preparación respaldada por un conjunto de datos. El mismo (prepareJobId, strategyId, storeSignals, equityCurve, baseConfig, params) → el mismo jobId (idempotente) — una petición que omite equityCurve, baseConfig o params deduplica exactamente igual que antes de que esos campos existieran. Dos vectores de params distintos sobre la misma preparación son dos jobs distintos, y 9 y 9.0 son el mismo.

Acepta opcionalmente params: propiedades de estrategia para esta única ejecución, aplicadas sin recompilar. Úsalo para volver a ejecutar una fila de un barrido como un resultado de backtest normal con el vector de parámetros que elijas — por ejemplo, cuando necesitas el resultado del backtest simple junto a la curva del barrido (consulta docs/backtest_sweep.md). Compila la estrategia una vez, llama a este endpoint N veces con distintos params, y cada respuesta incluye la curva en las mismas condiciones que cualquier otro backtest simple. Es una ejecución independiente, no una repetición del ensayo del barrido, pero las dos vías están fijadas para coincidir en todas las métricas de la clasificación para un mismo vector. Trata una diferencia como un fallo que merece reportarse, no como comportamiento esperado.

Acepta opcionalmente baseConfig: ajustes de capital, comisión y tamaño de posición, con la misma forma SweepBaseConfig que acepta executeSweep — envía el mismo objeto a cualquiera de los dos endpoints. Este endpoint tiene una única tasa de comisión efectiva, no las dos patas independientes de compra/venta de un barrido: un baseConfig que resuelva en tasas de compra/venta distintas, o que fije un feeLeg distinto del predeterminado, se rechaza con 400 en vez de colapsarse silenciosamente a un lado. Omítelo para ejecutar con los valores por defecto de la plataforma (initialFunding: 100, feeRate: 0.001).

Cuerpo de la petición

Ejemplo

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

Con un baseConfig personalizado (capital y tamaño de posición, en vez de los valores por defecto de la plataforma):

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

Reejecutar una fila de la clasificación de un barrido para obtener su curva, con 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..."}

Errores: 400 petición inválida, o un type que aún no se puede ejecutar (funding) · 404 job de preparación no encontrado o expirado · 429 limitado por tasa.

Sondear el resultado

GET .../execute/{jobId}

Un 202 (cuerpo vacío, {}) significa que el resultado aún no es legible — sigue sondeando dentro de tu timeout habitual, y nunca lo trates como terminal. Se devuelve tanto mientras el job sigue en marcha como cuando el resultado almacenado de un job terminal no se pudo leer de vuelta, así que un bucle de sondeo debe fijarse en 200 más state.status, no en “ya no es 202”.

Respuesta — BacktestJobResult

state (JobState) más results (ResultMap):

Ejemplo

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

Errores: 400 petición inválida · 404 job de ejecución no encontrado.

Cancelar

DELETE .../execute/{jobId}

Solicita la cancelación; el estado pasa a Aborted una vez procesado — asíncrono, así que sondea con GET para confirmarlo. 200 {"status": "cancelling", "jobId": "..."} · 404 no encontrado.

Visualizar la curva de equity

La guía compartida de curvas de equity cubre el trazado, la normalización porcentual, las formas ARRAY y SHORT, el remuestreo, la codificación diferencial, los metadatos, las salvaguardas de tamaño y la distinta semántica de envío/lectura para backtests simples y ensayos retenidos de un barrido.