SDK для Python и TypeScript
Клиенты lootx (Python) и @lootx/sdk (TypeScript) — листание страниц, таблицы в DataFrame, потоки и повторы при 429 без ручного кода.
Оба клиента устроены одинаково: метод на каждый маршрут, те же имена параметров, листание страниц одним вызовом, таблицы в записи или DataFrame, потоки с автоматическим переподключением.
Установка
Python 3.10 и новее.
pip install lootx # после публикации
pip install "lootx[pandas]" # + to_dataframe()
pip install "lootx[protobuf]" # + format="protobuf"Node.js 18 и новее или браузер.
npm install @lootx/sdk # после публикацииПервый запрос
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()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 и помнит подписки: после обрыва переподключается и подписывается заново сам.
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);
}Весь рынок канала densities или screener с фильтрами — subscribe_market (subscribeMarket), те же параметры, что у scope: "market". Одна подписка на канал в соединении: новая заменяет прежнюю, открывать их можно раз в секунду. Снимает подписку unsubscribe_market (unsubscribeMarket). После обрыва feed() отправляет подписку заново.
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() повторяет сам, если шлюз ответил 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 — только если сервер назвал паузу не длиннее предела ожидания.
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)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.
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);Кадр 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 и подобные — исключение без переподключения, остальное — переподключение с паузой.