← Volver a la documentación
LootX

SDK para Python y TypeScript

Generado: 2026-11-21 docs.lootx.trade
Начало работы

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.

Shell
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.

Shell
npm install @lootx/sdk            # tras la publicación

Primera solicitud

Python
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()
TypeScript
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.

Python
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"])
TypeScript
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.

Python
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"])
TypeScript
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.

Python
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)
TypeScript
const lx = new Client({ apiKey: "lx_live_...", retry: { maxRetries: 5, maxWaitMs: 60_000 } });  // { maxRetries: 0 } — sin reintentos

Lí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.

Python
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)
TypeScript
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