Conjuntos de datos
Sube datos históricos de ticker y úsalos en el flujo estándar de backtesting.
Haz backtest contra un CSV, un fichero parquet o un fichero lastra que subes en lugar de contra un exchange
gestionado: crea un conjunto de datos, sube el fichero (PUT) a una URL prefirmada, finalízalo
para disparar la ingesta, y luego prepara/ejecuta exactamente como de
costumbre pero con el exchangeId: user reservado.
| Método | Ruta | Propósito |
|---|---|---|
POST | /datasets | Crear un conjunto de datos + primera sesión de subida |
GET | /datasets | Listar tus conjuntos de datos |
GET | /datasets/{datasetId} | Obtener uno |
DELETE | /datasets/{datasetId} | Eliminar |
POST | /datasets/{datasetId}/uploads | Abrir una nueva sesión de subida para un conjunto de datos existente |
POST | /datasets/{datasetId}/uploads/{uploadId}/finalize | Disparar la ingesta |
GET | /datasets/{datasetId}/uploads/{uploadId} | Sondear el estado de subida/ingesta |
POST | /datasets/imports | Crear un conjunto de datos buscando el histórico en lugar de subirlo |
GET | /datasets/{datasetId}/imports/{importId} | Sondear el estado de búsqueda/ingesta |
Un conjunto de datos contiene un instrumento, y su type — ticker o klines — dice qué son sus filas: se
lee de los datos cuando una subida o una importación se ha ingerido, consulta Qué es el type. instrument debe ser
un par spot llano (BASE/QUOTE, exactamente una /); las formas de derivados (BTC/USDT:USDT) se rechazan.
Crear un conjunto de datos
POST /datasets — crea el conjunto de datos y su primera sesión de subida en una sola
llamada: una URL prefirmada a la que tu cliente sube (PUT) el fichero directamente, sin
credenciales de la API implicadas en ese PUT.
| Campo | Tipo | Notas |
|---|---|---|
name | string | obligatorio, único entre tus conjuntos de datos. 409 si ya está en uso |
instrument | string | obligatorio, par spot llano |
curl -X POST https://api.qtsurfer.net/v1/datasets
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"name":"My BTC ticks","instrument":"BTC/USDT"}' DatasetCreated (201) — los metadatos disponibles inmediatamente tras la creación más la
sesión de subida. Todavía no es el Dataset completo: campos de
ciclo de vida como createdAt, currentVersionId, el rango y la cadencia se obtienen de GET /datasets/{datasetId} tras las etapas correspondientes del ciclo de vida.
{
"datasetId": "ds_3f9a1c2e7b0d4a5f", "name": "My BTC ticks",
"type": "ticker", "instrument": "BTC/USDT",
"uploadId": "up_1a2b3c4d5e6f7a8b",
"upload": {
"url": "https://storage.qtsurfer.com/.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
"expiresInMinutes": 15
}
} uploadId es lo que pasas a finalizar; upload.url es el destino prefirmado — sube (PUT) el fichero en bruto ahí directamente, sin cabecera Authorization.
El "type": "ticker" de esta respuesta es provisional: el conjunto de datos aún no tiene datos. Una vez
ingerida la subida, su type es lo que contiene el fichero (Qué es el type), así que un fichero de velas es klines cuando lo lees de nuevo.
¿Perdiste esta respuesta? No se pierde nada — llama a POST .../uploads sobre el id de este conjunto de datos y recuperas exactamente la misma sesión de subida, siempre
que aún no la hayas finalizado.
Errores: 400 petición inválida, o instrument no es un par spot llano · 409 nombre de
conjunto de datos ya en uso · 429 se ha alcanzado el límite de conjuntos de datos de tu plan —
elimina uno, o mejora de plan.
Abrir una nueva sesión de subida
POST /datasets/{datasetId}/uploads — obtén una sesión de subida nueva para un conjunto de datos
que ya tienes: un fichero corregido, o el siguiente tramo de histórico. Mismo contrato de
idempotencia que la mitad de subida propia de POST /datasets: como mucho hay una sesión abierta
por conjunto de datos a la vez, así que volver a llamar a esto antes de finalizar simplemente
devuelve esa misma sesión — seguro de reintentar si se pierde una respuesta. Una vez que una
sesión se ha finalizado (con éxito o no), la siguiente llamada aquí abre una genuinamente nueva.
curl -X POST https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads
-H "Authorization: Bearer $TOKEN" 201 — la misma forma {uploadId, upload} que devuelve POST /datasets, sin los metadatos del
conjunto de datos alrededor:
{
"uploadId": "up_1a2b3c4d5e6f7a8b",
"upload": {
"url": "https://storage.qtsurfer.com/.../uploads/up_1a2b3c4d5e6f7a8b/raw.csv?X-Amz-...",
"expiresInMinutes": 15
}
} Errores: 404 no existe ese conjunto de datos para este usuario.
Subir el fichero
CSV, parquet o lastra. Un CSV necesita fila de cabecera; un fichero parquet ya lleva sus
columnas con nombre; un fichero lastra es nuestro propio formato columnar nativo — el mismo que
te devuelve por defecto el dataUrl de un conjunto de datos, así que descargar un conjunto de
datos y entregarle ese mismo fichero a otro usuario para que lo suba funciona sin ninguna
conversión de por medio. Para CSV/parquet, timestamp (una fecha o fecha-hora ISO-8601, que sin zona significa UTC, o segundos/milisegundos/
microsegundos de época numéricos — las formas se listan más abajo) y close son obligatorias; opcionales: open, high, low, volume, quoteVolume, bid, bidSize, ask, askSize. Una subida lastra lleva su propio conjunto fijo de columnas en
su lugar (ya es una descarga de dataUrl, no un formato que construyas a mano) y solo necesita que
estén presentes una serie de marca de tiempo y una de cierre. La cadencia y la unidad de la marca
de tiempo se descubren a partir de los datos, no se declaran, para las tres.
Una subida CSV se convierte a nuestro formato columnar nativo (lastra) para almacenarla. Una
subida parquet o lastra se guarda hoy tal cual. En ambos casos, consulta dataFormat en la versión lista para saber qué recibes de vuelta
realmente — no lo des por hecho a partir de cómo la subiste (un CSV convertido y un fichero lastra
subido reportan ambos dataFormat: "lastra").
Los bytes que se suben (PUT) a upload.url pueden ser ese fichero directamente, comprimidos en
gzip (.gz), o en zip (.zip, exactamente un fichero dentro — un conjunto de datos es un único
fichero sin importar cómo viaje). El formato se detecta a partir del propio contenido: en este
flujo no hay ni nombre de fichero ni Content-Type con los que un cliente pueda declararlo, así
que no hace falta enviar nada más que los bytes.
curl -X PUT "$UPLOAD_URL" --data-binary @my-btc-ticks.csv
# or gzip/zip it first -- detected from content, no extra parameter needed
curl -X PUT "$UPLOAD_URL" --data-binary @my-btc-ticks.csv.gz La columna timestamp
El timestamp de un CSV se lee en cualquiera de estas formas:
| Forma | Ejemplos | Se lee como |
|---|---|---|
| fecha ISO-8601 | 2010-06-29 | medianoche UTC, 2010-06-29T00:00:00Z |
| fecha-hora ISO-8601 con zona | 2010-06-29T14:30:00Z, 2010-06-29T14:30:00+02:00, 2010-06-29T14:30:00.123Z | ese instante; se respeta el desfase horario |
| fecha-hora ISO-8601 sin zona | 2010-06-29T14:30:00, 2010-06-29T14:30 | esa hora en UTC |
lo mismo con un espacio en lugar de T | 2010-06-29 14:30:00 | esa hora en UTC (o la zona, si la nombra) |
| época en segundos, milisegundos o microsegundos | 1277821800, 1277821800000, 1277821800000000 | la unidad se deduce de la magnitud de la primera fila |
- Sin zona significa UTC. Un fichero exportado en hora local debe llevar la zona, o convertirse, antes de subirlo: de lo contrario sus filas se leen como UTC.
- La primera fila decide si la columna es ISO-8601 o de época, y cada fila posterior debe ser del mismo tipo. Las filas de época también deben seguir en la unidad que fijó la primera fila; las filas ISO-8601 pueden mezclar una fecha y una fecha-hora.
- Las marcas de tiempo deben crecer estrictamente. La cadencia y los huecos se descubren como en cualquier fichero:
una serie diaria, con fechas sueltas, tiene cadencia
1d, y un día sin fila (un fin de semana, por ejemplo) cuenta engapsy no es un error. La versión informatimestampUnit: "iso"para todas las formas ISO-8601. - No se aceptan: fechas con el día primero o el mes primero (
29/06/2010,06/29/2010) ni nombres de mes, que son ambiguos. Reescribe una columna así como ISO-8601 antes de subirla.
Una marca de tiempo que no esté en ninguna de esas formas hace fallar la subida: status es failed y error nombra la línea (la línea 1 es la cabecera) y lo que se habría aceptado:
line 2: not a valid timestamp: 29/06/2010. Accepted: an ISO-8601 date (2010-06-29, read as midnight UTC), an ISO-8601 date-time with or without a zone (2010-06-29T14:30:00Z, 2010-06-29 14:30:00; no zone means UTC), or epoch seconds, milliseconds or microseconds. Una fila posterior que no es del tipo que fijó la primera lo dice: Line 2 was read as ISO-8601, so every later line must be one too.
Finalizar una subida (disparar la ingesta)
POST /datasets/{datasetId}/uploads/{uploadId}/finalize — llama a esto una vez que el PUT de
arriba se ha completado. Encola la ingesta y devuelve el control de inmediato; sondea GET .../uploads/{uploadId} más abajo. Idempotente mientras la subida
siga abierta — un finalize repetido antes de que haya producido una versión devuelve el mismo jobId en lugar de encolar una segunda ingesta. Una vez que SÍ ha producido una versión, uploadId queda gastado: volver a finalizarlo es un 409, incluso con bytes distintos recién
subidos (PUT) a la misma URL — abre una nueva sesión de subida en lugar de reutilizar una ya gastada.
curl -X POST https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads/$UPLOAD_ID/finalize
-H "Authorization: Bearer $TOKEN"
# → 202 {"jobId": "dataset-upload:.../ds_3f9a1c2e7b0d4a5f:up_1a2b3c4d5e6f7a8b"} Errores: 404 no existe ese conjunto de datos para este usuario; uploadId no se emitió para
este conjunto de datos (nunca se acuñó, o se acuñó para otro distinto); o todavía no se ha subido
(PUT) nada a upload.url — un finalize sin nada que finalizar · 409 uploadId ya produjo una
versión (el mensaje de error lo nombra) · 413 el fichero subido es muchas veces el límite de tamaño de tu
plan para un conjunto de datos (consulta Límites de tamaño: el límite en sí se
aplica al tamaño almacenado, que solo se conoce tras la conversión) · 429 se alcanzó o se superaría el límite de almacenamiento total
de tu cuenta (maxTotalStorageBytes de GET /account) — elimina un conjunto de datos
para liberar espacio, o mejora de plan.
Límites de tamaño
maxDatasetBytes (GET /account) limita el tamaño almacenado de una versión de un
conjunto de datos: los bytes que reporta su versión lista, que para una subida CSV es el fichero lastra convertido, no el fichero que subiste. Estima a partir de las filas, no del tamaño del
fichero. El tamaño almacenado sigue a las filas y a las columnas, y un CSV puede salir más grande o
más pequeño que el fichero. Medido con datos sintéticos de un segundo: unos 92 bytes por fila para un
CSV timestamp,close, unos 55 para timestamp,open,high,low,close,volume. Los datos reales se
comprimen de otra manera, así que toma estas cifras como un orden de magnitud y, para un fichero
grande, sube primero un trozo pequeño y escala a partir de sus bytes y rows.
El tamaño almacenado solo se conoce una vez convertido el fichero, así que ahí es donde decide el
límite: POST .../finalize responde 202, y una subida por encima del límite acaba failed cuando
la sondeas, con un error como Dataset is 196976000 bytes, exceeds the tier's 100000000 byte limit. Sondea en lugar de dar por hecho que el 202 significa que se almacenó. Lo
que finalize rechaza por sí mismo con 413 es un fichero muchas veces mayor que el límite, muy por
encima de lo que la conversión podría dejar por debajo.
Sondear la ingesta
GET /datasets/{datasetId}/uploads/{uploadId} — sondea tras finalizar hasta que status sea ready o failed. También informa de uploading (finalize aún no llamado, pero el fichero ya se
subió) antes de que finalices. Se registra de forma duradera una vez existe una versión, así que ready/failed son respuestas permanentes; uploading/ingesting reflejan estado en curso que
puede caducar por sí mismo (ver el caso 404 más abajo).
Respuesta — DatasetUploadState
| Campo | Notas |
|---|---|
status | uploading (fichero subido con PUT, aún no finalizado) → ingesting (finalize llamado, el worker analiza/valida) → ready (version lleva el resultado) | failed (por ejemplo, contrato CSV incorrecto, una marca de tiempo que no está en ninguna de las formas aceptadas, unidades de marca de tiempo mezcladas, un .zip sin fichero dentro o con más de uno) |
jobId | el id del job de ingesta, mientras status es ingesting |
error | motivo legible, presente cuando status es failed. Se registra de forma duradera junto con el fallo — sigue disponible sondees cuando sondees después |
version | una DatasetVersion, presente cuando status es ready o failed |
DatasetVersion — una subida ingerida con éxito
| Campo | Notas |
|---|---|
id | el id de la versión — pásalo como datasetVersionId en la preparación para fijarla |
bytes | tamaño del fichero almacenado (dataUrl) — un lastra convertido para una subida CSV (descomprimida antes, si llegó como .gz/.zip), o el propio fichero parquet/lastra, sin convertir, para una subida parquet o lastra. No el tamaño de los bytes subidos originalmente (PUT) |
rows | número de filas de datos |
cadence | descubierta a partir de las propias marcas de tiempo de los datos: una cuadrícula fija (1s, 5s, 15s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 1w) cuando al menos la mitad de los intervalos entre filas caen en ese paso (se tolera un pequeño desajuste de reloj), o rt — datos nativos a la tasa en que se capturaron, cada fila con su propia marca de tiempo sin paso fijo (swaps on-chain por operación, ticks espaciados por bloque o de menos de un segundo, intervalos irregulares). Un conjunto de datos rt se puede remuestrear a cualquier cadencia fija al preparar |
timestampUnit | iso | s | ms | us — la unidad en la que llegó la columna timestamp |
gaps, largestGapSteps | número de huecos a la cadencia descubierta, y el tamaño del mayor en pasos de esa cadencia. Siempre 0 para rt |
dataUrl | URL GET prefirmada al fichero almacenado — consulta dataFormat. Presente una vez ready |
dataFormat | lastra (convertido, desde una subida CSV/gzip/zip, o sin convertir, desde una subida lastra — el valor por sí solo no distingue cuál) | parquet (sin convertir, desde una subida parquet) |
curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID/uploads/$UPLOAD_ID
-H "Authorization: Bearer $TOKEN" {
"uploadId": "up_1a2b3c4d5e6f7a8b",
"status": "ready",
"version": {
"datasetId": "ds_3f9a1c2e7b0d4a5f", "id": "dsv_8e2b4f19c6a03d7e",
"bytes": 4831022, "rows": 86400, "cadence": "1s",
"timestampUnit": "iso", "gaps": 0, "largestGapSteps": 0,
"dataUrl": "https://storage.qtsurfer.com/.../dsv_8e2b4f19c6a03d7e/ticker_BTC_USDT_....lastra?X-Amz-...",
"dataFormat": "lastra"
}
} Errores: 404 no existe ese conjunto de datos para este usuario, o realmente no se sabe nada de
este uploadId — sin versión, sin job en curso, nunca se subió (PUT) nada a su URL de subida.
Importar un conjunto de datos en lugar de subirlo
POST /datasets/imports — una segunda forma de meter datos en un conjunto de datos: en lugar de
subir (PUT) un fichero tú mismo, le pides a la API que vaya a buscar el histórico por ti. Crea el
conjunto de datos y arranca la búsqueda en la misma llamada — no hay un paso de subida aparte, y el
resultado acaba siendo una versión de conjunto de datos indistinguible de una subida una vez lista.
type elige el tipo de mercado del que viene el histórico, con los mismos dos valores que el venueType de GET /exchanges: dex — histórico sobre el propio mercado on-chain
de un pool/par — y cex — el histórico del mercado de un exchange centralizado, que conserva la
plataforma. Cada uno tiene su propio bloque (dex, cex). Un exchange descentralizado de GET /exchanges (robinhood, por ejemplo) se importa con type: dex; como exchange de una
importación cex, su id es 400.
Una importación cex cubre un instrumento a lo largo de un rango: la API lee ese rango del
histórico del exchange, construye las barras de la cadence pedida a partir de los datos más finos
que tiene y guarda el resultado como una versión de conjunto de datos, exactamente igual que en una
subida. Consulta Importar el histórico de un exchange más
abajo.
Una importación está sujeta a las cadencias de tu plan, las mismas que la preparación de los datos de un exchange
(Cadencias por plan). Una cadence que tu plan no incluye es 402; una petición que no indica ninguna recibe la de por defecto del plan; cualquier otra cadencia que tu plan incluya
se puede pedir, y el 202 dice la cadence a la que se construye el conjunto de datos. Una subida no está sujeta a esto: se guarda a
la cadencia detectada en ella, sea cual sea, y se prepara a ella sea cual sea tu plan.
Una importación dex tiene dos formas de datos:
- Velas a la
cadenceque pides, o a la de por defecto del plan si no pides ninguna. Eltypedel conjunto de datos resultante esklines, noticker(Qué es eltype: las velas no llevan libro), ydex.id/dex.versionno hacen falta. Los swaps reproducidos como barras de una anchura, también sin libro, salen igualmente comoklines. - Histórico de swaps on-chain, reproducido directamente desde la propia cadena del pool/par, cada swap con su
propia marca de tiempo (cadencia nativa por operación) — solo en un plan que incluya la tasa nativa de una fuente,
y cuando se omite
cadence.
| Campo | Tipo | Notas |
|---|---|---|
name | cadena | obligatorio, único entre tus conjuntos de datos. 409 si ya está en uso |
instrument | cadena | obligatorio, par spot llano — la etiqueta propia del conjunto de datos, independiente del orden de los tokens on-chain del pool |
from, to | cadena (fecha-hora) | obligatorio, ISO-8601 UTC. from inclusivo, to exclusivo, from < to. El rango total está limitado por tu plan |
cadence | cadena | opcional, las mismas etiquetas que una preparación (de 1s a 1q; cualquier otro valor es 400); una que tu plan no incluye es 402. Para dex: velas a esa anchura en una red que las soporte; omitida/en blanco = la de por defecto del plan, o la cadencia nativa por operación en un plan que incluye la tasa nativa (ver abajo). Para cex: consulta Importar el histórico de un exchange |
type | cadena | obligatorio, "dex" | "cex" |
dex.network | cadena | obligatorio, uno de ethereum | robinhood | solana. solana solo tiene velas (ver abajo) |
dex.id | cadena | obligatorio solo para la importación por operación (sin cadence, en un plan que incluye la tasa nativa); se ignora cuando se construyen velas. "uniswap" es el único valor por ahora — qué protocolo DEX on-chain implementa dex.contract |
dex.version | cadena | obligatorio solo para la importación por operación (sin cadence, en un plan que incluye la tasa nativa); se ignora cuando se construyen velas. "v2" | "v3" |
dex.contract | cadena | obligatorio, la dirección del contrato del pool (v3) o par (v2) |
dex.factory | cadena | opcional — omite para autodescubrirla on-chain a partir de contract; indícala solo si ya la conoces o el pool/par pertenece a una factory no canónica. En cualquier caso el pool/par se valida contra la factory que se use antes de buscar nada. Se ignora si una cadence de velas realmente se resuelve (ver abajo) |
La cadencia on-chain es nativa, no se remuestrea. Una importación dex normal (sin cadence) en un plan que
incluye la tasa nativa de una fuente mantiene la propia cadencia de eventos por operación de la fuente — cada swap en la marca de tiempo
en la que ocurrió, así que la cadence de la versión resultante es rt salvo que los swaps caigan
por casualidad en una cuadrícula fija — en lugar de agruparlos en velas; remuestrea a una cadencia
más gruesa después, como un paso aparte, si necesitas una a partir de datos on-chain. Cualquier otro plan recibe en su lugar velas
a la suya de por defecto, y lo mismo una importación que pide una cadence: las barras se construyen a esa anchura directamente —
pero solo en una red que realmente tenga una fuente de velas detrás. En cualquier otra red, un plan que no incluye datos por operación no
puede ser atendido y la petición es 402; en un plan que sí los incluye, la cadence se ignora y la importación
sigue como si nunca se hubiera enviado (nativa, dex.id/dex.version obligatorios). Qué redes soportan velas hoy
no forma parte de este contrato y puede cambiar.
Solana solo tiene velas. No hay importación por operación para un pool de Solana, así que no existe
allí el caso de la tasa nativa: una petición que no indica cadence recibe la de por defecto del plan
como velas en cualquier plan, Elite incluido (1s), y dex.id, dex.version y dex.factory nunca
hacen falta. Se puede pedir cualquier cadencia que tu plan incluya, y una que no incluye es 402,
como en cualquier otro sitio. El dex.contract de un pool de Solana es su dirección en base58, que
distingue mayúsculas de minúsculas: envíala exactamente como está escrita.
Las velas llegan hasta 180 días atrás. Una importación de velas — una que indica una cadence o
que recibe la de por defecto del plan — cuyo from es anterior a 180 días antes de la petición es 400, sea cual sea la red; el mensaje dice el instante más antiguo que puede leer. Se rechaza de
entrada en lugar de aceptarse y fallar después. La ventana no se aplica a una importación por operación
ni a una de cex.
Una anchura en la que el pool no tuvo ninguna operación puede no tener barra. Las velas de un pool
no son una rejilla contigua: un segundo (o un minuto) sin operaciones puede faltar en el conjunto de
datos, y eso solo significa que el precio no se movió y no se operó. Es más frecuente a 1s y en pools
que operan poco.
curl -X POST https://api.qtsurfer.net/v1/datasets/imports
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{
"name": "weth-usdc-week",
"instrument": "WETH/USDC",
"from": "2026-08-01T00:00:00Z",
"to": "2026-08-08T00:00:00Z",
"type": "dex",
"dex": {
"network": "ethereum",
"id": "uniswap",
"version": "v3",
"contract": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
}
}'
# → 202 {"datasetId":"ds_3f9a1c2e7b0d4a5f","importId":"imp_01j9z...","jobId":"dataset-import:...","status":"fetching"} O, para velas pre-agregadas en lugar de swaps on-chain en bruto:
curl -X POST https://api.qtsurfer.net/v1/datasets/imports
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{
"name": "weth-usdc-1s",
"instrument": "WETH/USDC",
"from": "2026-10-27T00:00:00Z",
"to": "2026-10-27T06:00:00Z",
"cadence": "1s",
"type": "dex",
"dex": {
"network": "ethereum",
"contract": "0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
}
}' Lo mismo para un pool de Solana — solo velas, la dirección tal como está escrita:
curl -X POST https://api.qtsurfer.net/v1/datasets/imports
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{
"name": "sol-usdc-5m",
"instrument": "SOL/USDC",
"from": "2026-10-27T00:00:00Z",
"to": "2026-10-27T06:00:00Z",
"cadence": "5m",
"type": "dex",
"dex": {
"network": "solana",
"contract": "Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE"
}
}' importId es con lo que sondeas, más abajo — no hay un paso de “finalizar” aparte como en una
subida.
Errores: 400 petición inválida, instrument no es un par spot llano, from >= to, cadence presente pero no uno de sus valores soportados, una importación de velas cuyo from es anterior a los
180 días a los que llegan las velas, el rango excede el límite de importación de tu
plan, la estimación aproximada de tamaño del rango excede el límite de filas de tu plan, dex.network/dex.id no es uno de sus valores soportados, dex.contract/dex.factory fallan la
validación básica de forma, o (cuando se omite cadence en un plan que incluye la tasa nativa) falta dex.id/dex.version (si el
pool/par realmente se resuelve, y para una cadence de velas si esa combinación se puede servir en
la red pedida, se comprueba después, de forma asíncrona — ver failed abajo) · 402 cadence no es una de las de tu plan, o datos por operación que tu
plan no incluye · 409 nombre de
conjunto de datos ya en uso · 429 se alcanzó el límite de conjuntos de datos de tu plan, ya se
alcanzó el límite de almacenamiento total de tu cuenta (maxTotalStorageBytes de GET /account), o ya tienes tantas importaciones en curso como permite tu plan
(maxConcurrentImports) — elimina un conjunto de datos para liberar hueco o espacio, espera a que termine una
importación, o mejora de plan. Una importación está en curso desde que se acepta hasta que está lista o ha fallado; no
hace falta sondearla para que su plaza se libere.
Importar el histórico de un exchange
type: "cex" importa un instrumento de un exchange centralizado a lo largo de un rango. Mismo
endpoint, mismos campos name, instrument, from, to y cadence, el mismo sondeo de más abajo y
los mismos límites, salvo el rango: lo limita el maxCexImportRangeHours de tu plan (GET /account), en
horas y aparte del maxImportRangeHours de una pool. El histórico ya lo guarda la plataforma, así que en los planes
mayores el rango llega a semanas; lo que lo acota es cuánto cargas después, ya que una barra por segundo son unos 57
bytes en el fichero guardado y 88 en memoria. Solo cambia el bloque que dice qué importar:
| Campo | Tipo | Notas |
|---|---|---|
cex.exchange | cadena | obligatorio, el id de un exchange centralizado (venueType cex) de GET /exchanges, en minúsculas. El id de un exchange descentralizado es 400: usa type: dex |
cex.segment | cadena | obligatorio, uno de los segments del exchange. spot es el único segmento que admite hoy una importación cex, lo que concuerda con que instrument sea un par spot llano |
cex.dataType | cadena | obligatorio, "ticker" | "klines". Lo que se trae, y por tanto el type del conjunto de datos resultante (Qué es el type: los tickers llevan el libro, las klines no) |
cadence es opcional y admite las mismas etiquetas que la cadencia de una preparación de backtest,
tanto para tickers como para klines: 1s, 5s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 1w o 1q. Cualquier otra etiqueta es 400, y una que tu plan no incluye es 402.
Si se omite, el conjunto de datos recibe la de por defecto del plan; un plan que incluye la tasa nativa de una fuente
recibe en su lugar la cadencia más fina que contienen todas las partes del rango. Las barras se
construyen a partir de los datos más finos que contienen todas las partes del rango, así que, cuando decide el rango, un
rango cuyo histórico cambia de cadencia a mitad (de 1m a 1s, por ejemplo) sale entero con la más
gruesa: el conjunto de datos no tiene ningún hueco que sea solo un cambio de cadencia. Una cadence más fina que esa, o que no sea múltiplo exacto de ella, hace fallar la importación (failed, y error nombra la cadencia más fina que contiene el rango) en lugar de darte un conjunto de datos
con una cadencia distinta de la que pediste.
curl -X POST https://api.qtsurfer.net/v1/datasets/imports
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{
"name": "btc-usdt-1s-sept",
"instrument": "BTC/USDT",
"from": "2026-09-01T00:00:00Z",
"to": "2026-09-01T06:00:00Z",
"cadence": "1s",
"type": "cex",
"cex": {
"exchange": "binance",
"segment": "spot",
"dataType": "klines"
}
}'
# → 202 {"datasetId":"ds_3f9a1c2e7b0d4a5f","importId":"imp_01j9z...","jobId":"dataset-import:...","status":"fetching"} Errores, además de los anteriores: 400 falta el bloque cex, cex.exchange no es un exchange
centralizado de GET /exchanges (uno descentralizado incluido), cex.segment no es spot, cex.dataType no es ticker ni klines, o una cadence que no es ninguna de las etiquetas
anteriores. Si el rango contiene datos, y si los contiene lo bastante finos para la cadence, se
comprueba después, de forma asíncrona: ver failed abajo.
Sondear una importación
GET /datasets/{datasetId}/imports/{importId} — sondea tras POST /datasets/imports hasta que status sea ready o failed. Una importación pasa tiempo real buscando en su fuente antes de
que se aloje nada; una vez buscada, reentra exactamente en la misma cadena de ingesta que usa una
subida.
Respuesta — DatasetImportState
| Campo | Notas |
|---|---|
status | fetching (leyendo de la fuente, nada alojado todavía — el único estado que solo reporta una importación) → ingesting (buscado, alojado, el worker analiza/valida) → ready (version lleva el resultado) | failed |
jobId | el id del job de búsqueda/ingesta, mientras status es fetching o ingesting |
error | motivo legible, presente cuando status es failed — un pool/par que no se resuelve, sin datos en el rango pedido, un rango más antiguo de lo que retiene la fuente, una cadence cex más fina que la que contiene el rango (el mensaje nombra la más fina), la búsqueda superando el límite de tiempo de tu plan, o cualquiera de los motivos del lado de ingesta que puede llevar DatasetUploadState.error, una vez que la búsqueda pasa el testigo a esa misma cadena. Se registra de forma duradera, igual que en la vía de subida |
version | una DatasetVersion, presente cuando status es ready o failed |
curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID/imports/$IMPORT_ID
-H "Authorization: Bearer $TOKEN" {
"importId": "imp_01j9z1x2y3z4a5b6c7d8e9f0g1",
"status": "ready",
"version": {
"datasetId": "ds_3f9a1c2e7b0d4a5f", "id": "dsv_8e2b4f19c6a03d7e",
"bytes": 4831022, "rows": 604800, "cadence": "rt",
"timestampUnit": "us", "gaps": 0, "largestGapSteps": 0,
"dataUrl": "https://storage.qtsurfer.com/.../dsv_8e2b4f19c6a03d7e/ticker_WETH_USDC_....lastra?X-Amz-...",
"dataFormat": "lastra"
}
} Errores: 404 no existe ese conjunto de datos para este usuario, o realmente no se sabe nada de
este importId.
Qué es el type
El type de un conjunto de datos dice qué son sus filas. Se decide cuando una versión pasa a ready, y es el type de la versión actual. Una importación que ya sabe qué trajo lo dice, y no se adivina nada: una
importación cex es su dataType, y una importación dex que pidió velas es klines. Todo lo demás (una
subida de CSV, Lastra o Parquet, una importación dex de swaps on-chain) se lee de las filas:
| Las filas | type |
|---|---|
llevan un libro de órdenes (bid, bidSize, ask o askSize) en alguna fila | ticker |
no tienen libro, y llevan open, high, low y close en todas las filas | klines |
cualquier otra cosa: solo un close (un fichero de timestamp,close es un precio), o solo algunas de las cuatro columnas OHLC, o solo algunas filas | ticker |
Dos comprobaciones más evitan que un ticker pase por velas. En un ticker, la apertura, el máximo, el mínimo y el
volumen son las cifras móviles de 24 horas del exchange, no las de un intervalo. Un fichero sin libro sigue
siendo ticker si se cumple alguna de estas dos condiciones:
- El máximo y el mínimo casi nunca cambian. Al menos 100 filas en las que cambian entre menos de 1 de cada
200 filas consecutivas. Un fichero donde todas las filas tienen el mismo precio (
highigual alow, un instrumento que nadie negoció) sigue siendo de velas. Esta comprobación no distingue las cifras de 24 horas de barras con una cadencia gruesa (una hora o más). - Las aperturas no siguen a los cierres. Una barra abre donde cerró la anterior (dentro del 0,01 % de él); la apertura de una ventana de 24 horas no. Al menos 20 filas, de las que menos de 1 de cada 20 abren en el cierre que tienen antes.
Solo las filas de una subida y de una importación dex de swaps pasan por estas comprobaciones. No deciden nada
para una importación que declara su type.
Hasta que la primera versión es ready, el type es solo la etiqueta de la forma en que se creó el conjunto de
datos (ticker para una subida, klines para una importación que pidió velas). Una subida posterior de otro
tipo de datos cambia el type del conjunto de datos; cada versión conserva el suyo, y un backtest que fija datasetVersionId se juzga por el de esa versión. Los conjuntos de datos almacenados antes de esta regla
conservan el type que tenían.
Forma del conjunto de datos
Tanto GET /datasets como GET /datasets/{datasetId} devuelven esto — from/to/cadence/ timestampUnit reflejan el rango, la cadencia y la unidad de marca de tiempo propios descubiertos
de la versión actual, y status, bytes, rows, gaps y largestGapSteps dicen si es
utilizable y qué tamaño tiene, así que no necesitas una segunda llamada para ver qué cubre un
conjunto de datos.
| Campo | Notas |
|---|---|
datasetId, name, type ("ticker" | "klines"), instrument, createdAt, status | siempre presentes. type dice qué son las filas de la versión actual, decidido cuando la versión pasó a ready (Qué es el type): "klines" para velas (una subida con open, high, low y close en todas las filas y sin libro; una importación dex que pidió una cadence de velas; una importación cex con dataType: "klines"), "ticker" para un libro o un precio suelto. Antes de que la primera versión sea ready es solo la etiqueta de la forma en que se creó el conjunto de datos |
currentVersionId | la versión finalizada e ingerida con éxito más reciente. Ausente hasta que al menos una subida ha terminado de ingerirse |
status | ready — currentVersionId está fijado y los campos de abajo lo describen; failed — el intento de subida o importación más reciente falló, no hay nada que leer todavía (consulta error); pending — nunca se intentó nada (recién creado, o una subida nunca se finalizó) |
updatedAt | cuándo cambió currentVersionId por última vez; ausente hasta que tiene un valor |
from, to, cadence, timestampUnit | el rango/cadencia/unidad de marca de tiempo propios de la versión actual (una cuadrícula fija o cadencia rt, iso|s|ms|us para timestampUnit, consulta DatasetVersion), tal como se descubrieron en la ingesta. Ausentes hasta que existe una versión |
bytes, rows, gaps, largestGapSteps | el tamaño almacenado, el número de filas, el número de huecos y el mayor hueco (en pasos de su cadencia) propios de la versión actual. Presentes solo cuando status es ready — consulta DatasetVersion para saber qué mide bytes exactamente |
error | por qué falló el intento más reciente. Presente solo cuando status es failed |
GET /datasets/{datasetId} por sí solo añade dataUrl/dataFormat (con el mismo significado que
en DatasetVersion) una vez que la versión
actual está ready, más _links.self. El listado masivo no los emite nunca — una URL de descarga
prefirmada para cada conjunto de datos en una pantalla que no dibuja ninguna gráfica no compensa
la exposición.
Listar tus conjuntos de datos
GET /datasets — todos los conjuntos de datos que has creado y no has eliminado, los creados más
recientemente primero. Nunca un 404 — un array vacío si no tienes ninguno, la misma
convención que GET /strategies.
curl https://api.qtsurfer.net/v1/datasets -H "Authorization: Bearer $TOKEN" GET /datasets?includeDeleted=true lista también los conjuntos de datos que has eliminado, cada uno
con el deletedAt en que se eliminó — útil para mantener tu propia copia de la lista sincronizada,
de modo que un conjunto eliminado aparezca como eliminado en lugar de limitarse a desaparecer.
Obtener un conjunto de datos
GET /datasets/{datasetId} — un Dataset más un _links.self.
curl https://api.qtsurfer.net/v1/datasets/$DATASET_ID -H "Authorization: Bearer $TOKEN" Errores: 404 no existe ese conjunto de datos para este usuario.
Eliminar un conjunto de datos
DELETE /datasets/{datasetId} — eliminación suave. Deja de aparecer en los endpoints de listado/
obtención y ya no puede usarse para preparar, pero sus datos de objeto se recuperan más tarde en
lugar de purgarse en el acto, así que un backtest ya en marcha contra una de sus versiones no se
interrumpe.
curl -X DELETE https://api.qtsurfer.net/v1/datasets/$DATASET_ID -H "Authorization: Bearer $TOKEN"
# → {"datasetId": "ds_3f9a1c2e7b0d4a5f", "deleted": true} Errores: 404 no existe ese conjunto de datos para este usuario, o ya está eliminado.
Hacer backtest contra un conjunto de datos
Una vez que una versión está ready, prepara y ejecuta exactamente igual que contra un exchange
gestionado, pero con exchangeId: user y datasetId en lugar de instrument:
curl -X POST https://api.qtsurfer.net/v1/backtest/user/ticker/prepare
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"datasetId":"ds_3f9a1c2e7b0d4a5f","from":"2026-03-14","to":"2026-03-15"}'
# → 202 {"jobId":"5ikYAMIO...","datasetId":"ds_3f9a1c2e7b0d4a5f","datasetVersionId":"dsv_8e2b4f19c6a03d7e"} execute no cambia — el mismo cuerpo de petición que contra un exchange gestionado, ya que el
instrumento y el rango se recuperan de prepareJobId en cualquier caso. Consulta docs/backtest_execute.md para la referencia completa de prepare/execute,
incluidos los campos datasetId/datasetVersionId de PrepareRequest y la forma de cobertura
respaldada por conjunto de datos en PrepareJobState (cadence/gaps/largestGapSteps en lugar
de los totalHours/hoursWithData/hoursWithoutData recorridos por hora).
Qué conjuntos de datos se ejecutan con cada {type}
El {type} de la ruta dice con qué se alimenta la estrategia; el type del propio conjunto de datos dice lo
que contiene. Tanto las ejecuciones ticker como las kline aceptan un conjunto de datos, y un conjunto de
datos de velas se puede ejecutar de cualquiera de las dos maneras:
{type} de la ejecución | conjunto de datos de type ticker | conjunto de datos de type klines |
|---|---|---|
ticker | sí | sí |
kline | 400 al preparar | sí |
Una ejecución kline sobre un conjunto de datos lee las filas del propio conjunto como las barras: no se
construye ningún ticker a partir de ellas. Por defecto cada fila es una barra, con la cadence propia del
conjunto de datos. Una cadence más gruesa que sea un múltiplo exacto de ella agrega las filas en barras más
anchas, y una barra que el rango cubre solo en parte se descarta en lugar de emitirse corta. execute, executeSweep y walk-forward la aceptan.
La barra a la que pertenece una fila es su marca de tiempo truncada a la cadencia del conjunto de datos, así que
un fichero marcado en la apertura de cada barra y otro marcado en su cierre (el último milisegundo de la barra)
dan las mismas barras. Una marca de tiempo fuera de la rejilla de la cadencia (un fichero de un minuto marcado
en el :20 de cada minuto) se trunca sobre ella, y la primera barra, que entonces abre antes de tu from, se
descarta como cualquier barra que el rango cubre solo en parte.
Una preparación kline sobre un conjunto de datos que no es klines se rechaza con un 400 que nombra el
tipo del conjunto de datos, antes de encolar nada, y dice que se prepare como datos de ticker. Una ejecución ticker sobre un conjunto de datos klines se acepta: cada barra se lee como una muestra, sin libro de
órdenes.
El type que lee esta tabla es el de la versión que leerá la ejecución: la actual, o la que fija un datasetVersionId (Qué es el type). Por tanto, un fichero que subes es klines una vez ingerido si contiene velas
(open, high, low y close en todas las filas, cada apertura en el cierre anterior, sin libro), y se
ejecuta como barras; un fichero con libro, o solo con un precio, es ticker. Un conjunto de datos de velas
también procede de una importación de las velas de un
exchange (o de una importación dex que pide una cadence de velas).