Python & TypeScript SDK
The lootx (Python) and @lootx/sdk (TypeScript) clients — pagination in one call, tables as records or DataFrames, streams, and automatic retries on 429 without boilerplate.
Both clients work the same way: one method per route, identical parameter names, pagination in a single call, tables as records or DataFrames, and streams with automatic reconnection.
Install
Python 3.10 or newer.
pip install lootx # after publication
pip install "lootx[pandas]" # + to_dataframe()
pip install "lootx[protobuf]" # + format="protobuf"Node.js 18 or newer, or a browser.
npm install @lootx/sdk # after publicationFirst request
from lootx import Client
lx = Client("lx_live_...") # or the LOOTX_API_KEY environment variable
bars = lx.candles("binance:perp:BTCUSDT", tf="1m", from_=1793750400000, limit=500)
df = bars.to_dataframe(datetimes=True)
# all pages at once
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_..." }); // or LOOTX_API_KEY in the environment (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();Same in both
| Python | TypeScript | |
|---|---|---|
| Methods | snake_case, name = operationId from the spec |
camelCase of the same name |
| Parameters | as in the API; from → from_ |
as in the API, as an object |
| Time | Unix ms UTC or datetime |
Unix ms UTC or Date |
| All pages | iter_*() → collect(), rows(), to_dataframe() |
iter*() → collect(), rows() |
| Table | records(), column(), to_dataframe() |
records(t), column(t, name) |
| Binary format | Client(format="protobuf") |
new Client({ format: "protobuf" }) |
| Errors | exceptions by code, .code, .request_id, .retry_after |
same classes, .code, .requestId, .retryAfter |
| Streams | feed() — single /v1/ws |
feed() |
Streams
feed() opens one connection to /v1/ws and remembers subscriptions: after a disconnect it reconnects and resubscribes on its own.
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);
}Market-wide data for the densities or screener channels with filters — subscribe_market (subscribeMarket), with the same parameters as scope: "market". One market subscription per channel per connection: a new one replaces the previous, and they can be opened once per second. unsubscribe_market (unsubscribeMarket) removes the subscription. After a disconnect, feed() resends the subscription.
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);
}If a subscription sent during initial connect or reconnection fails, feed() retries it automatically when the gateway responds with market_subs_limit or rate_limited: the gateway does not restore the old subscription immediately. Up to 3 retries, pause is retry_after but no longer than 30 s, or 1, 4, and 16 s with random jitter up to a quarter; these are the default reconnection settings. You receive the rejection frame only on the last attempt, when all retries are exhausted. A subscription sent during initial connect or reconnection that is rejected for this reason or any other, such as bad_params, stays in the SDK and will be sent again on the next reconnection; unsubscribe_market (unsubscribeMarket) removes it. The SDK does not repeat a command on a live connection: the rejection is delivered to you. Filters rejected by a live command are rolled back by the SDK: on reconnection it sends what the gateway accepted via a live command or what was sent during initial connect and not removed, and if there is none, nothing is sent. A new market command for that channel (subscribe_market or unsubscribe_market), a new connection, or closing feed() cancels the pending retry.
Errors and retries
An API error becomes an exception of its own class — MissingKeyError, RevokedKeyError, PlanInactiveError, BadInstrumentError, and so on per the error code; for 405, 406, 408, and 413 it is MethodNotAllowedError, NotAcceptableError, RequestTimeoutError, and PayloadTooLargeError. The exception has code, request_id (requestId), and the details from the error body: param, expected, limit, remaining, window, scope, retry_after (retryAfter, seconds — from the body, otherwise from Retry-After), reset_at_ms (resetAtMs), history_days, earliest_allowed_ms, allow. Fields the server did not send are None (undefined).
On 429, 503, or a network error, the client retries the request automatically — according to Retry-After, up to 3 times. If the server asks to wait longer than 30 s, the error is returned immediately. daily_quota_exceeded is never retried; hourly_limit and daily_limit are retried only if the server specified a pause no longer than the wait limit.
from lootx import Client, RetryPolicy, errors
lx = Client("lx_live_...", retry=RetryPolicy(max_retries=5, max_wait=60)) # RetryPolicy(max_retries=0) — no retries
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: retries exhausted or wait > 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 } — no retriesLimits from code
usage() — GET /v1/usage: plan, limits, daily usage, and current windows. Rate-limit headers from the latest response — rate_limit (rateLimit): X-RateLimit-* plus parsed RateLimit-Policy and 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);An error frame on a stream arrives as a regular message; errors.error_from_frame(msg) (errorFromFrame(frame)) turns it into an exception with the same details. A close with 1008/1013 and a code in the reason is stored in the stream’s last_close_error (lastCloseError) — for feed() this is f.stream.last_close_error (f.stream.lastCloseError) — as an exception of the appropriate class, e.g. SlowConsumerError for slow_consumer; access denial such as revoked_key and similar produces an exception without reconnection, everything else reconnects with a pause.