Інструменти, час і сторінки
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. Які кроки приймає маршрут — у його описі.
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) не стискається — він і так щільний.
Добовий обсяг тарифу рахується за тілом до стиснення: запит коштує однаково зі стисненням і без, а стиснення економить лише час і трафік.
https://docs.lootx.trade/uk/market-api/conventions