Instrumentos, tiempo y páginas
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,upbity otros. Qué exchange existe para cada tipo de dato varía: la lista completa está en/v1/instruments. - market —
spotoperp. Un nombre confutureuoptionse interpreta, pero no hay datos de ellos: dicha solicitud recibe400 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:
1793750400000es el 4 de noviembre de 2026, 00:00 UTC. - La ventana de solicitud es semiabierta
[from, to):fromse incluye,tono. Así, ventanas adyacentes se unen sin repeticiones. - Cada ruta tiene sus propios valores predeterminados: velas sin
fromtomanlimitpasos hacia atrás desdeto, operaciones: la última hora, interés abierto: las últimas 24 horas. Sinto, “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.
from datetime import datetime, timezone
t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000) # 1793750400000La 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.
{
"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:
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.
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,limity lo demás.400 bad_cursorse 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-Cursores el cursor yLink, 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 camponext_cursor(formatos).
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMALa 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.