SDK para Python y TypeScript
1SDK para Python y TypeScript
Clientes lootx (Python) y @lootx/sdk (TypeScript): paginación, tablas en DataFrame, flujos y reintentos ante 429 sin código manual.
Ambos clientes están organizados igual: un método por ruta, los mismos nombres de parámetros, paginación con una sola llamada, tablas como registros o DataFrame, flujos con reconexión automática.
Instalación
Python 3.10 y superior.
pip install lootx # tras la publicación
pip install "lootx[pandas]" # + to_dataframe()
pip install "lootx[protobuf]" # + format="protobuf"Node.js 18 y superior, o navegador.
npm install @lootx/sdk # tras la publicaciónPrimera solicitud
from lootx import Client
lx = Client("lx_live_...") # o variable de entorno LOOTX_API_KEY
bars = lx.candles("binance:perp:BTCUSDT", tf="1m", from_=1793750400000, limit=500)
df = bars.to_dataframe(datetimes=True)
# todas las páginas de una vez
oi = lx.iter_oi("bybit:perp:ETHUSDT", from_=1793750400000, to=1793836800000).collect()import { Client, records } from "@lootx/sdk";
const lx = new Client({ apiKey: "lx_live_..." }); // o LOOTX_API_KEY en el entorno (Node)
const bars = await lx.candles({ instrument: "binance:perp:BTCUSDT", tf: "1m", from: 1793750400000, limit: 500 });
const rows = records(bars); // [{ ts, open, high, ... }]
const oi = await lx.iterOi({ instrument: "bybit:perp:ETHUSDT", from: 1793750400000, to: 1793836800000 }).collect();Igual en ambos
| Python | TypeScript | |
|---|---|---|
| Métodos | snake_case, nombre = operationId de la especificación |
camelCase del mismo nombre |
| Parámetros | como en la API; from → from_ |
como en la API, como objeto |
| Tiempo | Unix-ms UTC o datetime |
Unix-ms UTC o Date |
| Todas las páginas | iter_*() → collect(), rows(), to_dataframe() |
iter*() → collect(), rows() |
| Tabla | records(), column(), to_dataframe() |
records(t), column(t, name) |
| Formato binario | Client(format="protobuf") |
new Client({ format: "protobuf" }) |
| Errores | excepciones por código, .code, .request_id, .retry_after |
las mismas clases, .code, .requestId, .retryAfter |
| Flujos | feed() — un único /v1/ws |
feed() |
Flujos
feed() abre una única conexión /v1/ws y recuerda las suscripciones: tras una caída se reconecta y se vuelve a suscribir solo.
with lx.feed() as f:
f.subscribe("trades", ["binance:perp:BTCUSDT"])
f.subscribe("densities", ["binance:perp:BTCUSDT", "hyperliquid:perp:BTC"])
for msg in f:
if msg["type"] == "update" and msg["channel"] == "trades":
print(msg["instrument"], msg["data"]["trades"])const f = lx.feed();
f.subscribe("trades", ["binance:perp:BTCUSDT"]);
f.subscribe("densities", ["binance:perp:BTCUSDT", "hyperliquid:perp:BTC"]);
for await (const m of f) {
if (m.type === "update" && m.channel === "trades") console.log(m.instrument, m.data);
}Todo el mercado del canal densities o screener con filtros — subscribe_market (subscribeMarket), los mismos parámetros que scope: "market". Una suscripción por canal en la conexión: la nueva reemplaza a la anterior; se pueden abrir una vez por segundo. unsubscribe_market (unsubscribeMarket) cancela la suscripción. Tras una caída, feed() reenvía la suscripción.
with lx.feed() as f:
f.subscribe_market("densities", venues=["binance"], markets=["perp"], min_usd=250_000)
for msg in f:
if msg["type"] in ("snapshot", "update") and msg.get("scope") == "market":
for item in msg["items"]:
print(item["instrument"], item["data"])const f = lx.feed();
f.subscribeMarket("densities", { venues: ["binance"], markets: ["perp"], min_usd: 250_000 });
for await (const m of f) {
if (m.scope === "market" && m.items) for (const it of m.items) console.log(it.instrument, it.data);
}feed() repite por sí mismo una suscripción enviada al conectar o reconectar, si el gateway respondió market_subs_limit o rate_limited: el gateway no devuelve de inmediato la posición anterior. Hasta 3 reintentos, pausa — retry_after, pero no más de 30 s, o 1, 4 y 16 s con un factor aleatorio de hasta un cuarto; estos son los ajustes de reconexión por defecto. Recibirá el cuadro de rechazo solo al final, cuando se agoten los intentos. Una suscripción enviada al conectar o reconectar, tras tal rechazo y tras cualquier otro, por ejemplo bad_params, permanece en el SDK y se reenviará en la próxima reconexión; unsubscribe_market (unsubscribeMarket) la cancela. El SDK no repite una orden en una conexión viva: el rechazo le llega a usted. El SDK revierte los filtros rechazados por una orden viva: al reconectar se enviará lo que el gateway aceptó por orden viva o lo que se envió al conectar y no se canceló, y si no hay nada de eso, no se enviará nada. Una nueva orden de mercado de ese canal (subscribe_market o unsubscribe_market), una nueva conexión o el cierre de feed() cancelan el reintento pendiente.
Errores y reintentos
Un error de la API se convierte en una excepción de su clase: MissingKeyError, RevokedKeyError, PlanInactiveError, BadInstrumentError y así según el código de error; para 405, 406, 408 y 413: MethodNotAllowedError, NotAcceptableError, RequestTimeoutError y PayloadTooLargeError. La excepción tiene code, request_id (requestId) y detalles del cuerpo del error: param, expected, limit, remaining, window, scope, retry_after (retryAfter, segundos — del cuerpo, sin él de Retry-After), reset_at_ms (resetAtMs), history_days, earliest_allowed_ms, allow. Los campos que el servidor no envió son None (undefined).
Ante 429 y 503 y ante una caída de red, el cliente repite la solicitud por sí mismo — según Retry-After, hasta 3 veces. Si el servidor pide esperar más de 30 s, el error se devuelve de inmediato. daily_quota_exceeded nunca se repite; hourly_limit y daily_limit solo si el servidor indicó una pausa no mayor que el límite de espera.
from lootx import Client, RetryPolicy, errors
lx = Client("lx_live_...", retry=RetryPolicy(max_retries=5, max_wait=60)) # RetryPolicy(max_retries=0) — sin reintentos
try:
lx.candles("binance:perp:BTCUSDT", from_=0)
except errors.HistoryOutOfPlanError as e: # 403 history_out_of_plan
print(e.earliest_allowed_ms, e.request_id)
except errors.RateLimitError as e: # 429: reintentos agotados o espera mayor que max_wait
print(e.code, e.window, e.scope, e.retry_after)const lx = new Client({ apiKey: "lx_live_...", retry: { maxRetries: 5, maxWaitMs: 60_000 } }); // { maxRetries: 0 } — sin reintentosLímites desde el código
usage() — GET /v1/usage: plan, límites, consumo del día y ventanas actuales. Los encabezados de límites de la última respuesta — rate_limit (rateLimit): X-RateLimit-* y RateLimit-Policy y RateLimit analizados.
u = lx.usage()
print(u.plan and u.plan.slug, u.limits.rpm, u.today.requests, u.today.bytes)
m = u.now.window("minute") # limit, burst, used, remaining, reset_at_ms
print(m and m.remaining, lx.rate_limit)const u = await lx.usage();
const minute = u.now.windows.find((w) => w.scope === "account" && w.window === "minute");
console.log(u.plan?.slug, minute?.remaining, lx.rateLimit);El cuadro error del flujo llega como un mensaje normal; errors.error_from_frame(msg) (errorFromFrame(frame)) lo convertirá en una excepción con los mismos detalles. El cierre 1008/1013 con un código en la razón se guarda en last_close_error (lastCloseError) del flujo — en feed() es f.stream.last_close_error (f.stream.lastCloseError) — como una excepción de su clase, por ejemplo SlowConsumerError para slow_consumer; un rechazo de acceso — revoked_key y similares — es una excepción sin reconexión; el resto — reconexión con pausa.
https://docs.lootx.trade/es/market-api/sdk