Форматы ответа, числа и деньги
1Форматы ответа, числа и деньги
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.
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"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,51270CSV
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⁵³ не теряются.
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.
https://docs.lootx.trade/es/market-api/formats