LootX

SDK для Python та TypeScript

скоро Оновлено 6 листопада 2026 р. Ця сторінка у PDF

Клієнти 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 і подібні — виняток без перепідключення, решта — перепідключення з паузою.