LootX

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

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

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.