← До документації
LootX

API данных

Платный API рыночных данных: свечи, сделки, стакан, OI, фандинг, плотности и скринер — один ключ, REST и WebSocket.

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

1Швидкий старт

Ключ, адреса, перший запит — свічки BTCUSDT з Binance за п'ять хвилин.

API ринкових даних LootX віддає ті самі дані, на яких працює термінал: свічки від однієї секунди, стрічки угод, футпринт, теплову карту біржового стакана, відкритий інтерес, ставку фінансування, щільності та скринери. Усі біржі — через одну адресу й один ключ, з однаковими іменами інструментів і одним форматом часу.

За п’ять хвилин

Отримайте ключ

Відкрийте Кабінет → API-ключі і натисніть Створити ключ. Дайте ключу зрозуміле ім’я — наприклад, за назвою скрипта чи сервера, де він житиме.

Ключ має вигляд lx_live_ і ще 43 знаки. Він показується один раз: збережіть його в менеджер паролів або у змінну оточення. Загубили — відкличте ключ і випустіть новий.

Ключ працює, поки в акаунта є діючий API-тариф. Тариф обирається на тій самій сторінці, якщо він відкритий для купівлі, або його призначає адміністратор LootX.

Запам’ятайте адресу і спосіб передати ключ

Базовий адрес — https://market-api.lootx.trade. Ключ передається заголовком:

HTTP
Authorization: Bearer lx_live_...

або X-API-Key: lx_live_.... Ключ ніколи не кладеться в адресу: рядки запитів осідають у логах проксі та браузерів, тому запит із ключем в адресі отримує 400 key_in_query.

Зробіть перший запит

Три останні хвилинні свічки безстрокового контракту BTCUSDT на Binance (остання — поточна хвилина, вона ще не закрита):

Shell
export LOOTX_API_KEY="lx_live_..."

curl -s "https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&limit=3" \
  -H "Authorization: Bearer $LOOTX_API_KEY"

Відповідь — таблиця колонками: імена в columns, рядки в rows, значення в тому самому порядку (числа нижче — для прикладу):

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "columns": ["ts", "open", "high", "low", "close", "volume", "quote_volume",
              "buy_volume", "buy_quote_volume", "trades", "buy_trades"],
  "rows": [
    [1793750400000, 104250.5, 104262.0, 104241.1, 104255.3, 41.27, 4302517.62, 22.91, 2388563.12, 1824, 1003],
    [1793750460000, 104255.3, 104270.0, 104249.8, 104266.9, 28.04, 2923450.40, 15.33, 1598336.46, 1310, 702],
    [1793750520000, 104266.9, 104268.4, 104230.2, 104233.0, 36.58, 3813166.95, 14.02, 1461540.90, 1597, 688]
  ],
  "next_cursor": null,
  "coverage": { "oldest": 1792741800000, "newest": 1793750520000 }
}
  • ts — початок свічки в мілісекундах UTC;
  • volume — обсяг у монетах, quote_volume — у валюті котирування (у USDT-пар це долари);
  • next_cursor: null — більше сторінок немає; інакше передайте його як cursor= (як гортати);
  • coverage — який період узагалі є у сховищі за цим інструментом. Історія свічок в API починається 23.10.2026 (докладніше — у Свічках).

Якщо щось не так

Будь-яка помилка шлюзу — HTTP-код і JSON із машинним кодом. Без ключа — 401 із заголовком WWW-Authenticate: Bearer realm="lootx" і тілом:

JSON
{
  "error": {
    "code": "missing_key",
    "message": "нужен ключ: заголовок Authorization: Bearer <ключ> или X-API-Key",
    "request_id": "a553713a48d85b96-VIE",
    "docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#missing_key"
  }
}

Розбирайте поле code, а не текст message — текст може змінюватися. API читає тільки GET (і HEAD, OPTIONS): інший метод отримає 405 method_not_allowed. request_id надішліть у підтримку, якщо помилка незрозуміла: за ним ми знайдемо запит. Усі коди — у розділі Помилки.

Що далі

Інтерактивна специфікація — market-api.lootx.trade/docs, машиночитана — /v1/openapi.json (OpenAPI 3.1, ключ не потрібен).

https://docs.lootx.trade/uk/market-api/getting-started

Начало работы

2Інструменти, час і сторінки

Три правила, спільні для всіх маршрутів: ім'я інструмента venue:market:SYMBOL, час у мілісекундах UTC і гортання через next_cursor.

Усі маршрути API говорять однією мовою: інструмент називається однаково в будь-якої біржі та будь-якого джерела, час — завжди Unix-мілісекунди UTC, довга відповідь гортається курсором. Тут — ці три правила один раз і докладно.

Ім’я інструмента

Інструмент пишеться як venue:market:SYMBOL:

Приклад Що це
binance:perp:BTCUSDT безстроковий USDT-контракт BTC на Binance
bybit:spot:ETHUSDT спот ETH/USDT на Bybit
hyperliquid:perp:BTC перп BTC на Hyperliquid — у цієї біржі перп називається монетою
coinbase:spot:BTC-USD спот BTC/USD на Coinbase — через дефіс, як у самої біржі
lighter:perp:BTCUSDC перп BTC на Lighter, розрахунки в USDC
hyperliquid:perp:AAPLUSDC.XYZ акція Apple на деці xyz Hyperliquid (ринок HIP-3); дані є не в усіх маршрутів
  • venue — біржа малими літерами: binance, bybit, okx, bitget, gate, mexc, bingx, kucoin, hyperliquid, aster, lighter, kraken, coinbase, upbit та інші. Яка біржа є для якого виду даних, різне: повний список — /v1/instruments.
  • market — spot або perp. Ім’я з future або option розбирається, але даних по них немає: такий запит отримує 400 unsupported_instrument.
  • SYMBOL — база і котирування разом, великими: BTCUSDT, ETHUSDC. Винятки — Hyperliquid і Coinbase, як у таблиці.

Неправильна форма імені — 400 bad_instrument. Ім’я правильне, але маршрут не знає такий ринок або біржу — 400 unsupported_instrument з param: "instrument". Символ звіряють лише /v1/candles і /v1/series, і то не завжди: пара, якої в джерела немає, може отримати там 400 unsupported_instrument з param: "symbol", а при збої джерела — порожній 200. На решті маршрутів символ з реєстром не звіряється: пара й друкарська помилка, ім’я яких пройшло перевірку біржі, ринку та котирування, отримують 200 без рядків. Перевіряйте ім’я за реєстром, умови відмови та винятки — на сторінці помилок.

Час

  • Час скрізь — Unix-мілісекунди UTC, цілим числом: 1793750400000 — 4 листопада 2026, 00:00 UTC.
  • Вікно запиту — напіввідкрите [from, to): from входить, to — ні. Так сусідні вікна стикуються без повторів.
  • У кожного маршруту свої усталені значення: свічки без from беруть limit кроків назад від to, угоди — останню годину, відкритий інтерес — останню добу. Без to — «зараз».
  • Крок (tf) пишеться числом із суфіксом: 1s, 30s, 1m, 5m, 1h, 4h, 1d. Які кроки приймає маршрут — у його описі.
Python
from datetime import datetime, timezone

t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000)  # 1793750400000

Відповідь — таблиця колонками

Ряди приходять не масивом об’єктів, а таблицею: імена колонок один раз, рядки — масивами значень у тому самому порядку. Так відповідь коротша в кілька разів.

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "columns": ["ts", "open", "high", "low", "close"],
  "rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3]],
  "next_cursor": null
}

Перетворити на звичні об’єкти — один рядок:

JavaScript
const records = body.rows.map((r) => Object.fromEntries(body.columns.map((c, i) => [c, r[i]])));

Полів у відповіді може стати більше — не покладайтеся на їхній порядок і не падайте на незнайомому полі. Порядок колонок усередині таблиці задає columns.

Сторінки

Якщо відповідь не вмістилася в одну сторінку, у ній є next_cursor. Передайте його як cursor= з тими самими рештою параметрів — отримаєте наступну сторінку. next_cursor: null — сторінок більше немає.

Python
import os, requests

URL = "https://market-api.lootx.trade/v1/trades"
HEAD = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
params = {"instrument": "binance:perp:BTCUSDT", "from": 1793750400000, "to": 1793754000000}

rows = []
while True:
    page = requests.get(URL, params=params, headers=HEAD, timeout=30).json()
    rows += page["rows"]
    if not page.get("next_cursor"):
        break
    params["cursor"] = page["next_cursor"]
  • Курсор — непрозорий рядок: усередині лише позиція продовження. Шлюз не звіряє решту параметрів із тими, що були в першої сторінки: з іншими параметрами сторінка побудується за ними з цієї позиції. Тому передавайте курсор із тими самими instrument, tf, to, limit та іншим. 400 bad_cursor — лише якщо курсор пошкоджений.
  • Свічки ріжуться на сторінки по сітці кроку, а в угод записи однієї мілісекунди цілком ідуть на одну сторінку: повторів і пропусків на стику немає.
  • Напрямок у більшості маршрутів — від старого до нового. Виняток: історія щільностей гортається від свіжих до старих.
  • У будь-якому форматі наступна сторінка є і в заголовках: X-Next-Cursor — курсор, Link — готова адреса наступної сторінки (RFC 8288). У CSV курсор є лише в заголовку, у protobuf — ще й у полі next_cursor (формати).
HTTP
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMA

Адреса в Link — той самий запит із новим cursor: можна йти за нею, нічого не збираючи. Остання сторінка заголовків Link і X-Next-Cursor не несе.

Заголовки, які варто логувати

Заголовок Навіщо
X-Request-Id номер запиту; той самий, що request_id у тілі помилки. Надішліть його в підтримку
X-RateLimit-Remaining скільки запитів залишилося в найтіснішому ліміті — докладно
X-Cache є лише у відповідей, які шлюз може кешувати (закриті діапазони): HIT — з пам’яті шлюзу, MISS — від джерела. Закриті діапазони шлюз пам’ятає до 10 хвилин. У решти відповідей заголовка немає
RateLimit залишок і секунди до скидання за всіма вікнами тарифу — докладно

X-Request-Id шлюз ставить сам на кожну відповідь; це і є номер, за яким ми знайдемо запит.

Стиснення

Відповіді стискаються, якщо клієнт про це просить: Accept-Encoding: gzip або br. curl просить із --compressed, requests і браузер — самі. Бінарник теплової карти (HMP1/HMP2) не стискається — він і так щільний.

Добовий обсяг тарифу рахується за тілом до стиснення: запит коштує однаково зі стисненням і без, а стиснення економить лише час і трафік.

https://docs.lootx.trade/uk/market-api/conventions

Начало работы

3SDK для 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/uk/market-api/sdk

Справочник

4Інструменти та стан

Які є інструменти та в яких видах даних — реєстр /v1/instruments; чи здорові джерела — /v1/status.

Група тарифу — instruments. Почніть із реєстру: він показує, як називається інструмент і в яких маршрутах по ньому є дані.

Реєстр інструментів

GET/v1/instruments

Усі інструменти всіх джерел з одним канонічним ім’ям. Колонка sources — де він є: candles, footprint, densities, screener.

Параметр Що
venue біржа: binance, okx, …
market spot або perp. Датованих ф’ючерсів та опціонів поки немає
source тільки інструменти з даними в цьому виді: candles, footprint, densities, screener
q підрядок символа, без урахування регістру: q=btc
limit рядків на сторінку, 1–10 000, за замовчуванням 1000
cursor курсор із next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/instruments?venue=binance&market=perp&q=BTC" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "columns": ["instrument", "venue", "market", "symbol", "sources"],
  "rows": [
    ["binance:perp:BTCUSDT", "binance", "perp", "BTCUSDT", ["candles", "footprint", "densities", "screener"]],
    ["binance:perp:BTCUSDC", "binance", "perp", "BTCUSDC", ["candles", "footprint", "densities"]]
  ],
  "next_cursor": null,
  "updated_at": 1793750400000
}

updated_at — коли шлюз востаннє отримав список хоча б від одного джерела, 0 — ще жодного разу. Реєстр оновлюється раз на 5 хвилин і показує те, що джерела збирають прямо зараз, а не всі лістинги бірж. Нова пара з’явиться, коли її почне збирати джерело; у частини джерел це відбувається після порога добового обороту.

Стан джерел

GET/v1/status

Чи відповідають джерела даних за шлюзом і з якою затримкою. Зручно для власного моніторингу: якщо ok: false, помилки 502/504 по маршрутах цього джерела очікувані.

JSON
{
  "ok": true,
  "ts": 1793750400000,
  "upstreams": [
    { "name": "data", "ok": true, "latency_ms": 12, "http_status": 200 },
    { "name": "clusters", "ok": true, "latency_ms": 18, "http_status": 200 }
  ]
}

У /v1/status немає таблиці, тому немає й CSV — тільки JSON і protobuf. Маршрут не входить до жодної групи тарифу і витрачає тільки загальні ліміти.

https://docs.lootx.trade/uk/market-api/instruments

Справочник

5Свічки та ряди

Свічки з будь-яким кроком від секунди до доби та ряди потоку угод — CVD, дельта, об'єм, кількість угод.

Свічки

GET/v1/candles

Свічки OHLCV з об’ємом покупок окремо. Крок — будь-яке число із суфіксом s, m, h, d, до доби: 1s, 15s, 1m, 5m, 1h, 4h, 1d.

Параметр Що
instrument обов’язковий, venue:market:SYMBOL
tf крок свічки, за замовчуванням 1m
from початок вікна, мс, включно. За замовчуванням to − limit × tf
to кінець вікна, мс, не включно. За замовчуванням — зараз
limit свічок на сторінку, 1–10 000, за замовчуванням 1000
fill чи заповнювати порожні інтервали пласкими свічками, за замовчуванням true
cursor курсор з next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=5m&from=1793750400000&limit=2" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "5m",
  "columns": ["ts", "open", "high", "low", "close", "volume", "quote_volume",
              "buy_volume", "buy_quote_volume", "trades", "buy_trades"],
  "rows": [
    [1793750400000, 104250.5, 104301.2, 104190.0, 104288.7, 182.43, 19021884.31, 97.12, 10127740.05, 8410, 4522],
    [1793750700000, 104288.7, 104322.0, 104260.4, 104270.1, 133.06, 13878523.60, 61.88, 6454361.73, 6128, 2930]
  ],
  "next_cursor": "YzE6MTc5Mzc1MTAwMDAwMA",
  "coverage": { "oldest": 1792741800000, "newest": 1793754000000 }
}
Колонка Що
ts початок свічки, мс UTC
open, high, low, close ціни у валюті котирування
volume, buy_volume весь об’єм і об’єм покупок агресором, у монетах (у каналі candles потоку поле volume інше — у валюті котирування)
quote_volume, buy_quote_volume те саме у валюті котирування — гроші, без округлення до кроку ціни
trades, buy_trades кількість угод, всього та покупок

Продажі — volume − buy_volume, якщо сторону відомо у всіх угод свічки. У частини бірж сторону угоди видно не завжди; такі угоди входять у volume, але не в buy_volume, і віднімання зарахує їх у продажі. Окремої колонки для них у відповіді немає.

coverage — який період взагалі є у сховищі за інструментом: запитавши раніше oldest, ви отримаєте порожню сторінку, а не помилку.

Символ, якого немає у джерел, може отримати 400 unsupported_instrument з param: "symbol", а може й порожній 200: умови. Те саме у /v1/series.

Секундні свічки

Крок менше хвилини — окрема група тарифу candles_1s. Тариф може закрити її (403 route_not_in_plan), обмежити своїм лімітом запитів або своєю глибиною історії — все це діє разом із загальними лімітами. Хвилинні та більші свічки — група candles.

Ряди потоку угод

GET/v1/series

Один ряд t, value за кроками: накопичена дельта, дельта кроку, об’єм або кількість угод. Група тарифу — series.

Параметр Що
instrument обов’язковий
metric обов’язковий: cvd — накопичена дельта від початку вікна from; delta — покупки мінус продажі агресором за крок; volume; trades_n — кількість угод
unit quote (за замовчуванням, у валюті котирування) або base (монети). У trades_n не передавайте
tf крок, за замовчуванням 1m. Менше хвилини — секундна історія тарифу
from, to, limit, cursor як у свічок; limit до 10 000, за замовчуванням 1000
Shell
curl -s "https://market-api.lootx.trade/v1/series?instrument=binance:perp:BTCUSDT&metric=cvd&tf=1m&from=1793750400000&limit=3" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "metric": "cvd",
  "unit": "quote",
  "tf": "1m",
  "columns": ["t", "value"],
  "rows": [[1793750400000, 214877.31], [1793750460000, -51260.04], [1793750520000, -1830.66]],
  "next_cursor": "eyJ0IjoxNzkzNzUwNTgwMDAwfQ"
}

https://docs.lootx.trade/uk/market-api/candles

Справочник

6Футпринт і дельта

Кластери — обсяг покупок і продажів на кожному рівні ціни за вікнами; дельта агресора за вікнами з екстремумами всередині вікна; відкриття й закриття позицій за рівнями ціни Hyperliquid.

Футпринт

GET/v1/footprint

Кластери: для кожного вікна часу — обсяг по рівням ціни, окремо угоди по біду й по аску. Група тарифу — footprint.

Параметр Що
instrument обов’язковий
tf вікно кластера: 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. За замовчуванням 1m
from початок, мс. За замовчуванням — 60 вікон назад від to
to кінець, мс, не включно
cursor курсор із next_cursor

В відповіді дві таблиці: levels — рівні ціни, windows — самі вікна.

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "windows": {
    "columns": ["ts", "open", "high", "low", "close", "closed"],
    "rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3, true]]
  },
  "levels": {
    "columns": ["ts", "price", "bid_qty", "ask_qty", "trades", "trades_buy", "trades_sell"],
    "rows": [
      [1793750400000, 104250.5, 1.204, 0.832, 41, 23, 18],
      [1793750400000, 104250.6, 0.317, 2.115, 37, 12, 25]
    ]
  },
  "next_cursor": null
}
  • ts у рівня — початок вікна, якому він належить;
  • bid_qty — обсяг, де агресор купував, ask_qty — де агресор продав, у монетах. Імена — за стороною агресора, а не за стороною біржового стакана, у яку припала угода: перевіряйте це, якщо переносите розрахунки з іншої платформи;
  • trades_buy, trades_sell — скільки з trades угод купив і продав агресор, ті ж сторони, що й у bid_qty та ask_qty; коли відомі, trades_buy + trades_sell = trades. null у обох — розбивки немає: історія до того, як сторони почали зберігатися, або вікно 5m…1d, до якого потрапила така хвилина. Це не «жодної покупки». Колонки стоять у кінці рядка, перші п’ять — на звичних місцях;
  • closed: true — вікно закрите й більше не зміниться. Останнє вікно у «зараз» може прийти з closed: false і дорости.

Вікон на сторінку — до 2000. CSV — одна таблиця, тому для футпринта оберіть її: ?format=csv&table=levels або table=windows.

Дельта

GET/v1/delta

Дельта агресора за вікнами: покупки, продажі, їхня різниця й екстремуми рухомої дельти всередині вікна — у монетах і в грошах. Група тарифу — delta.

Параметр Що
instrument обов’язковий
tf вікно: 1s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. За замовчуванням 1m
from початок, мс; вирівнюється вниз по вікну. За замовчуванням — limit вікон назад від to
to кінець, мс, не включно
limit вікон на сторінку, 1–10 000, за замовчуванням 1000
cursor курсор із next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/delta?instrument=binance:perp:BTCUSDT&tf=5m&limit=1" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "5m",
  "columns": ["t", "buy", "sell", "delta", "delta_min", "delta_max", "trades",
              "buy_quote", "sell_quote", "delta_quote", "delta_quote_min", "delta_quote_max",
              "close", "closed"],
  "rows": [[1793750400000, 97.12, 85.31, 11.81, -4.06, 15.27, 8410,
            10127740.0512, 8894144.2587, 1233595.7925, -423187.164, 1592311.0033,
            104288.7, true]],
  "next_cursor": null
}
Колонка Що
t початок вікна, мс
buy, sell, delta покупки, продажі агресором і їхня різниця, монети
delta_min, delta_max мінімум і максимум рухомої дельти всередині вікна, монети
buy_quote … delta_quote_max те саме в грошах (валюта котирування); точність — 0,0001, без округлення до кроку ціни
close ціна закриття вікна
closed вікно закрите

Вікна без жодної угоди не надходять: пропуск у часі — це тиша на ринку, а не втрата даних.

Відкриття та закриття позицій Hyperliquid

GET/v1/hyperliquid/footprint

Футпринт NL/NS: на кожному рівні ціни Hyperliquid — наскільки зросли або скоротилися лонги і шорти, окремо у тейкера і у мейкера. Рахується за заливками ноди Hyperliquid: по позиції учасника до кожної заливки. Група тарифу — footprint.

Параметр Що
instrument обов’язковий, перп Hyperliquid: hyperliquid:perp:BTC, ринок HIP-3 — hyperliquid:perp:AAPLUSDC.XYZ або коротше hyperliquid:perp:AAPL.XYZ. Інша біржа або спот — 400 unsupported_instrument
tf вікно: 1m, 5m, 15m, 30m, 1h, 4h, 1d. За замовчуванням 1m. Секунд немає: інший крок — 400 bad_request з param: "tf"
from початок, мс; вирівнюється вниз по вікну. За замовчуванням — 60 вікон назад від to
to кінець, мс, не включно
cursor курсор із next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/hyperliquid/footprint?instrument=hyperliquid:perp:BTC&tf=1m&from=1794500100000&to=1794500220000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "hyperliquid:perp:BTC",
  "tf": "1m",
  "levels": {
    "columns": ["ts", "price", "dl_taker", "ds_taker", "dl_maker", "ds_maker", "n_fills"],
    "rows": [
      [1794500100000, 68960.5, 0.001, 0.0, 0.0, 0.001, 4],
      [1794500100000, 68961.0, -0.0005, 0.0003, 0.0008, 0.0, 2],
      [1794500160000, 68960.0, 0.0, -0.0002, -0.0001, 0.0001, 2]
    ],
    "next_cursor": null
  },
  "windows": {
    "columns": ["ts", "closed"],
    "rows": [[1794500100000, true], [1794500160000, false]],
    "next_cursor": null
  },
  "asof_ms": 1794500205000,
  "next_cursor": null
}
Колонка Що
ts початок вікна, мс
price рівень ціни
dl_taker, ds_taker зміна лонгів і шортів тейкерів на рівні, у монетах: плюс — відкрили, мінус — закрили
dl_maker, ds_maker те саме у мейкерів
n_fills скільки заливок на рівні; заливка — половина угоди, одна сторона матчу

Три види NL/NS збираються з чотирьох колонок: по всіх учасниках — dl_taker + dl_maker, і це ж ds_taker + ds_maker — зміна відкритого інтересу на рівні; у тейкерів — dl_taker і ds_taker; у мейкерів — dl_maker і ds_maker. Грошей у відповіді немає: ціна й кількість — в одиницях інструмента.

  • windows — вікна з closed: true — вікно закрите й більше не зміниться, у «зараз» може прийти false. asof_ms — до якого моменту джерело записало повні хвилини.
  • instrument у відповіді — канонічне ім’я монети, а не написання запиту: на hyperliquid:perp:aapl.xyz прийде hyperliquid:perp:AAPLUSDC.XYZ, на hyperliquid:perp:BTCUSDC — hyperliquid:perp:BTC.
  • Ім’я шлюзу перевіряє тільки за формою — латинські букви й цифри, до 32 знаків, у ринку HIP-3 дек через крапку. Чи є така монета на Hyperliquid, він не звіряє.
  • Вікон на сторінку — до 2000, далі — next_cursor. Одне вікно довше стелі рядків джерела — 413 too_large, візьміть tf менший.
  • Сум по майданчиках немає: instruments= з двома й більше інструментами — 400 bad_request.

https://docs.lootx.trade/uk/market-api/order-flow

Справочник

7Угоди

Стрічки угод від порога розміру — гарячий шар за останні дні та безстроковий архів угод від $5000 з 11.09.2026.

GET/v1/trades

Угоди по одній, з ціною, обсягом, сумою та стороною агресора. Група тарифу — trades.

Параметр Що
instrument обов’язковий
from початок, мс, включно. За замовчуванням — година тому від to
to кінець, мс, не включно
limit угод на сторінку, 1–50 000, за замовчуванням 10 000
min_usd поріг угоди в доларах (ціна × обсяг), включно: min_usd=5000 — лише від $5000
source шар зберігання: auto (за замовчуванням: свіжі дні — гарячий, старші — архів), hot, archive
cursor курсор з next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/trades?instrument=binance:perp:BTCUSDT&min_usd=100000&limit=2" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "source": "hot",
  "source_min_usd": 0,
  "min_usd": 100000,
  "columns": ["t", "price", "qty", "quote_qty", "side", "aggregated", "fills", "trade_id", "seq"],
  "rows": [
    [1793750412318, 104251.2, 1.25, 130314.0, "buy", true, 4, 6213554801, 18822107],
    [1793750431906, 104247.9, 2.004, 208912.7916, "sell", false, 1, 6213555367, 18822345]
  ],
  "next_cursor": "eyJ0IjoxNzkzNzUwNDMxOTA3fQ"
}
Колонка Що
t час угоди, мс
price ціна у валюті котирування
qty обсяг у монетах
quote_qty сума угоди у валюті котирування, точністю 0,0001 — не округлюється до кроку ціни
side сторона агресора: buy — купував, sell — продавав
aggregated, fills true — кілька виконань однієї заявки склеєно в одну угоду; fills — скільки їх
trade_id, seq trade_id — номер угоди в біржі (0, якщо біржа його не дає); seq — номер угоди в межах однієї мілісекунди, заповнений лише при trade_id = 0, інакше 0

Гортання — за часом, без повторів: якщо сторінку обрізано посеред мілісекунди, угоди цієї мілісекунди цілком переходять на наступну.

https://docs.lootx.trade/uk/market-api/trades

Справочник

8Тепловая карта стакана

Объём лимитных заявок в каждой ячейке цены в каждой колонке времени — таблицей или компактным бинарём HMP1/HMP2; полосы книги — сколько долларов стоит в стакане до ±0,1…±10 % от середины.

GET/v1/heatmap

Тепловая карта стакана: объём бидов и асков в ячейках цены по колонкам времени. Группа тарифа — heatmap; тариф часто задаёт ей свои, более строгие лимиты.

Параметр Что
instrument обязательный
from начало, мс. По умолчанию — час назад от to
to конец, мс, не включительно. По умолчанию — сейчас
tf шаг колонки, кратный секунде: 1s, 5s, 1m, … По умолчанию — самый мелкий, при котором окно влезает в 4096 колонок. Если окно начинается раньше, чем сутки назад, отдаётся минутная свёртка: шаг округлится вверх до минуты
price_step высота ячейки в единицах цены: 10 — ячейки по $10 у BTCUSDT. Округляется вверх до сетки хранения; итоговый шаг — в price_step ответа. Без данных книги в минуте перед to возможен 400 bad_request: условие
agg avg (по умолчанию) — средний объём за колонку, max — максимум
price_from, price_to ценовое окно, только парой. Без него — ±20 % от середины книги
format json, protobuf, csv — таблица; hmp1, hmp2 — бинарь
qbits, layout только для format=hmp2
cursor курсор из next_cursor, если источник обрезал ответ по объёму
Shell
curl -s "https://market-api.lootx.trade/v1/heatmap?instrument=binance:perp:BTCUSDT&tf=1m&price_step=10&from=1793750400000&to=1793754000000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"

Таблица содержит только ненулевые ячейки — строку на каждую пару «колонка времени × уровень цены», где объём был:

JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "from": 1793750400000,
  "to": 1793754000000,
  "time_step_ms": 60000,
  "price_step": 10,
  "agg": "avg",
  "price_from": null,
  "price_to": null,
  "frames": 60,
  "columns": ["t", "side", "price", "qty"],
  "rows": [
    [1793750400000, "bid", 104240, 18.402],
    [1793750400000, "ask", 104260, 9.117]
  ],
  "next_cursor": null
}
  • price — нижняя граница ячейки: ячейка — это [price, price + price_step);
  • qty — объём в монетах, средний (agg=avg) или максимальный за колонку;
  • frames — сколько колонок времени в ответе; from выровнен наружу по шагу.

Пределы

  • До 4096 колонок и 500 000 ячеек в таблице. Больше — 413 too_large: сузьте окно, укрупните tf или price_step либо возьмите бинарь.
  • История книг у Binance длиннее; у остальных бирж стакан пишется с 30.10.2026 — раньше этой даты по ним ответ пустой, а с price_step может прийти 400, условие ниже.
  • price_step переводится в сетку хранения по данным самой книги: шлюз запрашивает минуту перед to, границы выравниваются наружу по минутной сетке. Данных в этой минуте нет — 400 bad_request, запрашивайте без price_step. Решает окно, а не статус инструмента: торгуемый инструмент с to раньше начала истории книг получит 400, снятый с торгов с данными в этой минуте — 200. Удачный перевод шлюз помнит до часа, независимо от ключа, и теряет его при перезапуске: пока он помнит, минута перед to не проверяется, и запрос без данных получит 200 с пустым ответом.
  • Бинарь hmp1/hmp2 во много раз короче таблицы, идёт потоком и кэшируется — для отрисовки берите его. Разбор — Формат HMP1 и HMP2.
  • Закрытые диапазоны бинаря отдаются с ETag и долгим Cache-Control: повторный запрос с If-None-Match получает 304 без тела и не расходует суточный объём.

Полосы книги

GET/v1/book/bands

Сколько долларов стоит в стакане в пределах ±0,1 … ±10 % от середины книги, а с bands=deep — ещё ±3, ±8, ±15 % и вся сторона — по окнам времени. Группа тарифа та же, что у тепловой карты, — heatmap.

Параметр Что
instrument обязательный
tf окно: 1s, 5s, 10s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. По умолчанию 1m. Другие — 400 bad_request с param: "tf"
from начало, мс; выравнивается вниз по окну. По умолчанию — 60 окон назад от to
to конец, мс, не включительно; выравнивается вверх по окну
bands набор полос: без параметра — семь полос до ±10 %, deep — одиннадцать, до всей стороны (глубокие полосы). Другие значения — 400 bad_request с param: "bands"

Полоса — уровень книги, а не поток: значение окна — последний срез в окне, а не сумма за окно. Поэтому окна только из списка: 45s из минут не собрать.

Shell
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&from=1794500160000&to=1794500220000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "columns": ["ts", "sample_ms", "best_bid", "best_ask", "mid",
              "bid_bp10_e8", "bid_bp25_e8", "bid_bp50_e8", "bid_bp100_e8", "bid_bp200_e8", "bid_bp500_e8", "bid_bp1000_e8",
              "ask_bp10_e8", "ask_bp25_e8", "ask_bp50_e8", "ask_bp100_e8", "ask_bp200_e8", "ask_bp500_e8", "ask_bp1000_e8",
              "reach_bid_bp", "reach_ask_bp", "complete_bid", "complete_ask", "closed"],
  "rows": [
    [1794500160000, 1794500219950, 68961.0, 68961.1, 68961.05,
     "51234500000000", "98765400000000", "150000000000000", "310000000000000", "640000000000000", "1500000000000000", "2900000000000000",
     "48765400000000", "91234500000000", "140000000000000", "300000000000000", "620000000000000", "1450000000000000", "2800000000000000",
     1000, 213, 7, 5, true]
  ],
  "next_cursor": null,
  "bands_bp": [10, 25, 50, 100, 200, 500, 1000],
  "units_revision": 1,
  "source": "book_bands_1m",
  "asof_ms": 1794500325000
}
Колонка Что
ts начало окна, мс
sample_ms момент среза книги, которым представлено окно, мс
best_bid, best_ask, mid лучшие цены и середина книги в этом срезе
bid_bp…_e8 биды от середины книги вниз до −0,1 %, −0,25 %, −0,5 %, −1 %, −2 %, −5 % и −10 %: число в имени — граница в базисных пунктах
ask_bp…_e8 аски от середины вверх до тех же границ
reach_bid_bp, reach_ask_bp самая широкая граница, в базисных пунктах, все цены до которой книга знала
complete_bid, complete_ask сколько первых полос полны: полоса номер k по порядку bands_bp, с нуля, полна, если k < complete
closed окно закрыто и больше не изменится

Деньги полос — в e8 USD строкой: "51234500000000" — это 512 345 $, делите целое на 10⁸. Строкой — потому что у книг крупных монет число больше 2⁵³ и в double потеряло бы знаки: читайте его как целое 64 бита или десятичное. Шаг цены инструмента к этим суммам не относится. Полосы нарастающие: bp25 включает bp10. В примере у асков полны первые пять полос, до ±2 %, а ask_bp500_e8 и ask_bp1000_e8 неполны: книга знала аски только до 2,13 % от середины.

  • Окно без среза книги не приходит строкой: пропуск — это дыра в данных, а не нули.
  • Секундные окна (1s … 30s) есть не у всех инструментов и только за последние 7 суток, у остальных ответ пустой. Минутные и крупнее — у книг с долларовой котировкой, без срока. Таблица источника — в поле source: book_bands_1s или book_bands_1m.
  • asof_ms — до какого момента склад источника полон: окна раньше него не изменятся. units_revision — ревизия единиц источника, сейчас 1 (e8 USD).
  • Окон в запросе — до 20 000, больше — 413 too_large: сузьте окно или возьмите tf крупнее. Курсора нет, next_cursor всегда null.
  • Суммы площадок нет: полоса каждой биржи отсчитана от её середины книги и снята в свой момент. instruments= с двумя и больше инструментами — 400 bad_request: запрашивайте каждую биржу своим instrument и складывайте e8-строки сами.
  • Символ с реестром шлюз не сверяет.

Глубокие полосы

bands=deep — одиннадцать полос вместо семи: bands_bp — [10, 25, 50, 100, 200, 300, 500, 800, 1000, 1500, 10000], в ответе 32 колонки. К прежним границам добавлены ±3 %, ±8 %, ±15 % и 10000 — вся сторона: биды до нуля, аски до двух mid. Колонки идут в том же порядке, что bands_bp: bid_bp10_e8 … bid_bp10000_e8, затем ask_bp10_e8 … ask_bp10000_e8; голова и хвост строки — как без параметра.

Shell
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&bands=deep&from=1794500160000&to=1794500220000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
  • null в полосе — «неизвестно», а не 0. Так приходят глубокие полосы у строк, записанных до того, как их начали считать, и вся сторона, если книга её не знала целиком.
  • complete_* — до 11 и считается до первой неизвестной полосы: у старых строк — не больше 5.
  • Полосу берите по bands_bp, а не по номеру колонки: номера в двух наборах разные — bid_bp500_e8 шестая в обычном ответе и седьмая в глубоком.
  • Вес и группа тарифа — те же, что без параметра.

https://docs.lootx.trade/uk/market-api/heatmap

Справочник

9Відкритий інтерес і ставка фінансування

Хвилинні бари відкритого інтересу в доларах, монетах або рідній одиниці біржі; ставка фінансування по хвилинах і самі нарахування; long/short ratio по 5‑хвилинним бакетам; mark і index по секундах і хвилинах.

Тільки безстрокові контракти: market = perp. Біржі: binance, bybit, okx, bitget, gate, mexc, bingx, kucoin, hyperliquid, aster, kraken, coinbase. У long/short і mark і index свої набори бірж — вони названі в розділах.

Відкритий інтерес

GET/v1/oi

Хвилинні бари відкритого інтересу: відкриття, максимум, мінімум і закриття хвилини. Група тарифу — oi.

Параметр Що
instrument обов’язковий, тільки перпи
from початок, мс. За замовчуванням — добу назад від to
to кінець, мс, не включно
unit usd (за замовчуванням), coins або native — як у біржі: монети, контракти або долари
cursor курсор з next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/oi?instrument=bybit:perp:ETHUSDT&unit=usd&from=1793750400000&to=1793750520000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "bybit:perp:ETHUSDT",
  "tf": "1m",
  "columns": ["ts", "open", "high", "low", "close"],
  "rows": [
    [1793750400000, 1843204551.12, 1843990120.4, 1842871003.57, 1843511876.03],
    [1793750460000, 1843511876.03, 1844102233.9, 1843300418.65, 1843877021.18]
  ],
  "next_cursor": null
}

ts — початок хвилини. Сторінка — до тижня хвилин; довгий період перегортайте курсором.

Ставка фінансування

GET/v1/funding

Ставка фінансування, як біржа показувала її кожну хвилину, з часом наступного нарахування там, де біржа його повідомляє (у Hyperliquid, MEXC, Kraken і Coinbase next_funding_ts — null). Група тарифу — funding.

Параметр Що
instrument обов’язковий
from, to, cursor вікно і курсор
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "columns": ["ts", "rate", "next_funding_ts", "interval_hours"],
  "rows": [[1793750400000, 0.0001, 1793779200000, 8]],
  "next_cursor": null
}
  • rate — частка за період виплати біржі: 0.0001 — це 0,01 % за 8 годин;
  • interval_hours — період виплати, як його повідомляє джерело.

Нарахування ставки фінансування

GET/v1/funding/events

Самі моменти розрахунку: яка ставка застосувалася і за якою маркувальною ціною (mark). Та сама група funding.

Параметр Що
instrument обов’язковий, тільки перпи
from початок, мс. За замовчуванням — 30 діб назад від to
to кінець, мс, не включно
cursor курсор з next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/funding/events?instrument=binance:perp:BTCUSDT" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "columns": ["t", "rate", "mark_price"],
  "rows": [
    [1793721600000, 0.00009249, null],
    [1793721600006, 0.00009208, 104012.4],
    [1793750400000, 0.000072, 104250.5]
  ],
  "next_cursor": null
}

mark_price заповнюється тільки у Binance, у інших бірж вона null; у Binance null стоїть і в повторному рядку нарахування (див. вище). Для розрахунку своїх платежів множте ставку на номінал позиції в момент нарахування: суми не округлюються до кроку ціни ні у нас, ні у ваших розрахунках.

Long/Short ratio

GET/v1/ls-ratio

Співвідношення лонгів і шортів та об’єм тейкера по 5‑хвилинним бакетам — як їх публікує біржа. Група тарифу — ls_ratio.

Параметр Що
instrument обов’язковий, тільки перпи. Ряди є у binance (global_account, top_account, top_position, taker_volume), bybit (global_account) і okx (ті самі чотири і global_account_ccy); у інших бірж відкритого інтересу відповідь порожня
kind вид ряду: global_account, top_account, top_position, taker_volume, global_account_ccy. За замовчуванням — всі. Інший — 400 bad_request з param: "kind"
from початок, мс, по ts. За замовчуванням — добу назад від to
to кінець, мс, не включно
cursor курсор з next_cursor

Відношення майданчиків не складаються: instruments= з двома і більше інструментами — 400 bad_request, запитуйте кожну біржу своїм instrument.

Shell
curl -s "https://market-api.lootx.trade/v1/ls-ratio?instrument=binance:perp:BTCUSDT&from=1793278200000&to=1793278500000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "5m",
  "columns": ["ts", "as_of", "kind", "long_ratio", "short_ratio", "long_short_ratio", "buy_vol", "sell_vol", "unit"],
  "rows": [
    [1793278200000, 1793278200000, "global_account", 0.6849, 0.3151, 2.1736, null, null, null],
    [1793278200000, 1793278500000, "taker_volume", null, null, 1.1138, "82.8880", "74.4160", "base"],
    [1793278200000, 1793278200000, "top_account", 0.6982, 0.3018, 2.3135, null, null, null],
    [1793278200000, 1793278200000, "top_position", 0.6774, 0.3226, 2.0995, null, null, null]
  ],
  "next_cursor": null
}
Колонка Що
ts бакет біржі (bucket_ts), мс. Рядки йдуть за ts, всередині — за kind
as_of момент, до якого відноситься значення, мс. У global_account, top_account, top_position Binance і у global_account Bybit — ts: це знімок на відмітці. У taker_volume Binance та у всіх видів OKX — ts + 5 хвилин: значення за період [ts, ts + 5 хв). У інших пар — ts. Ряди різних бірж і видів зводьте за as_of
long_ratio, short_ratio частки лонгів і шортів, безрозмірні: 0.6849 — 68,49 %
long_short_ratio відношення лонгів до шортів, у taker_volume — покупок тейкера до продажів
buy_vol, sell_vol об’єм покупок і продажів тейкера за бакет — рядком, точний десятковий запис біржі, в одиниці unit. Тільки у taker_volume
unit одиниця buy_vol і sell_vol: base — монети. У інших видів — null

Чого біржа не публікує, те null: у OKX, наприклад, приходить лише long_short_ratio, без часток. Останній бакет біржа дописує і після його закінчення: перечитуйте останні ~10 хвилин. Вікно довше тижня шлюз обрізає і віддає next_cursor; сторінка — до 10 000 рядків, і рядки одного ts повністю потрапляють на одну сторінку.

GET/v1/ls-ratio/latest

Останній рядок кожного виду — або тільки виду kind — за 35 діб. Та сама група ls_ratio, ті самі колонки, next_cursor — null.

Параметр Що
instrument обов’язковий, тільки перпи
kind вид ряду, як у /v1/ls-ratio. За замовчуванням — всі
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "5m",
  "columns": ["ts", "as_of", "kind", "long_ratio", "short_ratio", "long_short_ratio", "buy_vol", "sell_vol", "unit"],
  "rows": [
    [1793279100000, 1793279100000, "global_account", 0.684, 0.316, 2.1646, null, null, null],
    [1793278800000, 1793279100000, "taker_volume", null, null, 2.9092, "786.2880", "270.2730", "base"],
    [1793279100000, 1793279100000, "top_account", 0.6978, 0.3022, 2.3091, null, null, null],
    [1793279100000, 1793279100000, "top_position", 0.6779, 0.3221, 2.1047, null, null, null]
  ],
  "next_cursor": null
}

У кожного виду свій останній рядок, і ts у них може відрізнятись, як у taker_volume в прикладі. Жодного рядка за 35 діб — 404 not_found; ряд, що замовк раніше, читайте через /v1/ls-ratio з вікном.

Mark і index

GET/v1/mark

Маркувальна ціна (mark) і індексна ціна (index) перпа по секундах або хвилинах. Група тарифу залежить від кроку: tf=1m — mark, tf=1s — mark_1s.

Параметр Що
instrument обов’язковий, тільки перпи: binance, bybit, okx, bitget, gate, hyperliquid, mexc, kraken, lighter, aster. Інша біржа — 400 unsupported_instrument
tf 1s — секунди, зберігаються 7 діб; 1m — хвилини, без терміну зберігання. За замовчуванням 1m. Інший крок — 400 bad_request з param: "tf": крупніше хвилини згортайте 1m самі
from початок, мс, по ts. За замовчуванням — добу назад від to, у 1s — година
to кінець, мс, не включно. За замовчуванням — зараз; to у майбутньому шлюз зсуває на «зараз»
cursor курсор з next_cursor
Shell
curl -s "https://market-api.lootx.trade/v1/mark?instrument=binance:perp:BTCUSDT&tf=1m&from=1794531600000&to=1794531720000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1m",
  "columns": ["ts", "mark_open", "mark_high", "mark_low", "mark_close", "index_close", "premium", "secs"],
  "rows": [
    [1794531600000, "71111.39908546", "71137.9", "71045.18452774", "71045.18452774", "71084.41304348", -0.0005518581931035318, 60],
    [1794531660000, "71044.18909295", "71044.18909295", "70970.4", "71007.3", "71051.90695652", -0.0006278080129122655, 60]
  ],
  "next_cursor": null
}
Колонка Що
ts початок секунди або хвилини, мс
mark (1s); mark_open, mark_high, mark_low, mark_close (1m) ціна маркування в валюті котирування — рядком, десятковий запис з точністю біржі
index (1s), index_close (1m) індексна ціна, рядком, як mark. Немає у біржі — null. У Hyperliquid це оракульна ціна (oraclePx)
premium mark / index − 1 (у 1m — по закриттю хвилини): безрозмірна частка, число. Без index — null
secs тільки у 1m: скільки секунд хвилина мала значення, 1…60

Ціни приходять рядком, щоб не втратити знаки: тримайте їх рядком або десятковим типом, а не float, і не округляйте до кроку ціни.

  • Секунди без рядка тримають попереднє значення: біржа шле лише зміни. Протягуйте останнє відоме значення.
  • Поточна хвилина в 1m не віддається — малюйте її по секундах.
  • Секунди старші за 7 діб не зберігаються: вікно tf=1s цілком старіше — 400 bad_request з param: "from", частково — from підтягується до краю зберігання.
  • Сторінки. Вікно 1s довше години і вікно 1m довше тижня шлюз обрізає і віддає next_cursor; сторінка — до 10 000 рядків. У живого краю, пізніше ніж 2 хвилини тому, курсора немає: наступний запит починайте з останнього отриманого рядка.

Ціни майданчиків не складаються: instruments= з двома і більше інструментами — 400 bad_request.

GET/v1/mark/latest

Остання секунда mark і index за 7 діб: один рядок з колонками tf=1s. Група тарифу — mark.

Параметр Що
instrument обов’язковий, перп однієї з бірж /v1/mark
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "tf": "1s",
  "columns": ["ts", "mark", "index", "premium"],
  "rows": [[1794534182000, "70906.31457271", "70933.00695652", -0.00037630413477835085]],
  "next_cursor": null
}

Жодної секунди за 7 діб — 404 not_found. Останні ~3 секунди джерело може ще не записати, тому питати частіше, ніж раз на секунду, немає сенсу.

https://docs.lootx.trade/uk/market-api/oi-funding

Справочник

10Щільності та айсберги

Великі лімітні стіни в стакані прямо зараз, історія знятих і з'їдених стін (зберігається не більше 90 днів), айсберги та поглинання.

Щільність — велика лімітна заявка (стіна), помітно більша за звичайний об’єм на сусідніх рівнях. Сервіс щільностей стежить за стаканами бірж і віддає стіни одразу з розміром у доларах, відстанню до ціни та віком.

Живі щільності

GET/v1/densities

Поточний знімок стін: за одним інструментом або зведенням по ринку. Група тарифу — densities.

Параметр Що
instrument один інструмент. Без нього — зведення по ринку з фільтрами нижче
venue біржі через кому: binance,bybit
market ринки через кому: spot, perp
coins монети через кому: BTC,ETH — не символи
side bid або ask
min_usd мінімальний розмір стіни, $
max_dist_bp максимальна відстань до середини стакана, базисні пункти: 200 = ±2 %
limit скільки стін, за замовчуванням 200
sort usd (за замовчуванням), age, dist
Shell
curl -s "https://market-api.lootx.trade/v1/densities?coins=BTC&market=perp&min_usd=1000000&limit=2" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "ts": 1793750400000,
  "columns": ["instrument", "side", "price", "qty", "usd", "dist_bp", "first_ts", "age_ms",
              "peak_usd", "state", "touched", "size", "score", "agg", "wall_id"],
  "rows": [
    ["binance:perp:BTCUSDT", "bid", 103500.0, 41.8, 4326300.0, -72, 1793741112000, 9288000,
     4512000.0, "live", false, "strong", 2.37, "tick", "11658847687750313317"]
  ],
  "next_cursor": null
}
Колонка Що
side bid — купівля, ask — продаж
price, qty, usd ціна, об’єм у монетах і розмір стіни в доларах
dist_bp відстань до середини стакана зі знаком, б. п.: мінус — нижче середини (зазвичай біди), плюс — вище (аски). Фільтр max_dist_bp порівнює модуль
first_ts, age_ms коли стіна з’явилася і скільки вона вже стоїть
peak_usd найбільший розмір стіни за її життя
state live — стоїть без помітних змін, updated — розмір помітно змінився з минулого зрізу
touched за ціною стіни вже проходили угоди, які її їдять
size normal, weak, optimal, strong — ступінь розміру щодо ліквідності пари; normal — щільність є, але нижче слабкої ступені
score міра великості: 1 — поріг optimal, 2 — поріг strong, 0 — не рахувалася
agg tick — стіна на одному рівні, natr — рівні склеєні за волатильністю
wall_id номер стіни рядком: це 64-бітне число, у JavaScript воно не вміщується в number без втрат

Зведення відсортовано за usd, ts — момент знімка. Знімок живий: кешу в щільностей немає, кожен запит — свіжий стан. Для безперервного стеження візьміть канал densities у WebSocket: за списком інструментів або весь ринок з фільтрами. Зміни приходять самі, без опитування; байти кадрів ідуть у добовий об’єм разом з REST.

Історія щільностей

GET/v1/densities/history

Закриті стіни: зняті (pulled) і з’їдені угодами (eaten). Зберігаються не більше 90 днів. Група тарифу — densities_history.

Параметр Що
instrument обов’язковий
from початок за моментом появи стіни, мс. За замовчуванням — доба тому від to
to кінець, мс, не включно
kind pulled, eaten або обидва через кому (за замовчуванням)
limit стін на сторінку, 1–10 000, за замовчуванням 1000
cursor курсор: сторінки йдуть від свіжих до старих
JSON
{
  "instrument": "binance:perp:BTCUSDT",
  "columns": ["t", "side", "kind", "price", "qty_open", "qty_close", "usd_open", "usd_peak",
              "end_ts", "duration_ms", "dist_bp_open", "mid_at_close", "touched", "size"],
  "rows": [
    [1793741112000, "bid", "eaten", 103500.0, 41.8, 0.0, 4326300.0, 4512000.0,
     1793752004000, 10892000, -72, 103498.6, true, "S"]
  ],
  "next_cursor": null
}

t — поява стіни, end_ts — коли її не стало; qty_open/qty_close — об’єм на початку і в кінці, mid_at_close — середина стакана в момент закриття. size в історії — короткий код: "" — без ступеня, W — weak, O — optimal, S — strong.

В історію пишуться стіни стисненого стакана (agg = natr), а не окремих рівнів: ціна і розмір не збігаються зі стінами живого знімка (там за замовчуванням tick), а wall_id в історії немає — пов’язати закриту стіну з живою за номером не можна.

Айсберги та поглинання

GET/v1/icebergs

Приховані заявки, які добиваються по шматочку (iceberg), і рівні, що поглинають ринковий потік (absorption). Група тарифу — icebergs.

Параметр Що
instrument один інструмент. Без нього — по ринку з фільтрами
venue, market, coins, side фільтри, як у щільностей; coins — до 100
kind iceberg, absorption або all (за замовчуванням)
min_usd мінімальний прихований виконаний об’єм, $
state active (за замовчуванням — ті, що йдуть), ended (закінчені) або all
limit 1–5000, за замовчуванням 200

Колонки: instrument, id (рядком — 64-бітне число), side, kind, price, first_ts, last_ts, trades, executed_qty, hidden_qty, visible_max, clip_qty (монети), executed_usd, hidden_usd ($; прихований об’єм — нижня оцінка), refills, end (null — ще йде; інакше idle, broken або reset).

https://docs.lootx.trade/uk/market-api/densities

Справочник

11Скринер

Метрики по сотнях інструментів одним запитом — ціна, зміна, обсяг, ставка фінансування, OI та їх зміни за вікна; довідник усіх метрик.

Знімок скринера

GET/v1/screener

Таблиця «інструмент × метрика» по ринку: остання ціна, зміна за добу, обсяг, ставка фінансування, OI та десятки інших. Група тарифу — screener.

Параметр Що
venue біржі через кому, регістр не важливий, той самий набір, що й у ринкової підписки: Upbit у скринера немає. За замовчуванням — усі. Невідома біржа — 400 bad_request з param: "venue", а не «усі біржі»
market spot, perp через кому, регістр не важливий. Інше значення — 400 bad_request
instruments точний набір інструментів через кому, правила нижче. З ним venue і market не читаються. top_n діє і тут: для набору більше 100 інструментів передайте top_n не менше його розміру, інакше відповідь тихо обріжеться
top_n перші N за добовим обсягом, 1–2000, за замовчуванням 100. 0 і значення більші за 2000 притискаються до межі
names імена колонок: long (за замовчуванням: volume_24h_usd, oi_change_usd_5m, …) або short — короткі ключі (v24, odu5, …). Інше значення — 400 bad_request
Shell
curl -s "https://market-api.lootx.trade/v1/screener?venue=binance&market=perp&top_n=2" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "ts": 1793750400000,
  "columns": ["instrument", "ts", "last_price", "change_24h_pct", "volume_24h_usd", "funding_rate", "open_interest"],
  "rows": [
    ["binance:perp:BTCUSDT", 1793750399870, 104250.5, 1.84, 18234455120.4, 0.0001, 8423311987.2],
    ["binance:perp:ETHUSDT", 1793750399912, 3712.44, -0.62, 9122870411.7, 0.000085, 4120098211.6]
  ],
  "next_cursor": null
}

Приклад скорочено: справжня відповідь несе всі метрики, які джерело знає по інструменту. Метрики, яких в інструмента немає, приходять null.

Набір інструментів

  • Символ з реєстром не порівнюється. Ім’я пройшло перевірки нижче, а інструмента у скринера немає, зокрема через одрук, — рядка по ньому немає, відповідь 200. Жодного не знайшлося — 200 з порожніми rows: звіряйтеся з /v1/instruments.
  • Неправильна форма імені — 400 bad_instrument, весь запит.
  • 400 unsupported_instrument з param: "instrument", весь запит: ринок не spot і не perp; котирування символу не розібрати, як у okx:perp:BTC-USDT-SWAP; перп з котируванням не з USDT, USDC і USD, як у binance:perp:ETHBTC. Перпів Hyperliquid дві останні перевірки не стосуються.
  • Біржа в імені не звіряється: невідома біржа дає не відмову, а відсутність рядка.
  • У скринера деки немає: рядок один на всі деки монети, і у відповіді він називається без деки. hyperliquid:perp:AAPLUSDC.XYZ і hyperliquid:perp:AAPLUSDC — один рядок hyperliquid:perp:AAPLUSDC.
  • Порожнє значення instruments= — те саме, що без параметра: весь ринок з урахуванням venue і market.

Довідник метрик

GET/v1/screener/metrics

Які колонки бувають у скринера: короткий ключ, довге ім’я, одиниця, вікно, група та опис. Статичний — можна закешувати в себе. Та сама група screener.

JSON
{
  "columns": ["key", "name", "unit", "window", "group", "description"],
  "rows": [
    ["odu5", "oi_change_usd_5m", "usd", "5m", "oi", "Зміна відкритого інтересу за 5 хвилин у доларах: OI зараз − OI 5 хвилин тому (опора шукається за часом)."]
  ]
}

Якщо джерело завело нову метрику раніше, ніж вона потрапила до довідника, вона приходить під коротким ключем як є — колонки з незнайомим ім’ям не відкидайте мовчки.

Для живого скринера використовуйте канал screener у WebSocket: оновлення приходять лише за зміненими метриками. За всім ринком одразу стежить підписка на весь ринок з фільтрами за біржами, ринками та метриками.

https://docs.lootx.trade/uk/market-api/screener

Справочник

12Маржинальное кредитование

Займы и возвраты пула маржи Binance по активам, чистые займы и их z-оценки, запас пула, ставки займа Binance, OKX, Bybit и ставка кредитора Gate, эпизоды «пул пуст» и покрытие источников.

Пул маржи Binance — кросс (kind=margin) и изолированный (kind=isolated): сколько актива заняли и вернули, чистые займы и их z-оценки, запас пула; ставки займа Binance, OKX и Bybit и ставка кредитора Gate; эпизоды, когда пул актива опустел. Все шесть маршрутов — одна группа тарифа margin. Инструмента здесь нет: актив называется так, как его называет площадка, — BTC, USDT, PEPE.

Займы и возвраты выводятся из запаса пула по минутам: убыль запаса за минуту — займ, прибыль — возврат. Это нижняя граница: займ и возврат внутри одной минуты гасят друг друга, а пополнение пула самой площадкой попадает в возвраты. Минута без наблюдения не даёт ни займа, ни возврата, и следующая за ней тоже: разницу через дыру не считают.

Единицы и null

Что Как приходит Где
Время мс Unix UTC; бакеты — по сетке своего шага в UTC ts, start, end, as_of, inventory_ts
Деньги *_usd_e8 — целым числом строкой, USDT × 10⁸: "4795955961" — 47,95955961 USDT borrow_usd_e8, net_usd_e8, inventory_usd_e8, borrow24h_usd_e8, net_usd_e8:<АКТИВ>
Количества в единицах актива, точная десятичная запись строкой, без хвостовых нулей, ноль — "0" borrow, repay, volume, net, net_cum, inventory, borrow_24h, borrow_limit
Цены в USDT, десятичной строкой price, price_usdt, btc_price_usdt
Ставки годовая доля десятичной строкой, простая: дневная × 365, часовая × 8760, годовая как есть. "0.0460484" — 4,60484 % годовых rate_apr, rate_apr_binance, rate_apr_okx, rate_apr_bybit, lend_apr_gate
z и проценты числом с двумя знаками: 4.99, -12.5 — это статистика, а не деньги borrow_z, repay_chg_pct, growth_pct

Деньги за окно — сумма займа каждой минуты по цене этой же минуты, посчитанная точно и округлённая один раз. Разбирайте *_usd_e8 как целое произвольной длины или десятичный тип: значение бывает больше 2⁵³. Деньги не округляются к шагу цены ни у нас, ни в ваших расчётах не должны.

null — «нет данных», а не ноль. Бакет без единой минуты с данными — null. Нет цены — null в долларовых колонках, а количества в единицах актива есть. Меньше 20 точек для z — null. Изменение от нуля — null.

Активы пула

GET/v1/margin/assets

Строка на актив пула, по имени: суммы за окно, z и изменения, запас, цена и ставки четырёх площадок. Группа тарифа — margin.

Параметр Что
window окно сумм: 1d, 7d, 30d, 90d, по умолчанию 7d. Окно начинается с часа, текущий час включён
change_period период изменений и z: 5m, 15m, 30m, 1h, 4h, 12h, 1d, 7d, 30d, по умолчанию 1h. Берутся целые периоды, текущий неполный не входит
z_window выборка z: 3d, 7d, 14d, 30d, по умолчанию 7d
units base (по умолчанию) — в единицах актива, usdt — деньги *_usd_e8
kind пул: margin (кросс, по умолчанию) или isolated
Shell
curl -s "https://market-api.lootx.trade/v1/margin/assets?window=7d&units=usdt" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "as_of": 1795049940000,
  "columns": ["asset", "borrow_usd_e8", "repay_usd_e8", "volume_usd_e8", "net_usd_e8", "borrow_z", "repay_z", "borrow_chg_pct", "repay_chg_pct", "borrow_chg_z", "repay_chg_z", "inventory_usd_e8", "inventory_ts", "price_usdt", "rate_apr_binance", "rate_apr_okx", "rate_apr_bybit", "lend_apr_gate"],
  "rows": [
    ["BTC", "1843077512200", "1702455120000", "3545532632200", "140622392200", 1.27, 0.84, 12.5, -3.1, 0.92, -0.2, "4513220551834400", 1795049940000, "100294.5", "0.0460484", "0.0365", "0.0219", "0.05"]
  ],
  "next_cursor": null
}
Колонка Что
as_of новейшая минута, к которой относятся суммы и запас, мс
borrow, repay, volume, net займы, возвраты, их сумма и разность за окно, в единицах актива. С units=usdt — borrow_usd_e8, repay_usd_e8, volume_usd_e8, net_usd_e8
borrow_z, repay_z z-оценка займов (возвратов) за последний период change_period против периодов выборки z_window перед ним
borrow_chg_pct, repay_chg_pct изменение к предыдущему периоду, %
borrow_chg_z, repay_chg_z z-оценка этого изменения
inventory запас пула на новейшей наблюдённой минуте, в единицах актива; null, если она старше as_of больше чем на 5 минут. С units=usdt — inventory_usd_e8
inventory_ts время этой минуты, мс; null — наблюдений нет за 48 часов
price_usdt цена актива на as_of
rate_apr_binance, rate_apr_okx, rate_apr_bybit ставка займа базового уровня площадки (Binance 0, OKX basic, Bybit No VIP) не старше 15 минут
lend_apr_gate ставка кредитора Gate — не ставка займа

z и изменения считаются в единицах актива при любом units. Источник пересобирает ответ раз в минуту, а не на запрос: as_of говорит, к какой минуте он относится.

Ряд актива

GET/v1/margin/series

Ряд одного актива по бакетам шага: цена, займы, возвраты, чистые и накопленные займы, z и изменения, запас, ставка Binance. Группа тарифа — margin.

Параметр Что
asset обязательный: актив, как его называет площадка, любое письмо, без запятой, до 64 байт
step шаг бакета: 1m, 5m, 1h, по умолчанию 5m
from начало, мс; источник округляет его вниз к шагу. По умолчанию — окно шага до to: 1 сутки у 1m, 7 суток у 5m, 30 суток у 1h. Глубина тарифа меряется по нему
to конец, мс; округляется вверх к шагу, не позже конца текущей минуты. По умолчанию — сейчас
metrics метрики через запятую: price, borrow, repay, net, net_cum, borrow_z, repay_z, borrow_chg_pct, repay_chg_pct, borrow_chg_z, repay_chg_z, inventory, rate_apr. По умолчанию — price,borrow,repay
units base (по умолчанию) или usdt
kind margin (по умолчанию) или isolated
z_window выборка z: 3d, 7d, 14d, 30d, по умолчанию 7d; период z — шаг

Самое длинное окно — 1 сутки у 1m, 8 суток у 5m и 90 суток у 1h; длиннее — 400 upstream_rejected с param: "from".

Shell
curl -s "https://market-api.lootx.trade/v1/margin/series?asset=BTC&step=1h&from=1794960000000&to=1794967200000&metrics=price,borrow,repay,net&units=usdt" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "columns": ["ts", "price", "borrow_usd_e8", "repay_usd_e8", "net_usd_e8"],
  "rows": [
    [1794960000000, "99812.4", "512300410000", "498112000000", "14188410000"],
    [1794963600000, "100120.1", "301772500000", "355910020000", "-54137520000"]
  ],
  "next_cursor": null
}
  • ts — начало бакета, дальше по колонке на метрику в порядке metrics. С units=usdt borrow, repay, net, net_cum и inventory приходят как borrow_usd_e8, repay_usd_e8, net_usd_e8, net_cum_usd_e8 и inventory_usd_e8.
  • price — закрытие бакета: последняя цена в нём или протянутая в него не дольше 5 минут.
  • inventory — запас на последней наблюдённой минуте бакета; rate_apr — ставка займа Binance базового уровня, последняя в бакете.
  • net_cum — нарастающий net от первого бакета ряда; у бакета без данных — null.

Страниц нет: next_cursor всегда null, окно режьте сами.

Сравнение активов

GET/v1/margin/compare

Чистые займы нескольких активов в USDT по бакетам и цена BTC — для одного графика. Группа тарифа — margin.

Параметр Что
assets активы через запятую, до 8. По умолчанию — BTC,ETH,USDT,USDC
window окно: 1d, 7d, 30d, 90d, по умолчанию 7d
step шаг: 5m (только окно 1d), 1h (по умолчанию), 1d
kind margin (по умолчанию) или isolated
Shell
curl -s "https://market-api.lootx.trade/v1/margin/compare?assets=BTC,ETH&window=1d&step=1h" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "as_of": 1795049940000,
  "columns": ["ts", "btc_price_usdt", "net_usd_e8:BTC", "net_usd_e8:ETH"],
  "rows": [
    [1794963600000, "99950.2", "140622392200", "-2311045000"],
    [1794967200000, "100120.1", "-54137520000", "905512300"]
  ],
  "next_cursor": null
}

Пример сокращён до двух бакетов. Колонки — ts, закрытие BTC btc_price_usdt и по колонке net_usd_e8:<АКТИВ> на каждый актив запроса, в его порядке. Бакеты идут от того, в котором лежит начало окна, до текущего включительно.

Эпизоды «пул пуст»

GET/v1/margin/events

Эпизоды, когда запас актива в пуле кончился, задевшие окно, — новые первыми. Группа тарифа — margin.

Параметр Что
window окно: 1d, 7d, 30d, 90d, по умолчанию 7d
borrow24h_min_usd порог займа за сутки до начала эпизода, USDT, десятичной записью ≥ 0; 0 — без порога. По умолчанию 10000
growth_period период роста займа: только 15m
growth_min_pct порог роста займа, %, десятичной записью; 0 — без порога. По умолчанию 100
kind margin или isolated; без параметра — оба пула
JSON
{
  "as_of": 1795049940000,
  "columns": ["asset", "kind", "start", "end", "end_reason", "borrow_24h", "borrow24h_usd_e8", "growth_pct", "empty_for_s"],
  "rows": [
    ["ACT", "margin", 1795020000000, 1795023600000, "refilled", "125000000", "2187500000000", 340.5, 3600]
  ],
  "next_cursor": null
}
Колонка Что
start, end начало и конец эпизода, мс; end: null — пул всё ещё пуст
end_reason refilled — пул пополнился, delisted — актив сняли, null — эпизод идёт
borrow_24h, borrow24h_usd_e8 займ за сутки до начала: в единицах актива строкой и в USDT × 10⁸ по цене минуты начала
growth_pct рост займа: 15 минут до начала против 15 минут перед ними, %; null — сравнивать не с чем
empty_for_s секунд от начала до конца, у идущего — до «сейчас»

В ответ попадают эпизоды, у которых займ за сутки выше порога borrow24h_min_usd и рост выше growth_min_pct; рост null проходит только порог 0. Эпизодов нет — 200 с пустыми rows, так же и без ключа Binance. Источник держит эпизоды 90 суток, не больше 5 000: сверх этого — новейшие по началу, а покрытие говорит events_truncated: true.

Ставки площадок

GET/v1/margin/rates

Ставки одного актива по времени, старые первыми. Группа тарифа — margin.

Параметр Что
asset обязательный, как у /v1/margin/series
venues площадки через запятую: binance, okx, bybit, gate. По умолчанию — все четыре
from начало, мс. По умолчанию — сутки до to. Глубина тарифа меряется по нему
to конец, мс; позже «сейчас» — считается «сейчас». Окно — до 31 суток
vip_level уровень VIP для каждой площадки запроса. По умолчанию — базовый у каждой
side borrow — ставка заёмщика: Binance, OKX, Bybit; lend — ставка кредитора: Gate. Без параметра — обе стороны
Shell
curl -s "https://market-api.lootx.trade/v1/margin/rates?asset=USDT&venues=binance,bybit,gate&from=1795046400000&to=1795050000000" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "columns": ["ts", "venue", "side", "vip_level", "rate_apr", "src_unit", "borrow_limit"],
  "rows": [
    [1795046400000, "binance", "borrow", "0", "0.0460484", "day", "1500.5"],
    [1795046400000, "bybit", "borrow", "No VIP", "0.0219", "hour", null],
    [1795046400000, "gate", "lend", "", "0.05", "year", null]
  ],
  "next_cursor": null
}
Колонка Что
side чья ставка: borrow — платит заёмщик, lend — получает кредитор
vip_level уровень площадки: базовый у Binance — 0, у OKX — basic, у Bybit — No VIP, у Gate уровня нет — ""
rate_apr годовая доля десятичной строкой
src_unit в какой единице ставку дала площадка: day, hour или year
borrow_limit предел займа в единицах актива строкой; нет у площадки — null

Ставка Gate — только кредитора. Ставку заёмщика Gate отдаёт только по ключу аккаунта, её не собирают: side=borrow строк Gate не даёт, а в /v1/margin/assets у Gate колонка lend_apr_gate, а не ставка займа.

Покрытие источников

GET/v1/margin/coverage

Что источник маржи собирает и насколько свежо: запас пула и его пулы, цены, ставки площадок. Не таблица: CSV — 400 bad_format. Группа тарифа — margin; параметров, кроме format, нет.

JSON
{
  "as_of": 1795049940000,
  "events_truncated": false,
  "sources": [
    {"source": "inventory", "state": "no_key", "reason": null, "last_minute": null, "gaps_24h": [], "gap_minutes_24h": 0, "used_weight_ip_1m": null},
    {"source": "rates_binance", "state": "enabled", "reason": null, "last_minute": 1795049940000, "gaps_24h": [], "gap_minutes_24h": 0, "used_weight_ip_1m": null}
  ]
}

Источники идут по порядку: inventory, inventory_margin, inventory_isolated, prices, rates_binance, rates_okx, rates_bybit, rates_gate (пример сокращён до двух).

Поле Что
as_of новейшая минута кэша источника, мс; null — источник ещё прогревается
events_truncated events_truncated: true — эпизодов за 90 суток больше 5 000: в /v1/margin/events — новейшие 5 000 по началу, старшие опущены
state enabled; disabled — источник выключен или данных не было; no_key — нет ключа Binance, запас не опрашивается, остальное отвечает; error
reason у error: stale — данные отстали (запас — больше 5 минут, цены и ставки — 5 и 15 минут), store — склад не читается, warming — прогрев; иначе null
last_minute новейшая минута источника, мс
gaps_24h, gap_minutes_24h дыры за последние сутки — [from, to или null, причина] — и сколько в них минут
used_weight_ip_1m вес запросов к Binance на новейшем ответе запаса; только у inventory

Покрытие отвечает всегда, и в прогреве тоже.

Глубина истории

Глубину проверяет тариф — history_days: меньший из общего и группового (группы margin), если у группы свой. Как меряется, зависит от маршрута:

  • /v1/margin/assets, /compare, /events — по окну. window=30d требует 30 суток истории от «сейчас». Глубже тарифа — 403 history_out_of_plan с param: "window", в expected — «окно не длиннее N сут.», где N — history_days тарифа: возьмите окно короче.
  • /v1/margin/series и /rates — по from. У series присланный from источник округляет вниз к шагу, и шлюз меряет округлённый: from ровно на границе тарифа посреди часа у step=1h получит отказ. earliest_allowed_ms в отказе — первый from на сетке шага не раньше границы, повтор с ним проходит.
  • Без from шлюз меряет окно по умолчанию от min(to, сейчас). Если оно глубже тарифа, отказ — param: "from" с текстом «from не прислан, окно по умолчанию … глубже тарифа — пришлите from не раньше X»: пришлите from не раньше earliest_allowed_ms.

change_period и z_window глубиной тарифа не меряются.

Кэш и ETag

/v1/margin/assets, /compare, /events и /coverage источник собирает из своего кэша раз в минуту; шлюз их не кэширует, свежесть — по as_of.

Слабый ETag есть только у закрытых окон /v1/margin/series и /v1/margin/rates: окно, кончившееся не позже чем за 30 минут до начала текущего часа. Метка приходит в любом формате — данные те же.

  • Пришлите её в If-None-Match — если данные не менялись, ответ 304 без тела: запрос засчитывается, а в суточный объём не идёт.
  • Повтор закрытого окна шлюз отдаёт из своего кэша с той же меткой.
  • Поздняя запись источника в закрытое окно меняет метку; кэш шлюза увидит её не сразу.
Shell
curl -s -o /dev/null -w "%{http_code}\n" "https://market-api.lootx.trade/v1/margin/series?asset=BTC&step=1h&from=1794960000000&to=1794967200000" \
  -H "Authorization: Bearer $LOOTX_API_KEY" -H 'If-None-Match: W/"m1-00ff"'

Отказы

Ответ Когда Что делать
400 bad_request параметра нет у маршрута (param — его имя), параметр повторён, window или step series не из списка, нет asset исправьте запрос по param и expected
400 upstream_rejected источник отверг значение: его текст в message начинается с имени параметра (units: …), оно же в param исправьте названный параметр
403 history_out_of_plan окно или from глубже тарифа — выше окно короче или from не раньше earliest_allowed_ms
503 upstream_unavailable источник перегружен или прогревается: кэш после запуска, склад не читается, очередь сборки ответов assets и compare полна. Приходит с Retry-After: 2 повторите через Retry-After
502 upstream_error источник ответил ошибкой или телом не той формы, маршрутов маржи у источника нет повторите позже; не проходит — напишите в поддержку с request_id
502 upstream_unavailable, 504 upstream_timeout источник недоступен или не ответил вовремя (за 15 с) повторите позже; у assets и compare долгая сборка не теряется — повтор присоединится к ней и получит готовый ответ

Все коды — на странице ошибок.

https://docs.lootx.trade/uk/market-api/margin

Справочник

13Опционы

Опционы Deribit, Binance, Bybit и OKX по цепочкам — базы с ликвидностью, каталог с правилом поставки, экспирации с max pain, GEX, ATM IV и ожидаемым ходом, цепочка минуты, ряд волатильности книги, экспозиция и уровни GEX, живой поток, история цепочки за диапазон минут, покрытие сбора.

Опционы четырёх площадок — deribit, binance, bybit, okx — по цепочкам базы: базы площадок с ликвидностью, каталог инструментов, экспирации с суммами объёма и OI и расчётом (max pain, GEX, ATM IV, ожидаемый ход), цепочка одной минуты (котировки, mark, подразумеваемая волатильность, OI, объёмы, форвард и индекс), история одной цепочки за диапазон минут, ряд волатильности книги, экспозиция GEX, DEX, VEX и CEX новейшей минуты по страйкам, история уровней книги (zero gamma, стены, max pain), покрытие сбора и живой поток цепочек по WebSocket. Все десять маршрутов и поток — одна группа тарифа options.

База — монета, на которую выписаны опционы: BTC, ETH, SOL. У базы бывает несколько цепочек — например, у Deribit BTC (inverse) и BTC_USDC (linear). Инструмента в виде venue:market:SYMBOL здесь нет: площадку выбирает venue, базу — base, цепочку — chain.

Доступ

  • Группа тарифа — options. Пока тариф не задаёт ей своих лимитов, запросы к ней расходуют общие лимиты ключа (лимиты групп). Тариф, закрывший группу, получает 403 route_not_in_plan.
  • Область — derivatives. API-ключу нужна область market:read — та же, что у остальных маршрутов. Токен терминала должен нести область derivatives: у бесплатного её нет, ответ — 403 insufficient_scope, к источнику запрос не уходит.
  • Площадка по умолчанию — deribit, кроме /v1/options/bases: без venue он отдаёт все четыре площадки. Какие базы и цепочки есть у площадки, говорит /v1/options/bases; база без опционов или чужая цепочка — 400 upstream_rejected с param: "base" или "chain".

Единицы и null

Что Как приходит Где
Время Unix-мс UTC, целым expiry_ms, ts_min, snap_ts, oi_asof_ms, last_ts_min, from_ms, to_ms, from, to, ts_ms, asof_ms, expiries_ms, max_pain_expiry_ms
Деньги *_usd_e8 — целым числом строкой, USD, USDT или USDC × 10⁸: "16400000" — 0,164 USDT у binance. Валюта и смысл — по площадке, цепочке и полю, в таблице ниже. Со знаком — только gamma_usd_e8, gex_usd_e8, dex_usd_e8, vex_usd_e8, cex_usd_e8, gex_put_usd_e8 и net_gex_usd_e8 volume_usd_e8, volume_notional_usd_e8 — объёмы за 24 ч в деньгах; volume_24h_usd_e8, oi_usd_e8 — ликвидность баз, max_pain_payout_usd_e8, gamma_usd_e8 — расчёт экспираций, gex_usd_e8, dex_usd_e8, vex_usd_e8, cex_usd_e8, gex_call_usd_e8, gex_put_usd_e8 — экспозиция, net_gex_usd_e8 — история уровней, валюта — рядом в ответе
Цены точной десятичной записью строкой, за 1 монету базы в валюте котировки цепочки: у settle: inverse — в монете базы (0.005 — BTC), у linear — в USD, USDT или USDC bid, ask, mark, tick_size, tick_steps
Форвард и индекс десятичной строкой forward, index
Страйк и размеры десятичной строкой strike, contract_size, min_trade
Количества в контрактах, десятичной строкой; контракты × contract_size — монеты базы. volume — за 24 ч oi_asof, volume, bid_size, ask_size, oi_calls, oi_puts
OI экспирации в монетах десятичной строкой: (Σ oi_asof call + Σ oi_asof put) × contract_size oi_coins
Волатильность iv_bp — целым, в 0,01 пункта: 4872 — 48,72 % iv_bp, atm_iv_bp, IV ряда волатильности, rr25_bp_30d, bf25_bp_30d
Ожидаемый ход целым, в базисных пунктах от форварда F: 273 — 2,73 % от F. Это доля цены, а не пункты волатильности move_straddle_bp, move_sigma_bp

Деньги опционов — премия или номинал. Номинал в ответе есть только у Bybit, остальные деньги — премия. Валюта денег — не всегда валюта цен цепочки: у Deribit *_USDC цены в USDC, а volume_usd_e8 — в USD. Номинал у Deribit и Binance оценивайте сами: volume × contract_size × index. Премию с номиналом не сравнивайте, а суммы разных площадок не складывайте без оговорки: USDT — не USD. Разбирайте *_usd_e8 как целое произвольной длины или десятичный тип: значение бывает больше 2⁵³, а в число с плавающей точкой его не переводите. Деньги не округляются к шагу цены ни у нас, ни в ваших расчётах не должны. Цены и количества тоже не превращайте в double, пока не нужно: строка — точное значение площадки.

null — «нет данных», а не ноль. Поле, которого площадка не шлёт, — null всегда, в каждой строке цепочки и в суммах экспираций. Деньги и пропуски по цепочкам:

Площадка Цепочка BTC volume_usd_e8 volume_notional_usd_e8 Не шлёт — всегда null
deribit BTC — inverse премия, USD нет bid_size, ask_size, volume_notional_usd_e8
deribit BTC_USDC — linear, USDC премия, USD нет bid_size, ask_size, volume_notional_usd_e8
binance BTC — linear, USDT премия, USDT нет forward, bid_size, ask_size, volume_notional_usd_e8
bybit BTC — linear, USDT нет номинал, USDT volume_usd_e8
bybit BTC_USDC — linear, USDC; сейчас Bybit таких не листит нет номинал, USDC volume_usd_e8
okx BTC — inverse нет нет index, volume_usd_e8, volume_notional_usd_e8
okx BTC_UM — linear, USD нет нет index, volume_usd_e8, volume_notional_usd_e8

Остальное бывает null по случаю: нет котировки — null в bid или ask, а у Bybit и OKX — и в размере этой стороны; у Binance и OKX минута бывает записана без части снимка (в покрытии это дыра stream: oi или quotes) — тогда null в oi_asof или в полях тикера: котировках, их размерах, volume, у Binance ещё в volume_usd_e8 и index; суммы объёма экспирации без кадра — null; instrument: null — имени инструмента в каталоге нет.

OI — на момент oi_asof_ms, а не минуты. oi_asof строки — OI на момент oi_asof_ms её цепочки. У Deribit он на 8 часов раньше снимка минуты.

JSON — тело источника как есть: у catalog и chain поле venue первое, у expiries и coverage ключи по алфавиту. Разбирайте поля по именам, а не по порядку.

Валюта цепочки

Валюта цепочки — в ответе. settle, price_ccy, volume_usd_ccy и volume_notional_ccy приходят у цепочек каталога и минуты (chain, chain/latest) и у экспираций, settle и price_ccy — ещё у баз; в кадрах OPC1 и в ряду chain/range их нет — берите их из каталога или bases. price_ccy — валюта цен bid, ask, mark (у inverse — монета базы), volume_usd_ccy — валюта volume_usd_e8, volume_notional_ccy — валюта volume_notional_usd_e8; null — такого поля у цепочки нет. Все четыре — у цепочки, а не у инструмента: null в settle или price_ccy — у инструментов цепочки не одно значение.

Площадка Цепочка базы BTC settle price_ccy volume_usd_ccy volume_notional_ccy
deribit BTC inverse BTC USD null
deribit BTC_USDC linear USDC USD null
binance BTC linear USDT USDT null
bybit BTC linear USDT null USDT
bybit BTC_USDC linear USDC null USDC
okx BTC inverse BTC null null
okx BTC_UM linear USD null null

Премия в долларах. volume_usd_e8 / 10⁸ — сумма в валюте volume_usd_ccy: у Deribit — USD (BTC и BTC_USDC) и у Binance — USDT. Долларами она становится только при volume_usd_ccy: "USD"; USDT и USDC переводите в USD своим курсом, а не 1 : 1. Номинал — так же, по volume_notional_ccy: у Bybit без суффикса — USDT, на *_USDC — USDC. Валюту берите из ответа, а не из этой таблицы: таблица — то, что площадки шлют сейчас.

Базы

GET/v1/options/bases

Базы опционов и их цепочки по площадкам — то, что листингуется сейчас: settle, price_ccy, версия каталога, сколько инструментов и экспираций, ликвидность новейшей минуты. Группа тарифа — options.

Параметр Что
venue площадка: deribit, binance, bybit, okx; строчными. Без параметра — все четыре: умолчания deribit у этого маршрута нет
Shell
curl -s "https://market-api.lootx.trade/v1/options/bases" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venues": [
    {
      "venue": "deribit",
      "bases": [
        {
          "base": "BTC",
          "volume_24h_usd_e8": "4810545000000000", "volume_ccy": "USD", "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795152664164,
          "chains": [
            {"chain": "BTC", "settle": "inverse", "price_ccy": "BTC", "catalog_ver": 13, "instruments": 950, "expiries": 12, "volume_24h_usd_e8": "4718235000000000", "volume_ccy": "USD", "oi_usd_e8": "1893412000000000000", "oi_ccy": "USD", "oi_asof_ms": 1795152664164},
            {"chain": "BTC_USDC", "settle": "linear", "price_ccy": "USDC", "catalog_ver": 6, "instruments": 576, "expiries": 8, "volume_24h_usd_e8": "92310000000000", "volume_ccy": "USD", "oi_usd_e8": "61200000000000000", "oi_ccy": "USDC", "oi_asof_ms": 1795152665101}
          ]
        }
      ]
    },
    {
      "venue": "binance",
      "bases": [
        {
          "base": "BTC",
          "volume_24h_usd_e8": "51730000000000", "volume_ccy": "USDT", "oi_usd_e8": "38410000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181462000,
          "chains": [
            {"chain": "BTC", "settle": "linear", "price_ccy": "USDT", "catalog_ver": 6, "instruments": 688, "expiries": 11, "volume_24h_usd_e8": "51730000000000", "volume_ccy": "USDT", "oi_usd_e8": "38410000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181462000}
          ]
        }
      ]
    },
    {
      "venue": "bybit",
      "bases": [
        {
          "base": "BTC",
          "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": "29870000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181413387,
          "chains": [
            {"chain": "BTC", "settle": "linear", "price_ccy": "USDT", "catalog_ver": 17, "instruments": 720, "expiries": 11, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": "29870000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181413387}
          ]
        }
      ]
    },
    {
      "venue": "okx",
      "bases": [
        {
          "base": "BTC",
          "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000,
          "chains": [
            {"chain": "BTC", "settle": "inverse", "price_ccy": "BTC", "catalog_ver": 12, "instruments": 770, "expiries": 13, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000},
            {"chain": "BTC_UM", "settle": "linear", "price_ccy": "USD", "catalog_ver": 9, "instruments": 626, "expiries": 9, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000}
          ]
        }
      ]
    }
  ]
}

Пример — ответ без venue, сокращённый до одной базы на площадку. Состав цепочек — живой ответ 20.11, числа ликвидности показывают форму, а не снимок рынка.

Поле Что
venues[] площадки: присланная venue или все четыре
bases[] базы площадки по имени; база, у которой ничего не листингуется, в список не попадает
chains[] цепочки базы, где что-то листингуется: chain, settle, price_ccy — как у каталога (выше), catalog_ver — та же версия, что у каталога, instruments — сколько инструментов листингуется, expiries — сколько у них разных экспираций

Ликвидность новейшей минуты — у каждой цепочки и у базы: премия за сутки и OI в деньгах, у каждой суммы — своя валюта. null, а не 0: у цепочки нет кадра, площадка поле не шлёт, у инструментов цепочки не одна валюта или сумма не уместилась в e8. Суммы считаются по новейшей минуте каждой цепочки, поэтому ETag ответа меняется с каждой минутой.

Поле ликвидности Что
volume_24h_usd_e8 премия за 24 ч — сумма volume_usd_e8 строк новейшей минуты, целым e8 строкой
volume_ccy валюта volume_24h_usd_e8 — та же, что volume_usd_ccy цепочки: у Deribit — USD (BTC и BTC_USDC) и у Binance — USDT; Bybit и OKX премию не шлют — null
oi_usd_e8 OI в деньгах — Σ oi_asof × contract_size × index строк с OI, целым e8 строкой; это не премия и не номинал оборота
oi_ccy валюта oi_usd_e8 — валюта котировки книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; OKX индекс не шлёт — null
oi_asof_ms на какой момент OI, Unix-мс: у Deribit — на 8 часов раньше снимка; у базы — самой старой цепочки

Сумма базы — по всем её цепочкам и только когда значение есть у каждой и валюта одна, иначе null. У Deribit OI BTC — в USD, BTC_USDC — в USDC, поэтому oi_usd_e8 базы — null; премия у обеих — в USD, она сложена.

Список баз и цепочек — из каталога в памяти источника. ETag ответа — хэш тела: If-None-Match даёт 304, пока не пришла следующая минута или листинг.

Каталог

GET/v1/options/catalog

Инструменты базы по цепочкам: страйк, экспирация, вид, расчёт, размер контракта, шаг цены и его ступени, наименьшая заявка, состояние на площадке; у цепочки — правило поставки. Группа тарифа — options.

Параметр Что
base обязательный: база, 1–16 знаков из A-Z, 0-9 — BTC, ETH, SOL
venue площадка: deribit, binance, bybit, okx, по умолчанию deribit; строчными
chain одна цепочка базы: A-Z, 0-9, _, до 32 знаков — BTC_USDC. Без параметра — все цепочки
Shell
curl -s "https://market-api.lootx.trade/v1/options/catalog?base=BTC&chain=BTC" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chains": [
    {
      "chain": "BTC",
      "catalog_ver": 13,
      "settle": "inverse",
      "price_ccy": "BTC",
      "volume_usd_ccy": "USD",
      "volume_notional_ccy": null,
      "settle_rule": {"kind": "twap", "window_s": 1800, "at_utc": "08:00"},
      "instruments": [
        {"instrument": "BTC-21NOV26-62500-C", "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "settle": "inverse", "contract_size": "1", "tick_size": "0.0001", "tick_steps": [["0.005", "0.0005"]], "min_trade": "0.1", "settlement_period": "day", "settlement_currency": "BTC", "price_index": "btc_usd", "state": "open"}
      ]
    }
  ]
}
Поле Что
catalog_ver версия каталога цепочки: растёт при листинге и делистинге
settle, price_ccy, volume_usd_ccy, volume_notional_ccy у цепочки, а не у инструмента — выше
settle_rule как цепочка поставляется: kind — twap (средняя индекса за окно перед поставкой), window_s — окно в секундах, at_utc — время поставки ЧЧ:ММ UTC. Сейчас у всех четырёх площадок — twap за 1800 с; spot и auction зарезервированы. null — правило не известно, листингов нет или экспирации цепочки поставляются в разное время суток
instrument имя инструмента у площадки
type call или put
settle у инструмента linear или inverse
tick_steps ступени шага цены: [цена от, шаг]; пусто — шаг один, tick_size
min_trade наименьшая заявка, в контрактах
settlement_period day, week, month, quarter; пустая строка — площадка периода не называет (все, кроме Deribit)
state состояние на площадке, open — торгуется

Каталог BTC — около полумегабайта. Его ETag строится из catalog_ver цепочек: пришлите метку в If-None-Match — пока листингов не было, ответ 304 без тела. Метка начинается с "cat3-; старая, выданная до settle_rule, даёт 200 с новым телом.

Экспирации

GET/v1/options/expiries

Экспирации базы по цепочкам: сколько call и put, суммы объёма и OI новейшей минуты. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
JSON
{
  "base": "BTC",
  "expiries": [
    {"calls": 23, "chain": "BTC", "expiry_ms": 1795248000000, "oi_asof_ms": 1795152664164, "oi_calls": "1070.2", "oi_coins": "2871.5", "oi_puts": "1801.3", "oi_rows": 46, "price_ccy": "BTC", "puts": 23, "settle": "inverse", "settlement_period": "day", "volume_notional_ccy": null, "volume_notional_usd_e8": null, "volume_usd_ccy": "USD", "volume_usd_e8": "174016738000000"},
    {"calls": 23, "chain": "BTC_USDC", "expiry_ms": 1795248000000, "oi_asof_ms": 1795152665101, "oi_calls": "76.41", "oi_coins": "229.93", "oi_puts": "153.52", "oi_rows": 46, "price_ccy": "USDC", "puts": 23, "settle": "linear", "settlement_period": "day", "volume_notional_ccy": null, "volume_notional_usd_e8": null, "volume_usd_ccy": "USD", "volume_usd_e8": "3401646000000"}
  ],
  "venue": "deribit"
}

Пример — живой ответ, сокращённый до экспирации на цепочку. volume_usd_e8 и volume_notional_usd_e8 — суммы по инструментам экспирации на новейшей минуте за 24 ч, валюта и смысл — как у строк цепочки (таблица выше). null — кадра ещё нет или площадка поле не шлёт.

Поле Что
oi_calls, oi_puts OI call и put экспирации — сумма oi_asof строк новейшей минуты, в контрактах, точной десятичной строкой; null — OI нет ни у одной строки этой стороны, а не ноль
oi_coins OI экспирации в монетах базы: (oi_calls + oi_puts) × contract_size
oi_asof_ms к какому моменту относится OI — как у цепочки: у Deribit на 8 часов раньше снимка
oi_rows сколько строк кадра вошло в суммы OI: меньше calls + puts — у части экспирации OI нет, суммы — по остальным
settle, price_ccy, volume_usd_ccy, volume_notional_ccy как у каталога — выше

Пока у цепочки нет ни одного кадра, все пять полей OI — null.

Расчёт экспирации — ещё шесть полей у каждой экспирации, по той же новейшей минуте: max pain, GEX, ATM IV и ожидаемый ход двумя способами.

JSON
{
  "base": "BTC",
  "expiries": [
    {"atm_iv_bp": 5945, "chain": "BTC", "expiry_ms": 1795248000000, "gamma_usd_e8": "42000000000000", "max_pain": "62000", "max_pain_payout_usd_e8": "310000000000000", "move_sigma_bp": 327, "move_straddle_bp": 262, "price_ccy": "BTC", "settle": "inverse"},
    {"atm_iv_bp": 5951, "chain": "BTC_USDC", "expiry_ms": 1795248000000, "gamma_usd_e8": "-3500000000000", "max_pain": "62000", "max_pain_payout_usd_e8": "21500000000000", "move_sigma_bp": 327, "move_straddle_bp": 259, "price_ccy": "USDC", "settle": "linear"}
  ],
  "venue": "deribit"
}

Пример — только поля расчёта, settle и price_ccy, остальные поля экспирации — как выше; числа показывают форму, а не снимок рынка.

Деньги расчёта — в валюте котировки книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC. Какая у экспирации — по её settle и price_ccy. Суффикс _usd_e8 в имени — по образцу volume_usd_e8, а не валюта: USDT — не USD, суммы разных цепочек без перевода курсом не складывайте.

Поле расчёта Что
max_pain страйк, при котором держатели опционов экспирации получают меньше всего, — среди листингованных страйков; десятичной строкой в шкале страйка
max_pain_payout_usd_e8 сколько продавцы заплатят держателям, если поставка пройдёт по max_pain; целым e8 строкой
gamma_usd_e8 net GEX экспирации в режиме naive (знак по OI): Σ Γ × OI × F² × 0,01 — деньги на ход форварда в 1 %; call — плюсом, put — минусом. Целым e8 строкой со знаком
atm_iv_bp ATM IV у форварда, целым в 0,01 пункта: 5945 — 59,45 %
move_straddle_bp ожидаемый ход по рынку: ATMF-страддл по mark, интерполяция у форварда, / F — в базисных пунктах от F
move_sigma_bp ожидаемый ход по модели: σ_ATM × √T, T — до поставки без поправки на окно поставки, в базисных пунктах от F

null расчёта — «нет данных», а не 0. Нет OI в экспирации — max_pain и max_pain_payout_usd_e8; нет строк с греками — gamma_usd_e8; нет форварда или котировок у него — IV и ход; экспирации нет в новейшей минуте (листинг позже) или поставка уже прошла — все шесть полей; у цепочки нет кадра или у её инструментов не одна валюта — тоже все шесть; деньги, не уместившиеся в e8, — null.

Цепочка последней минуты

GET/v1/options/chain/latest

Новейшая минута цепочек базы: строка на инструмент — котировки, mark, iv_bp, OI, объёмы, форвард и индекс. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
chain одна цепочка базы; без параметра — все
Shell
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chains": [
    {
      "chain": "BTC",
      "ts_min": 1795181400000,
      "snap_ts": 1795181464164,
      "oi_asof_ms": 1795152664164,
      "catalog_ver": 13,
      "settle": "inverse",
      "price_ccy": "BTC",
      "volume_usd_ccy": "USD",
      "volume_notional_ccy": null,
      "rows": [
        {"expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0041", "ask": "0.0045", "mark": "0.00433933", "iv_bp": 5961, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61415.57", "index": "61437.37", "bid_size": null, "ask_size": null}
      ]
    },
    {
      "chain": "BTC_USDC",
      "ts_min": 1795181400000,
      "snap_ts": 1795181465101,
      "oi_asof_ms": 1795152665101,
      "catalog_ver": 6,
      "settle": "linear",
      "price_ccy": "USDC",
      "volume_usd_ccy": "USD",
      "volume_notional_ccy": null,
      "rows": [
        {"expiry_ms": 1795248000000, "strike": "63500", "type": "call", "instrument": "BTC_USDC-21NOV26-63500-C", "bid": "80", "ask": "95", "mark": "88.33583281", "iv_bp": 5903, "oi_asof": "13.53", "volume": "13.24", "volume_usd_e8": "566902000000", "volume_notional_usd_e8": null, "forward": "61416.63", "index": "61435.68", "bid_size": null, "ask_size": null}
      ]
    }
  ]
}

Пример — живой ответ, сокращённый до строки на цепочку. Номинал в ответе есть только у Bybit:

Shell
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC&venue=bybit" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "bybit",
  "base": "BTC",
  "chains": [
    {
      "chain": "BTC",
      "ts_min": 1795181340000,
      "snap_ts": 1795181413387,
      "oi_asof_ms": 1795181413387,
      "catalog_ver": 17,
      "settle": "linear",
      "price_ccy": "USDT",
      "volume_usd_ccy": null,
      "volume_notional_ccy": "USDT",
      "rows": [
        {"expiry_ms": 1795248000000, "strike": "62000", "type": "call", "instrument": "BTC-21NOV26-62000-C-USDT", "bid": "470", "ask": "475", "mark": "470.28075375", "iv_bp": 6043, "oi_asof": "33.15", "volume": "146.47", "volume_usd_e8": null, "volume_notional_usd_e8": "905865257399944", "forward": "61517.00049217", "index": "61510.93639245", "bid_size": "1.82", "ask_size": "37.54"}
      ]
    }
  ]
}

Пример с номиналом — живой ответ Bybit, сокращённый до строки. volume_notional_usd_e8 — номинал, USDT: 9 058 652,57 USDT при volume × index = 146,47 × 61 510,94 ≈ 9 009 507 — оборот набран за сутки по цене BTC во время сделок, а индекс взят на снимке. Размеры котировок есть, OI — на момент снимка.

Shell
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=SOL" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "SOL",
  "chains": [
    {
      "chain": "SOL_USDC",
      "ts_min": 1795181400000,
      "snap_ts": 1795181465101,
      "oi_asof_ms": 1795152665101,
      "catalog_ver": 8,
      "settle": "linear",
      "price_ccy": "USDC",
      "volume_usd_ccy": "USD",
      "volume_notional_ccy": null,
      "rows": [
        {"expiry_ms": 1795248000000, "strike": "73", "type": "call", "instrument": "SOL_USDC-21NOV26-73-C", "bid": "0.17", "ask": "0.23", "mark": "0.20924689", "iv_bp": 7178, "oi_asof": "19", "volume": "211", "volume_usd_e8": "156548000000", "volume_notional_usd_e8": null, "forward": "70.722", "index": "70.7067", "bid_size": null, "ask_size": null}
      ]
    }
  ]
}

Пример по альту — живой ответ Deribit по SOL, сокращённый до строки. Количества и у альтов — в контрактах: у SOL_USDC контракт — 10 SOL (contract_size в каталоге, min_trade — "1"), монеты базы — volume или oi_asof × 10.

Поле Что
ts_min начало минуты, мс
snap_ts когда снят снимок площадки — сразу после закрытия минуты, мс
oi_asof_ms к какому моменту относится oi_asof строк
catalog_ver версия каталога цепочки, на которой собрана минута
settle, price_ccy, volume_usd_ccy, volume_notional_ccy как у каталога — выше, по текущему каталогу источника, а не каталогу той минуты
bid, ask, mark котировки и mark инструмента
iv_bp подразумеваемая волатильность, 0,01 пункта
volume, volume_usd_e8, volume_notional_usd_e8 объём за 24 ч: в контрактах и в деньгах, валюта и смысл денег — по площадке и цепочке в таблице выше
forward, index форвард и индекс
bid_size, ask_size объёмы лучших котировок, в контрактах

Следующий ответ того же адреса — уже новая минута, поэтому chain/latest не кэшируется. Цепочки без минуты — в missing (неполная минута).

Цепочка минуты

GET/v1/options/chain

Цепочки базы в минуту, закрытую в at или раньше; поля — как у chain/latest. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
chain одна цепочка базы; без параметра — все
at обязательный: момент, Unix-мс UTC или ISO-8601. Ответ — минута, закрытая в at или раньше. Глубина тарифа меряется по началу этой минуты

Какая минута придёт. Шлюз берёт новейшую минуту, которая к at уже закрыта: её начало T = ⌊(at − 60 000) / 60 000⌋ · 60 000, она идёт от T до T + 60 000. at=1795110000000 (17:40:00 UTC) и at=1795110030000 (17:40:30) дают одну и ту же минуту 17:39–17:40 с ts_min: 1795109940000: минута 17:40–17:41 к 17:40:30 ещё не закрыта. Время в секундах или микросекундах — 400 bad_request с param: "at".

Shell
curl -s "https://market-api.lootx.trade/v1/options/chain?base=BTC&chain=BTC&at=2026-11-19T17:40:00Z" \
  -H "Authorization: Bearer $LOOTX_API_KEY"

Минуты нет ни у одной цепочки базы или у присланной chain — 404 not_found; минута, которую не восстановить из кадров источника, — тоже 404 not_found, со словом gap в message. Где дыры, говорит покрытие.

Неполная минута

Минута бывает не у всех цепочек базы. Тогда ответ 200, а цепочки без минуты перечислены в missing тела и в заголовке x-options-missing:

Где Что
missing[] chain, reason, detail: no_frame — кадра нет, это дыра сбора; gap — минута не восстанавливается
заголовке x-options-missing те же цепочки строкой ЦЕПОЧКА:причина через запятую: BTC_USDC:no_frame. Приходит в любом формате, у OPC1 это единственное место, где о них сказано

detail — пояснение источника по-английски, для человека, а не для разбора. Так выглядит missing ответа /v1/options/chain за минуту, у которой нет кадра BTC_USDC:

JSON
[
  {"chain": "BTC_USDC", "reason": "no_frame", "detail": "minute 1795137660000: no frame (a hole: see /v1/options/coverage)"}
]

У chain/latest detail другой: no frame yet — у цепочки ещё нет ни одной минуты, newest minute <мс> cannot be rebuilt (…) — новейшая минута не собирается (gap). Поля missing нет — на месте все цепочки. Неполная минута не бывает неизменной: Cache-Control: private, no-cache, и кэш шлюза её не держит — повторите позже, когда источник дособерёт.

История цепочки

GET/v1/options/chain/range

История одной цепочки за [from, to) — до 360 минут: JSON и protobuf — ряд одного инструмента по минутам, format=opc1 — кадры всей цепочки по минутам. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
chain обязательный: одна цепочка базы, как у каталога. Диапазон — всегда одной цепочки
from обязательный: начало, Unix-мс UTC или ISO-8601, целая минута. Глубина тарифа меряется по нему
to обязательный: конец, в диапазон не входит; целая минута, from < to, не больше 360 минут после from — иначе 400 bad_request с param: "to"
instrument инструмент цепочки — BTC-21NOV26-62500-C: A-Z, a-z, 0-9, -, _, ., до 64 знаков. Обязательный у JSON и protobuf: ответ — его ряд. У format=opc1 его нет — кадры всей цепочки; instrument с ним, как и JSON без него, — 400 bad_request с param: "instrument"
Shell
curl -s "https://market-api.lootx.trade/v1/options/chain/range?base=BTC&chain=BTC&instrument=BTC-21NOV26-62500-C&from=2026-11-20T13:00:00Z&to=2026-11-20T13:03:00Z" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chain": "BTC",
  "instrument": "BTC-21NOV26-62500-C",
  "from": 1795179600000,
  "to": 1795179780000,
  "rows": [
    {"ts_min": 1795179600000, "snap_ts": 1795179664261, "oi_asof_ms": 1795150864261, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0043", "ask": "0.0046", "mark": "0.00439472", "iv_bp": 5718, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61488.53", "index": "61517.02", "bid_size": null, "ask_size": null},
    {"ts_min": 1795179660000, "snap_ts": 1795179720021, "oi_asof_ms": 1795150920021, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0046", "ask": "0.0049", "mark": "0.00475026", "iv_bp": 5719, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61555.04", "index": "61575.39", "bid_size": null, "ask_size": null},
    {"ts_min": 1795179720000, "snap_ts": 1795179784781, "oi_asof_ms": 1795150984781, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0045", "ask": "0.0048", "mark": "0.00469664", "iv_bp": 5720, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61543.46", "index": "61565.5", "bid_size": null, "ask_size": null}
  ]
}

Пример — живой ответ за три минуты. Строка минуты — шапка минуты /v1/options/chain (ts_min, snap_ts, oi_asof_ms, catalog_ver) и строка инструмента той минуты — поле в поле, как у /v1/options/chain?at= этой минуты. До листинга инструмента строк нет — это не пропуск.

Поле Что
from, to диапазон запроса, мс; to не входит
rows[] минуты, где инструмент есть, по порядку
missing[] минуты, которых нет у цепочки: from_ms, to_ms (не входит), reason — no_frame (минута осела, кадра нет) или gap (кадр не связывается с отданным перед ним); соседние минуты одной причины — одним интервалом. Поля нет — на месте все. Минуты, ещё не закрытые к запросу (диапазон в настоящее), — не пропуск

Вес запроса — час диапазона. Диапазон до 60 минут — 1 единица лимитов, 61–120 — 2, …, 301–360 — 6: столько запросов он списывает из ведра минуты и окон часа и суток (лимиты). Повтор из кэша шлюза (X-Cache: HIT) и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет chain, from или to, не целые минуты, from ≥ to, больше 360 минут — стоит 1; Глубже тарифа, CSV, JSON без instrument и format=opc1 с ним отказывают уже после списания полного веса.

Длинную историю читайте подряд диапазонами по 6 часов: to одного — from следующего. Кадры OPC1 (format=opc1) — вся цепочка за минуту, а ряд JSON — один инструмент: для всей цепочки берите кадры.

x-options-missing — одно имя, два синтаксиса. У /v1/options/chain и /v1/options/chain/latest — цепочки базы без минуты: ЦЕПОЧКА:причина через запятую (BTC_USDC:no_frame). У /v1/options/chain/range — интервалы минут без кадра: FROM_MS-TO_MS:причина через запятую, Unix-мс UTC, [FROM_MS, TO_MS), например 1795148100000-1795148220000:no_frame; заголовок не длиннее 1 КиБ, интервалы, которые не уместились, — последним элементом +N, полный список — в missing JSON. Разбирайте заголовок по маршруту, а не по виду строки. У кадров OPC1 о пропусках больше нигде не сказано.

Покрытие

GET/v1/options/coverage

Цепочки базы — новейшая минута, отставание и минута, которую не собрать, — и дыры сбора окна. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
from начало окна дыр, Unix-мс UTC или ISO-8601. По умолчанию — сутки до «сейчас». Глубина тарифа меряется по нему
to конец окна; по умолчанию — сейчас. Нужно from < to, окно — до 31 суток, иначе 400 upstream_rejected с param: "from"
Shell
curl -s "https://market-api.lootx.trade/v1/options/coverage?base=BTC&from=2026-11-20T03:00:00Z&to=2026-11-20T05:00:00Z" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "base": "BTC",
  "chains": [
    {"chain": "BTC", "lag_ms": 15018, "last_ts_min": 1795181520000},
    {"chain": "BTC_USDC", "lag_ms": 15018, "last_ts_min": 1795181520000}
  ],
  "from": 1795143600000,
  "gaps": [
    {"chain": "BTC", "from_ms": 1795148109131, "reason": "disconnect", "source": "btc_usd", "stream": "live", "to_ms": 1795148109353}
  ],
  "to": 1795150800000,
  "venue": "deribit"
}

Пример — живой ответ: 20.11 в 04:15:09 UTC поток Deribit оборвался на 0,2 секунды (disconnect). Дыра записана под индексом btc_usd — он в source, а chain — цепочка, чья книга идёт по этому индексу. chains — состояние на «сейчас», окно from–to к нему не относится.

Поле Что
last_ts_min новейшая минута цепочки у источника, мс; null — минуты ещё нет
lag_ms насколько она отстала от «сейчас», мс
unbuilt новее хранится минута, которую не собрать: ts_min, reason и detail — как у missing, например "reason": "gap", "detail": "cannot be rebuilt (reference: no key frame)"; поля нет — такой нет
gaps[] дыры сбора окна: chain, source, stream, from_ms, to_ms, reason
chain дыры цепочка (книга), к которой относится дыра. null — записанное имя не удалось сопоставить ни одной цепочке: единица опроса (*, ALL и подобные) или индекс, которого нет в каталоге; имя — в source, и такая дыра приходит в ответе каждой базы площадки
source записанное имя, когда дыра записана не под своей цепочкой: индекс (btc_usd), базовый актив OKX (BTC-USD) или единица опроса. Поля нет — дыра записана под самой цепочкой
stream что прервалось: chain — минута цепочки не записана; oi, quotes — у Binance и OKX минута записана без OI (у Binance — иногда без OI только части экспираций) или без тикера: эта часть снимка не получена в окне минуты; live — поток Deribit, имя индекса — в source; catalog — каталога площадки нет, минута потеряна
reason почему: ошибка запроса к площадке — transport, rate_limited, http_status, rpc_error, decode; window_passed — окно минуты прошло, snapshot_time — снимок не из окна минуты; у chain ещё restart и leader_change — сборщик перезапущен или лидерство перешло к другому узлу, missed — минуты без учёта до следующей дыры или кадра, encode — кадр не собрался; у live — disconnect, silence, subscribe_refused; у catalog — no_catalog или ошибка запроса каталога

Ряд волатильности книги

GET/v1/options/vol/book-range

Ряд волатильности одной книги — цепочки базы — по границам часа или суток: ATM IV постоянного срока 7, 30 и 90 суток, крылья 25Δ на 30 суток, RR, BF и индекс. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
chain книга базы, как у каталога. Без параметра — книга с именем базы, а если её нет и книга у базы одна — она; иначе 404. Присылайте всегда: без неё ряд зависит от того, какие книги листингуются сейчас
from обязательный: начало [from, to), Unix-мс UTC или ISO-8601; первая точка — первая граница шага не раньше него. Глубина тарифа — по нему
to обязательный: конец, не входит; from < to, при step=1h — не больше 90 суток, при step=1d — не больше 365 суток
step обязательный: 1h — границы часов, 1d — полночь UTC
Shell
curl -s "https://market-api.lootx.trade/v1/options/vol/book-range?base=BTC&venue=deribit&chain=BTC&from=1795089600000&to=1795100400000&step=1h" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chain": "BTC",
  "step": "1h",
  "from": 1795089600000,
  "to": 1795100400000,
  "asof_ms": 1795096800000,
  "coverage": {
    "complete": false,
    "gaps": [{"from_ms": 1795093200000, "to_ms": 1795093260000, "chain": "BTC", "stream": "chain", "reason": "no_frame"}]
  },
  "rows": [
    {"ts_ms": 1795089600000, "index": "62480.15", "atm_iv_bp": {"d7": 4810, "d30": 5120, "d90": null}, "put25_iv_bp_30d": 5390, "call25_iv_bp_30d": 4980, "rr25_bp_30d": -410, "bf25_bp_30d": 65},
    {"ts_ms": 1795096800000, "index": "62511.40", "atm_iv_bp": {"d7": null, "d30": 5105, "d90": null}, "put25_iv_bp_30d": null, "call25_iv_bp_30d": null, "rr25_bp_30d": null, "bf25_bp_30d": null}
  ]
}

Пример — три часа шагом 1h: точка второго часа — дыра, у последней точки нет срока 7 суток и крыльев.

Поле Что
venue, base, chain, step, from, to запрос, как его понял источник: chain — выбранная книга
asof_ms ts_ms последней строки; строк нет — null
rows[].ts_ms точка — минута, которая начинается ровно на границе шага: границы — кратные шага от 1970 года, сутки — по UTC
rows[].index индекс минуты точной десятичной строкой; null — индекса нет (OKX его не шлёт)
atm_iv_bp ATM IV постоянного срока: d7, d30, d90 — по полной дисперсии между экспирациями вокруг срока, по mark; срок раньше первой экспирации или позже последней — null, а не IV ближайшей
put25_iv_bp_30d, call25_iv_bp_30d IV пута и колла с дельтой 25 % на сроке 30 суток; дельта — Black-76 по форварду
rr25_bp_30d risk reversal: колл − пут
bf25_bp_30d butterfly: (колл + пут) / 2 − ATM 30 суток
coverage.complete true — ни одной дыры
coverage.gaps[] дыры: точки подряд без строки с одной причиной — [from_ms, to_ms), to_ms — конец минуты последней точки; stream — chain; reason — no_frame (кадра нет), gap (кадр не восстанавливается), replay_limit (за один запрос не дошли — повторите запрос, точки догрузятся)

IV, RR и BF — целым, в 0,01 пункта волатильности: 5120 — 51,2 %. Любое число строки бывает null — расчёту не хватило экспираций или котировок; дыра — это нет строки, а не строка из null. Границы после новейшей минуты книги ещё не настали — это не дыра: таких строк просто нет.

Вес ряда — границы шага на 64: число границ шага в [from, to) делится на 64 и округляется вверх, — от 1 до 34 единиц лимитов: сутки часами — 1, 90 суток часами — 34, год сутками — 6. Повтор из кэша шлюза и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет step, from или to, from ≥ to, окно длиннее предела — стоит 1; глубже тарифа (403 history_out_of_plan) и CSV (400 bad_format) отказывают уже после списания полного веса.

Экспозиция

GET/v1/options/exposure/latest

GEX, DEX, VEX и CEX новейшей минуты одной книги — или всех книг базы разом — по страйкам группы экспираций: итоги группы, страйки и профиль net GEX по сетке цен. Знак дилера — naive. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога, или all — все книги базы на всех площадках (ниже); по умолчанию deribit
chain книга базы, как у ряда волатильности: без параметра — книга с именем базы, а если её нет и книга у базы одна — она; иначе 404. С venue=all — 400 bad_request (param: "chain"): книги берутся все
expiry группа экспираций от метки снимка: 0dte — поставка до конца текущих суток UTC, 1d, 7d, 31d, 91d — не позже снимка + N суток, all — все; по умолчанию all. Иная — 400 bad_request
mode знак дилера: только naive — коллы плюсом, путы минусом; по умолчанию naive. Иной — 400 bad_request
Shell
curl -s "https://market-api.lootx.trade/v1/options/exposure/latest?base=BTC&venue=deribit&chain=BTC&expiry=7d" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chain": "BTC",
  "expiry": "7d",
  "mode": "naive",
  "asof_ms": 1795096800000,
  "coverage": {"complete": true, "gaps": []},
  "usd_ccy": "USD",
  "spot": "62511.40",
  "expiries_ms": [1795161600000, 1795507200000],
  "totals": {"gex_usd_e8": "-4260000000000000", "dex_usd_e8": "18240000000000000", "vex_usd_e8": "-81200000000000", "cex_usd_e8": "-2735000000000"},
  "strikes": [
    {"strike": "62000", "gex_call_usd_e8": "1520000000000000", "gex_put_usd_e8": "-2810000000000000", "dex_usd_e8": "-4120000000000000", "vex_usd_e8": "-31500000000000", "cex_usd_e8": "1240000000000", "oi_call_coins": "1204.5", "oi_put_coins": "2310.1"},
    {"strike": "65000", "gex_call_usd_e8": "980000000000000", "gex_put_usd_e8": "-120000000000000", "dex_usd_e8": "8730000000000000", "vex_usd_e8": "26400000000000", "cex_usd_e8": "-950000000000", "oi_call_coins": "3150", "oi_put_coins": "212.4"}
  ],
  "profile": [
    {"price": "53134.69", "gex_usd_e8": "3905000000000000"},
    {"price": "53290.97", "gex_usd_e8": "3871000000000000"},
    {"price": "71888.11", "gex_usd_e8": "-1532000000000000"}
  ]
}

Пример сокращён: страйков — два, точек профиля — три из 121.

Поле Что
venue, base, chain, expiry, mode запрос, как его понял источник: chain — выбранная книга, у venue=all — null
asof_ms минута расчёта; минуты нет — null
usd_ccy валюта всех *_usd_e8 ответа — котировка книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; у venue=all — валюта опорной книги (ниже)
spot индекс точной десятичной строкой; у книги без индекса (OKX его не шлёт) — null, а профиль пуст
expiries_ms экспирации группы, Unix-мс UTC
totals итоги группы: gex_usd_e8 — net GEX, dex_usd_e8, vex_usd_e8, cex_usd_e8 — целым e8 строкой; книга без минуты, без расчёта или с переполнением — null
strikes[] страйк группы: strike — десятичной строкой в шкале страйка; gex_call_usd_e8 и gex_put_usd_e8 — GEX коллов и путов, dex_usd_e8, vex_usd_e8, cex_usd_e8 — целым e8 строкой; oi_call_coins и oi_put_coins — OI коллов и путов в монетах базы десятичной строкой; у venue=all ещё venue_share
profile[] net GEX группы, если бы цена была price: 121 точка, ±15 % от spot шагом 0,25 %; price — spot × (1 + x) в шкале цены
coverage complete — ни одной дыры; gaps[] — {from_ms, to_ms, chain, stream: "chain", reason}: no_frame — у книги нет минуты, no_calc — расчёта нет, money_overflow — не уместилось в e8, иначе — причина сборки минуты

Экспозиция — в деньгах котировки книги. D — позиция дилера в монетах по знаку naive (коллы плюсом, путы минусом), F — форвард строки. GEX = Γ × D × F² × 0,01 — хедж на ход цены в 1 %; DEX = Δ × D × F — дельта; VEX = vanna × D × F × 0,01 — сдвиг дельты на +1 пункт IV; CEX = charm × D × F / 365 — сдвиг дельты за сутки. Все *_usd_e8 — целым e8 строкой со знаком, кроме gex_call_usd_e8, в валюте usd_ccy: USDT — не USD, ответы книг разных котировок без перевода курсом не складывайте.

null и пусто — «нет данных», а не 0. Книга без минуты, без расчёта или с переполнением отвечает 200: totals: null, пустые strikes и profile и дыра в coverage.gaps. Группа 0dte с 08:00 до полуночи UTC пуста: expiries_ms: [], итоги — нули, strikes пуст.

Все площадки

venue=all — все книги базы на всех площадках разом: каждая книга переводится к индексу опорной — первой книги с индексом в порядке deribit, binance, bybit, okx, внутри площадки первой идёт книга с именем базы. Минута ответа — новейшая общая: пока последняя площадка не дописала новую минуту, приходит предыдущая у всех книг, а не часть книг.

У страйка — venue_share: доля каждой площадки в |net GEX| страйка по модулю, {deribit, binance, bybit, okx}, вместе — 1, четыре знака; площадка без вклада — 0, у страйка с нулевым GEX все доли — null.

Дыры книг у venue=all называют площадку: no_frame:okx, no_calc:binance, other_minute:deribit — книги нет в минуте ответа, no_index:okx — книга без индекса в ответ не входит. Дыры ответа целиком — без площадки, chain — база: no_index — ни одного индекса, sum_refused: …, money_overflow.

Ответ живой: Cache-Control: private, no-cache и ETag; пришлите метку в If-None-Match — та же минута придёт 304. Кэш шлюза его не держит. Вес экспозиции — 1 единица: окна и глубины тарифа у неё нет.

История уровней

GET/v1/options/levels/range

История уровней одной книги по границам шага: индекс, форвард, zero gamma, стены коллов и путов, abs gamma, net GEX, max pain и ожидаемый ход ближайшей поставки группы. Знак дилера — naive. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit. all — 400 bad_request: уровни — одной книги, ряда по всем площадкам пока нет
chain книга базы, как у ряда волатильности. Присылайте всегда: без неё ряд зависит от того, какие книги листингуются сейчас
expiry группа экспираций, как у экспозиции; по умолчанию all
mode только naive, как у экспозиции
from обязательный: начало [from, to), Unix-мс UTC или ISO-8601; первая точка — первая граница шага не раньше него. Глубина тарифа — по нему
to обязательный: конец, не входит; from < to, при step=1m — не больше 7 суток, при step=5m — не больше 30 суток, при step=1h — не больше 90 суток (ровно предел проходит)
step обязательный: 1m, 5m или 1h — границы, кратные шагу от 1970 года
Shell
curl -s "https://market-api.lootx.trade/v1/options/levels/range?base=BTC&venue=deribit&chain=BTC&from=1795089600000&to=1795100400000&step=1h" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "venue": "deribit",
  "base": "BTC",
  "chain": "BTC",
  "expiry": "all",
  "mode": "naive",
  "step": "1h",
  "from": 1795089600000,
  "to": 1795100400000,
  "asof_ms": 1795096800000,
  "coverage": {
    "complete": false,
    "gaps": [{"from_ms": 1795093200000, "to_ms": 1795093260000, "chain": "BTC", "stream": "calc", "reason": "no_calc"}]
  },
  "usd_ccy": "USD",
  "rows": [
    {"ts_ms": 1795089600000, "spot": "62480.15", "fwd": "62528.7", "zero_gamma": "61850.3", "zero_gamma_sticky_delta": null, "unstable": false, "call_walls": ["65000", "70000"], "put_walls": ["60000", "58000"], "abs_gamma": "60000", "net_gex_usd_e8": "-4115000000000000", "max_pain": "62000", "max_pain_expiry_ms": 1795161600000, "move_straddle_bp": 121, "move_sigma_bp": 152},
    {"ts_ms": 1795096800000, "spot": "62511.40", "fwd": "62560.1", "zero_gamma": null, "zero_gamma_sticky_delta": null, "unstable": false, "call_walls": ["65000", "70000"], "put_walls": ["60000", "55000"], "abs_gamma": "60000", "net_gex_usd_e8": "-4260000000000000", "max_pain": "62000", "max_pain_expiry_ms": 1795161600000, "move_straddle_bp": 118, "move_sigma_bp": 148}
  ]
}

Пример — три часа шагом 1h: у точки второго часа нет строки расчёта, у последней точки профиль не меняет знак.

Поле Что
venue, base, chain, expiry, mode, step, from, to запрос, как его понял источник: chain — выбранная книга
asof_ms ts_ms последней строки; строк нет — null
usd_ccy валюта net_gex_usd_e8 — котировка книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; строк нет — null
rows[].ts_ms точка — минута, которая начинается ровно на границе шага
spot, fwd индекс и форвард ближайшей поставки группы точной десятичной строкой
zero_gamma цена, где профиль net GEX меняет знак; смены знака на сетке нет — null
zero_gamma_sticky_delta, unstable второй режим волатильности — пока всегда null и false
call_walls, put_walls две стены: страйки с наибольшим GEX коллов выше индекса и путов ниже, главная первой; стены — null или [null, null] у книги без индекса
abs_gamma страйк с наибольшей суммой модулей GEX коллов и путов
net_gex_usd_e8 net GEX группы в валюте usd_ccy — целым e8 строкой со знаком; нет экспирации в группе (у 0dte — с 08:00 до полуночи UTC) — "0"
max_pain, max_pain_expiry_ms max pain ближайшей поставки группы и её срок; нет экспирации в группе — null
move_straddle_bp, move_sigma_bp ожидаемый ход ближайшей поставки группы с ATM IV, в базисных пунктах от форварда: модельный ATMF-страддл и σ√T, T — до поставки от снимка
coverage.complete true — ни одной дыры
coverage.gaps[] дыры: точки подряд без строки с одной причиной — [from_ms, to_ms), to_ms — конец минуты последней точки; stream — calc; reason — no_calc (граница не позже новейшей минуты книги, а строки расчёта нет), no_frame (у книги нет ни одной минуты)

Цены и страйки — точной десятичной строкой в шкале инструмента, null — «нет данных», а не 0: дыра — это нет строки, а не строка из null. Границы после новейшей минуты книги ещё не настали — это не дыра: таких строк просто нет. Дыру с осевшими границами источник держит до 10 минут: дозалитая строка появится не позже чем через 10 минут.

Вес истории уровней — точки шага на 1440: число границ шага в [from, to) делится на 1440 и округляется вверх, — от 1 до 7 единиц лимитов: сутки минутами — 1, 7 суток минутами — 7, 30 суток по 5 минут — 6, 90 суток часами — 2. Повтор из кэша шлюза и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет step, from или to, from ≥ to, окно длиннее предела, venue=all, иные expiry или mode — стоит 1; глубже тарифа (403 history_out_of_plan) и CSV (400 bad_format) отказывают уже после списания полного веса.

Живой поток

GET/v1/options/stream

WebSocket кадров цепочек базы: сначала текст hello, затем кадры OPC1 — по одному на сообщение. Группа тарифа — options.

Параметр Что
base обязательный, как у каталога
venue площадка, как у каталога; по умолчанию deribit
chain цепочки базы через запятую, до 64 цепочек; каждая — A-Z, 0-9, _, до 32 знаков. Без параметра — все цепочки базы на момент соединения; набор держится всё соединение, новая цепочка — только в новом соединении
resume продолжение после обрыва: <epoch>:<цепочка>:<seq> через запятую, по одному на цепочку — ниже

Адрес — wss://market-api.lootx.trade/v1/options/stream, отдельный от /v1/ws. Ключ — как у /v1/ws: заголовком или подпротоколом ["lx.v1", "key.<ключ>"] (подключение). Команд у потока нет: сообщения клиента читаются и отбрасываются.

JavaScript
const ws = new WebSocket("wss://market-api.lootx.trade/v1/options/stream?base=BTC", ["lx.v1", `key.${apiKey}`]);
ws.binaryType = "arraybuffer";

Первое сообщение — текст JSON hello:

JSON
{"type": "hello", "epoch": "3f9c0a1b2c3d4e5f", "venue": "deribit", "base": "BTC", "chains": [{"chain": "BTC", "seq": 41, "live": true}, {"chain": "BTC_USDC", "seq": 7, "live": false}]}
Поле hello Что
epoch процесс источника, 16 hex: другой процесс — другая эпоха
chains[].seq кадр, на котором цепочка стоит: с него начнётся её поток; 0 — кадров ещё не было, первый придёт ключевым
chains[].live у цепочки есть живой канал: кроме кадров минуты идут живые кадры

Кадры — по одному на бинарное сообщение, без uvarint-длины: раскладка та же, формат предварительный — байт 4 кадра сверяйте. По каждой цепочке сначала ключевой кадр на hello.seq (с resume — пропущенные кадры), затем каждый новый по порядку:

  • кадр минуты — новейшая минута цепочки, та же, что у /v1/options/chain/latest: дельта к кадру перед ней, когда строки и шкалы те же, иначе ключевой — листинг, новая строка;
  • живой кадр — только у цепочек с live: true: дельта, в которой меняются только mark и iv_bp строк, не чаще раза в секунду на цепочку; ts_min, catalog_ver и прочие поля — от минуты.

seq заголовка кадра — счёт потока, а не минуты: u32 на цепочку, +1 на кадр. Дельта ссылается на кадр перед ней (ref_ts_min, ref_snap_ts). Сверяйте, что seq — прошлый + 1 и звено дельты совпало; разрыв — переподключитесь с resume. Источник пингует раз в 20 с.

Продолжение потока

resume — epoch из hello и seq последнего принятого кадра каждой цепочки, элементы — через запятую: resume=3f9c0a1b2c3d4e5f:BTC:41. Тот же процесс и seq ещё в его памяти — придут ровно пропущенные кадры; новая эпоха, seq, которого уже нет в памяти, или seq из будущего — ключевой кадр. В новом hello seq — кадр, на котором вы теперь стоите.

Отказы — до апгрейда, обычным HTTP-ответом с телом ошибки, как у REST, а не 101 и закрытием: 400 bad_request — параметр не той формы, больше 64 цепочек, format или table; 400 upstream_rejected — bad_resume → resume, bad_chain → chain; 404 not_found — нет присланной цепочки или у базы нет ни одной; 429 ws_limit — заняты все ws_conns тарифа; 503 upstream_unavailable с Retry-After — источник загружает цепочки после запуска или держит предельное число соединений потока.

Отметка «поток выключен» на узле — выкладка, а не окончательный отказ: приходит 503 upstream_unavailable с Retry-After: 30.

Код закрытия Причина Что делать
4008 slow consumer клиент не успевал читать: очередь 64 кадра или отправка дольше 5 с. Переподключитесь с resume
1011 hello источник не собрал hello. Переподключитесь
1001 — источник останавливается. Переподключитесь с resume: у нового процесса другая эпоха — придёт ключевой кадр
1013 upstream_unavailable источник оборвал соединение. Переподключитесь с паузой и resume
1008 daily_quota_exceeded, revoked_key, plan_inactive, invalid_key, insufficient_scope, route_not_in_plan кончился суточный объём или доступ — как у /v1/ws, но кадра error перед закрытием нет: код — только в причине

Учёт. Соединение — один запрос группы options и одно место из ws_conns тарифа на всё время соединения. Байты hello и кадров идут в суточный объём аккаунта и группы options; пинги — нет.

Форматы

  • JSON (по умолчанию) — тело источника байт в байт.
  • protobuf — общий конверт lootx.v1.Response (форматы): поля верхнего уровня — в meta, вложенное (цепочки, строки, экспирации, дыры) — JSON-текстом.
  • CSV нет: ответы — вложенные объекты, таблицей их не разложить. format=csv и Accept: text/csv — 400 bad_format, в message — форматы маршрута.
  • format=opc1 — только у /v1/options/chain, /v1/options/chain/latest и /v1/options/chain/range: кадры OPC1 источника насквозь, application/octet-stream. У баз, каталога, экспираций, покрытия, ряда волатильности, экспозиции и истории уровней — 400 bad_format. По заголовку кадры не выбираются: Accept: application/octet-stream без параметра — 406 not_acceptable.

JSON и protobuf — стабильные формы ответа: они меняются только вместе с версией API. Поток /v1/options/stream — не ответ, а WebSocket: hello текстом JSON и кадры OPC1 (живой поток); format у него нет.

Чего нет в ответе OPC1, сказано только в заголовке x-options-missing (два синтаксиса). Ошибки приходят JSON и при format=opc1: сначала проверьте код ответа. Как устроен ответ кадрами, коротко сказано и в спецификации — ответ application/octet-stream этих трёх маршрутов в /v1/openapi.json.

Раскладка кадров OPC1

Тело минуты (chain, chain/latest) — на каждую цепочку минуты uvarint-длина и один ключевой кадр, встык до конца тела; дельт в нём нет. Тело диапазона (chain/range) — кадры одной цепочки по минутам, у каждого uvarint-длина, встык до конца тела: первый — ключевой, следующие — как их хранит источник, ключевой кадр часа или дельта к кадру перед ней, версии 1 и 2 вперемешку. Проигрывайте их по порядку и сверяйте звено каждой дельты (ref_ts_min, ref_snap_ts) с кадром перед ней: не совпало — цепочка разорвана, не читайте дальше наугад. Шлюз тело не сжимает: DEFLATE уже внутри кадра. Заголовок кадра:

Байты Что
0–3 магия OPC1
4 версия раскладки: сейчас пишется 2, бывает и 1. Незнакомую — отвергайте
5 флаги: бит 0 — тело сжато сырым DEFLATE. Незнакомые биты — отвергайте
6–7 длина заголовка, u16 little-endian: с этого байта начинается тело
8 вид кадра: 0 — ключевой, 1 — дельта (только в теле диапазона). Незнакомый — отвергайте
9 площадка: 1 — Deribit, 2 — Binance, 3 — Bybit, 4 — OKX
дальше varint-ы: цепочка (uvarint-длина и ASCII), catalog_ver, ts_min, snap_ts − ts_min (zigzag), сдвиг OI назад от snap_ts в мс, номер кадра, число строк; затем у ключевого — шкалы значений и множитель контракта, у дельты — опорный кадр: ref_ts_min и ref_snap_ts − ref_ts_min (zigzag)

Значения в теле — целые в шкалах заголовка, деньги — в e8, как *_usd_e8 в JSON. Пределы: кадр — до 8 МиБ и после распаковки, строк — до 16 384, экспираций — до 1 024, имя цепочки — до 32 байт. Раскладка тела меняется вместе с версией: читайте кадр, только если знаете его байт 4.

Кэш и ETag

У каждого ответа 200 есть ETag; одна метка у JSON, protobuf и сжатого тела того же ответа.

  • Пришлите метку в If-None-Match — если ответ не изменился, придёт 304 без тела с теми же ETag, Cache-Control и x-options-missing: запрос засчитывается, а в суточный объём не идёт. Сравнение слабое: W/"…", список меток и * тоже подходят.
  • Неизменны — Cache-Control: private, max-age=31536000, immutable — четыре ответа: /v1/options/chain за целую осевшую минуту (все цепочки базы на месте, у каждой строки есть имя инструмента, после закрытия прошло 2 минуты), /v1/options/chain/range за целый осевший диапазон (ни одной минуты без кадра, после to прошло 2 минуты) /v1/options/vol/book-range за целый осевший ряд (ни одной дыры, у книги есть расчёт, после минуты последней границы прошло 2 минуты) и /v1/options/levels/range за целый осевший ряд (строка у каждой границы, последняя граница осела). Повтор шлюз отдаёт из своего кэша (X-Cache: HIT).
  • Свежая или неполная минута chain, диапазон chain/range в настоящее или с пропусками, ряд vol/book-range или levels/range с неосевшей границей или с дырами, chain/latest, exposure/latest, bases, catalog, expiries и coverage — private, no-cache: кэшируйте с меткой и спрашивайте с If-None-Match.
Shell
curl -s -o /dev/null -w "%{http_code}\n" "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC" \
  -H "Authorization: Bearer $LOOTX_API_KEY" -H 'If-None-Match: "f42b9c0e7d1a3b55"'

Глубина истории

Глубину проверяет тариф — history_days: меньший из общего и группового (группы options), если у группы свой. Меряется не у всех маршрутов:

  • /v1/options/chain — по минуте ответа. Меряется начало минуты, закрытой в at. Глубже тарифа — 403 history_out_of_plan с param: "at"; earliest_allowed_ms в отказе — первый at, который пройдёт.
  • /v1/options/chain/range — по from. Глубже тарифа — 403 history_out_of_plan с param: "from". earliest_allowed_ms в этом отказе бывает не кратен минуте, а from — целая минута: округлите его вверх до минуты.
  • /v1/options/coverage — по from. Без from — по суткам до «сейчас». Глубже тарифа — 403 history_out_of_plan с param: "from".
  • /v1/options/vol/book-range — по from. Глубже тарифа — 403 history_out_of_plan с param: "from", уже после списания полного веса (до 34 единиц).
  • /v1/options/levels/range — по from. Глубже тарифа — 403 history_out_of_plan с param: "from", уже после списания полного веса (до 7 единиц). Сколько истории есть у книги, говорит покрытие: дыры расчёта в нём не видны — они в coverage.gaps самого ряда.
  • bases, catalog, expiries, chain/latest, exposure/latest и поток окна не имеют и глубиной не меряются.

Отказы

Источник отказывает телом {"error", "detail"} — кодом и пояснением. Клиенту оно не приходит как есть: шлюз отвечает своим телом ошибки, код и пояснение источника — в message, параметр — в param.

Ответ Когда Что делать
400 bad_request параметр, которого нет у маршрута, или повтор параметра — и в процентной записи имени (b%61se — тоже base); нет base, at, а у chain/range — chain, from или to; base, venue, chain, instrument не той формы; at, from, to не мс и не ISO-8601, в секундах или микросекундах; у chain/range — не целые минуты, from ≥ to, больше 360 минут, JSON или protobuf без instrument, format=opc1 с instrument; у vol/book-range — нет step или он не 1h и не 1d, from ≥ to, больше 90 суток при step=1h или 365 суток при step=1d (param: "to"); у exposure/latest и levels/range — expiry не из групп, mode не naive; у exposure/latest — chain при venue=all; у levels/range — venue=all, нет step или он не 1m, 5m, 1h, from ≥ to, больше 7 суток при step=1m, 30 при 5m, 90 при 1h (param: "to") — до источника. param — его имя исправьте запрос по param и expected
400 bad_format format=csv или Accept: text/csv; format=opc1 у баз, каталога, экспираций, покрытия, ряда волатильности, экспозиции или истории уровней; неизвестный format message называет форматы маршрута: format=json или protobuf, у цепочек — format=json, protobuf или opc1
406 not_acceptable в Accept нет ни одного известного шлюзу типа — в том числе Accept: application/octet-stream без параметра. Accept: text/csv — не 406, а 400 bad_format Accept: application/json или application/x-protobuf — типы маршрута в expected; кадры OPC1 — только ?format=opc1
400 upstream_rejected источник отверг значение; param — по его коду: bad_base → base, bad_venue → venue, bad_chain → chain, bad_at → at, bad_format → format, bad_range → from, range_too_long → to, bad_instrument → instrument, bad_resume → resume исправьте названный параметр
403 insufficient_scope токен без области derivatives — например, бесплатный токен терминала запрашивайте с API-ключом
403 route_not_in_plan тариф закрыл группу options смените тариф
403 history_out_of_plan минута at или from глубже тарифа — выше at или from не раньше earliest_allowed_ms
404 not_found у chain и chain/latest нет минуты у базы или у присланной chain, либо минута не восстанавливается (gap); у chain/range нет цепочки у базы, инструмента у цепочки или в диапазоне не отдать ни одной минуты (gap — ни одна не восстанавливается); у vol/book-range, exposure/latest и levels/range нет книги у базы — присланной chain или книги по умолчанию, у exposure/latest с venue=all — ни одной книги базы; у потока нет присланной цепочки или у базы нет ни одной другая минута или диапазон; дыры — в покрытии
429 rate_limited и другие 429 лимит тарифа; chain/range весит 1–6 единиц — вес запроса, vol/book-range — 1–34 (вес ряда), levels/range — 1–7 (вес истории уровней); у потока ещё 429 ws_limit — заняты все ws_conns повторите после Retry-After
503 upstream_unavailable источник загружает цепочки после запуска или склад не читается; у vol/book-range — источник уже собирает предельное число рядов со склада, у levels/range — уже читает предельное число рядов уровней; у потока — предельное число соединений или «поток выключен» (Retry-After: 30). Приходит с Retry-After источника — обычно Retry-After: 1, не дольше 60 с повторите через Retry-After
502 upstream_error источник ответил ошибкой или телом не той формы (деньги числом, не кадры на format=opc1), маршрутов опционов у источника нет повторите позже; не проходит — напишите в поддержку с request_id
502 upstream_unavailable, 504 upstream_timeout источник недоступен или не ответил вовремя повторите позже

Все коды — на странице ошибок.

https://docs.lootx.trade/uk/market-api/options

Форматы и потоки

14Форматы ответа, числа и деньги

JSON, protobuf или CSV одним параметром; в каких единицах приходят цены, объёмы и суммы и почему деньги не округляются до шага цены.

Выбор формата

По умолчанию ответ — JSON. Тот же ответ можно получить бинарным protobuf или CSV — параметром или заголовком:

Формат Параметр Заголовок Accept Content-Type ответа
JSON ?format=json application/json application/json
protobuf ?format=protobuf application/x-protobuf application/x-protobuf; messageType=lootx.v1.Response
CSV ?format=csv text/csv text/csv; charset=utf-8
HMP1 / HMP2 ?format=hmp1, hmp2 — только /v1/heatmap, отдельный формат
OPC1 ?format=opc1 — только /v1/options/chain, /v1/options/chain/latest и /v1/options/chain/range: application/octet-stream, предварительный формат
  • Параметр главнее заголовка.
  • Неизвестный формат — 400 bad_format; формат не этого маршрута — тоже: opc1 вне цепочек опционов, CSV у ответа без таблицы — и ?format=csv, и Accept: text/csv. В message — форматы, которые есть у маршрута.
  • 406 not_acceptable — в Accept нет ни одного известного шлюзу типа: ни JSON, ни protobuf, ни text/csv, ни маски вроде */*. В отказе — типы этого маршрута, у ответов без таблицы — без text/csv.
  • OPC1 — предварительный формат: версия кадра (байт 4 после магии OPC1) может вырасти без смены версии API, клиент сверяет её и отвергает незнакомую. Выбирается только параметром format=opc1: Accept: application/octet-stream без параметра — 406 not_acceptable. JSON и protobuf — стабильны.
  • Ошибки — всегда JSON, в каком бы формате вы ни просили ответ. Проверяйте код ответа прежде, чем разбирать тело.
  • Суточный объём тарифа считается по фактически отданному телу: protobuf обычно короче JSON.
Shell
curl -s "https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1h&limit=24&format=csv" \
  -H "Authorization: Bearer $LOOTX_API_KEY"
TEXT
ts,open,high,low,close,volume,quote_volume,buy_volume,buy_quote_volume,trades,buy_trades
1793664000000,103877.2,104412.0,103801.5,104250.5,2210.41,229972451.07,1150.88,119730911.64,98412,51270

CSV

RFC 4180: первая строка — имена колонок, null — пустое поле, пустая строка — "", массивы и объекты — JSON-текстом. Курсор следующей страницы — в заголовке X-Next-Cursor. CSV — одна таблица: у /v1/footprint их две, выберите ?format=csv&table=levels или table=windows. У ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) CSV нет.

protobuf

Один конверт lootx.v1.Response на любой маршрут. Схема — GET /v1/proto, ключ для неё не нужен.

  • таблицы лежат по колонкам: sint64 для целых и времени в мс, uint64 для целых больше 2⁶³−1, double, string, bool; колонки с массивами, объектами или смесью типов — JSON-текстом в strings; в колонке double номера строк, где в JSON было целое, лежат в int_rows; null — номерами строк;
  • главная таблица — с пустым именем и всегда первая, вложенные (levels, windows у футпринта) — под именем поля;
  • прочие поля ответа (instrument, tf, coverage, …) — в meta, курсор — в next_cursor.

Перевод взаимно однозначный: из protobuf восстанавливается ровно тот же JSON, а целые больше 2⁵³ не теряются.

Shell
curl -s https://market-api.lootx.trade/v1/proto -o lootx.proto
protoc --python_out=. lootx.proto

Числа и деньги

Числа приходят готовыми к использованию — в человеческих единицах, без шкал, которые нужно применять самому. Исключения названы в таблице: деньги полос книги, маржи и опционов — целым e8 строкой, цены mark, объём тейкера long/short, количества, цены и ставки маржи, цены, страйки и количества опционов — десятичной строкой.

Что В чём Пример колонок
Цена в валюте котировки инструмента; у /v1/mark — строкой, десятичная запись биржи price, open, close, mark_price, mark, index
Количество в монетах (базовой валюте); объём тейкера /v1/ls-ratio — строкой qty, volume и buy_volume в REST, bid_qty, buy_vol
Деньги в валюте котировки; у USDT- и USDC-пар — практически доллары quote_volume, quote_qty, *_quote, usd, *_usd, notional_usd, volume в канале candles потока
Деньги e8 e8 строкой: целое, 1 = 10⁻⁸ доллара; у полос книги — USD, у маржи — USDT × 10⁸, у опционов — USD, USDT или USDC × 10⁸ по площадке, цепочке и полю: номинал — только у Bybit, остальное — премия; USDT — не USD bid_bp…_e8, ask_bp…_e8 у полос книги, *_usd_e8 у маржинального кредитования и опционов
Ставка, доля доля, не проценты: 0.0001 = 0,01 % rate, funding_rate, premium, long_ratio
Время Unix-мс UTC, целым ts, t, first_ts
Номера строкой, если число может быть больше 2⁵³ wall_id, id у айсбергов

Внутри хранилища цены и объёмы живут целыми со своими шкалами, но в JSON, CSV и protobuf шлюз отдаёт их уже переведёнными. Шкалы видны только в бинаре тепловой карты: там price_scale и qty_scale стоят в заголовке, и переводить нужно самому — как.

Числа в JSON — обычные JSON-числа двойной точности, кроме строк из таблицы выше. Для денежных расчётов в своём коде переводите их в Decimal (Python) или в целые центы — и суммируйте уже их, а не float.

https://docs.lootx.trade/uk/market-api/formats

Форматы и потоки

15Потоки WebSocket

Одно соединение /v1/ws на несколько каналов — плотности, скринер, сделки, открытый интерес и секундные свечи; подписка по инструментам или на весь рынок с фильтрами, команды, кадры, пределы и коды закрытия.

wss://market-api.lootx.trade/v1/ws — одно соединение на несколько каналов и инструментов — в пределах тарифа и пределов соединения. Кадры — JSON с именами venue:market:SYMBOL и временем в Unix-мс, как у REST; написание имени в кадре может отличаться от вашего.

Поток опционов — отдельный адрес wss://market-api.lootx.trade/v1/options/stream со своим протоколом: текст hello и кадры OPC1, без команд и каналов, группа тарифа — options, а не ws (живой поток). Ключ передаётся так же, как здесь.

Подключение

Ключ — как у REST: Authorization: Bearer <ключ> или X-API-Key. Из браузера заголовок не задать, поэтому ключ передаётся подпротоколом: ["lx.v1", "key.<ключ>"] — сервер выберет lx.v1. В адрес ключ не кладётся.

JavaScript
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "subscribe", id: 1, channel: "trades",
    instruments: ["binance:perp:BTCUSDT"],
  }));
};

ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "update" && m.channel === "trades") {
    for (const t of m.data.trades) console.log(m.instrument, t.side, t.price, t.qty);
  } else if (m.type === "error") {
    console.warn(m.code, m.message);
  }
};

ws.onclose = (e) => console.log("закрыто", e.code, e.reason);
Python
import asyncio, json, os
import websockets   # pip install "websockets>=14"

async def main():
    headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
    async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
                                  additional_headers=headers) as ws:
        await ws.send(json.dumps({"op": "subscribe", "id": 1, "channel": "densities",
                                  "instruments": ["binance:perp:BTCUSDT"]}))
        async for raw in ws:
            m = json.loads(raw)
            if m["type"] == "snapshot":
                print("стен:", len(m["data"]["walls"]))
            elif m["type"] == "update":
                print("+", len(m["data"]["upsert"]), "-", len(m["data"]["remove"]))

asyncio.run(main())

Сервер шлёт WS-ping каждые 5 секунд (одновременно с проверкой доступа) — библиотеки отвечают на него сами.

Команды

Текстовые JSON-кадры, не больше 64 КиБ:

JSON
{"op":"subscribe","id":1,"channel":"densities","instruments":["binance:perp:BTCUSDT","hyperliquid:perp:BTC"]}
{"op":"unsubscribe","id":2,"channel":"densities","instruments":["binance:perp:BTCUSDT"]}
{"op":"unsubscribe","id":3,"channel":"densities"}
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000}}
{"op":"unsubscribe","id":6,"channel":"densities","scope":"market"}
{"op":"ping","id":4}
  • id — любое число или строка; сервер вернёт его в ответе на команду. На каждую команду с id приходит ответ с этим id, пока соединение открыто: subscribed, unsubscribed, pong или error.
  • unsubscribe без непустого массива instruments снимает все инструменты канала; рыночную подписку — нет, она снимается со scope: "market".
  • params у подписки по инструментам, кроме null и пустого объекта, дают bad_params. Фильтры есть у подписки на весь рынок.

Кадры сервера

type Когда Поля
subscribed подписка принята id, channel, instruments — имена, под которыми пойдут кадры, с одним исключением
unsubscribed снята id, channel, instruments
snapshot состояние инструмента целиком channel, instrument, t, data
update изменение channel, instrument, t, data
removed инструменты вышли из рыночной подписки channel, scope, t, instruments
status связь с источником channel, state, instruments, message
error отказ id, code, message, instrument
pong ответ на ping id

У рыночной подписки кадры другой формы — см. ниже. По каждому инструменту сначала приходит ровно один snapshot, потом update (у trades снимка нет). snapshot может прийти снова — после обрыва источника: это «замените состояние целиком», а не дубль. После unsubscribed ещё могут дойти кадры, уже стоявшие в очереди.

Обрыв источника соединение не рвёт. Приходит status с state: "reconnecting" и списком задетых инструментов; шлюз сам переподключается к источнику и повторяет подписки, затем state: "live" и свежие снимки. state: "gap" — источник потерял кадры без восстановления (бывает у ленты сделок): дочитайте пропуск через REST.

Каналы

Канал snapshot.data update.data Группа тарифа
densities {"walls": [стена…]} {"upsert": [стена…], "remove": [{"wall_id", "reason", "duration_ms"}]} densities
screener метрики {"last_price": …, …} изменившиеся метрики; null — значение сброшено screener
trades — {"trades": [{"ts", "price", "qty", "quote_qty", "side", "fills", "aggregated"}]} trades
oi бар текущей минуты или null бар минуты; незакрытый — с растущим samples oi
candles {"candles": [до 600 секундных свечей]} {"candles": […]} candles_1s
  • Стена — те же поля, что у /v1/densities: wall_id строкой, side, price, qty (в монетах), usd (в долларах), dist_bp, first_ts (мс), age_ms, peak_usd, touched, agg и, где есть, size, score. reason при удалении — pulled (снята) или eaten (съедена); null — служебное удаление.
  • Метрики скринера — длинные имена, как у /v1/screener.
  • Сделка: price (в валюте котировки), qty (в монетах), quote_qty (в валюте котировки, без округления к шагу цены), side — сторона агрессора.
  • Бар OI: bucket_ts (мс, начало минуты), samples, native_unit (coins, usd или contracts), native_open … native_close, oi_coins_open … oi_coins_close, oi_usd_open … oi_usd_close, price_used_close. Живой поток OI есть у binance, bybit, okx, bingx, kucoin, mexc, bitget, hyperliquid, aster и gate. У kraken и coinbase потока нет: подписка даёт unsupported_instrument, история — через REST /v1/oi. У остальных бирж OI в шлюзе нет: и подписка, и REST дают unsupported_instrument.
  • Свеча: ts (мс), open, high, low, close, volume (в валюте котировки, у USDT-пар это доллары), trades; trades: 0 — пустая секунда, OHLC равны прошлому закрытию. Это не volume из REST: в /v1/candles колонка volume — монеты, а сумма в котировке лежит в quote_volume. Значение volume канала соответствует quote_volume REST; объёма в монетах в канале нет.

Канал, группа которого закрыта тарифом, отвечает на подписку error route_not_in_plan; соединение при этом живёт.

Имена в кадрах

Кадры подписки называются не так, как написал клиент, а по имени инструмента на этом канале. Разные написания одного инструмента — одна подписка и одно имя в кадрах. Обычные символы (binance:perp:BTCUSDT, hyperliquid:perp:BTC) это не меняет. Особые случаи:

  • hyperliquid:perp:kPEPE и hyperliquid:perp:KPEPE идут как hyperliquid:perp:KPEPE на всех каналах, кроме oi. На oi имя монеты остаётся как у биржи: kPEPE и KPEPE, как и btc и BTC, — разные подписки под этими же именами.
  • binance:perp:btcusdt на каналах candles и densities идёт как binance:perp:BTCUSDT. На trades и oi регистр не приводится, на screener такое имя получает unsupported_instrument.
  • Варианты монеты Hyperliquid BTCUSDC и BTCUSDT в любом регистре хвоста идут как hyperliquid:perp:BTC. У screener hyperliquid:perp:BTCUSDC читается по его списку инструментов: монета без акции с таким именем идёт как hyperliquid:perp:BTC, остальное — как акция.
  • На screener дека нет: AAPLUSDC.XYZ и AAPLUSDC идут как hyperliquid:perp:AAPLUSDC, кадр один на все деки монеты.
  • Имя, которое не собирается обратно из имени источника (опечатка, котировка вне списка шлюза), идёт как написал клиент. На oi у bingx BT-CUSDT и BTCUSDT — разные имена источника, поэтому разные подписки и разные имена кадров.

Имя кадров называет subscribed, с одним исключением: несколько написаний такого имени, которые у источника совпадают, например hyperliquid:perp:AAPLUSDC.XYZUSDC и hyperliquid:perp:aaplusdc.xyzusdc на densities. subscribed отвечает каждому его написанием, а кадры идут под написанием первого подписчика, пока у инструмента есть подписчики. На одном соединении отписка одного написания останавливает кадры обоих, а второе считается подпиской, пока его не снимут или соединение не закроется. Настоящих символов это не касается.

unsubscribe принимает то имя, которым подписывались, а unsubscribed называет имя, под которым шла подписка.

Подписка не сверяет символ

unsupported_instrument в потоке значит, что у источника канала нет такого рынка или биржи, а на oi и screener ещё и что не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает.

  • Котировка на oi проверяется только у okx, bingx, mexc и kucoin: okx:perp:BTC-USDT-SWAP, kucoin:perp:XBTUSDTM.
  • Канал screener биржу не сверяет: неизвестная биржа подписку проходит. Он отказывает, если котировку не разобрать, и перпу с котировкой не из USDT, USDC и USD; перпов Hyperliquid это не касается.

Опечатка, имя которой шлюз смог перевести, подписку проходит: binance:perp:BTCUSDTT на candles, densities, trades и oi получит subscribed, а дальше в лучшем случае пустой snapshot. Данных не будет, ошибки тоже. Символ проверяют только REST /v1/candles и /v1/series, и не всегда. Молчание подписки не значит, что инструмент существует: имя берите из /v1/instruments.

Весь рынок

Подписка scope: "market" даёт весь рынок канала densities или screener без списка инструментов. Фильтры задаются в params, применяет их источник — тем же кодом, что и для терминала. У других каналов такой подписки нет: bad_params.

JSON
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000,"max_dist_pct":2}}
{"op":"subscribe","id":6,"channel":"screener","scope":"market","params":{"markets":["perp"],"fields":["last_price","volume_24h_usd"],"filters":[{"metric":"volume_24h_usd","op":"gt","value":1000000}]}}
{"op":"unsubscribe","id":7,"channel":"densities","scope":"market"}
  • Ответ — кадр subscribed с нормализованными params: что применено на самом деле. Он приходит раньше кадров подписки и не теряется, даже если следующая команда снимает её сразу.
  • subscribed и unsubscribed этой подписки идут через очередь к клиенту: в порядке команд и вслед за кадрами прежней подписки. Отказы error приходят сразу и могут их обогнать: сопоставляйте ответы по id.
  • В соединении одна рыночная подписка на канал. Повторный subscribe заменяет её: прежняя обрывается, после нового subscribed кадров старых фильтров нет. Неверная команда прежнюю подписку не трогает. Открывать подписку канала на соединении можно раз в секунду: чаще — rate_limited, прежняя подписка, если она есть, остаётся.
  • unsubscribe со scope: "market" снимает подписку и отвечает unsubscribed со scope, в том числе когда подписки не было. instruments в этой команде не читаются. Без scope рыночная подписка не снимается.
  • Непустой массив instruments вместе со scope: "market" в команде subscribe — bad_params.
  • Рыночная подписка и подписка канала по инструментам друг другу не мешают. Рыночная не считается ни в 200 подписок на соединение, ни в долю too_many_instruments.
  • Группа тарифа — та же, что у канала: закрытая группа даёт route_not_in_plan.

Фильтры densities

Параметр Значение
venues биржи массивом, тот же набор, что у /v1/densities. Нет параметра — все
markets массив из spot и perp. Нет параметра — все
min_usd номинал стены от этого значения, в долларах, не меньше 0
max_dist_pct дальше от середины стакана не идти, в процентах: 2 — это ±2 %. От 0.01 до 100, шаг 0.01: значение округляется до шага, в subscribed.params приходит округлённое. Округлилось в ноль — bad_params
side bid или ask
min_size класс стены не ниже указанного: weak, optimal или strong
agg tick (по умолчанию) или natr
hide_stables, hide_commodities, hide_stocks, hide_indices true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы
tier1_only true — только Tier-1

Удержание 10 %. Вход в подписку строгий, выход мягче. Стена, которую источник уже показал этому соединению, остаётся, пока usd не меньше 90 % от min_usd, а расстояние не больше max_dist_pct, делённого на 0,9, в целых базисных пунктах с округлением вверх. При min_usd: 250000 стена снимается ниже 225 000 $, при max_dist_pct: 2 — дальше 223 б.п., то есть 2,23 %. До этого приходят обычные upsert со значениями вне фильтра: не считайте их ошибкой. Остальные фильтры, min_size тоже, удержания не имеют.

Фильтры screener

Параметр Значение
venues биржи массивом, тот же набор, что у /v1/screener: Upbit у скринера нет. Нет параметра — все
markets массив из spot и perp. Нет параметра — все
fields какие метрики слать: длинные имена из GET /v1/screener/metrics массивом. Нет параметра — все
filters до 32 условий, выполняться должны все: {"metric":"volume_24h_usd","op":"gt","value":1000000}. op — gt, gte, lt, lte, eq, ne или between (вторая граница — в value2)
hide_stables, hide_commodities, hide_stocks, hide_indices true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы
tier1_only true — только Tier-1

Остальные параметры — bad_params с именем параметра в тексте ошибки, в том числе имена из REST (venue, market, coins). Окна и сортировки нет: top_n, sort_by, limit, offset тоже дают bad_params. Окно заморозило бы набор инструментов до следующей подписки, а подписка отдаёт весь отфильтрованный набор живьём: сузьте его через filters и сортируйте у себя.

Кадры рыночной подписки

У всех кадров этой подписки есть scope: "market", а данные лежат в items: [{"instrument", "data"}]. data — те же, что в таблице каналов.

JSON
{"type":"subscribed","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000.0,"max_dist_pct":2.0,"agg":"tick"}}
{"type":"snapshot","channel":"densities","scope":"market","t":1793750400000,"part":1,"parts":1,"complete":true,"items":[{"instrument":"binance:perp:BTCUSDT","data":{"walls":[…]}}]}
{"type":"update","channel":"densities","scope":"market","t":1793750401000,"items":[{"instrument":"binance:perp:ETHUSDT","data":{"upsert":[…],"remove":[…]}}]}
{"type":"removed","channel":"screener","scope":"market","t":1793750402000,"instruments":["binance:perp:BTCUSDT"]}
{"type":"unsubscribed","id":7,"channel":"densities","scope":"market"}
  • snapshot — всё состояние. Он идёт частями не длиннее 1 МиБ: part из parts. Первая часть заменяет всё, что было. Стены одного инструмента могут лежать в нескольких элементах items — сливайте их.
  • complete: false — снимок densities неполон. Причин четыре: шлюз выбрал предел запросов к источнику; снимок вышел за предел по байтам; срез одной биржи, рынка и стороны упёрся в предел стен, и делить его дальше нечем; источник не ответил. Числа — в пределах. Только в последнем случае за снимком приходит ещё status с state: "gap" и message. Дальше идут только изменения, новый снимок — повторной подпиской, а при упоре в предел — с более узкими фильтрами.
  • update — изменения, как в таблице каналов.
  • removed — инструменты вышли из фильтров скринера или символ снят.
  • Стена вышла из фильтров densities с учётом удержания — remove с reason: null в update.

Обрыв источника подписку не снимает. Приходит status с state: "reconnecting", шлюз сам переподключается, затем state: "live" и новый snapshot — у densities шлюз снимает его заново. status рыночной подписки — со scope: "market" и без instruments.

Пределы рыночной подписки

Что Предел Сверх предела
Рыночных подписок на аккаунт ws_market_subs тарифа — все ключи, соединения и каналы вместе. Ноль или нет поля — значение шлюза, одна подписка market_subs_limit с limit, remaining: 0, scope: "account", window: "concurrent"
Рыночных соединений шлюза потолок на канал, общий для всех клиентов, по умолчанию 8: на каждую подписку шлюз держит своё соединение с источником channel_unavailable с channel, scope: "market" и retry_after
Открытие подписки канала на соединении раз в секунду. Считается открытие: и замена, и снятие с повторной подпиской rate_limited с limit: 1, remaining: 0, scope: "connection", window: "second" и retry_after, прежняя подписка, если она есть, остаётся
Снимок densities 100 запросов к источнику, 5000 стен на срез одной биржи, рынка и стороны, потолок шлюза по объёму снимка complete: false
Снимков densities одновременно на шлюз 4, остальные подписки ждут очереди снимок приходит позже, изменения за это время копятся
Накопленные изменения шлюз копит их, пока подписка ждёт снимок или клиент забирает очередь; объём ограничен потолком шлюза за время снимка шлюз заново подключается к источнику, за время записи клиенту — slow_consumer и закрытие 1008
Очередь к клиенту подписка занимает не больше половины очереди и ждёт, пока клиент заберёт кадры; ответу на команду хватает любого свободного места slow_consumer и закрытие 1008
Суточный объём кадры идут в объём тарифа вместе с REST на исчерпанном объёме новая подписка получает daily_quota_exceeded

Снимок может быть длиннее очереди: клиент, который читает, получит его весь. slow_consumer приходит, если клиент за 10 секунд не освободил место под кадр подписки, если очередь забита целиком дольше 10 секунд и ответу на команду некуда встать либо если изменения, пришедшие за это время, вышли за потолок шлюза.

Место возвращается отпиской или закрытием соединения. Клиент, вернувшийся раньше, чем шлюз заметил обрыв старого сокета, может получить market_subs_limit: старое место ещё занято. Повторите подписку. channel_unavailable со scope: "market" без retry_after значит, что подписку остановил сбой шлюза: место уже свободно, подпишитесь заново.

Пример

JavaScript
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);
const walls = new Map();   // инструмент → wall_id → стена

const table = (name) => walls.get(name) ?? walls.set(name, new Map()).get(name);

ws.onopen = () => {
  ws.send(JSON.stringify({
    op: "subscribe", id: 1, channel: "densities", scope: "market",
    params: { venues: ["binance"], markets: ["perp"], min_usd: 250000, max_dist_pct: 2 },
  }));
};

ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === "error") return console.warn(m.code, m.message);
  if (m.scope !== "market") return;
  if (m.type === "snapshot") {
    if (m.part === 1) walls.clear();
    for (const { instrument, data } of m.items) {
      for (const w of data.walls) table(instrument).set(w.wall_id, w);
    }
    if (m.part === m.parts && !m.complete) console.warn("снимок неполон");
  } else if (m.type === "update") {
    for (const { instrument, data } of m.items) {
      for (const w of data.upsert) table(instrument).set(w.wall_id, w);
      for (const r of data.remove) table(instrument).delete(r.wall_id);
    }
  }
};
Python
import asyncio, json, os
import websockets   # pip install "websockets>=14"

SUBSCRIBE = {
    "op": "subscribe", "id": 1, "channel": "screener", "scope": "market",
    "params": {
        "markets": ["perp"],
        "fields": ["last_price", "volume_24h_usd"],
        "filters": [{"metric": "volume_24h_usd", "op": "gt", "value": 1000000}],
    },
}

async def main():
    headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
    rows = {}   # инструмент → метрики
    async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
                                  additional_headers=headers) as ws:
        await ws.send(json.dumps(SUBSCRIBE))
        async for raw in ws:
            m = json.loads(raw)
            if m["type"] == "error":
                print(m["code"], m["message"])
            elif m.get("scope") != "market":
                continue
            elif m["type"] == "snapshot":
                if m["part"] == 1:
                    rows.clear()
                for item in m["items"]:
                    rows[item["instrument"]] = item["data"]
            elif m["type"] == "update":
                for item in m["items"]:
                    rows.setdefault(item["instrument"], {}).update(item["data"])
            elif m["type"] == "removed":
                for name in m["instruments"]:
                    rows.pop(name, None)

asyncio.run(main())

Пределы

Что Предел Сверх предела
Одновременных соединений ws_conns тарифа, на аккаунт — все ключи вместе 429 ws_limit при подключении
Подписок на соединение 200; подписка — пара «канал + инструмент»: binance:perp:BTCUSDT в двух каналах занимает два места too_many_subscriptions, команда отвергается целиком
Команд от клиента 10 в секунду, запас 20 rate_limited, команда пропущена
Размер кадра клиента 64 КиБ соединение закрывается
Очередь кадров к клиенту 1024 кадра или 32 МиБ slow_consumer и закрытие 1008
Рыночные подписки свои пределы market_subs_limit, channel_unavailable, rate_limited

Ещё два ответа связаны с общей ёмкостью каналов: соединения шлюза с источниками делятся между всеми клиентами.

  • channel_unavailable с instrument — канал сейчас выбрал свой потолок соединений с источником. Повторите подписку позже. Со scope: "market" и retry_after это потолок рыночных соединений шлюза.
  • too_many_instruments с instrument — ваш аккаунт уже держит свою долю канала (по умолчанию — половину его ёмкости). Подписка на инструмент, который уже кто-то смотрит, места не занимает; отписка возвращает место.

Коды закрытия

Код Причина в reason Что делать
1008 slow_consumer клиент не успевает читать: разбирайте кадры быстрее или подпишитесь на меньшее
1008 daily_quota_exceeded кончился суточный объём: перед закрытием приходит кадр error с limit, remaining: 0, window: "bytes_day" и scope. Сброс в 00:00 UTC (подробно)
1008 revoked_key, plan_inactive, invalid_key, insufficient_scope, route_not_in_plan доступ кончился посреди соединения: ключ отозван, тариф закончился или в нём больше нет группы ws. Переподключение не поможет, пока не исправлен доступ
1013 ws_limit слот соединения потерян: у аккаунта открыто больше соединений, чем разрешает тариф. Закройте лишнее и переподключитесь через 5 с

Причина закрытия — код ошибки, не длиннее 123 байт. Кадр error перед закрытием несёт те же поля, что тело ошибки REST, — docs_url и детали лимита (подробно).

Доступ перепроверяется каждые 5 секунд; отзыв ключа закрывает поток почти сразу, конец тарифа — не позже чем через два такта. Перед закрытием приходит кадр error с тем же кодом.

Если закрылась только группа одного канала, приходит error route_not_in_plan с channel, подписки этого канала снимаются — и рыночная тоже, — а соединение живёт.

Переподключение

Свой обрыв сети клиент восстанавливает сам: переподключитесь с паузой (0,5 с, затем удваивая до 30 с) и повторите подписки. После subscribed придут свежие snapshot — состояние до обрыва выбрасывайте. Рыночную подписку повторите так же; если придёт market_subs_limit, шлюз мог ещё не заметить обрыв старого сокета: повторите ещё раз с паузой.

В SDK feed() повторяет сам только подписки, ушедшие при подключении и переподключении: на market_subs_limit и rate_limited до 3 раз, с паузой retry_after или 1, 4 и 16 с, затем отдаёт кадр error. Команды живого соединения он не повторяет, а новая рыночная команда канала, новое подключение и закрытие feed() отменяют ожидающий повтор. Пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.

https://docs.lootx.trade/uk/market-api/websocket

Форматы и потоки

16Формат HMP1 і HMP2

Бінарник теплової карти байт за байтом — заголовок, кадри, коди об'єму HMP2 і ряди ціни, з декодером на Python.

GET /v1/heatmap?format=hmp1 або format=hmp2 віддає теплову карту не таблицею, а бінарником: він у багато разів коротший за таблицю, іде потоком і кешується. Його зручно малювати — розбирати можна кадр за кадром, не чекаючи кінця тіла. Параметри запиту — ті самі, що й у таблиці.

format Що всередині Content-Type
hmp1 об’єми точними цілими application/octet-stream
hmp2 об’єм кодом у 6–9 біт, коротший за HMP1; qbits — біт мантиси (6–9, за замовчуванням 6), layout — 0 кадри або 1 ряди application/x-hmp2

format=hmp1|hmp2 в інших маршрутах — 400 bad_format; qbits або layout без format=hmp2 — 400 bad_request. Помилки приходять JSON, як завжди.

Кеш і обсяг

Заголовок ставить джерело теплової карти, шлюз передає його як є:

Cache-Control Коли
no-store вікно закінчується в останній хвилині — живий край
public, max-age=600 кінець вікна не старший за 50 годин: ремонт з архіву ще може залити діри
public, max-age=86400, immutable старіше

У закритих діапазонів є ETag. Повторний запит з If-None-Match: <ETag> отримує 304 Not Modified без тіла — добовий обсяг він не витрачає. Обірване завантаження витрачає стільки байт, скільки встигло отримати.

Заголовок

Little-endian, 48 байт:

Зсув Розмір Поле
0 4 magic: HMP1 або HMP2
4 2 version: 1 у HMP1, 2 у HMP2
6 2 flags
8 8 bucket_size (i64) — висота комірки в одиницях price_scale
16 1 price_scale (u8)
17 1 qty_scale (u8)
18 1 HMP1: 0; HMP2: qty_bits (6–9)
19 1 HMP1: 0; HMP2: layout (0 — кадри, 1 — ряди)
20 4 time_step_ms (u32)
24 8 from_ms (i64)
32 8 to_ms (i64)
40 4 frame_count (u32) — число колонок часу
44 4 stream_id (u32), у REST 0

flags: біт 0 — значення агреговані максимумом (інакше середнім); біт 1 — відповідь уперлася в стелю тіла джерела (16 МБ) і обрізана справа за часом. Продовження — той самий запит з from = час останнього кадру + time_step_ms.

Розбирайте відповідь за заголовком (magic, version, layout), а не за своїм запитом.

Ціна й об’єм комірки:

TEXT
price = idx * bucket_size / 10^price_scale     нижня межа комірки [price, price + крок)
qty   = q / 10^qty_scale                       у монетах
крок   = bucket_size / 10^price_scale

Кадри — HMP1 і HMP2 з layout=0

Після заголовка — frame_count кадрів підряд:

TEXT
varint  ts_delta_ms    від ts попереднього кадру; у першого — від from_ms
u8      kind           1 = KEY (повний стан), 0 = DELTA (зміни)
zigzag  best_bid_d     різниця до best_bid попереднього кадру; у першого — до 0
zigzag  best_ask_d     те саме для best_ask
varint  bid_count
  bid_count разів:
    zigzag  idx_delta  до idx попередньої комірки; у першої — до 0
    varint  qty        АБСОЛЮТНИЙ об'єм комірки (у HMP2 — код); 0 = рівень зник
varint  ask_count
  ask_count разів:       те саме

varint — LEB128 без знаку. zigzag — LEB128 поверх (n << 1) ^ (n >> 63), розкодовується як (u >> 1) ^ -(u & 1).

Тримайте два словники idx → qty, для бідів і асків:

  • KEY — словники заміщуються вмістом кадру;
  • DELTA — накладається поверх: qty > 0 — присвоїти, qty == 0 — видалити ключ.

Перший кадр завжди KEY, далі KEY повторюється кожні 512 кадрів. Лічильники ts, best_bid, best_ask живуть у межах однієї відповіді. Стан словників після кадру — одна колонка теплової карти.

Python
import struct

def uvarint(b, p):
    out = shift = 0
    while True:
        x = b[p]; p += 1
        out |= (x & 0x7F) << shift
        if x < 0x80:
            return out, p
        shift += 7

def svarint(b, p):
    u, p = uvarint(b, p)
    return (u >> 1) ^ -(u & 1), p

def columns(b):
    """HMP1 -> [(ts, {price: qty} біди, {price: qty} аски)]."""
    assert b[:4] == b"HMP1"
    bucket, ps, qs = struct.unpack_from("<qBB", b, 8)
    step_ms, from_ms, _to, frames = struct.unpack_from("<IqqI", b, 20)
    if frames == 0:
        return []
    bid, ask, out, p, ts = {}, {}, [], 48, from_ms
    for _ in range(frames):
        d, p = uvarint(b, p); ts += d
        kind = b[p]; p += 1
        _, p = svarint(b, p); _, p = svarint(b, p)        # best_bid_d, best_ask_d
        for book in (bid, ask):
            n, p = uvarint(b, p)
            cells, idx = [], 0
            for _ in range(n):
                di, p = svarint(b, p); idx += di
                q, p = uvarint(b, p)
                cells.append((idx, q))
            if kind == 1:
                book.clear()
                book.update((i, q) for i, q in cells if q > 0)
            else:
                for i, q in cells:
                    if q: book[i] = q
                    else: book.pop(i, None)
        price = lambda i: i * bucket / 10**ps
        out.append((ts,
                    {price(i): q / 10**qs for i, q in sorted(bid.items())},
                    {price(i): q / 10**qs for i, q in sorted(ask.items())}))
    assert p == len(b), "після кадрів залишилися байти"
    return out

Таблиця format=json — рівно цей розбір: рядок на кожну ненульову комірку кожної колонки.

HMP2: об’єм кодом

Кадри з layout=0 — байт у байт як у HMP1, але замість varint qty стоїть varint code:

  • code = 0 — рівня немає (у DELTA — «рівень зник»);
  • інакше code — об’єм комірки в монетах у форматі з m = qty_bits бітами мантиси.

DELTA порівнює коди: комірка, у якої код не змінився, у DELTA не потрапляє, навіть якщо сирий об’єм трохи зсунувся.

Розкодування (d = 23 − m): code = 0 → 0, інакше v = from_bits(((code + (64 << m)) << d) as u32) як float32 — об’єм у монетах, qty_scale до нього вже не застосовується. При m = 9 помилка не більша за 2⁻¹⁰, діапазон — від 2⁻⁶³ до 2⁶⁵ монет.

Python
import struct

def hmp2_qty(code, m):
    if code == 0:
        return 0.0
    bits = (code + (64 << m)) << (23 - m)
    return struct.unpack("<f", struct.pack("<I", bits))[0]

Вектори для перевірки своєї реалізації:

Об’єм Код m=9 Назад Код m=6 Назад
1e-8 18607 9.997166e-9 2326 1.0011718e-8
0.001 27148 0.0009994507 3394 0.0010070801
0.5 31744 0.5 3968 0.5
1 32256 1 4032 1
1023 37375 1023 4672 1024
12345.678 39172 12352 4896 12288

HMP2, layout=1: ряди ціни

Той самий заголовок з байтом 19 = 1. Тіло — чотири потоки підряд, без kind і лічильників кадру:

  1. Час: frame_count разів varint ts_delta, zigzag best_bid_d, zigzag best_ask_d — як у кадру.
  2. Ряди: для бідів, потім асків — varint R, потім R разів zigzag idx_delta (перший — від 0, далі — від idx минулого ряду цієї сторони, строго за зростанням) і varint run_count.
  3. Довжини: всі ряди бідів, потім асків, по кожній серії varint (len − 1). Сума довжин по ряду = frame_count.
  4. Коди: у тому самому порядку по кожній серії zigzag(code − prev), prev = 0 на початку кожного ряду. code = 0 — рівня немає в цих колонках.

Ряд без жодного ненульового коду не пишеться. Колонку рядів не можна прочитати окремо від усього тіла — для потокового відмалювання беріть layout=0.

https://docs.lootx.trade/uk/market-api/heatmap-binary

Лимиты и ошибки

17Лимиты и тарифы

Что ограничивает API-тариф, почему лимиты общие на все ключи аккаунта, как читать заголовки X-RateLimit и RateLimit, живые лимиты /v1/usage и что делать при 429.

Лимиты задаёт API-тариф аккаунта. Он отдельный от подписки на терминал: можно иметь Pro терминала и не иметь API-тарифа, и наоборот. Какой тариф у вас и что в него входит — на странице API-ключи в кабинете.

Что ограничивает тариф

Лимит Как считается
Запросов в минуту ведро с допустимым всплеском: короткая пачка запросов проходит, средний темп — не выше лимита
Запросов в час окно UTC с начала часа, hh:00
Запросов в сутки окно UTC с 00:00
Байт выдачи в сутки по фактически отданному телу ответа и по кадрам WebSocket, сброс в 00:00 UTC
Глубина истории сколько дней назад от «сейчас» можно спрашивать. Это предел, а не обещание глубины: раньше, чем лежат данные, ответ пустой (свечи, например, есть с 23.10.2026 — смотрите coverage), кроме price_step у тепловой карты
WebSocket-соединений одновременно открытых
Рыночных WebSocket-подписок scope: "market", поле тарифа ws_market_subs: на аккаунт — все ключи, соединения и каналы вместе. Ноль — значение шлюза, одна подписка
Ключей действующих ключей на аккаунт

Ноль в тарифе означает «без ограничения» — кроме рыночных подписок: там ноль значит значение шлюза, одну подписку.

Лимиты групп маршрутов

Тариф может дать группе маршрутов свои, более строгие лимиты — например, тепловой карте или секундным свечам — или закрыть группу совсем: тогда ответ 403 route_not_in_plan. Лимит группы действует вместе с общим, а не вместо него: запрос к тепловой карте тратит и запас группы heatmap, и общий запас аккаунта.

Группа Маршруты
instruments /v1/instruments
candles /v1/candles с шагом от минуты
candles_1s /v1/candles с шагом меньше минуты; канал candles в WebSocket
series /v1/series
footprint /v1/footprint, /v1/hyperliquid/footprint
delta /v1/delta
trades /v1/trades
heatmap /v1/heatmap, /v1/book/bands
oi /v1/oi
funding /v1/funding, /v1/funding/events
ls_ratio /v1/ls-ratio, /v1/ls-ratio/latest
mark /v1/mark с шагом 1m и /v1/mark/latest
mark_1s /v1/mark с шагом 1s
margin /v1/margin/*: все шесть маршрутов маржинального кредитования
options /v1/options/*: все десять маршрутов опционов и поток /v1/options/stream — соединение, его кадры и объём; группы ws у потока нет. /v1/options/chain/range весит час диапазона — от 1 до 6 единиц (вес запроса), /v1/options/vol/book-range — границы шага на 64, вверх, от 1 до 34 единиц (вес ряда), /v1/options/levels/range — точки шага на 1440, вверх, от 1 до 7 единиц (вес истории уровней), /v1/options/exposure/latest — 1 единица
densities /v1/densities
densities_history /v1/densities/history
icebergs /v1/icebergs
screener /v1/screener, /v1/screener/metrics
ws подключение к /v1/ws и /v1/ws/*; поток опционов — в группе options

/v1/status не входит ни в одну группу и расходует только общие лимиты; /v1/usage — тоже.

Заголовки

Каждый ответ на запрос с ключом — и успешный, и с ошибкой — несёт состояние лимитов. Две записи одного и того же: короткая X-RateLimit-* — по самому тесному окну, где осталось меньше всего, и RateLimit-Policy с RateLimit по черновику IETF (draft-ietf-httpapi-ratelimit-headers) — по всем окнам тарифа сразу.

HTTP
HTTP/1.1 200 OK
X-Request-Id: 9f2c4a1be07d4e55a1c3b2d4e5f60718
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1793793601
X-RateLimit-Scope: account
X-RateLimit-Window: minute
RateLimit-Policy: "minute";q=600;w=60, "day";q=50000;w=86400, "bytes_day";q=10737418240;w=86400;qu="content-bytes"
RateLimit: "minute";r=99;t=1, "day";r=45000;t=43200, "bytes_day";r=10733418240;t=43200
Заголовок Смысл
X-RateLimit-Limit потолок самого тесного окна; у минуты — запросов в минуту, у bytes_day — байт в сутки
X-RateLimit-Remaining сколько в нём осталось
X-RateLimit-Reset когда это окно сбросится — момент, Unix-секунды UTC. У минуты — когда ведро снова полное
X-RateLimit-Scope account — общий лимит аккаунта, route:<группа> — лимит группы
X-RateLimit-Window minute, hour, day или bytes_day
RateLimit-Policy все окна тарифа для этого запроса: q — потолок, w — длина окна в секундах, у байтов — qu="content-bytes". Окна группы называются "route:<группа>:<окно>"
RateLimit остаток r и секунд до сброса t по каждому окну с потолком
Retry-After только у 429 и 503: через сколько секунд повторить

Окно без потолка (0 в тарифе) в RateLimit-Policy и RateLimit не попадает. Все эти заголовки, как и X-Request-Id, X-Next-Cursor, Link и X-Cache, открыты браузеру (Access-Control-Expose-Headers): fetch со страницы их читает.

Предохранитель по адресу

Перед шлюзом стоит край сети, и у него свой предохранитель — по IP-адресу, до проверки ключа: около 50 запросов в секунду с одного адреса, короткий залп — до 100. Сверх него — 429 rate_limited со scope: "ip", window: "second" и retry_after: 1. Это защита от залпов, а не тариф: обычному клиенту, который держится в лимите тарифа, до него не дойти. Несколько сервисов за одним NAT делят этот предохранитель между собой.

Ответы края сети — того же вида, что ошибки шлюза: JSON с code. Кроме 429 это 413 payload_too_large (тело запроса больше 64 КБ) и 503 unavailable / 504 upstream_timeout с Retry-After: 5, если шлюз недоступен или не ответил.

Когда лимит исчерпан

Код HTTP Что случилось Когда пройдёт
rate_limited 429 темп в минуту — аккаунта или группы через Retry-After секунд
hourly_limit 429 запросы за час в начале следующего часа UTC
daily_limit 429 запросы за сутки в 00:00 UTC
daily_quota_exceeded 429 суточный объём выдачи в 00:00 UTC
ws_limit 429 открыто слишком много WebSocket закройте лишнее соединение
market_subs_limit кадр потока рыночных подписок столько, сколько разрешает тариф снимите лишнюю: unsubscribe со scope: "market"
rate_limited кадр потока сверх 10 команд в секунду и запаса 20 на соединение или рыночная подписка канала открывается чаще раза в секунду. Считается открытие: снятие с повторной подпиской паузу не обходит через retry_after секунд; прежняя подписка, если она есть, остаётся
history_out_of_plan 403 запрошено глубже разрешённой истории сдвиньте from не раньше earliest_allowed_ms; у /v1/margin/assets, /compare и /events глубину меряет окно — возьмите window короче; у /v1/options/chain — минута at: at не раньше earliest_allowed_ms; у /v1/options/chain/range — from, округлённый вверх до минуты; у /v1/options/vol/book-range и /v1/options/levels/range отказ приходит уже после списания полного веса
route_not_in_plan 403 группа маршрута не входит в тариф смените тариф

В теле 429 — детали лимита: limit, remaining, window, scope, retry_after и reset_at_ms. У 403 history_out_of_plan — history_days, earliest_allowed_ms и scope, у 403 route_not_in_plan — только scope (тело ошибки).

Что отказ делает со счётчиками:

  • 429 по окнам часа и суток и по объёму, как правило, не двигает ни одного счётчика: запрос не засчитан, повторять после Retry-After безопасно. Исключение — гонка параллельных запросов: окна часа и суток сверяются до вёдер минуты, а засчитываются после них, и если между сверкой и зачётом окно заполнил соседний запрос, отказ придёт уже после того, как этот запрос потратил жетон минутного ведра аккаунта (и группы, если у неё свой темп). Сами окна часа и суток он при этом не засчитывает. Объём суток так не гоняется: он сверяется только до вёдер.
  • 429 rate_limited по ведру группы не двигает ничего. По ведру аккаунта — тоже, кроме одного: жетон ведра группы этого запроса уже списан. Потеря — не больше ёмкости ведра группы и только когда вы и так упёрлись в общий лимит.
  • 403 history_out_of_plan — уже засчитанный запрос: он расходует окна минуты, часа и суток, как обычный.
  • 403 route_not_in_plan счётчиков не двигает.

И ещё:

  • Объём учитывается после ответа: запрос, начатый до исчерпания, отдаётся целиком, следующий получит 429.
  • Ответ из кэша шлюза (X-Cache: HIT) считается в лимитах и объёме как обычный.
  • Объём считается по телу до сжатия: со сжатием и без запрос стоит одинаково (сжатие).
  • 503 upstream_busy — не ваш лимит, а очередь шлюза к источнику: она защищает источники от всплесков. Повторите через Retry-After (обычно 1 с).
Python
import time, requests

WAIT_FOR_RESET = ("daily_limit", "daily_quota_exceeded", "hourly_limit", "ws_limit")

def get(url, **kw):
    for attempt in range(4):
        r = requests.get(url, **kw)
        if r.status_code in (429, 503):
            err = r.json()["error"]
            if err["code"] in WAIT_FOR_RESET:
                raise RuntimeError(f"лимит {err['code']}: окно сбросится в {err.get('reset_at_ms')}")
            time.sleep(min(int(err.get("retry_after") or r.headers.get("Retry-After", 1)), 30))
            continue
        return r
    return r

Такой же цикл есть в SDK, но пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.

WebSocket в суточном объёме

Байты кадров, которые сервер шлёт клиенту, идут в суточный объём вместе с REST: данные любых каналов /v1/ws, ответы на команды, кадры сырых потоков /v1/ws/* и hello с кадрами OPC1 потока /v1/options/stream. Считается длина кадра без служебных заголовков WebSocket. WS-ping и кадр error, с которым шлюз закрывает соединение, не считаются.

Учёт тот же, что у REST: общий объём аккаунта, группа соединения ws и группа данных канала (densities, screener, trades, oi, candles_1s); у потока опционов — общий объём и группа options, те же письма на 80 и 100 %. Лимит объёма группы действует и на кадры: лимит ws тратят все эти кадры соединения, лимит группы канала — только кадры этого канала. В разбивке расхода по группам ответы на команды, subscribed рыночной подписки тоже, стоят в ws, данные — в группе канала.

Кадры копятся и списываются раз в такт соединения (5 с) и при закрытии, поэтому перерасход — не больше одного такта потока.

Когда объём кончился:

  • /v1/ws — кадр error с кодом daily_quota_exceeded (limit, remaining: 0, window: "bytes_day", scope — account или route:<группа>) и закрытие 1008 с тем же кодом в причине;
  • сырой поток /v1/ws/* и поток опционов — закрытие с кодом в причине;
  • новое соединение — 429 daily_quota_exceeded, как у REST;
  • новая рыночная подписка на открытом соединении — отказ кадром error с тем же кодом.

Если счётчики объёма временно недоступны, поток не рвётся, а прибавка за это время теряется.

Живые лимиты: GET /v1/usage

GET/v1/usage

Тариф ключа, его лимиты, расход за сутки UTC и состояние каждого окна прямо сейчас. Сам запрос — обычный: он расходует общие окна аккаунта (минуту, час, сутки и байты), но не лимиты групп — ни в одну группу он не входит.

Shell
curl -s "https://market-api.lootx.trade/v1/usage" -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "plan": { "id": "6f1c…", "slug": "pro", "name": "Pro" },
  "tier": "pro",
  "limits": { "rpm": 600, "burst": 100, "rph": 0, "rpd": 50000, "daily_bytes": 10737418240, "history_days": 365, "ws_conns": 5 },
  "routes": { "heatmap": { "rpd": 5000, "rpm": null, "rph": null, "daily_bytes": null, "history_days": null, "enabled": true } },
  "today": { "day": "2026-11-04", "requests": 5000, "bytes": 4000000 },
  "now": {
    "at_ms": 1793793600000,
    "windows": [
      { "scope": "account", "window": "minute", "limit": 600, "burst": 100, "used": 37, "remaining": 63, "reset_at_ms": 1793793603700 },
      { "scope": "account", "window": "hour", "limit": null, "used": 1234, "remaining": null, "reset_at_ms": 1793797200000 },
      { "scope": "account", "window": "day", "limit": 50000, "used": 5000, "remaining": 45000, "reset_at_ms": 1793836800000 },
      { "scope": "account", "window": "bytes_day", "limit": 10737418240, "used": 4000000, "remaining": 10733418240, "reset_at_ms": 1793836800000 },
      { "scope": "route:heatmap", "window": "day", "limit": 5000, "used": 10, "remaining": 4990, "reset_at_ms": 1793836800000 }
    ],
    "throttled_today": 3,
    "last_limited": { "at_ms": 1793793500000, "code": "rate_limited", "scope": "account", "window": "minute" }
  }
}
Поле Что
plan, tier тариф ключа
limits общие лимиты аккаунта; 0 — без ограничения. ws_market_subs приходит, только если тариф задал его не нулём; нет поля — значение шлюза, одна подписка
routes группы тарифа так, как их применяет шлюз: enabled — открыта ли группа на деле (false — закрыта: запросы к ней получают 403 route_not_in_plan); в лимите null — как в общем, 0 — без ограничения в группе
today за сутки UTC: засчитанные запросы (429 и 403 route_not_in_plan не входят, 403 history_out_of_plan входит) и отданные байты до сжатия
now.windows окна сейчас: общие — всегда, окна группы — только у групп со своим лимитом
now.throttled_today сколько раз за сутки UTC запрос отбит по лимиту (429 и лимитные 403)
now.last_limited последний такой отказ за сутки или null

Окно в now.windows:

Поле Минута Час, сутки, байты
limit установившаяся скорость, запросов в минуту потолок окна; у bytes_day — байт
burst ёмкость ведра: сколько запросов можно подряд нет
remaining целые жетоны в ведре сейчас, с пополнением сколько осталось до потолка
used burst − remaining сколько уже засчитано
reset_at_ms когда ведро снова полное когда окно сбросится

limit: null и remaining: null — у окна нет потолка. Заполнение минуты считайте как used / burst, а не used / limit: минута — ведро, а не счётчик.

Счётчики лимитов временно недоступны — 503 usage_unavailable с Retry-After, а не ответ с пустыми окнами или нулями: повторите позже. На ваши запросы к остальным маршрутам это не влияет.

Уведомления о расходе

Когда расход за сутки или за час доходит до 80 % и до 100 % лимита — общего или лимита группы, — на почту аккаунта приходит письмо. Следим за суточным объёмом, запросами в сутки и запросами в час. Одно письмо на порог: на суточные лимиты — раз в сутки, на часовой — раз в час.

Где смотреть расход

Кабинет → API-ключи → Расход:

  • запросы и объём по дням за 7 или 30 суток UTC, с долей ошибок и отказов 429. Подключение WebSocket считается запросом, поток — нет: его кадры дают только объём. До 06.11.2026 17:17 UTC запросами считались и такты соединения, эти итоги не пересчитаны;
  • разбивка по ключам или по группам маршрутов;
  • расход за сегодня (UTC) против лимитов тарифа: от 80 % — предупреждение, на 100 % — лимит исчерпан.

Живой остаток в своём коде — из заголовков X-RateLimit-* и RateLimit любого ответа или целиком из /v1/usage.

https://docs.lootx.trade/uk/market-api/limits

Лимиты и ошибки

18Ошибки

Тело ошибки с деталями, все коды REST и WebSocket — что значит каждый и что с ним делать.

Тело ошибки

Любая ошибка шлюза — HTTP-код и JSON, в каком бы формате вы ни просили ответ: и отказ маршрута, и неизвестный путь, и неподдержанный Accept, и внутренний сбой.

JSON
{
  "error": {
    "code": "rate_limited",
    "message": "лимит 600 запросов в минуту исчерпан",
    "request_id": "9f2c4a1be07d4e55a1c3b2d4e5f60718",
    "docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
    "limit": 600,
    "remaining": 0,
    "window": "minute",
    "scope": "account",
    "retry_after": 1,
    "reset_at_ms": 1793750461000
  }
}
Поле Что
code машинный код, snake_case, стабильный. Разбирайте его
message объяснение для человека; может меняться, не разбирайте его
request_id тот же номер, что в заголовке X-Request-Id. Пришлите его в поддержку
docs_url этот код на этой странице: https://docs.lootx.trade/ru/market-api/error-codes#<код>

Детали

Рядом с code лежат поля, которые помогают исправить запрос. Каждое есть, только когда оно к месту:

Когда Поля Что в них
400 — параметр не разобрался param, expected какой параметр и что в нём ожидалось: "param": "from", "expected": "целое: Unix-миллисекунды UTC"
406 not_acceptable param, expected "param": "Accept" и список типов, которые отдаёт этот маршрут
429 limit, remaining, window, scope, retry_after, reset_at_ms потолок окна и остаток; окно — minute, hour, day, bytes_day (у края сети — second); чьё — account, route:<группа> или ip; через сколько секунд повторить; когда окно сбросится, Unix-мс UTC
403 history_out_of_plan history_days, earliest_allowed_ms, scope, param, expected глубина истории тарифа в сутках (с учётом группы); самый ранний допустимый from, Unix-мс UTC; чей предел — account или route:<группа>; "param": "from", а у маршрутов маржи с окном — "param": "window", у /v1/options/chain — "param": "at"
403 route_not_in_plan scope закрытая группа — route:<группа>
405 method_not_allowed allow разрешённые методы — как в заголовке Allow

У bytes_day limit и remaining — в байтах. Как устроены окна — Лимиты и тарифы.

Заголовки ошибки

Заголовок Когда
X-Request-Id у каждого ответа
Retry-After у каждого 429 и 503 — через сколько секунд повторить; у 503 без своего срока — 5
WWW-Authenticate у 401: Bearer realm="lootx", а с негодным ключом — Bearer realm="lootx", error="invalid_token"
Allow у 405 и у OPTIONS: GET, HEAD, OPTIONS
X-RateLimit-*, RateLimit-Policy, RateLimit у ответов с ключом, и с ошибкой тоже — подробно

Ключ и доступ

Код HTTP Что значит Что делать
missing_key 401 ключа нет передайте Authorization: Bearer <ключ> или X-API-Key
invalid_key 401 такого ключа нет проверьте, что ключ скопирован целиком: lx_live_ и 43 знака. Повтор с тем же ключом не поможет
invalid_token 401 токен входа не прошёл проверку для API используйте ключ, а не токен терминала
token_expired 401 срок токена входа истёк то же
key_in_query 400 ключ передан в адресе уберите ключ из адреса — только заголовок. Ключ, засветившийся в адресе, лучше отозвать
revoked_key 403 ключ отозван выпустите новый в кабинете
plan_inactive 403 у аккаунта нет действующего API-тарифа продлите или выберите тариф
insufficient_scope 403 у ключа нет нужной области доступа. У /v1/options/* нужна область derivatives: токен терминала без неё (бесплатный) получает этот отказ выпустите ключ с нужными областями; к опционам — с API-ключом
route_not_in_plan 403 группа маршрута не входит в тариф смените тариф; что в него входит — в кабинете
history_out_of_plan 403 история глубже, чем разрешает тариф (общий лимит или лимит группы). У /v1/margin/assets, /compare и /events глубину меряет окно window — param: "window"; у /v1/options/chain — начало минуты, закрытой в at, — param: "at" сдвиньте from не раньше earliest_allowed_ms из тела ошибки; у маржи с окном — возьмите window короче; у опционов — at не раньше earliest_allowed_ms
forbidden 403 доступ запрещён по иной причине проверьте ключ и тариф; не проходит — напишите в поддержку с request_id
auth_unavailable 503 проверка ключа временно недоступна повторите через Retry-After

Лимиты

Код HTTP Что значит Что делать
rate_limited 429 превышен лимит запросов в минуту — аккаунта или группы маршрутов (scope); со scope: "ip" — предохранитель края сети по адресу подождите Retry-After секунд; держите темп ниже RateLimit-Policy
hourly_limit 429 исчерпан лимит запросов в час сброс в начале следующего часа UTC — reset_at_ms
daily_limit 429 исчерпан лимит запросов в сутки сброс в 00:00 UTC — reset_at_ms
daily_quota_exceeded 429 исчерпан суточный объём выдачи — аккаунта или группы; кадры WebSocket считаются в него же сброс в 00:00 UTC; protobuf и бинарь тепловой карты короче JSON
ws_limit 429 слишком много одновременных WebSocket закройте лишнее соединение

Подробно про лимиты, заголовки и живой остаток — Лимиты и тарифы.

Параметры запроса

Код HTTP Что значит Что делать
bad_request 400 параметры не разобрались исправьте параметр из param по expected
bad_instrument 400 инструмент не в виде venue:market:SYMBOL как называть инструменты
unsupported_instrument 400 инструмента нет у источника: param: "instrument" — биржа, рынок или котировка, param: "symbol" — символ, только на /v1/candles и /v1/series и не всегда. На остальных маршрутах символ не сверяется: пустой 200 не значит, что инструмент есть. Условия и пределы проверьте имя и колонку sources в /v1/instruments
bad_cursor 400 курсор не разобрался: он повреждён. С параметрами запроса он не сверяется передавайте next_cursor (или ссылку из Link) из прошлого ответа без изменений, с теми же остальными параметрами
bad_format 400 неизвестный format, или CSV для ответа из нескольких таблиц, или формат не этого маршрута: CSV у ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) — и format=csv, и Accept: text/csv, opc1 вне /v1/options/chain, /chain/latest и /chain/range — в том числе у /v1/options/vol/book-range, /exposure/latest и /levels/range message называет форматы маршрута: format=json, protobuf или csv, у ответов без таблицы — format=json или protobuf; для футпринта — table=levels или windows
not_acceptable 406 в Accept нет ни одного известного шлюзу типа — ни JSON, ни protobuf, ни text/csv, ни маски вроде */*. Accept: text/csv у ответа без таблицы — не 406, а 400 bad_format Accept: application/json, application/x-protobuf или text/csv — или ?format=. У ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) в expected типы без text/csv; кадры OPC1 цепочек опционов — только ?format=opc1, по Accept их не попросить
method_not_allowed 405 метод не GET, HEAD или OPTIONS метод из Allow (GET, HEAD, OPTIONS)
request_timeout 408 запрос не дошёл до шлюза вовремя повторите запрос
payload_too_large 413 тело запроса больше 64 КБ запросам API тело не нужно — отправляйте GET без тела
too_large 413 ответ слишком велик сузьте окно, укрупните шаг или возьмите бинарный формат
not_found 404 нет такого маршрута. У /v1/ls-ratio/latest и /v1/mark/latest — по инструменту нет ни одной строки: у long/short за 35 суток, у mark за 7 суток. У /v1/options/chain и /chain/latest — нет минуты у базы или у присланной chain либо она не восстанавливается (gap в message); у /chain/range — нет цепочки, инструмента или ни одной минуты диапазона; у /vol/book-range, /exposure/latest и /levels/range — нет книги у базы; у потока опционов — нет присланной цепочки или у базы нет ни одной, отказ до апгрейда список маршрутов — /v1/openapi.json; замолчавший ряд читайте /v1/ls-ratio или /v1/mark с окном
not_available 404 маршрут есть, но таких данных шлюз не отдаёт: их ещё не собирают или они не включены у источника. Это не ошибка запроса и не сбой источника повтор не поможет; какие маршруты отвечают так — в описании ответов /v1/openapi.json

Неизвестный инструмент

unsupported_instrument приходит в двух случаях, в REST их различает поле param. В потоке различителя нет: подписка символ не сверяет.

  • param: "instrument" — биржа, рынок или котировка. Отказ приходит сразу, до запроса к источнику: binance:future:BTCUSDT, спот у /v1/oi, биржа, которой нет у маршрута. /v1/oi, /v1/funding, /v1/funding/events, /v1/ls-ratio и /v1/ls-ratio/latest у okx, bingx, mexc и kucoin, а /v1/mark и /v1/mark/latest у okx и mexc собирают имя для источника из базы и котировки, поэтому так же отказывают символу, котировку которого не разобрать: okx:perp:BTC-USDT-SWAP, kucoin:perp:XBTUSDTM. Свои правила у /v1/screener?instruments=: биржу он не сверяет, а котировку сверяет.
  • param: "symbol" — символ. Только /v1/candles и /v1/series: биржа и рынок есть, а символ не найден, например binance:perp:BTCUSDTT. В message — что не найдено и ссылка на /v1/instruments?venue=…&market=….

На остальных маршрутах пустой ответ не значит, что инструмент существует. /v1/trades, /v1/footprint, /v1/delta, /v1/heatmap, /v1/oi, /v1/funding, /v1/funding/events, /v1/ls-ratio, /v1/mark, /v1/densities, /v1/densities/history, /v1/icebergs и /v1/screener?instruments= на символ, по которому нет данных, отвечают 200 с пустым ответом, на опечатку тоже, если имя прошло проверки выше. Исключение — /v1/heatmap с price_step: без данных книги в минуте перед to шаг не во что перевести, ответ 400 bad_request, запрашивайте без него. Условие и оговорка — в пределах тепловой карты. Живые списки источников не знают снятые символы с историей, поэтому отказ по ним был бы ложным.

Отказ с param: "symbol" не гарантирован. Он приходит, только когда сошлось всё:

  1. Строк нет, в запросе нет cursor, а в ответе не было бы next_cursor. Есть строки — они отдаются, даже если инструмент снят с торгов и ни в одном списке его больше нет.
  2. Источник подтвердил, что по символу нет ни одного бара за всю историю, а не только в окне запроса. Не смог подтвердить или запись баров у него выключена — отказа нет.
  3. Рынок вообще есть у источника свечей. Рынков HIP-3 там нет, см. ниже.
  4. Символа нет ни в одном списке источников, и шлюз не видел его в них с момента своего запуска. Имена сравниваются по базе без учёта регистра: BTC, BTCUSDC и btcusdt одной биржи и рынка — один инструмент. Поэтому BTCEUR на бирже с BTCUSDT, но без такой пары, отказа не получит.
  5. Все источники списков исправны: каждый недавно отдал непустой список, хотя бы в одном есть эта биржа и рынок, и с первого списка источника прошло достаточно времени. Источник только поднялся или вернулся после долгого сбоя — отказ включится не сразу.

Иначе ответ — 200 с пустым списком. Поэтому при сбое одного источника или вскоре после перезапуска шлюза опечатка на /v1/candles и /v1/series тоже может получить 200. Глубина истории проверяется раньше: 403 history_out_of_plan приходит до запроса к источнику, и отказ по символу его не заменяет.

400 бывает и у настоящего инструмента. Когда условия выше сошлись, это:

  • Новый листинг. Пока символа нет ни в одном списке, а первая сделка не дошла до баров, /v1/candles и /v1/series отвечают 400. Повторите позже.
  • Символа нет в барах, а в других данных он есть. Снятый с торгов, когда свечей по этой бирже ещё не писали, или с истёкшими барами. 400 здесь говорит о свечах и рядах: у /v1/footprint, /v1/trades и других маршрутов данные по нему могут быть.
  • Имя не в том виде, что в реестре. PF_XBTUSD, BTC-USDT-SWAP, XBTUSDTM, BTC_USDT к имени источника не приводятся. Имя берите из /v1/instruments: там это, например, kraken:perp:BTCUSD, okx:perp:BTCUSDT, kucoin:perp:BTCUSDT.

Акции Hyperliquid (рынки HIP-3) пишутся как в /v1/instruments: hyperliquid:perp:AAPLUSDC.XYZ, короткое hyperliquid:perp:AAPL.XYZ — то же самое. Данные по ним есть у /v1/footprint, /v1/delta, /v1/trades и /v1/heatmap (только деки xyz и io), у /v1/densities и /v1/screener. У /v1/candles, /v1/series, /v1/oi, /v1/funding и /v1/funding/events этих рынков нет: ответ — пустой 200, отказа нет. Имя Hyperliquid xyz:AAPL не подходит: двоеточие в символе — 400 bad_instrument.

Источники данных и шлюз

Код HTTP Что значит Что делать
upstream_rejected 400 источник отверг параметры запроса. У /v1/margin/* текст источника начинается с имени параметра — оно же в param; у /v1/options/* param — по коду источника (bad_base → base, bad_range → from, range_too_long → to, bad_instrument → instrument, bad_resume → resume, …), код — в конце message проверьте окно и шаг; message подскажет
upstream_error 502 источник ответил ошибкой. У /v1/margin/* и /v1/options/* так же приходит и 404 источника без кода минуты: маршрутов у него нет, это не not_found повторите позже; если повторяется — напишите в поддержку с request_id
upstream_unavailable 502 источник недоступен. У /v1/margin/* — ещё и 503 с Retry-After: 2: источник прогревается или перегружен (подробно); у /v1/options/* — 503 с Retry-After источника, обычно 1 с, не дольше 60 с: источник загружает цепочки после запуска, у /v1/options/vol/book-range уже собирает предельное число рядов со склада, у /v1/options/levels/range — читает предельное число рядов уровней, у потока опционов держит предельное число соединений; поток выключен на узле — 503 с Retry-After: 30, это выкладка, а не окончательный отказ (подробно) повторите позже; состояние — /v1/status
upstream_timeout 504 источник или шлюз не ответил вовремя сузьте окно или повторите через Retry-After
upstream_busy 503 очередь шлюза к источнику полна повторите через Retry-After, обычно 1 с
upstream_not_configured 503 источник ещё не подключён к шлюзу маршрут в бете — следите за обновлениями
usage_unavailable 503 /v1/usage: счётчики лимитов временно недоступны повторите через Retry-After
unavailable 503 сервис временно недоступен (в том числе край сети не достучался до шлюза) повторите через Retry-After, у края сети — 5 с
internal 500 внутренняя ошибка шлюза напишите в поддержку с request_id

Поток (WS)

Ошибки потока приходят кадром error того же вида, что тело ошибки REST: code, message, docs_url, id команды, если он был, и детали лимита, когда они к месту. Соединение при этом живёт, кроме отмеченных «закрытие».

JSON
{"type": "error", "id": 7, "code": "rate_limited",
 "message": "не больше 10 сообщений в секунду на соединение (запас 20); сообщение пропущено",
 "docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
 "limit": 10, "remaining": 0, "window": "second", "scope": "connection", "retry_after": 1}
Код Что значит
bad_request кадр не JSON или не текстовый, нет channel, неизвестный op, в subscribe без scope нет непустого массива instruments
unknown_channel такого канала нет
channel_unavailable канал пока не работает или, с instrument, выбрал потолок соединений с источником — повторите позже. Со scope: "market" и channel — потолок рыночных соединений шлюза (retry_after — через сколько секунд повторить); без retry_after — рыночную подписку остановил сбой шлюза, подпишитесь заново
too_many_instruments аккаунт уже держит свою долю ёмкости канала — отпишитесь от лишнего
bad_instrument имя не в виде venue:market:SYMBOL. Кадр несёт instrument, если имя пришло строкой; остальные имена команды обрабатываются дальше
unsupported_instrument у источника канала нет такого рынка или биржи, а на oi и screener ещё и не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает. Символ подписка не сверяет (подробно)
bad_params неверные params или scope, что не так — в тексте ошибки: params у подписки по инструментам, кроме null и пустого объекта, scope не market и не null, subscribe со scope: "market" у канала без рыночной подписки или вместе с непустым массивом instruments, параметр рыночной подписки вне списка или с неверным значением
market_subs_limit аккаунт уже держит столько рыночных подписок, сколько разрешает тариф (ws_market_subs, все ключи и соединения вместе). limit, remaining: 0, scope: "account", window: "concurrent". Снимите лишнюю — unsubscribe со scope: "market" — или смените тариф
route_not_in_plan группа канала не в тарифе; без instrument и channel — тариф лишился группы ws: закрытие 1008
too_many_subscriptions больше 200 подписок на соединение; команда отвергнута целиком. limit и remaining — сколько можно и сколько осталось
rate_limited сверх 10 команд в секунду и запаса 20; команда пропущена. scope: "connection", window: "second". То же у рыночной подписки канала, открытой на соединении чаще раза в секунду, заменой или снятием с повторной подпиской: limit: 1, remaining: 0, retry_after — секунд до следующего открытия, прежняя подписка, если она есть, остаётся
ws_limit слот соединения потерян: у аккаунта открыто больше соединений, чем ws_conns тарифа. window: "concurrent", retry_after: 5; закрытие 1013
slow_consumer клиент не успевает читать: очередь переполнена, кадр рыночной подписки не встал в очередь за 10 секунд, очередь забита целиком дольше 10 секунд и ответу на команду некуда встать или накопленные изменения вышли за потолок шлюза. Закрытие 1008
daily_quota_exceeded кончился суточный объём: limit, remaining: 0, window: "bytes_day", scope — account или route:<группа>. Открытое соединение закрывается 1008, новая рыночная подписка получает отказ тем же кодом
revoked_key, plan_inactive, invalid_key, insufficient_scope доступ кончился посреди соединения: закрытие 1008 с кодом в причине

Поток опционов /v1/options/stream кадров error не шлёт: отказы приходят HTTP-ответом до апгрейда, закрытия — кодом и причиной (4008, 1011, 1001, 1013, 1008), подробно — живой поток.

Подробно — Потоки WebSocket.

https://docs.lootx.trade/uk/market-api/error-codes