LootX

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

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

Три правила, спільні для всіх маршрутів: ім'я інструмента 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) не стискається — він і так щільний.

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