← К документации
LootX

Инструменты, время и страницы

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

1Инструменты, время и страницы

Три правила, общие для всех маршрутов: имя инструмента 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/ru/market-api/conventions