Маржинальное кредитование
1Маржинальное кредитование
Займы и возвраты пула маржи Binance по активам, чистые займы и их z-оценки, запас пула, ставки займа Binance, OKX, Bybit и ставка кредитора Gate, эпизоды «пул пуст» и покрытие источников.
Пул маржи Binance — кросс (kind=margin) и изолированный (kind=isolated): сколько актива заняли и вернули, чистые займы и их z-оценки, запас пула; ставки займа Binance, OKX и Bybit и ставка кредитора Gate; эпизоды, когда пул актива опустел. Все шесть маршрутов — одна группа тарифа margin. Инструмента здесь нет: актив называется так, как его называет площадка, — BTC, USDT, PEPE.
Займы и возвраты выводятся из запаса пула по минутам: убыль запаса за минуту — займ, прибыль — возврат. Это нижняя граница: займ и возврат внутри одной минуты гасят друг друга, а пополнение пула самой площадкой попадает в возвраты. Минута без наблюдения не даёт ни займа, ни возврата, и следующая за ней тоже: разницу через дыру не считают.
Единицы и null
| Что | Как приходит | Где |
|---|---|---|
| Время | мс Unix UTC; бакеты — по сетке своего шага в UTC | ts, start, end, as_of, inventory_ts |
| Деньги | *_usd_e8 — целым числом строкой, USDT × 10⁸: "4795955961" — 47,95955961 USDT |
borrow_usd_e8, net_usd_e8, inventory_usd_e8, borrow24h_usd_e8, net_usd_e8:<АКТИВ> |
| Количества | в единицах актива, точная десятичная запись строкой, без хвостовых нулей, ноль — "0" |
borrow, repay, volume, net, net_cum, inventory, borrow_24h, borrow_limit |
| Цены | в USDT, десятичной строкой | price, price_usdt, btc_price_usdt |
| Ставки | годовая доля десятичной строкой, простая: дневная × 365, часовая × 8760, годовая как есть. "0.0460484" — 4,60484 % годовых |
rate_apr, rate_apr_binance, rate_apr_okx, rate_apr_bybit, lend_apr_gate |
| z и проценты | числом с двумя знаками: 4.99, -12.5 — это статистика, а не деньги |
borrow_z, repay_chg_pct, growth_pct |
Деньги за окно — сумма займа каждой минуты по цене этой же минуты, посчитанная точно и округлённая один раз. Разбирайте *_usd_e8 как целое произвольной длины или десятичный тип: значение бывает больше 2⁵³. Деньги не округляются к шагу цены ни у нас, ни в ваших расчётах не должны.
null — «нет данных», а не ноль. Бакет без единой минуты с данными — null. Нет цены — null в долларовых колонках, а количества в единицах актива есть. Меньше 20 точек для z — null. Изменение от нуля — null.
Активы пула
/v1/margin/assetsСтрока на актив пула, по имени: суммы за окно, z и изменения, запас, цена и ставки четырёх площадок. Группа тарифа — margin.
| Параметр | Что |
|---|---|
window |
окно сумм: 1d, 7d, 30d, 90d, по умолчанию 7d. Окно начинается с часа, текущий час включён |
change_period |
период изменений и z: 5m, 15m, 30m, 1h, 4h, 12h, 1d, 7d, 30d, по умолчанию 1h. Берутся целые периоды, текущий неполный не входит |
z_window |
выборка z: 3d, 7d, 14d, 30d, по умолчанию 7d |
units |
base (по умолчанию) — в единицах актива, usdt — деньги *_usd_e8 |
kind |
пул: margin (кросс, по умолчанию) или isolated |
curl -s "https://market-api.lootx.trade/v1/margin/assets?window=7d&units=usdt" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"as_of": 1795049940000,
"columns": ["asset", "borrow_usd_e8", "repay_usd_e8", "volume_usd_e8", "net_usd_e8", "borrow_z", "repay_z", "borrow_chg_pct", "repay_chg_pct", "borrow_chg_z", "repay_chg_z", "inventory_usd_e8", "inventory_ts", "price_usdt", "rate_apr_binance", "rate_apr_okx", "rate_apr_bybit", "lend_apr_gate"],
"rows": [
["BTC", "1843077512200", "1702455120000", "3545532632200", "140622392200", 1.27, 0.84, 12.5, -3.1, 0.92, -0.2, "4513220551834400", 1795049940000, "100294.5", "0.0460484", "0.0365", "0.0219", "0.05"]
],
"next_cursor": null
}| Колонка | Что |
|---|---|
as_of |
новейшая минута, к которой относятся суммы и запас, мс |
borrow, repay, volume, net |
займы, возвраты, их сумма и разность за окно, в единицах актива. С units=usdt — borrow_usd_e8, repay_usd_e8, volume_usd_e8, net_usd_e8 |
borrow_z, repay_z |
z-оценка займов (возвратов) за последний период change_period против периодов выборки z_window перед ним |
borrow_chg_pct, repay_chg_pct |
изменение к предыдущему периоду, % |
borrow_chg_z, repay_chg_z |
z-оценка этого изменения |
inventory |
запас пула на новейшей наблюдённой минуте, в единицах актива; null, если она старше as_of больше чем на 5 минут. С units=usdt — inventory_usd_e8 |
inventory_ts |
время этой минуты, мс; null — наблюдений нет за 48 часов |
price_usdt |
цена актива на as_of |
rate_apr_binance, rate_apr_okx, rate_apr_bybit |
ставка займа базового уровня площадки (Binance 0, OKX basic, Bybit No VIP) не старше 15 минут |
lend_apr_gate |
ставка кредитора Gate — не ставка займа |
z и изменения считаются в единицах актива при любом units. Источник пересобирает ответ раз в минуту, а не на запрос: as_of говорит, к какой минуте он относится.
Ряд актива
/v1/margin/seriesРяд одного актива по бакетам шага: цена, займы, возвраты, чистые и накопленные займы, z и изменения, запас, ставка Binance. Группа тарифа — margin.
| Параметр | Что |
|---|---|
asset |
обязательный: актив, как его называет площадка, любое письмо, без запятой, до 64 байт |
step |
шаг бакета: 1m, 5m, 1h, по умолчанию 5m |
from |
начало, мс; источник округляет его вниз к шагу. По умолчанию — окно шага до to: 1 сутки у 1m, 7 суток у 5m, 30 суток у 1h. Глубина тарифа меряется по нему |
to |
конец, мс; округляется вверх к шагу, не позже конца текущей минуты. По умолчанию — сейчас |
metrics |
метрики через запятую: price, borrow, repay, net, net_cum, borrow_z, repay_z, borrow_chg_pct, repay_chg_pct, borrow_chg_z, repay_chg_z, inventory, rate_apr. По умолчанию — price,borrow,repay |
units |
base (по умолчанию) или usdt |
kind |
margin (по умолчанию) или isolated |
z_window |
выборка z: 3d, 7d, 14d, 30d, по умолчанию 7d; период z — шаг |
Самое длинное окно — 1 сутки у 1m, 8 суток у 5m и 90 суток у 1h; длиннее — 400 upstream_rejected с param: "from".
curl -s "https://market-api.lootx.trade/v1/margin/series?asset=BTC&step=1h&from=1794960000000&to=1794967200000&metrics=price,borrow,repay,net&units=usdt" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"columns": ["ts", "price", "borrow_usd_e8", "repay_usd_e8", "net_usd_e8"],
"rows": [
[1794960000000, "99812.4", "512300410000", "498112000000", "14188410000"],
[1794963600000, "100120.1", "301772500000", "355910020000", "-54137520000"]
],
"next_cursor": null
}ts— начало бакета, дальше по колонке на метрику в порядкеmetrics. Сunits=usdtborrow,repay,net,net_cumиinventoryприходят какborrow_usd_e8,repay_usd_e8,net_usd_e8,net_cum_usd_e8иinventory_usd_e8.price— закрытие бакета: последняя цена в нём или протянутая в него не дольше 5 минут.inventory— запас на последней наблюдённой минуте бакета;rate_apr— ставка займа Binance базового уровня, последняя в бакете.net_cum— нарастающийnetот первого бакета ряда; у бакета без данных —null.
Страниц нет: next_cursor всегда null, окно режьте сами.
Сравнение активов
/v1/margin/compareЧистые займы нескольких активов в USDT по бакетам и цена BTC — для одного графика. Группа тарифа — margin.
| Параметр | Что |
|---|---|
assets |
активы через запятую, до 8. По умолчанию — BTC,ETH,USDT,USDC |
window |
окно: 1d, 7d, 30d, 90d, по умолчанию 7d |
step |
шаг: 5m (только окно 1d), 1h (по умолчанию), 1d |
kind |
margin (по умолчанию) или isolated |
curl -s "https://market-api.lootx.trade/v1/margin/compare?assets=BTC,ETH&window=1d&step=1h" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"as_of": 1795049940000,
"columns": ["ts", "btc_price_usdt", "net_usd_e8:BTC", "net_usd_e8:ETH"],
"rows": [
[1794963600000, "99950.2", "140622392200", "-2311045000"],
[1794967200000, "100120.1", "-54137520000", "905512300"]
],
"next_cursor": null
}Пример сокращён до двух бакетов. Колонки — ts, закрытие BTC btc_price_usdt и по колонке net_usd_e8:<АКТИВ> на каждый актив запроса, в его порядке. Бакеты идут от того, в котором лежит начало окна, до текущего включительно.
Эпизоды «пул пуст»
/v1/margin/eventsЭпизоды, когда запас актива в пуле кончился, задевшие окно, — новые первыми. Группа тарифа — margin.
| Параметр | Что |
|---|---|
window |
окно: 1d, 7d, 30d, 90d, по умолчанию 7d |
borrow24h_min_usd |
порог займа за сутки до начала эпизода, USDT, десятичной записью ≥ 0; 0 — без порога. По умолчанию 10000 |
growth_period |
период роста займа: только 15m |
growth_min_pct |
порог роста займа, %, десятичной записью; 0 — без порога. По умолчанию 100 |
kind |
margin или isolated; без параметра — оба пула |
{
"as_of": 1795049940000,
"columns": ["asset", "kind", "start", "end", "end_reason", "borrow_24h", "borrow24h_usd_e8", "growth_pct", "empty_for_s"],
"rows": [
["ACT", "margin", 1795020000000, 1795023600000, "refilled", "125000000", "2187500000000", 340.5, 3600]
],
"next_cursor": null
}| Колонка | Что |
|---|---|
start, end |
начало и конец эпизода, мс; end: null — пул всё ещё пуст |
end_reason |
refilled — пул пополнился, delisted — актив сняли, null — эпизод идёт |
borrow_24h, borrow24h_usd_e8 |
займ за сутки до начала: в единицах актива строкой и в USDT × 10⁸ по цене минуты начала |
growth_pct |
рост займа: 15 минут до начала против 15 минут перед ними, %; null — сравнивать не с чем |
empty_for_s |
секунд от начала до конца, у идущего — до «сейчас» |
В ответ попадают эпизоды, у которых займ за сутки выше порога borrow24h_min_usd и рост выше growth_min_pct; рост null проходит только порог 0. Эпизодов нет — 200 с пустыми rows, так же и без ключа Binance. Источник держит эпизоды 90 суток, не больше 5 000: сверх этого — новейшие по началу, а покрытие говорит events_truncated: true.
Ставки площадок
/v1/margin/ratesСтавки одного актива по времени, старые первыми. Группа тарифа — margin.
| Параметр | Что |
|---|---|
asset |
обязательный, как у /v1/margin/series |
venues |
площадки через запятую: binance, okx, bybit, gate. По умолчанию — все четыре |
from |
начало, мс. По умолчанию — сутки до to. Глубина тарифа меряется по нему |
to |
конец, мс; позже «сейчас» — считается «сейчас». Окно — до 31 суток |
vip_level |
уровень VIP для каждой площадки запроса. По умолчанию — базовый у каждой |
side |
borrow — ставка заёмщика: Binance, OKX, Bybit; lend — ставка кредитора: Gate. Без параметра — обе стороны |
curl -s "https://market-api.lootx.trade/v1/margin/rates?asset=USDT&venues=binance,bybit,gate&from=1795046400000&to=1795050000000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"columns": ["ts", "venue", "side", "vip_level", "rate_apr", "src_unit", "borrow_limit"],
"rows": [
[1795046400000, "binance", "borrow", "0", "0.0460484", "day", "1500.5"],
[1795046400000, "bybit", "borrow", "No VIP", "0.0219", "hour", null],
[1795046400000, "gate", "lend", "", "0.05", "year", null]
],
"next_cursor": null
}| Колонка | Что |
|---|---|
side |
чья ставка: borrow — платит заёмщик, lend — получает кредитор |
vip_level |
уровень площадки: базовый у Binance — 0, у OKX — basic, у Bybit — No VIP, у Gate уровня нет — "" |
rate_apr |
годовая доля десятичной строкой |
src_unit |
в какой единице ставку дала площадка: day, hour или year |
borrow_limit |
предел займа в единицах актива строкой; нет у площадки — null |
Ставка Gate — только кредитора. Ставку заёмщика Gate отдаёт только по ключу аккаунта, её не собирают: side=borrow строк Gate не даёт, а в /v1/margin/assets у Gate колонка lend_apr_gate, а не ставка займа.
Покрытие источников
/v1/margin/coverageЧто источник маржи собирает и насколько свежо: запас пула и его пулы, цены, ставки площадок. Не таблица: CSV — 400 bad_format. Группа тарифа — margin; параметров, кроме format, нет.
{
"as_of": 1795049940000,
"events_truncated": false,
"sources": [
{"source": "inventory", "state": "no_key", "reason": null, "last_minute": null, "gaps_24h": [], "gap_minutes_24h": 0, "used_weight_ip_1m": null},
{"source": "rates_binance", "state": "enabled", "reason": null, "last_minute": 1795049940000, "gaps_24h": [], "gap_minutes_24h": 0, "used_weight_ip_1m": null}
]
}Источники идут по порядку: inventory, inventory_margin, inventory_isolated, prices, rates_binance, rates_okx, rates_bybit, rates_gate (пример сокращён до двух).
| Поле | Что |
|---|---|
as_of |
новейшая минута кэша источника, мс; null — источник ещё прогревается |
events_truncated |
events_truncated: true — эпизодов за 90 суток больше 5 000: в /v1/margin/events — новейшие 5 000 по началу, старшие опущены |
state |
enabled; disabled — источник выключен или данных не было; no_key — нет ключа Binance, запас не опрашивается, остальное отвечает; error |
reason |
у error: stale — данные отстали (запас — больше 5 минут, цены и ставки — 5 и 15 минут), store — склад не читается, warming — прогрев; иначе null |
last_minute |
новейшая минута источника, мс |
gaps_24h, gap_minutes_24h |
дыры за последние сутки — [from, to или null, причина] — и сколько в них минут |
used_weight_ip_1m |
вес запросов к Binance на новейшем ответе запаса; только у inventory |
Покрытие отвечает всегда, и в прогреве тоже.
Глубина истории
Глубину проверяет тариф — history_days: меньший из общего и группового (группы margin), если у группы свой. Как меряется, зависит от маршрута:
/v1/margin/assets,/compare,/events— по окну.window=30dтребует 30 суток истории от «сейчас». Глубже тарифа —403 history_out_of_planсparam: "window", вexpected— «окно не длиннее N сут.», где N —history_daysтарифа: возьмите окно короче./v1/margin/seriesи/rates— поfrom. У series присланныйfromисточник округляет вниз к шагу, и шлюз меряет округлённый:fromровно на границе тарифа посреди часа уstep=1hполучит отказ.earliest_allowed_msв отказе — первыйfromна сетке шага не раньше границы, повтор с ним проходит.- Без
fromшлюз меряет окно по умолчанию отmin(to, сейчас). Если оно глубже тарифа, отказ —param: "from"с текстом «from не прислан, окно по умолчанию … глубже тарифа — пришлите from не раньше X»: пришлитеfromне раньшеearliest_allowed_ms.
change_period и z_window глубиной тарифа не меряются.
Кэш и ETag
/v1/margin/assets, /compare, /events и /coverage источник собирает из своего кэша раз в минуту; шлюз их не кэширует, свежесть — по as_of.
Слабый ETag есть только у закрытых окон /v1/margin/series и /v1/margin/rates: окно, кончившееся не позже чем за 30 минут до начала текущего часа. Метка приходит в любом формате — данные те же.
- Пришлите её в
If-None-Match— если данные не менялись, ответ304без тела: запрос засчитывается, а в суточный объём не идёт. - Повтор закрытого окна шлюз отдаёт из своего кэша с той же меткой.
- Поздняя запись источника в закрытое окно меняет метку; кэш шлюза увидит её не сразу.
curl -s -o /dev/null -w "%{http_code}\n" "https://market-api.lootx.trade/v1/margin/series?asset=BTC&step=1h&from=1794960000000&to=1794967200000" \
-H "Authorization: Bearer $LOOTX_API_KEY" -H 'If-None-Match: W/"m1-00ff"'Отказы
| Ответ | Когда | Что делать |
|---|---|---|
400 bad_request |
параметра нет у маршрута (param — его имя), параметр повторён, window или step series не из списка, нет asset |
исправьте запрос по param и expected |
400 upstream_rejected |
источник отверг значение: его текст в message начинается с имени параметра (units: …), оно же в param |
исправьте названный параметр |
403 history_out_of_plan |
окно или from глубже тарифа — выше |
окно короче или from не раньше earliest_allowed_ms |
503 upstream_unavailable |
источник перегружен или прогревается: кэш после запуска, склад не читается, очередь сборки ответов assets и compare полна. Приходит с Retry-After: 2 |
повторите через Retry-After |
502 upstream_error |
источник ответил ошибкой или телом не той формы, маршрутов маржи у источника нет | повторите позже; не проходит — напишите в поддержку с request_id |
502 upstream_unavailable, 504 upstream_timeout |
источник недоступен или не ответил вовремя (за 15 с) | повторите позже; у assets и compare долгая сборка не теряется — повтор присоединится к ней и получит готовый ответ |
Все коды — на странице ошибок.
https://docs.lootx.trade/uk/market-api/margin