Инструменты, время и страницы
Три правила, общие для всех маршрутов: имя инструмента 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. Какие шаги принимает маршрут — в его описании.
from datetime import datetime, timezone
t0 = int(datetime(2026, 11, 4, tzinfo=timezone.utc).timestamp() * 1000) # 1793750400000Ответ — таблица колонками
Ряды приходят не массивом объектов, а таблицей: имена колонок один раз, строки — массивами значений в том же порядке. Так ответ короче в несколько раз.
{
"instrument": "binance:perp:BTCUSDT",
"columns": ["ts", "open", "high", "low", "close"],
"rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3]],
"next_cursor": null
}Превратить в привычные объекты — одна строка:
const records = body.rows.map((r) => Object.fromEntries(body.columns.map((c, i) => [c, r[i]])));Полей в ответе может стать больше — не полагайтесь на их порядок и не падайте на незнакомом поле. Порядок колонок внутри таблицы задаёт columns.
Страницы
Если ответ не поместился в одну страницу, в нём есть next_cursor. Передайте его как cursor= с теми же остальными параметрами — получите следующую страницу. next_cursor: null — страниц больше нет.
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(форматы).
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) не сжимается — он и так плотный.
Суточный объём тарифа считается по телу до сжатия: запрос стоит одинаково со сжатием и без, а сжатие экономит только время и трафик.