LootX

Instrumentos, tiempo y páginas

Actualizado 7 de noviembre de 2026 Esta página en PDF

Tres reglas comunes a todas las rutas: el nombre del instrumento venue:market:SYMBOL, el tiempo en milisegundos UTC y la paginación mediante next_cursor.

Todas las rutas de la API hablan el mismo idioma: el instrumento se denomina igual en cualquier exchange y en cualquier fuente, el tiempo es siempre milisegundos Unix UTC, y una respuesta larga se pagina con un cursor. Aquí se explican estas tres reglas una vez y con detalle.

Nombre del instrumento

El instrumento se escribe como venue:market:SYMBOL:

Ejemplo Qué es
binance:perp:BTCUSDT contrato perpetuo USDT de BTC en Binance
bybit:spot:ETHUSDT spot ETH/USDT en Bybit
hyperliquid:perp:BTC perpetuo de BTC en Hyperliquid: en este exchange, al perpetuo se le llama moneda
coinbase:spot:BTC-USD spot BTC/USD en Coinbase, con guion, como en el propio exchange
lighter:perp:BTCUSDC perpetuo de BTC en Lighter, liquidado en USDC
hyperliquid:perp:AAPLUSDC.XYZ acción de Apple en la deck xyz de Hyperliquid (mercado HIP-3); los datos están disponibles no en todas las rutas
  • venue — exchange en minúsculas: binance, bybit, okx, bitget, gate, mexc, bingx, kucoin, hyperliquid, aster, lighter, kraken, coinbase, upbit y otros. Qué exchange existe para cada tipo de dato varía: la lista completa está en /v1/instruments.
  • market — spot o perp. Un nombre con future u option se interpreta, pero no hay datos de ellos: dicha solicitud recibe 400 unsupported_instrument.
  • SYMBOL — base y cotización juntas, en mayúsculas: BTCUSDT, ETHUSDC. Excepciones: Hyperliquid y Coinbase, como en la tabla.

Una forma de nombre inválida produce 400 bad_instrument. El nombre es correcto, pero la ruta no reconoce tal mercado o exchange: 400 unsupported_instrument con param: "instrument". El símbolo se verifica solo en /v1/candles y /v1/series, y no siempre: un par inexistente en la fuente puede recibir allí 400 unsupported_instrument con param: "symbol", y si la fuente falla, un 200 vacío. En las demás rutas, el símbolo no se contrasta con el registro: un par con un error tipográfico cuyo nombre pasa la validación de exchange, mercado y cotización recibe 200 sin filas. Verifique el nombre según el registro; las condiciones de rechazo y las excepciones figuran en la página de errores.

Tiempo

  • El tiempo es en todas partes milisegundos Unix UTC, como entero: 1793750400000 es el 4 de noviembre de 2026, 00:00 UTC.
  • La ventana de solicitud es semiabierta [from, to): from se incluye, to no. Así, ventanas adyacentes se unen sin repeticiones.
  • Cada ruta tiene sus propios valores predeterminados: velas sin from toman limit pasos hacia atrás desde to, operaciones: la última hora, interés abierto: las últimas 24 horas. Sin to, “ahora”.
  • El paso (tf) se escribe como número con sufijo: 1s, 30s, 1m, 5m, 1h, 4h, 1d. Qué pasos acepta la ruta se indica en su descripción.
Python
from datetime import datetime, timezone

t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000)  # 1793750400000

La respuesta es una tabla por columnas

Las filas no llegan como un array de objetos, sino como una tabla: los nombres de las columnas aparecen una vez y las filas son arrays de valores en el mismo orden. Así la respuesta es varias veces más corta.

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "columns": ["ts", "open", "high", "low", "close"],
  "rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3]],
  "next_cursor": null
}

Convertirla en objetos conocidos es una línea:

JavaScript
const records = body.rows.map((r) => Object.fromEntries(body.columns.map((c, i) => [c, r[i]])));

Puede haber más campos en la respuesta: no dependa de su orden y no falle ante un campo desconocido. El orden de las columnas dentro de la tabla lo define columns.

Páginas

Si la respuesta no cabe en una página, contiene next_cursor. Páselo como cursor= con los mismos demás parámetros y obtendrá la página siguiente. next_cursor: null significa que no hay más páginas.

Python
import os, requests

URL = "https://market-api.lootx.trade/v1/trades"
HEAD = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
params = {"instrument": "binance:perp:BTCUSDT", "from": 1793750400000, "to": 1793754000000}

rows = []
while True:
    page = requests.get(URL, params=params, headers=HEAD, timeout=30).json()
    rows += page["rows"]
    if not page.get("next_cursor"):
        break
    params["cursor"] = page["next_cursor"]
  • El cursor es una cadena opaca: dentro solo está la posición de continuación. El gateway no contrasta los demás parámetros con los de la primera página: con otros parámetros, la página se construirá a partir de esa posición según ellos. Por eso, pase el cursor con los mismos instrument, tf, to, limit y lo demás. 400 bad_cursor se devuelve solo si el cursor está dañado.
  • Las velas se cortan en páginas según la cuadrícula del paso, y en operaciones los registros de un mismo milisegundo van completos a una página: no hay repeticiones ni omisiones en la unión.
  • La dirección en la mayoría de las rutas es de lo antiguo a lo nuevo. Excepción: el historial de densidades se pagina de lo reciente a lo antiguo.
  • En cualquier formato, la página siguiente también está en los encabezados: X-Next-Cursor es el cursor y Link, la dirección ya preparada de la página siguiente (RFC 8288). En CSV, el cursor solo está en el encabezado; en protobuf, además en el campo next_cursor (formatos).
HTTP
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMA

La dirección en Link es la misma solicitud con un nuevo cursor: puede seguirla sin armar nada. La última página no lleva los encabezados Link ni X-Next-Cursor.

Encabezados que conviene registrar

Encabezado Para qué
X-Request-Id número de la solicitud; coincide con request_id en el cuerpo del error. Envíelo a soporte
X-RateLimit-Remaining cuántas solicitudes quedan en el límite más ajustado — detalle
X-Cache solo en respuestas que el gateway puede cachear (rangos cerrados): HIT, de la memoria del gateway; MISS, de la fuente. El gateway recuerda los rangos cerrados hasta 10 minutos. Las demás respuestas no llevan este encabezado
RateLimit restante y segundos hasta el restablecimiento en todas las ventanas del plan — detalle

X-Request-Id lo coloca el gateway en cada respuesta; es el número con el que encontraremos la solicitud.

Compresión

Las respuestas se comprimen si el cliente lo solicita: Accept-Encoding: gzip o br. curl lo pide con --compressed; requests y el navegador, solos. El binario del mapa de calor (HMP1/HMP2) no se comprime: ya es denso.

El volumen diario del plan se calcula sobre el cuerpo antes de la compresión: la solicitud cuesta lo mismo con o sin compresión; la compresión ahorra solo tiempo y tráfico.