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