← К документации
LootX

SDK для Python и TypeScript

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

1SDK для Python и TypeScript

Клиенты lootx (Python) и @lootx/sdk (TypeScript) — листание страниц, таблицы в DataFrame, потоки и повторы при 429 без ручного кода.

Оба клиента устроены одинаково: метод на каждый маршрут, те же имена параметров, листание страниц одним вызовом, таблицы в записи или DataFrame, потоки с автоматическим переподключением.

Установка

Python 3.10 и новее.

Shell
pip install lootx                 # после публикации
pip install "lootx[pandas]"       # + to_dataframe()
pip install "lootx[protobuf]"     # + format="protobuf"

Node.js 18 и новее или браузер.

Shell
npm install @lootx/sdk            # после публикации

Первый запрос

Python
from lootx import Client

lx = Client("lx_live_...")        # или переменная окружения LOOTX_API_KEY

bars = lx.candles("binance:perp:BTCUSDT", tf="1m", from_=1793750400000, limit=500)
df = bars.to_dataframe(datetimes=True)

# все страницы сразу
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_..." });   // или LOOTX_API_KEY в окружении (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();

Одинаково в обоих

Python TypeScript
Методы snake_case, имя = operationId спецификации camelCase того же имени
Параметры как в API; from → from_ как в API, объектом
Время Unix-мс UTC или datetime Unix-мс UTC или Date
Все страницы iter_*() → collect(), rows(), to_dataframe() iter*() → collect(), rows()
Таблица records(), column(), to_dataframe() records(t), column(t, name)
Бинарный формат Client(format="protobuf") new Client({ format: "protobuf" })
Ошибки исключения по коду, .code, .request_id, .retry_after те же классы, .code, .requestId, .retryAfter
Потоки feed() — единый /v1/ws feed()

Потоки

feed() открывает одно соединение /v1/ws и помнит подписки: после обрыва переподключается и подписывается заново сам.

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);
}

Весь рынок канала densities или screener с фильтрами — subscribe_market (subscribeMarket), те же параметры, что у scope: "market". Одна подписка на канал в соединении: новая заменяет прежнюю, открывать их можно раз в секунду. Снимает подписку unsubscribe_market (unsubscribeMarket). После обрыва feed() отправляет подписку заново.

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() повторяет сам, если шлюз ответил market_subs_limit или rate_limited: старое место шлюз возвращает не сразу. Повторов до 3 раз, пауза — retry_after, но не дольше 30 с, или 1, 4 и 16 с со случайной добавкой до четверти; это настройки переподключения по умолчанию. Кадр отказа вы получите только последний, когда попытки кончатся. Подписка, ушедшая при подключении или переподключении, после такого отказа и после любого другого, например bad_params, остаётся в SDK и уйдёт снова при следующем переподключении; снимает её unsubscribe_market (unsubscribeMarket). Команду на живом соединении SDK не повторяет: отказ приходит вам. Фильтры, отказанные живой команде, SDK откатывает: при переподключении уйдёт то, что шлюз принял живой командой или что ушло при подключении и не снято, а если такого нет, не уйдёт ничего. Новая рыночная команда этого канала (subscribe_market или unsubscribe_market), новое подключение и закрытие feed() отменяют ожидающий повтор.

Ошибки и повторы

Ошибка API превращается в исключение своего класса — MissingKeyError, RevokedKeyError, PlanInactiveError, BadInstrumentError и так далее по коду ошибки; у 405, 406, 408 и 413 — MethodNotAllowedError, NotAcceptableError, RequestTimeoutError и PayloadTooLargeError. У исключения есть code, request_id (requestId) и детали тела ошибки: param, expected, limit, remaining, window, scope, retry_after (retryAfter, секунды — из тела, без него из Retry-After), reset_at_ms (resetAtMs), history_days, earliest_allowed_ms, allow. Поля, которых сервер не прислал, — None (undefined).

На 429 и 503 и на обрыв сети клиент повторяет запрос сам — по Retry-After, до 3 раз. Если сервер просит ждать дольше 30 с, ошибка отдаётся сразу. daily_quota_exceeded не повторяется никогда, hourly_limit и daily_limit — только если сервер назвал паузу не длиннее предела ожидания.

Python
from lootx import Client, RetryPolicy, errors

lx = Client("lx_live_...", retry=RetryPolicy(max_retries=5, max_wait=60))   # RetryPolicy(max_retries=0) — без повторов

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: повторы кончились или ждать дольше 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 } — без повторов

Лимиты из кода

usage() — GET /v1/usage: тариф, лимиты, расход за сутки и окна сейчас. Заголовки лимитов последнего ответа — rate_limit (rateLimit): X-RateLimit-* и разобранные RateLimit-Policy и RateLimit.

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);

Кадр error потока приходит обычным сообщением; errors.error_from_frame(msg) (errorFromFrame(frame)) превратит его в исключение с теми же деталями. Закрытие 1008/1013 с кодом в причине сохраняется в last_close_error (lastCloseError) потока — у feed() это f.stream.last_close_error (f.stream.lastCloseError) — исключением своего класса — например, SlowConsumerError у slow_consumer; отказ доступа — revoked_key и подобные — исключение без переподключения, остальное — переподключение с паузой.

https://docs.lootx.trade/ru/market-api/sdk