API данных
Платный API рыночных данных: свечи, сделки, стакан, OI, фандинг, плотности и скринер — один ключ, REST и WebSocket.
1Արագ մեկնարկ
Բանալին, հասցեն, առաջին հարցումը — BTCUSDT մոմերը Binance-ից հինգ րոպեում։
API շուկայական տվյալների LootX-ը տալիս է նույն տվյալները, որոնց վրա աշխատում է տերմինալը. մոմեր մեկ վայրկյանից, time and sales, ֆուտպրինտ, order book-ի ջերմային քարտեզ, open interest, funding rate, liquidity walls և screener: Բոլոր բորսաները՝ մեկ հասցեով և մեկ բանալիով, նույն գործիքների անուններով և մեկ ժամանակի ձևաչափով։
Հինգ րոպեում
Ստացեք բանալին
Բացեք Կաբինետ → API բանալիները և սեղմեք Ստեղծել բանալի։ Տվեք բանալիին հասկանալի անուն՝ օրինակ, ըստ սկրիպտի կամ սերվերի անվան, որտեղ այն կապրի։
Բանալին ունի lx_live_ և ևս 43 նշան։ Այն ցուցադրվում է մեկ անգամ. պահպանեք այն գաղտնաբառերի մենեջերում կամ միջավայրի փոփոխականում։ Կորցրել եք՝ չեղարկեք բանալին և թողարկեք նորը։
Բանալին աշխատում է, քանի դեռ հաշիվն ունի գործող API սակագին։ Սակագինը ընտրվում է նույն էջում, եթե այն բաց է գնման համար, կամ այն նշանակում է LootX-ի ադմինիստրատորը։
Հիշեք հասցեն և բանալին փոխանցելու եղանակը
Բազային հասցեն՝ https://market-api.lootx.trade։ Բանալին փոխանցվում է վերնագրով՝
Authorization: Bearer lx_live_...կամ X-API-Key: lx_live_.... Բանալին երբեք չի դրվում հասցեի մեջ. հարցումների տողերը մնում են պրոքսիների և բրաուզերների լոգերում, ուստի հասցեում բանալիով հարցումը ստանում է 400 key_in_query։
Կատարեք առաջին հարցումը
Վերջին երեք րոպեական մոմերը Binance-ի անժամկետ BTCUSDT կոնտրակտի (վերջինը՝ ընթացիկ րոպեն է, այն դեռ փակված չէ)՝
export LOOTX_API_KEY="lx_live_..."
curl -s "https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&limit=3" \
-H "Authorization: Bearer $LOOTX_API_KEY"Պատասխանը սյունակներով աղյուսակ է. անունները columns-ում, տողերը rows-ում, արժեքները նույն հերթականությամբ (ստորև բերված թվերը օրինակի համար են)՝
{
"instrument": "binance:perp:BTCUSDT",
"tf": "1m",
"columns": ["ts", "open", "high", "low", "close", "volume", "quote_volume",
"buy_volume", "buy_quote_volume", "trades", "buy_trades"],
"rows": [
[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3, 41.27, 4302517.62, 22.91, 2388563.12, 1824, 1003],
[1793750460000, 104255.3, 104270.0, 104249.8, 104266.9, 28.04, 2923450.40, 15.33, 1598336.46, 1310, 702],
[1793750520000, 104266.9, 104268.4, 104230.2, 104233.0, 36.58, 3813166.95, 14.02, 1461540.90, 1597, 688]
],
"next_cursor": null,
"coverage": { "oldest": 1792741800000, "newest": 1793750520000 }
}ts— մոմի սկիզբը միլիվայրկյաններով UTC-ով;volume— ծավալը մետաղադրամներով,quote_volume— quote-արժույթով (USDT զույգերի դեպքում դոլարներով);next_cursor: null— էջերն ավարտվել են. հակառակ դեպքում փոխանցեք այն որպեսcursor=(ինչպես թերթել);coverage— ինչ ժամանակահատված ընդհանրապես կա պահեստում այս գործիքի համար: API-ում մոմերի պատմությունը սկսվում է 23.10.2026-ից (մանրամասն՝ Մոմերում):
Եթե ինչ-որ բան այն չէ
Գեյթվեյի ցանկացած սխալ՝ HTTP կոդ և JSON մեքենայական կոդով: Առանց բանալիի՝ 401 WWW-Authenticate: Bearer realm="lootx" վերնագրով և մարմնով՝
{
"error": {
"code": "missing_key",
"message": "պետք է բանալի. վերնագիր Authorization: Bearer <բանալի> կամ X-API-Key",
"request_id": "a553713a48d85b96-VIE",
"docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#missing_key"
}
}Վերլուծեք code դաշտը, ոչ թե message տեքստը. տեքստը կարող է փոխվել: API-ն կարդում է միայն GET (և HEAD, OPTIONS). այլ մեթոդը կստանա 405 method_not_allowed։ request_id-ն ուղարկեք աջակցությանը, եթե սխալն անհասկանալի է. դրանով մենք կգտնենք հարցումը։ Բոլոր կոդերը՝ Սխալներ բաժնում։
Ինչ հաջորդը
Ինչպես անվանել գործիքները, ինչով է հաշվվում ժամանակը և ինչպես ստանալ հաջորդ էջը։
Մոմեր և շարքերՄոմեր մեկ վայրկյանից մինչև օր, CVD, դելտա և ծավալ կողքին։
WebSocket հոսքերLiquidity walls, screener, գործարքներ, OI և վայրկյանական մոմեր իրական ժամանակում։
Սահմանաչափեր և սակագներԻնչն է սահմանափակում սակագինը, որ վերնագրերը դիտել և ինչ անել 429-ի դեպքում։
Ինտերակտիվ սպեցիֆիկացիա՝ market-api.lootx.trade/docs, մեքենայաընթեռնելի՝ /v1/openapi.json (OpenAPI 3.1, բանալին պետք չէ)։
https://docs.lootx.trade/hy/market-api/getting-started
2Գործիքներ, ժամանակ և էջեր
Երեք կանոն՝ ընդհանուր բոլոր երթուղիների համար․ գործիքի անունը venue:market:SYMBOL, ժամանակը UTC միլիվայրկյաններով և թերթում next_cursor-ի միջոցով։
API-ի բոլոր երթուղիները խոսում են մեկ լեզվով․ գործիքը նույն անունն ունի ցանկացած բորսայում և ցանկացած աղբյուրում, ժամանակը միշտ Unix-միլիվայրկյաններ է UTC, երկար պատասխանը թերթվում է cursor-ով։ Այստեղ այս երեք կանոնները մեկ անգամ և մանրամասն։
Գործիքի անունը
Գործիքը գրվում է venue:market:SYMBOL ձևաչափով․
| Օրինակ | Ինչ է սա |
|---|---|
binance:perp:BTCUSDT |
Բինանսում BTC-ի USDT անժամկետ կոնտրակտ |
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-ի բաժնետոմս Hyperliquid-ի xyz դեքում (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 - բազան և quote-ը միասին, մեծատառերով․
BTCUSDT,ETHUSDC։ Բացառությունները Hyperliquid-ն ու Coinbase-ն են, ինչպես աղյուսակում։
Անվան սխալ ձևը 400 bad_instrument է։ Անունը ճիշտ է, բայց երթուղին այդպիսի շուկա կամ բորսա չգիտի՝ 400 unsupported_instrument param: "instrument"-ով։ Սիմվոլը ստուգում են միայն /v1/candles-ը և /v1/series-ը, այն էլ ոչ միշտ․ զույգը, որը աղբյուրում չկա, կարող է այնտեղ ստանալ 400 unsupported_instrument param: "symbol"-ով, իսկ աղբյուրի խափանման դեպքում՝ դատարկ 200։ Մյուս երթուղիներում սիմվոլը ռեեստրի հետ չի ստուգվում․ զույգը և տառասխալ անունը, որոնք անցել են բորսայի, շուկայի և quote-ի ստուգումը, ստանում են 200 առանց տողերի։ Ստուգեք անունը ռեեստրով, մերժման պայմաններն ու բացառությունները՝ սխալների էջում։
Ժամանակ
- Ժամանակն ամենուր Unix-միլիվայրկյաններ է UTC-ով, ամբողջ թիվ․
1793750400000- 2026 թ. նոյեմբերի 4, 00:00 UTC։ - Հարցման պատուհանը կիսաբաց է
[from, to)․from-ը ներառվում է,to-ն՝ ոչ։ Այսպես հարակից պատուհանները միանում են առանց կրկնությունների։ - Յուրաքանչյուր երթուղի ունի իր լռելյայն արժեքները․ մոմերն առանց
from-ի վերցնում ենlimitքայլ հետto-ից, գործարքները՝ վերջին ժամը, open interest-ը՝ վերջին օրը։ Առանց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"]- Cursor-ը անթափանց տող է, ներսում միայն շարունակության դիրքն է։ Gateway-ը չի ստուգում մյուս պարամետրերը առաջին էջի հետ համապատասխանեցնելով․ այլ պարամետրերով էջը կկառուցվի դրանցով այդ դիրքից։ Ուստի cursor-ը փոխանցեք նույն
instrument-ով,tf-ով,to-ով,limit-ով և մնացածով։400 bad_cursor- միայն եթե cursor-ը վնասված է։ - Մոմերը էջերի են բաժանվում քայլի ցանցով, իսկ գործարքների դեպքում մեկ միլիվայրկյանի բոլոր գրառումներն ամբողջությամբ մեկ էջ են գնում, հանգույցում կրկնություններ և բացթողումներ չկան։
- Ուղղությունը երթուղիների մեծ մասում հնից նորին է։ Բացառություն․ liquidity walls-ի պատմությունը թերթվում է թարմից հնին։
- Ցանկացած ձևաչափում հաջորդ էջը կա նաև վերնագրերում․
X-Next-Cursor-ը cursor-ն է,Link-ը՝ հաջորդ էջի պատրաստի հասցեն (RFC 8288)։ CSV-ում cursor-ը միայն վերնագրում է, protobuf-ում՝ նաևnext_cursorդաշտում (ձևաչափեր)։
Link: <https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=1m&cursor=YzE6MTc5MTMzMTMyMDAwMA>; rel="next"
X-Next-Cursor: YzE6MTc5MTMzMTMyMDAwMALink-ի հասցեն նույն հարցումն է նոր cursor-ով․ կարող եք գնալ դրանով՝ ոչինչ չհավաքելով։ Վերջին էջը Link և X-Next-Cursor վերնագրեր չի կրում։
Վերնագրեր, որոնք արժե լոգավորել
| Վերնագիր | Ինչու |
|---|---|
X-Request-Id |
հարցման համարը, նույնը, ինչ request_id-ն սխալի մարմնում։ Ուղարկեք այն աջակցությանը |
X-RateLimit-Remaining |
քանի հարցում է մնացել ամենասեղմ սահմանաչափում, մանրամասն |
X-Cache |
կա միայն այն պատասխաններում, որոնք gateway-ը կարող է cache-ավորել (փակ դիապազոններ)․ HIT - gateway-ի հիշողությունից, MISS - աղբյուրից։ Փակ դիապազոնները gateway-ը հիշում է մինչև 10 րոպե։ Մյուս պատասխաններում այս վերնագիրը չկա |
RateLimit |
մնացորդը և վայրկյանները մինչև զրոյացում սակագնի բոլոր պատուհաններով, մանրամասն |
X-Request-Id-ը gateway-ը դնում է ինքը յուրաքանչյուր պատասխանի վրա, դա այն համարն է, որով մենք կգտնենք հարցումը։
Սեղմում
Պատասխանները սեղմվում են, եթե հաճախորդը դա խնդրում է․ Accept-Encoding: gzip կամ br։ curl-ը խնդրում է --compressed-ով, requests-ը և բրաուզերը՝ ինքնաբերաբար։ Ջերմաքարտեզի binary-ն (HMP1/HMP2) չի սեղմվում, այն առանց այդ էլ խիտ է։
Սակագնի օրական ծավալը հաշվվում է մինչև սեղմումը մարմնով․ հարցումը նույն արժեքն ունի սեղմմամբ և առանց դրա, իսկ սեղմումը խնայում է միայն ժամանակ և տրաֆիկ։
https://docs.lootx.trade/hy/market-api/conventions
3SDK Python-ի և TypeScript-ի համար
lootx (Python) և @lootx/sdk (TypeScript) հաճախորդներ — էջերի թերթում, աղյուսակներ DataFrame-ում, հոսքեր և կրկնություններ 429-ի դեպքում առանց ձեռքով կոդի։
Երկու հաճախորդներն էլ կառուցված են նույն կերպ. մեթոդ յուրաքանչյուր երթուղու համար, նույն պարամետրերի անունները, էջերի թերթում մեկ կանչով, աղյուսակները գրառումներում կամ DataFrame-ում, հոսքեր ավտոմատ վերամիացմամբ։
Տեղադրում
Python 3.10 և ավելի նոր։
pip install lootx # հրապարակումից հետո
pip install "lootx[pandas]" # + to_dataframe()
pip install "lootx[protobuf]" # + format="protobuf"Node.js 18 և ավելի նոր կամ բրաուզեր։
npm install @lootx/sdk # հրապարակումից հետոԱռաջին հարցում
from lootx import Client
lx = Client("lx_live_...") # կամ միջավայրի փոփոխական LOOTX_API_KEY
bars = lx.candles("binance:perp:BTCUSDT", tf="1m", from_=1793750400000, limit=500)
df = bars.to_dataframe(datetimes=True)
# բոլոր էջերը միանգամից
oi = lx.iter_oi("bybit:perp:ETHUSDT", from_=1793750400000, to=1793836800000).collect()import { Client, records } from "@lootx/sdk";
const lx = new Client({ apiKey: "lx_live_..." }); // կամ LOOTX_API_KEY շրջակա միջավայրում (Node)
const bars = await lx.candles({ instrument: "binance:perp:BTCUSDT", tf: "1m", from: 1793750400000, limit: 500 });
const rows = records(bars); // [{ ts, open, high, ... }]
const oi = await lx.iterOi({ instrument: "bybit:perp:ETHUSDT", from: 1793750400000, to: 1793836800000 }).collect();Նույնը երկուսում էլ
| Python | TypeScript | |
|---|---|---|
| Մեթոդներ | snake_case, անունը = operationId սպեցիֆիկացիայի |
camelCase նույն անվան |
| Պարամետրեր | ինչպես API-ում; from → from_ |
ինչպես API-ում, օբյեկտով |
| Ժամանակ | Unix-մվ UTC կամ datetime |
Unix-մվ UTC կամ Date |
| Բոլոր էջերը | iter_*() → collect(), rows(), to_dataframe() |
iter*() → collect(), rows() |
| Աղյուսակ | records(), column(), to_dataframe() |
records(t), column(t, name) |
| Երկուական ձևաչափ | Client(format="protobuf") |
new Client({ format: "protobuf" }) |
| Սխալներ | բացառություններ ըստ կոդի, .code, .request_id, .retry_after |
նույն դասերը, .code, .requestId, .retryAfter |
| Հոսքեր | feed() — միասնական /v1/ws |
feed() |
Հոսքեր
feed()-ը բացում է մեկ միացում /v1/ws և հիշում է բաժանորդագրությունները. ընդհատումից հետո վերամիանում է և նորից ինքնաբերաբար բաժանորդագրվում։
with lx.feed() as f:
f.subscribe("trades", ["binance:perp:BTCUSDT"])
f.subscribe("densities", ["binance:perp:BTCUSDT", "hyperliquid:perp:BTC"])
for msg in f:
if msg["type"] == "update" and msg["channel"] == "trades":
print(msg["instrument"], msg["data"]["trades"])const f = lx.feed();
f.subscribe("trades", ["binance:perp:BTCUSDT"]);
f.subscribe("densities", ["binance:perp:BTCUSDT", "hyperliquid:perp:BTC"]);
for await (const m of f) {
if (m.type === "update" && m.channel === "trades") console.log(m.instrument, m.data);
}Ամբողջ շուկան densities կամ screener ալիքի ֆիլտրերով — subscribe_market (subscribeMarket), նույն պարամետրերը, ինչ scope: "market"-ում։ Մեկ բաժանորդագրություն ալիքի համար միացման մեջ. նորը փոխարինում է նախորդին, բացել դրանք կարելի է վայրկյանը մեկ։ Հանում է բաժանորդագրությունը unsubscribe_market-ը (unsubscribeMarket)։ Ընդհատումից հետո feed()-ը բաժանորդագրությունը նորից է ուղարկում։
with lx.feed() as f:
f.subscribe_market("densities", venues=["binance"], markets=["perp"], min_usd=250_000)
for msg in f:
if msg["type"] in ("snapshot", "update") and msg.get("scope") == "market":
for item in msg["items"]:
print(item["instrument"], item["data"])const f = lx.feed();
f.subscribeMarket("densities", { venues: ["binance"], markets: ["perp"], min_usd: 250_000 });
for await (const m of f) {
if (m.scope === "market" && m.items) for (const it of m.items) console.log(it.instrument, it.data);
}Բաժանորդագրությունը, որը չի անցել միացման կամ վերամիացման ժամանակ, feed()-ը կրկնում է ինքը, եթե gateway-ը պատասխանել է market_subs_limit կամ rate_limited. հին տեղը gateway-ը անմիջապես չի վերադարձնում։ Կրկնություններ մինչև 3 անգամ, դադարը՝ retry_after, բայց ոչ ավելի քան 30 վ, կամ 1, 4 և 16 վ պատահական հավելումով մինչև քառորդը. սրանք վերամիացման լռելյայն կարգավորումներն են։ Մերժման կադրը կստանաք միայն վերջինը, երբ փորձերը սպառվեն։ Բաժանորդագրությունը, որը չի անցել միացման կամ վերամիացման ժամանակ, այդպիսի մերժումից հետո և ցանկացած այլից հետո, օրինակ bad_params, մնում է SDK-ում և նորից կուղարկվի հաջորդ վերամիացման ժամանակ. հանում է այն unsubscribe_market-ը (unsubscribeMarket)։ Կենդանի միացման վրա հրամանը SDK-ն չի կրկնում. մերժումը գալիս է ձեզ։ Ֆիլտրերը, որոնք մերժվել են կենդանի հրամանով, SDK-ն հետ է գլորում. վերամիացման ժամանակ կուղարկվի այն, ինչ gateway-ն ընդունել է կենդանի հրամանով կամ ինչ ուղարկվել է միացման ժամանակ և հանված չէ, իսկ եթե այդպիսին չկա, ոչինչ չի ուղարկվի։ Այդ ալիքի նոր շուկայական հրամանը (subscribe_market կամ unsubscribe_market), նոր միացումը և feed()-ի փակումը չեղարկում են սպասվող կրկնությունը։
Սխալներ և կրկնություններ
API-ի սխալը վերածվում է իր դասի բացառության — MissingKeyError, RevokedKeyError, PlanInactiveError, BadInstrumentError և այլն ըստ սխալի կոդի. 405-ի, 406-ի, 408-ի և 413-ի դեպքում՝ MethodNotAllowedError, NotAcceptableError, RequestTimeoutError և PayloadTooLargeError։ Բացառությունն ունի code, request_id (requestId) և սխալի մարմնի մանրամասներ. param, expected, limit, remaining, window, scope, retry_after (retryAfter, վայրկյաններ — մարմնից, առանց դրա Retry-After-ից), reset_at_ms (resetAtMs), history_days, earliest_allowed_ms, allow։ Դաշտերը, որոնք սերվերը չի ուղարկել, None են (undefined)։
429-ի և 503-ի դեպքում և ցանցի ընդհատման ժամանակ հաճախորդը կրկնում է հարցումը ինքը — ըստ Retry-After-ի, մինչև 3 անգամ։ Եթե սերվերը խնդրում է սպասել 30 վ-ից ավելի, սխալը տրվում է անմիջապես։ daily_quota_exceeded-ը երբեք չի կրկնվում, hourly_limit-ը և daily_limit-ը՝ միայն եթե սերվերը նշել է սպասման սահմանից ոչ ավելի դադար։
from lootx import Client, RetryPolicy, errors
lx = Client("lx_live_...", retry=RetryPolicy(max_retries=5, max_wait=60)) # RetryPolicy(max_retries=0) — առանց կրկնությունների
try:
lx.candles("binance:perp:BTCUSDT", from_=0)
except errors.HistoryOutOfPlanError as e: # 403 history_out_of_plan
print(e.earliest_allowed_ms, e.request_id)
except errors.RateLimitError as e: # 429: կրկնությունները սպառվել են կամ սպասել max_wait-ից ավելի
print(e.code, e.window, e.scope, e.retry_after)const lx = new Client({ apiKey: "lx_live_...", retry: { maxRetries: 5, maxWaitMs: 60_000 } }); // { maxRetries: 0 } — առանց կրկնություններիՍահմանաչափերը կոդից
usage()-ը — GET /v1/usage. սակագին, սահմանաչափեր, օրական ծախսը և պատուհանները հիմա։ Վերջին պատասխանի սահմանաչափերի վերնագրերը — rate_limit (rateLimit). X-RateLimit-* և վերլուծված RateLimit-Policy և RateLimit։
u = lx.usage()
print(u.plan and u.plan.slug, u.limits.rpm, u.today.requests, u.today.bytes)
m = u.now.window("minute") # limit, burst, used, remaining, reset_at_ms
print(m and m.remaining, lx.rate_limit)const u = await lx.usage();
const minute = u.now.windows.find((w) => w.scope === "account" && w.window === "minute");
console.log(u.plan?.slug, minute?.remaining, lx.rateLimit);Հոսքի error կադրը գալիս է որպես սովորական հաղորդագրություն. errors.error_from_frame(msg)-ը (errorFromFrame(frame)) այն կվերածի բացառության նույն մանրամասներով։ Փակումը 1008/1013՝ պատճառում կոդով, պահվում է հոսքի last_close_error-ում (lastCloseError) — feed()-ի դեպքում դա f.stream.last_close_error-ն է (f.stream.lastCloseError) — իր դասի բացառությամբ, օրինակ՝ SlowConsumerError slow_consumer-ի դեպքում. մուտքի մերժումը՝ revoked_key և նմանները, բացառություն է առանց վերամիացման, մնացածը՝ վերամիացում դադարով։
https://docs.lootx.trade/hy/market-api/sdk
4Գործիքներ և վիճակ
Ինչ գործիքներ կան և տվյալների որ տեսակներում՝ ռեեստր /v1/instruments, աղբյուրները առողջ են արդյոք՝ /v1/status։
Սակագնի խումբը՝ instruments։ Սկսեք ռեեստրից. այն ցույց է տալիս, թե ինչպես է կոչվում գործիքը և որ ուղիներով կան տվյալներ դրա վերաբերյալ։
Գործիքների ռեեստր
/v1/instrumentsԲոլոր աղբյուրների բոլոր գործիքները մեկ կանոնական անվամբ։ sources սյունակը ցույց է տալիս, թե որտեղ կա տվյալ գործիքը՝ candles, footprint, densities, screener։
| Պարամետր | Ինչ է |
|---|---|
venue |
բորսա՝ binance, okx, … |
market |
spot կամ perp։ Ամսաթվով ֆյուչերսներ և օպցիոններ դեռ չկան |
source |
միայն այն գործիքները, որոնց համար կան տվյալներ այս տեսակով՝ candles, footprint, densities, screener |
q |
սիմվոլի ենթատող՝ առանց ռեգիստրի հաշվի առնելու՝ q=btc |
limit |
տողեր մեկ էջում, 1–10 000, լռելյայն՝ 1000 |
cursor |
կուրսոր next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/instruments?venue=binance&market=perp&q=BTC" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"columns": ["instrument", "venue", "market", "symbol", "sources"],
"rows": [
["binance:perp:BTCUSDT", "binance", "perp", "BTCUSDT", ["candles", "footprint", "densities", "screener"]],
["binance:perp:BTCUSDC", "binance", "perp", "BTCUSDC", ["candles", "footprint", "densities"]]
],
"next_cursor": null,
"updated_at": 1793750400000
}updated_at-ը ցույց է տալիս, թե երբ է gateway-ը վերջին անգամ ստացել ցուցակը գոնե մեկ աղբյուրից, 0՝ դեռ ոչ մի անգամ։ Ռեեստրը թարմացվում է 5 րոպեն մեկ և ցույց է տալիս այն, ինչ աղբյուրները հավաքում են հենց հիմա, այլ ոչ բորսաների բոլոր լիստինգները։ Նոր զույգը կհայտնվի, երբ այն սկսի հավաքել աղբյուրը. աղբյուրների մի մասի մոտ դա տեղի է ունենում օրական շրջանառության շեմից հետո։
Աղբյուրների վիճակ
/v1/statusԱրդյոք gateway-ի հետևում տվյալների աղբյուրները պատասխանում են և ինչ ուշացումով։ Հարմար է ձեր մոնիտորինգի համար. եթե ok: false, ապա այդ աղբյուրի ուղիներով 502/504 սխալները սպասելի են։
{
"ok": true,
"ts": 1793750400000,
"upstreams": [
{ "name": "data", "ok": true, "latency_ms": 12, "http_status": 200 },
{ "name": "clusters", "ok": true, "latency_ms": 18, "http_status": 200 }
]
}/v1/status-ը աղյուսակ չունի, հետևաբար CSV էլ չկա՝ միայն JSON և protobuf։ Ուղին չի մտնում սակագնի որևէ խմբի մեջ և ծախսում է միայն ընդհանուր սահմանաչափերը։
https://docs.lootx.trade/hy/market-api/instruments
5Մոմեր և շարքեր
Մոմեր ցանկացած քայլով՝ մեկ վայրկյանից մինչև օր, և գործարքների հոսքի շարքեր՝ CVD, դելտա, ծավալ, գործարքների քանակ։
Մոմեր
/v1/candlesOHLCV մոմեր՝ առանձին գնման ծավալով։ Քայլը՝ ցանկացած թիվ s, m, h, d վերջածանցով, մինչև մեկ օր՝ 1s, 15s, 1m, 5m, 1h, 4h, 1d։
| Պարամետր | Ինչ է |
|---|---|
instrument |
պարտադիր, venue:market:SYMBOL |
tf |
մոմի քայլ, լռելյայն 1m |
from |
պատուհանի սկիզբ, մվ, ներառյալ։ Լռելյայն to − limit × tf |
to |
պատուհանի վերջ, մվ, չներառյալ։ Լռելյայն՝ հիմա |
limit |
մոմեր մեկ էջում, 1–10 000, լռելյայն 1000 |
fill |
լրացնել դատարկ ինտերվալները հարթ մոմերով, լռելյայն true |
cursor |
կուրսոր next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/candles?instrument=binance:perp:BTCUSDT&tf=5m&from=1793750400000&limit=2" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"tf": "5m",
"columns": ["ts", "open", "high", "low", "close", "volume", "quote_volume",
"buy_volume", "buy_quote_volume", "trades", "buy_trades"],
"rows": [
[1793750400000, 104250.5, 104301.2, 104190.0, 104288.7, 182.43, 19021884.31, 97.12, 10127740.05, 8410, 4522],
[1793750700000, 104288.7, 104322.0, 104260.4, 104270.1, 133.06, 13878523.60, 61.88, 6454361.73, 6128, 2930]
],
"next_cursor": "YzE6MTc5Mzc1MTAwMDAwMA",
"coverage": { "oldest": 1792741800000, "newest": 1793754000000 }
}| Սյունակ | Ինչ է |
|---|---|
ts |
մոմի սկիզբ, մվ UTC |
open, high, low, close |
գներ quote-արժույթով |
volume, buy_volume |
ամբողջ ծավալը և ագրեսորի գնման ծավալը, մետաղադրամներով (candles ալիքում հոսքի volume դաշտն այլ է՝ quote-արժույթով) |
quote_volume, buy_quote_volume |
նույնը quote-արժույթով՝ գումար, առանց գնի քայլի կլորացման |
trades, buy_trades |
գործարքների քանակ, ընդհանուր և գնումներ |
Վաճառքները՝ volume − buy_volume, եթե կողմը հայտնի է մոմի բոլոր գործարքների համար։ Որոշ բորսաներում գործարքի կողմը միշտ չէ, որ ընթերցվում է․ նման գործարքները մտնում են volume-ի մեջ, բայց ոչ buy_volume-ի, և հանումը դրանք կհաշվի վաճառք։ Առանձին սյունակ դրանց համար պատասխանում չկա։
coverage — ինչ ժամանակահատված ընդհանրապես կա պահեստում ըստ գործիքի․ եթե հարցնեք oldest-ից շուտ, դատարկ էջ կստանաք, ոչ թե սխալ։
Սիմվոլը, որը չկա աղբյուրներում, կարող է ստանալ 400 unsupported_instrument param: "symbol"-ով, կամ էլ դատարկ 200․ պայմանները։ Նույնը /v1/series-ում։
Վայրկյանային մոմեր
Մեկ րոպեից կարճ քայլը՝ սակագնի առանձին խումբ candles_1s։ Սակագինը կարող է փակել այն (403 route_not_in_plan), սահմանափակել իր հարցումների լիմիտով կամ պատմության իր խորությամբ․ այս ամենը գործում է ընդհանուր սահմանափակումների հետ միասին։ Րոպեական և ավելի խոշոր մոմերը՝ candles խումբ։
Գործարքների հոսքի շարքեր
/v1/seriesՄեկ շարք t, value ըստ քայլերի․ կուտակված դելտա, քայլի դելտա, ծավալ կամ գործարքների քանակ։ Սակագնի խումբը՝ series։
| Պարամետր | Ինչ է |
|---|---|
instrument |
պարտադիր |
metric |
պարտադիր․ cvd — կուտակված դելտա from պատուհանի սկզբից; delta — ագրեսորի գնումներ հանած վաճառքներ մեկ քայլում; volume; trades_n — գործարքների քանակ |
unit |
quote (լռելյայն, quote-արժույթով) կամ base (մետաղադրամներ)։ trades_n-ի դեպքում մի փոխանցեք |
tf |
քայլ, լռելյայն 1m։ Մեկ րոպեից կարճ՝ սակագնի վայրկյանային պատմություն |
from, to, limit, cursor |
ինչպես մոմերի դեպքում; limit մինչև 10 000, լռելյայն 1000 |
curl -s "https://market-api.lootx.trade/v1/series?instrument=binance:perp:BTCUSDT&metric=cvd&tf=1m&from=1793750400000&limit=3" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"metric": "cvd",
"unit": "quote",
"tf": "1m",
"columns": ["t", "value"],
"rows": [[1793750400000, 214877.31], [1793750460000, -51260.04], [1793750520000, -1830.66]],
"next_cursor": "eyJ0IjoxNzkzNzUwNTgwMDAwfQ"
}https://docs.lootx.trade/hy/market-api/candles
6Ֆուտպրինտ և դելտա
footprint cluster-ներ — յուրաքանչյուր գնի մակարդակի վրա պատուհանների համաձայն՝ գնումների և վաճառքների ծավալը; ագրեսորի delta պատուհաններով՝ պատուհան ներսի էքստրեմումներով; Hyperliquid-ում դիրքերի բացում-փակում ըստ գնի մակարդակների։
Ֆուտպրինտ
/v1/footprintfootprint cluster-ներ՝ յուրաքանչյուր պատուհանի ժամանակահատվածի համար — ծավալներ գնի մակարդակներով, առանձին՝ բիդով և ասքով. Հարկային խումբ — footprint.
| Պարամետր | Ինչը |
|---|---|
instrument |
պարտադիր |
tf |
կլաստերի պատուհան՝ 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. Լռելյայն 1m |
from |
սկիզբ, մս. Լռելյայն — 60 պատուհան առաջ to-ից |
to |
վերջ, մս, ներառյալ չէ |
cursor |
cursор՝ next_cursor-ից |
Պատասխանում երկու աղյուսակ են՝ levels — գնի մակարդակները, windows — պատուհանները:
{
"instrument": "binance:perp:BTCUSDT",
"tf": "1m",
"windows": {
"columns": ["ts", "open", "high", "low", "close", "closed"],
"rows": [[1793750400000, 104250.5, 104262.0, 104241.1, 104255.3, true]]
},
"levels": {
"columns": ["ts", "price", "bid_qty", "ask_qty", "trades", "trades_buy", "trades_sell"],
"rows": [
[1793750400000, 104250.5, 1.204, 0.832, 41, 23, 18],
[1793750400000, 104250.6, 0.317, 2.115, 37, 12, 25]
]
},
"next_cursor": null
}ts՝ մակարդակի վրա — այն պատուհանի սկիզբը, որի հետ այն կապված է;bid_qty— ծավալը, որտեղ ագրեսորը գնել է,ask_qty— որտեղ ագրեսորը վաճառել է; մոնետաներով. Սյունակների անունները համապատասխանում են ագրեսորի կողմին, ոչ թե order book-ի կողմին, որի մեջ ընկել է գործարքը. Ստուգեք դա՝ եթե տեղափոխում եք հաշվարկները մյուս պլատֆորմից;trades_buy,trades_sell— քանի առք/վաճառք էtrades-ից կատարվել ագրեսորի կողմից, նույն կողմերը, ինչbid_qtyևask_qty. Եթե արժեքները հայտնի են,trades_buy + trades_sell = trades. Եթե երկուսն էլnullեն, ապա բաժանման տվյալներ չկան՝ կամ դա պատմություն է մինչև կողմերի գրանցումը, կամ այն պատուհանն է (5m…1d), որի մեջ ընկած է այդ րոպեն. Սա չի նշանակում «ոչ մի գնում չի եղել». Սյունակները՝ ավարտին են, առաջին հինգը մնացել են տեղում;closed: true— պատուհանը փակված է և այլևս չի փոխվի. վերջին պատուհանը, «Հիմա»-ի համար, կարող է գալclosed: falseև հետո աճել։
Պատուհաններ մեկ էջում — մինչև 2000. CSV-ը ամբարգում է միայն մեկ աղյուսակ, ապա ֆուտպրինտի համար ընտրեք՝ ?format=csv&table=levels կամ table=windows.
Դելտա
/v1/deltaԱգրեսորի delta պատուհաններով՝ գնողներ, վաճառողներ, նրանց տարբերությունը և պատուհան ներսի վազող delta-ի էքստրեմումները — մոնետաներով և quote-արժույթով. Հարկային խումբ — delta.
| Պարամետր | Ինչը |
|---|---|
instrument |
պարտադիր |
tf |
պատուհան՝ 1s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. Լռելյայն 1m |
from |
սկիզբ, մս; հավասարեցվում է պատուհանի սկիզբին. Լռելյայն — limit պատուհան անցյալից to-ից |
to |
վերջ, մս, ներառյալ չէ |
limit |
պատուհաններ մեկ էջի համար, 1–10 000, լռելյայն 1000 |
cursor |
cursор՝ next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/delta?instrument=binance:perp:BTCUSDT&tf=5m&limit=1" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"tf": "5m",
"columns": ["t", "buy", "sell", "delta", "delta_min", "delta_max", "trades",
"buy_quote", "sell_quote", "delta_quote", "delta_quote_min", "delta_quote_max",
"close", "closed"],
"rows": [[1793750400000, 97.12, 85.31, 11.81, -4.06, 15.27, 8410,
10127740.0512, 8894144.2587, 1233595.7925, -423187.164, 1592311.0033,
104288.7, true]],
"next_cursor": null
}| Սյունակ | Ինչը |
|---|---|
t |
պատուհանի սկիզբ, մս |
buy, sell, delta |
ագրեսորի գնման և վաճառքի ծավալները և դրանց տարբերությունը՝ մոնետաներով |
delta_min, delta_max |
վազող delta-ի նվազագույն և առավելագույն արժեքները պատուհան ներսում, մոնետաներով |
buy_quote … delta_quote_max |
նույնը՝ գումարով (quote-արժույթում); ճշգրտությունը՝ 0.0001, առանց օղակավորման դեպի price step |
close |
պատուհանի փակման գին |
closed |
պատուհանը փակված է |
Պատուհաններ առանց միակ գործարքի չեն գալիս՝ ժամանակահատվածում բացթողումը շուկայի լռություն է, ոչ տվյալների կորուստ։
Hyperliquid-ում դիրքերի բացում և փակել
/v1/hyperliquid/footprintՖուտպրինտ NL/NS՝ յուրաքանչյուր գնի մակարդակում Hyperliquid-ում՝ թե որքան են ավելացել կամ նվազել long-ները և short-ները, առանձին՝ taker-ների և maker-ների համար. Սրան հաշվարկվում է Hyperliquid nodes-ի լցոնումներից (լցոնում)՝ ըստ մասնակցի դիրքի մինչ ու հետո յուրաքանչյուր լցոնման. Հարկային խումբ — footprint.
| Պարամետր | Ինչը |
|---|---|
instrument |
պարտադիր, պերպ Hyperliquid-ի համար: hyperliquid:perp:BTC, HIP-3 շուկան — hyperliquid:perp:AAPLUSDC.XYZ կամ կարճ hyperliquid:perp:AAPL.XYZ. Ավելի այլ բորսա կամ spot — 400 unsupported_instrument |
tf |
պատուհան՝ 1m, 5m, 15m, 30m, 1h, 4h, 1d. Լռելյայն 1m. Վայրկյաններ չկան — այլ քայլի համար վերադարձնի 400 bad_request՝ param: "tf" |
from |
սկիզբ, մս; հավասարեցվում է պատուհանի սկիզբին. Լռելյայն — 60 պատուհան առաջ to-ից |
to |
վերջ, մս, ներառյալ չէ |
cursor |
cursор՝ next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/hyperliquid/footprint?instrument=hyperliquid:perp:BTC&tf=1m&from=1794500100000&to=1794500220000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "hyperliquid:perp:BTC",
"tf": "1m",
"levels": {
"columns": ["ts", "price", "dl_taker", "ds_taker", "dl_maker", "ds_maker", "n_fills"],
"rows": [
[1794500100000, 68960.5, 0.001, 0.0, 0.0, 0.001, 4],
[1794500100000, 68961.0, -0.0005, 0.0003, 0.0008, 0.0, 2],
[1794500160000, 68960.0, 0.0, -0.0002, -0.0001, 0.0001, 2]
],
"next_cursor": null
},
"windows": {
"columns": ["ts", "closed"],
"rows": [[1794500100000, true], [1794500160000, false]],
"next_cursor": null
},
"asof_ms": 1794500205000,
"next_cursor": null
}| Սյունակ | Ինչը |
|---|---|
ts |
պատուհանի սկիզբ, մս |
price |
գնի մակարդակ |
dl_taker, ds_taker |
taker-ների long-ների և short-ների փոփոխությունը այդ մակարդակում, մոնետաներով. Դրական — բացեցին, բացասական — փակեցին |
dl_maker, ds_maker |
նույնը maker-ների համար |
n_fills |
քանի լցոնում է եղել այդ մակարդակում; լցոնումը (fill) — գործարքի կեսը, համապատասխան match-ի մեկ կողմը |
Երեք տեսակի NL/NS հաշվարկվում են չորս սյունակից՝ բոլոր մասնակիցների դեպքում dl_taker + dl_maker (և նույնը՝ ds_taker + ds_maker) — դա տվյալ մակարդակում open interest-ի փոփոխությունն է; taker-ների համար՝ dl_taker և ds_taker; maker-ների համար՝ dl_maker և ds_maker. Պատասխանում գումարներ փողով չկան՝ գինն ու քանակը նշված են ինստրումենտով.
windows— պատուհաններ՝closed-ով:true— պատուհանը փակված է և այլևս չի փոխվի; «հիմա»-ի համար կարող է գալfalse.asof_ms— այն պահը, մինչև երբ աղբյուրը գրանցել է ամբողջական րոպեները.instrumentպատասխանում — մոնետայի կանոնական անունը, ոչ հարցման ձևը: օրինակ՝hyperliquid:perp:aapl.xyzփոխարեն կգաhyperliquid:perp:AAPLUSDC.XYZ, իսկhyperliquid:perp:BTCUSDCփոխարեն՝hyperliquid:perp:BTC.- gateway-ի անունը ստուգվում է միայն ձևով — լատինատառ տառեր և թվեր, մինչև 32 նիշ, HIP-3 շուկաներում կարող է ունենալ դոմենից հետո կետ. Այն, թե կա՞ նման մոնետա Hyperliquid-ում, չի ստուգվում.
- Պատուհաններ մեկ էջում — մինչև 2000, այնուհետև՝
next_cursor. Եթե մեկ պատուհանը ավելի մեծ է, քան տվյալ աղբյուրի տողերի մաքսիմումը — վերադարձնվում է413 too_large, վերցրեք փոքրtf. - Պլատֆորմների գումարը չի տրամադրվում:
instruments=-ով երկու և ավել ինստրումենտ ուղարկելը՝ վերադարձնում է400 bad_request.
https://docs.lootx.trade/hy/market-api/order-flow
7Գործարքներ
Գործարքների ժապավեններ՝ սկսած չափի շեմից. վերջին օրերի թեժ շերտը և $5000-ից սկսած գործարքների անժամկետ արխիվը 11.09.2026-ից:
/v1/tradesԳործարքներ մեկ առ մեկ՝ գնով, ծավալով, գումարով և ագրեսորի կողմով։ Սակագնի խումբը՝ trades։
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր |
from |
սկիզբ, մվ, ներառյալ։ Լռելյայն՝ մեկ ժամ առաջ to-ից |
to |
վերջ, մվ, չներառյալ |
limit |
գործարք մեկ էջում, 1–50 000, լռելյայն 10 000 |
min_usd |
գործարքի շեմը դոլարով (գին × ծավալ), ներառյալ. min_usd=5000՝ միայն $5000-ից |
source |
պահպանման շերտ. auto (լռելյայն. թարմ օրերը՝ թեժ, ավելի հինը՝ արխիվ), hot, archive |
cursor |
կուրսոր next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/trades?instrument=binance:perp:BTCUSDT&min_usd=100000&limit=2" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"source": "hot",
"source_min_usd": 0,
"min_usd": 100000,
"columns": ["t", "price", "qty", "quote_qty", "side", "aggregated", "fills", "trade_id", "seq"],
"rows": [
[1793750412318, 104251.2, 1.25, 130314.0, "buy", true, 4, 6213554801, 18822107],
[1793750431906, 104247.9, 2.004, 208912.7916, "sell", false, 1, 6213555367, 18822345]
],
"next_cursor": "eyJ0IjoxNzkzNzUwNDMxOTA3fQ"
}| Սյունակ | Ինչ |
|---|---|
t |
գործարքի ժամանակը, մվ |
price |
գինը quote-արժույթով |
qty |
ծավալը մոնետաներով |
quote_qty |
գործարքի գումարը quote-արժույթով, 0,0001 ճշտությամբ, չի կլորացվում գնի քայլին |
side |
ագրեսորի կողմը. buy՝ գնել է, sell՝ վաճառել |
aggregated, fills |
true՝ մեկ հայտի մի քանի կատարում միացվել են մեկ գործարքի մեջ. fills՝ դրանց քանակը |
trade_id, seq |
trade_id՝ բորսայում գործարքի համարը (0, եթե բորսան այն չի տալիս). seq՝ գործարքի համարը մեկ միլիվայրկյանի ընթացքում, լրացվում է միայն trade_id = 0-ի դեպքում, հակառակ դեպքում 0 |
Թերթումը՝ ըստ ժամանակի, առանց կրկնությունների. եթե էջը կտրվել է միլիվայրկյանի մեջտեղում, այդ միլիվայրկյանի գործարքներն ամբողջությամբ անցնում են հաջորդ էջին։
https://docs.lootx.trade/hy/market-api/trades
8Тепловая карта стакана
Объём лимитных заявок в каждой ячейке цены в каждой колонке времени — таблицей или компактным бинарём HMP1/HMP2; полосы книги — сколько долларов стоит в стакане до ±0,1…±10 % от середины.
/v1/heatmapТепловая карта стакана: объём бидов и асков в ячейках цены по колонкам времени. Группа тарифа — heatmap; тариф часто задаёт ей свои, более строгие лимиты.
| Параметр | Что |
|---|---|
instrument |
обязательный |
from |
начало, мс. По умолчанию — час назад от to |
to |
конец, мс, не включительно. По умолчанию — сейчас |
tf |
шаг колонки, кратный секунде: 1s, 5s, 1m, … По умолчанию — самый мелкий, при котором окно влезает в 4096 колонок. Если окно начинается раньше, чем сутки назад, отдаётся минутная свёртка: шаг округлится вверх до минуты |
price_step |
высота ячейки в единицах цены: 10 — ячейки по $10 у BTCUSDT. Округляется вверх до сетки хранения; итоговый шаг — в price_step ответа. Без данных книги в минуте перед to возможен 400 bad_request: условие |
agg |
avg (по умолчанию) — средний объём за колонку, max — максимум |
price_from, price_to |
ценовое окно, только парой. Без него — ±20 % от середины книги |
format |
json, protobuf, csv — таблица; hmp1, hmp2 — бинарь |
qbits, layout |
только для format=hmp2 |
cursor |
курсор из next_cursor, если источник обрезал ответ по объёму |
curl -s "https://market-api.lootx.trade/v1/heatmap?instrument=binance:perp:BTCUSDT&tf=1m&price_step=10&from=1793750400000&to=1793754000000" \
-H "Authorization: Bearer $LOOTX_API_KEY"Таблица содержит только ненулевые ячейки — строку на каждую пару «колонка времени × уровень цены», где объём был:
{
"instrument": "binance:perp:BTCUSDT",
"from": 1793750400000,
"to": 1793754000000,
"time_step_ms": 60000,
"price_step": 10,
"agg": "avg",
"price_from": null,
"price_to": null,
"frames": 60,
"columns": ["t", "side", "price", "qty"],
"rows": [
[1793750400000, "bid", 104240, 18.402],
[1793750400000, "ask", 104260, 9.117]
],
"next_cursor": null
}price— нижняя граница ячейки: ячейка — это[price, price + price_step);qty— объём в монетах, средний (agg=avg) или максимальный за колонку;frames— сколько колонок времени в ответе;fromвыровнен наружу по шагу.
Пределы
- До 4096 колонок и 500 000 ячеек в таблице. Больше —
413 too_large: сузьте окно, укрупнитеtfилиprice_stepлибо возьмите бинарь. - История книг у Binance длиннее; у остальных бирж стакан пишется с 30.10.2026 — раньше этой даты по ним ответ пустой, а с
price_stepможет прийти400, условие ниже. price_stepпереводится в сетку хранения по данным самой книги: шлюз запрашивает минуту передto, границы выравниваются наружу по минутной сетке. Данных в этой минуте нет —400 bad_request, запрашивайте безprice_step. Решает окно, а не статус инструмента: торгуемый инструмент сtoраньше начала истории книг получит400, снятый с торгов с данными в этой минуте —200. Удачный перевод шлюз помнит до часа, независимо от ключа, и теряет его при перезапуске: пока он помнит, минута передtoне проверяется, и запрос без данных получит200с пустым ответом.- Бинарь
hmp1/hmp2во много раз короче таблицы, идёт потоком и кэшируется — для отрисовки берите его. Разбор — Формат HMP1 и HMP2. - Закрытые диапазоны бинаря отдаются с
ETagи долгимCache-Control: повторный запрос сIf-None-Matchполучает304без тела и не расходует суточный объём.
Полосы книги
/v1/book/bandsСколько долларов стоит в стакане в пределах ±0,1 … ±10 % от середины книги, а с bands=deep — ещё ±3, ±8, ±15 % и вся сторона — по окнам времени. Группа тарифа та же, что у тепловой карты, — heatmap.
| Параметр | Что |
|---|---|
instrument |
обязательный |
tf |
окно: 1s, 5s, 10s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d. По умолчанию 1m. Другие — 400 bad_request с param: "tf" |
from |
начало, мс; выравнивается вниз по окну. По умолчанию — 60 окон назад от to |
to |
конец, мс, не включительно; выравнивается вверх по окну |
bands |
набор полос: без параметра — семь полос до ±10 %, deep — одиннадцать, до всей стороны (глубокие полосы). Другие значения — 400 bad_request с param: "bands" |
Полоса — уровень книги, а не поток: значение окна — последний срез в окне, а не сумма за окно. Поэтому окна только из списка: 45s из минут не собрать.
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&from=1794500160000&to=1794500220000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"tf": "1m",
"columns": ["ts", "sample_ms", "best_bid", "best_ask", "mid",
"bid_bp10_e8", "bid_bp25_e8", "bid_bp50_e8", "bid_bp100_e8", "bid_bp200_e8", "bid_bp500_e8", "bid_bp1000_e8",
"ask_bp10_e8", "ask_bp25_e8", "ask_bp50_e8", "ask_bp100_e8", "ask_bp200_e8", "ask_bp500_e8", "ask_bp1000_e8",
"reach_bid_bp", "reach_ask_bp", "complete_bid", "complete_ask", "closed"],
"rows": [
[1794500160000, 1794500219950, 68961.0, 68961.1, 68961.05,
"51234500000000", "98765400000000", "150000000000000", "310000000000000", "640000000000000", "1500000000000000", "2900000000000000",
"48765400000000", "91234500000000", "140000000000000", "300000000000000", "620000000000000", "1450000000000000", "2800000000000000",
1000, 213, 7, 5, true]
],
"next_cursor": null,
"bands_bp": [10, 25, 50, 100, 200, 500, 1000],
"units_revision": 1,
"source": "book_bands_1m",
"asof_ms": 1794500325000
}| Колонка | Что |
|---|---|
ts |
начало окна, мс |
sample_ms |
момент среза книги, которым представлено окно, мс |
best_bid, best_ask, mid |
лучшие цены и середина книги в этом срезе |
bid_bp…_e8 |
биды от середины книги вниз до −0,1 %, −0,25 %, −0,5 %, −1 %, −2 %, −5 % и −10 %: число в имени — граница в базисных пунктах |
ask_bp…_e8 |
аски от середины вверх до тех же границ |
reach_bid_bp, reach_ask_bp |
самая широкая граница, в базисных пунктах, все цены до которой книга знала |
complete_bid, complete_ask |
сколько первых полос полны: полоса номер k по порядку bands_bp, с нуля, полна, если k < complete |
closed |
окно закрыто и больше не изменится |
Деньги полос — в e8 USD строкой: "51234500000000" — это 512 345 $, делите целое на 10⁸. Строкой — потому что у книг крупных монет число больше 2⁵³ и в double потеряло бы знаки: читайте его как целое 64 бита или десятичное. Шаг цены инструмента к этим суммам не относится. Полосы нарастающие: bp25 включает bp10. В примере у асков полны первые пять полос, до ±2 %, а ask_bp500_e8 и ask_bp1000_e8 неполны: книга знала аски только до 2,13 % от середины.
- Окно без среза книги не приходит строкой: пропуск — это дыра в данных, а не нули.
- Секундные окна (
1s…30s) есть не у всех инструментов и только за последние 7 суток, у остальных ответ пустой. Минутные и крупнее — у книг с долларовой котировкой, без срока. Таблица источника — в полеsource:book_bands_1sилиbook_bands_1m. asof_ms— до какого момента склад источника полон: окна раньше него не изменятся.units_revision— ревизия единиц источника, сейчас1(e8 USD).- Окон в запросе — до 20 000, больше —
413 too_large: сузьте окно или возьмитеtfкрупнее. Курсора нет,next_cursorвсегдаnull. - Суммы площадок нет: полоса каждой биржи отсчитана от её середины книги и снята в свой момент.
instruments=с двумя и больше инструментами —400 bad_request: запрашивайте каждую биржу своимinstrumentи складывайте e8-строки сами. - Символ с реестром шлюз не сверяет.
Глубокие полосы
bands=deep — одиннадцать полос вместо семи: bands_bp — [10, 25, 50, 100, 200, 300, 500, 800, 1000, 1500, 10000], в ответе 32 колонки. К прежним границам добавлены ±3 %, ±8 %, ±15 % и 10000 — вся сторона: биды до нуля, аски до двух mid. Колонки идут в том же порядке, что bands_bp: bid_bp10_e8 … bid_bp10000_e8, затем ask_bp10_e8 … ask_bp10000_e8; голова и хвост строки — как без параметра.
curl -s "https://market-api.lootx.trade/v1/book/bands?instrument=binance:perp:BTCUSDT&tf=1m&bands=deep&from=1794500160000&to=1794500220000" \
-H "Authorization: Bearer $LOOTX_API_KEY"nullв полосе — «неизвестно», а не 0. Так приходят глубокие полосы у строк, записанных до того, как их начали считать, и вся сторона, если книга её не знала целиком.complete_*— до 11 и считается до первой неизвестной полосы: у старых строк — не больше 5.- Полосу берите по
bands_bp, а не по номеру колонки: номера в двух наборах разные —bid_bp500_e8шестая в обычном ответе и седьмая в глубоком. - Вес и группа тарифа — те же, что без параметра.
https://docs.lootx.trade/hy/market-api/heatmap
9open interest և funding rate
Մինուտային բարեր open interest‑ի՝ դոլլարով, մոնետերով կամ բորսայի բնիկ միավորով; funding rate՝ ըստ րոպեների և դրանց հաշվարկները; long/short ratio՝ 5‑րոպեանոց բաքեթներով; mark և index՝ վայրկյաններով և րոպեներով.
Միայն պերպ կոնտրակտներ: market = perp. Բորսաներ: binance, bybit, okx, bitget, gate, mexc, bingx, kucoin, hyperliquid, aster, kraken, coinbase. long/short և mark և index բաժինների համար բորսաների հավաքածունները նշված են համապատասխան բաժիններում.
open interest
/v1/oiopen interest‑ի րոպեական բարեր՝ բացում, максимум, минимум և փակումը. Տարֆի խումբ — oi.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, միայն պերպեր |
from |
սկիզբ, մս. Լռելյայն — մեկ օր առաջ to-ից |
to |
վերջ, մս., չներառյալ |
unit |
usd (Լռելյայն), coins կամ native — ինչպես բորսան: մոնետա, կոնտրակտ կամ դոլլար |
cursor |
կուրսոր՝ վերցված next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/oi?instrument=bybit:perp:ETHUSDT&unit=usd&from=1793750400000&to=1793750520000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "bybit:perp:ETHUSDT",
"tf": "1m",
"columns": ["ts", "open", "high", "low", "close"],
"rows": [
[1793750400000, 1843204551.12, 1843990120.4, 1842871003.57, 1843511876.03],
[1793750460000, 1843511876.03, 1844102233.9, 1843300418.65, 1843877021.18]
],
"next_cursor": null
}ts — րոպեի սկիզբը. Էջը՝ մինչև մեկ շաբաթ րոպեների տվյալներ; երկար պատուհանների համար օգտագործեք կուրսորը.
funding rate
/v1/fundingFunding rate‑ը՝ այն, ինչ բորսան ցույց էր տալիս յուրաքանչյուր րոպե, և, երբ բորսան ասում է, հաջորդ հաշվարկի ժամանակը (next_funding_ts տողը; Hyperliquid, MEXC, Kraken և Coinbase-ում next_funding_ts — null). Տարֆի խումբ — funding.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր |
from, to, cursor |
պատուհան և կուրսոր |
{
"instrument": "binance:perp:BTCUSDT",
"tf": "1m",
"columns": ["ts", "rate", "next_funding_ts", "interval_hours"],
"rows": [[1793750400000, 0.0001, 1793779200000, 8]],
"next_cursor": null
}rate— բաժինը վճարման պարբերության համար:0.0001նշանակում է 0.01% միջակայքում 8 ժամի համար;interval_hours— վճարման պարբերությունը ժամերով, ինչպես այն հաղորդում է աղբյուրը.
funding rate‑ի հաշվարկներ
/v1/funding/eventsՀաշվարկների ինքնին ժամանակները՝ որ ставка կիրառվեց և այն ժամանակվա mark գինը, եթե կա. Տարֆի խումբ — funding.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, միայն պերպեր |
from |
սկիզբ, մս. Լռելյայն — 30 օր առաջ to-ից |
to |
վերջ, մս., չներառյալ |
cursor |
կուրսոր՝ վերցված next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/funding/events?instrument=binance:perp:BTCUSDT" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"columns": ["t", "rate", "mark_price"],
"rows": [
[1793721600000, 0.00009249, null],
[1793721600006, 0.00009208, 104012.4],
[1793750400000, 0.000072, 104250.5]
],
"next_cursor": null
}mark_price‑ը լրացվում է միայն Binance‑ում, մյուս բորսաներում այն null է; Binance‑ում կրկնվող տողում նույնպես null կարող է լինել (տես վերև). Ձեր վճարները հաշվարկելու համար բազմապատկեք ставка‑ը դիրքի նոմինալով տվյալ պահին։ Մեզ մոտ և ձեր հաշվարկներում գումարները չեն հսկվում գնի քայլով՝ չ.round անեք։
Long/Short ratio
/v1/ls-ratioLong/short հարաբերությունը և taker‑ների ծավալը 5‑րոպեանոց բաքեթներով՝ ինչպես դրանք հրապարակվում են բորսայով. Տարֆի խումբ — ls_ratio.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, միայն պերպեր. Փնթի դիտորդներ կան՝ binance (global_account, top_account, top_position, taker_volume), bybit (global_account) և okx (նույն չորսը և global_account_ccy); մյուս open interest‑ի բորսաներում պատասխանն դատարկ է |
kind |
շարքի տեսակը: global_account, top_account, top_position, taker_volume, global_account_ccy. Լռելյայն — բոլորը. Այլ արժեքը վերադարձնում է 400 bad_request՝ param: "kind" |
from |
սկիզբ, մս., ըստ ts. Լռելյայն — մեկ օր առաջ to-ից |
to |
վերջ, մս., չներառյալ |
cursor |
կուրսոր՝ վերցված next_cursor-ից |
Պлощадокի հարաբերությունները չի կարելի գումարել: instruments=‑ով երկու կամ ավելի ինստրումենտ ուղարկելը վերադարձնում է 400 bad_request — հարցրեք յուրաքանչյուր բորսան իր instrument-ով։
curl -s "https://market-api.lootx.trade/v1/ls-ratio?instrument=binance:perp:BTCUSDT&from=1793278200000&to=1793278500000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"tf": "5m",
"columns": ["ts", "as_of", "kind", "long_ratio", "short_ratio", "long_short_ratio", "buy_vol", "sell_vol", "unit"],
"rows": [
[1793278200000, 1793278200000, "global_account", 0.6849, 0.3151, 2.1736, null, null, null],
[1793278200000, 1793278500000, "taker_volume", null, null, 1.1138, "82.8880", "74.4160", "base"],
[1793278200000, 1793278200000, "top_account", 0.6982, 0.3018, 2.3135, null, null, null],
[1793278200000, 1793278200000, "top_position", 0.6774, 0.3226, 2.0995, null, null, null]
],
"next_cursor": null
}| Ստ conv | Ինչ |
|---|---|
ts |
բորսայի բաքեթի սկիզբ (bucket_ts), մս. Տողերը դասավորված են ըստ ts, ներսում՝ ըստ kind |
as_of |
պահին նշված ժամանակը, մս. Binance‑ի global_account, top_account, top_position և Bybit‑ի global_account uchun as_of == ts (snapshot այդ պահը). Binance‑ի taker_volume և OKX‑ի բոլոր տեսակների համար as_of == ts + 5 րոպե՝ արժեքը շրջանին [ts, ts + 5 րոպե). Մյուս զույգերի համար as_of == ts. Տարբեր բորսաների և տեսակների շարքերը համախմբեք לפי as_of |
long_ratio, short_ratio |
long-ների և short-ների բաժինները, առանց միավորի: 0.6849 == 68.49% |
long_short_ratio |
long-ների ու short-ների հարաբերությունը; taker_volume-ի համար՝ գնողների (taker-ների) և վաճառողների հարաբերությունը |
buy_vol, sell_vol |
taker-ների գնման և վաճառքի ծավալը բաքեթում — տող (բորսայի ճշգրիտ տասնորդական), միավորը՝ unit. Միայն taker_volume-ի համար |
unit |
buy_vol և sell_vol-ի միավոր: base — մոնետա. Մյուս տեսակների համար — null |
Թող բորսան չներկայացնի՝ նշանակում է null: օրինակ OKX‑ը հաճախ ուղարկում է միայն long_short_ratio, առանց բաժինների. Վերջին բաքեթը բորսան կարող է լրացնել նաև դրա ավարտից հետո՝ ցանկալի է կրկնվել վերջին ~10 րոպեն. Պատուհանը, որը երկար է մեկ շաբաթից, шлюզը կկոշտի և կվերադարձնի next_cursor; էջը՝ մինչև 10 000 տող: մեկ ts‑ի բոլոր տողերը ամբողջությամբ տեղափոխվում են մեկ էջին.
/v1/ls-ratio/latestՎերջին տողը յուրաքանչյուր տեսակի համար — կամ միայն տեսակ kind-ի համար — մինչև 35 օր: նույն ls_ratio խմբը, նույն սյուները, next_cursor — null.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, միայն պերպ |
kind |
շարքի տեսակը, ինչպես /v1/ls-ratio-ում. Լռելյայն — բոլորը |
{
"instrument": "binance:perp:BTCUSDT",
"tf": "5m",
"columns": ["ts", "as_of", "kind", "long_ratio", "short_ratio", "long_short_ratio", "buy_vol", "sell_vol", "unit"],
"rows": [
[1793279100000, 1793279100000, "global_account", 0.684, 0.316, 2.1646, null, null, null],
[1793278800000, 1793279100000, "taker_volume", null, null, 2.9092, "786.2880", "270.2730", "base"],
[1793279100000, 1793279100000, "top_account", 0.6978, 0.3022, 2.3091, null, null, null],
[1793279100000, 1793279100000, "top_position", 0.6779, 0.3221, 2.1047, null, null, null]
],
"next_cursor": null
}Ամեն տեսակի համար կարող է լինել իր վերջին տողը, և նրանց ts-երը կարող են տարբեր լինել, ինչպես օրինակում՝ taker_volume-ի դեպքում. Եթե 35 օրվա ընթացքում ոչ մի տող չկա՝ 404 not_found; նախքան լռած շարք դեպի վերադարձը կարդացեք /v1/ls-ratio-ով պատուհանով.
Mark և index
/v1/markPerp‑ի mark (mark price) և index գները վայրկյաններով կամ րոպեներով. Տարֆի խումբը կախված է քայլից՝ tf=1m — mark, tf=1s — mark_1s.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, միայն պերպեր: binance, bybit, okx, bitget, gate, hyperliquid, mexc, kraken, lighter, aster.Այլ բորսա — 400 unsupported_instrument |
tf |
1s — վայրկյաններ, хранатся 7 օր; 1m — րոպեներ, ժամկետ չկա. Լռելյայն 1m. Այլ քայլ — 400 bad_request՝ param: "tf": եթե ձեզ պետք է ավելի խոշոր քայլ, կարճացրեք ձեր եզրերը մինչև 1m ինքնուրույն |
from |
սկիզբ, մս., ըստ ts. Լռելյայն — մեկ օր առաջ to-ից, 1s համար՝ մեկ ժամ |
to |
վերջ, մս., չներառյալ. Լռելյայն — այժմ; եթե to ապագայում է՝ шлюզը այն զավթում է “ներկա”-ին |
cursor |
կուրսոր՝ վերցված next_cursor-ից |
curl -s "https://market-api.lootx.trade/v1/mark?instrument=binance:perp:BTCUSDT&tf=1m&from=1794531600000&to=1794531720000" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"instrument": "binance:perp:BTCUSDT",
"tf": "1m",
"columns": ["ts", "mark_open", "mark_high", "mark_low", "mark_close", "index_close", "premium", "secs"],
"rows": [
[1794531600000, "71111.39908546", "71137.9", "71045.18452774", "71045.18452774", "71084.41304348", -0.0005518581931035318, 60],
[1794531660000, "71044.18909295", "71044.18909295", "70970.4", "71007.3", "71051.90695652", -0.0006278080129122655, 60]
],
"next_cursor": null
}| Սյուն | Ինչ |
|---|---|
ts |
վայրկյանի կամ րոպեի սկիզբը, մս. |
mark (1s); mark_open, mark_high, mark_low, mark_close (1m) |
mark գինը quote-արժույթով — տող (բորսայի ճշգրիտ տասնորդական) |
index (1s), index_close (1m) |
index գինը՝ տողով, ինչպես mark. Եթե բորսան չի տալիս՝ null. Hyperliquid‑ում սա oraclePx է |
premium |
mark / index − 1 (1m‑ում՝ ըստ րոպեի փակման). Աճուրդային թիվ՝ առանց միավորի. Եթե index‑ը չկա՝ null |
secs |
միայն 1m համար՝ քանի վայրկյանում րոպեն ունեցել է արժեք, 1…60 |
Գները գալիս են տողով, որպեսզի չկորցնեք նշանները։ Պահեք դրանք տողով կամ թվաբանական տիպով, օգտագործեք ոչ float, և մի կլորացրեք գները գնի քայլով։
- Վայրկյանները առանց տողի՝ պահպանում են վերջին հայտնի արժեքը. բորսան հաճախ ուղարկում է միայն փոփոխությունները։ Ստացեք վերջին հայտնի արժեքը։
- Աշխատող րոպեն (
1m) չի ուղարկվում ամբողջությամբ՝ նկարը ստեղծեք վայրկյաններով։ - Վայրկյաններ, որոնք ավելի հին են 7 օրից չեն պահպանվում: ամբողջ
tf=1sպատուհանը, եթե հին է, վերադարձնում է400 bad_request՝param: "from"; մասնակի դեպքումfrom-ը մոտեցվում է պահպանման եզրին։ - Էջավորում. Եթե
1sպատուհանը ավելի քան մեկ ժամ է կամ1mպատուհանը ավելի քան մեկ շաբաթ է՝ шлюզը կկտրի և կվերադարձնիnext_cursor; էջը՝ մինչև 10 000 տող։ Կենդանի եզրից ավելի նոր քան 2 րոպե նշանակողի վրա՝ կուրսոր չկա՝ հաջորդ հարցումը սկսեք ընդունված վերջին տողից։
Գների հավաքը արտահաշվում է բորսաների առանձին, դրանք գումարել չեմ պետք: instruments=‑ով երկու կամ ավելի ինստրումենտներ ուղարկել նշանակում է 400 bad_request։
/v1/mark/latestՎերջին վայրկյանը mark և index‑ի համար 7 օրում: մեկ տող՝ tf=1s սյուներով. Տարֆի խումբ — mark.
| Պարամետր | Ինչ |
|---|---|
instrument |
պարտադիր, պերպ մեկը այն բորսաներից, որոնք նշված են /v1/mark բաժնում |
{
"instrument": "binance:perp:BTCUSDT",
"tf": "1s",
"columns": ["ts", "mark", "index", "premium"],
"rows": [[1794534182000, "70906.31457271", "70933.00695652", -0.00037630413477835085]],
"next_cursor": null
}Եթե 7 օրվա ընթացքում ոչ մի վայրկյան չկա՝ 404 not_found. Վերջին ~3 վայրկյանը աղբյուրը կարող է դեռ չգրանցել, այդ պատճառով հաճախ ավելի քան մեկ անգամ վայրկյանին հարցնելը անհրաժեշտ չէ.
https://docs.lootx.trade/hy/market-api/oi-funding
10Խտություններ և այսբերգներ
Խոշոր լիմիտային պատերը order book-ում հենց հիմա, հանված և կերված պատերի պատմությունը (պահվում է մինչև 90 օր), այսբերգները և կլանումները։
Խտությունը խոշոր լիմիտային հայտ է (պատ), որը նկատելիորեն մեծ է հարևան մակարդակների սովորական ծավալից։ Խտությունների ծառայությունը հետևում է բորսաների order book-ներին և պատերը տալիս է անմիջապես դոլարային չափով, գնից հեռավորությամբ և տարիքով։
Կենդանի խտություններ
/v1/densitiesՊատերի ընթացիկ պատկերը․ մեկ գործիքով կամ շուկայի ամփոփմամբ։ Սակագնի խումբը՝ densities։
| Պարամետր | Ինչ է |
|---|---|
instrument |
մեկ գործիք։ Առանց դրա՝ շուկայի ամփոփում՝ ստորև բերված ֆիլտրերով |
venue |
բորսաներ ստորակետով՝ binance,bybit |
market |
շուկաներ ստորակետով՝ spot, perp |
coins |
մետաղադրամներ ստորակետով՝ BTC,ETH — ոչ սիմվոլներ |
side |
bid կամ ask |
min_usd |
պատի նվազագույն չափը, $ |
max_dist_bp |
առավելագույն հեռավորությունը order book-ի միջնակետից, բազիսային կետեր․ 200 = ±2 % |
limit |
քանի պատ, լռելյայն 200 |
sort |
usd (լռելյայն), age, dist |
curl -s "https://market-api.lootx.trade/v1/densities?coins=BTC&market=perp&min_usd=1000000&limit=2" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"ts": 1793750400000,
"columns": ["instrument", "side", "price", "qty", "usd", "dist_bp", "first_ts", "age_ms",
"peak_usd", "state", "touched", "size", "score", "agg", "wall_id"],
"rows": [
["binance:perp:BTCUSDT", "bid", 103500.0, 41.8, 4326300.0, -72, 1793741112000, 9288000,
4512000.0, "live", false, "strong", 2.37, "tick", "11658847687750313317"]
],
"next_cursor": null
}| Սյունակ | Ինչ է |
|---|---|
side |
bid — գնում, ask — վաճառք |
price, qty, usd |
գին, ծավալը մետաղադրամներով և պատի չափը դոլարով |
dist_bp |
հեռավորությունը order book-ի միջնակետից նշանով, բ․ կ․․ մինուս — միջնակետից ցածր (սովորաբար bid-եր), պլյուս — վերև (ask-եր)։ max_dist_bp ֆիլտրը համեմատում է մոդուլը |
first_ts, age_ms |
երբ է պատը հայտնվել և որքան է արդեն կանգնած |
peak_usd |
պատի ամենամեծ չափը իր կյանքի ընթացքում |
state |
live — կանգնած է առանց նկատելի փոփոխության, updated — չափը նկատելիորեն փոխվել է նախորդ պատկերի համեմատ |
touched |
պատի գնով արդեն գործարքներ են անցել, որոնք նրան ուտում են |
size |
normal, weak, optimal, strong — չափի աստիճանը զույգի liquidity-ի նկատմամբ․ normal — խտություն կա, բայց թույլ աստիճանից ցածր է |
score |
խոշորության չափանիշ․ 1 — optimal շեմ, 2 — strong շեմ, 0 — չի հաշվվել |
agg |
tick — պատը մեկ մակարդակում, natr — մակարդակները սոսնձված են ըստ volatility-ի |
wall_id |
պատի համարը տողով․ դա 64-բիթանոց թիվ է, JavaScript-ում այն չի տեղավորվում number-ի մեջ առանց կորստի |
Ամփոփումը դասավորված է ըստ usd-ի, ts-ը պատկերի պահն է։ Պատկերը կենդանի է․ խտությունների քեշ չկա, յուրաքանչյուր հարցում թարմ վիճակ է։ Շարունակական հետևման համար վերցրեք densities ալիքը WebSocket-ում․ ըստ գործիքների ցանկի կամ ամբողջ շուկան ֆիլտրերով։ Փոփոխությունները գալիս են ինքնուրույն, առանց հարցման․ կադրերի բայթերը մտնում են օրական ծավալի մեջ REST-ի հետ միասին։
Խտությունների պատմություն
/v1/densities/historyՓակ պատեր․ հանված (pulled) և գործարքներով կերված (eaten)։ Պահվում են մինչև 90 օր։ Սակագնի խումբը՝ densities_history։
| Պարամետր | Ինչ է |
|---|---|
instrument |
պարտադիր |
from |
սկիզբը պատի հայտնվելու պահով, մվ։ Լռելյայն՝ մեկ օր առաջ to-ից |
to |
վերջ, մվ, չներառյալ |
kind |
pulled, eaten կամ երկուսն էլ ստորակետով (լռելյայն) |
limit |
պատեր էջում, 1–10 000, լռելյայն 1000 |
cursor |
կուրսոր․ էջերը գնում են թարմից հին |
{
"instrument": "binance:perp:BTCUSDT",
"columns": ["t", "side", "kind", "price", "qty_open", "qty_close", "usd_open", "usd_peak",
"end_ts", "duration_ms", "dist_bp_open", "mid_at_close", "touched", "size"],
"rows": [
[1793741112000, "bid", "eaten", 103500.0, 41.8, 0.0, 4326300.0, 4512000.0,
1793752004000, 10892000, -72, 103498.6, true, "S"]
],
"next_cursor": null
}t — պատի հայտնվելը, end_ts — երբ այն վերացավ․ qty_open/qty_close — ծավալը սկզբում և վերջում, mid_at_close — order book-ի միջնակետը փակման պահին։ size-ը պատմության մեջ կարճ կոդ է․ "" — առանց աստիճանի, W — weak, O — optimal, S — strong։
Պատմության մեջ գրվում են սեղմված order book-ի պատերը (agg = natr), ոչ թե առանձին մակարդակների․ գինը և չափը չեն համընկնում կենդանի պատկերի պատերի հետ (այնտեղ լռելյայն tick է), իսկ wall_id պատմության մեջ չկա — փակ պատը կենդանու հետ համարով կապել հնարավոր չէ։
Այսբերգներ և կլանումներ
/v1/icebergsԹաքնված հայտեր, որոնք լրացվում են մաս-մաս (iceberg), և մակարդակներ, որոնք կլանում են շուկայական հոսքը (absorption)։ Սակագնի խումբը՝ icebergs։
| Պարամետր | Ինչ է |
|---|---|
instrument |
մեկ գործիք։ Առանց դրա՝ ըստ շուկայի՝ ֆիլտրերով |
venue, market, coins, side |
ֆիլտրեր, ինչպես խտությունների դեպքում․ coins — մինչև 100 |
kind |
iceberg, absorption կամ all (լռելյայն) |
min_usd |
նվազագույն թաքնված կատարված ծավալ, $ |
state |
active (լռելյայն — ընթացիկ), ended (ավարտված) կամ all |
limit |
1–5000, լռելյայն 200 |
Սյունակներ․ instrument, id (տողով — 64-բիթանոց թիվ), side, kind, price, first_ts, last_ts, trades, executed_qty, hidden_qty, visible_max, clip_qty (մետաղադրամներ), executed_usd, hidden_usd ($․ թաքնված ծավալը ստորին գնահատական է), refills, end (null — դեռ ընթացքի մեջ է, այլապես idle, broken կամ reset)։
https://docs.lootx.trade/hy/market-api/densities
11Screener
Հարյուրավոր գործիքների մետրիկաներ մեկ հարցումով՝ գին, փոփոխություն, ծավալ, funding rate, OI և դրանց փոփոխությունները պատուհաններում. բոլոր մետրիկաների տեղեկատու:
Սքրիների պատկեր
/v1/screenerԱղյուսակ «գործիք × մետրիկա» շուկայով. վերջին գին, փոփոխություն օրվա ընթացքում, ծավալ, ֆանդինգ, OI և տասնյակ այլ ցուցանիշներ։ Սակագնի խումբը՝ screener:
| Պարամետր | Ինչ |
|---|---|
venue |
բորսաներ ստորակետով, ռեգիստրը կարևոր չէ, նույն հավաքածուն, ինչ շուկայի բաժանորդագրության մոտ. Upbit սքրիներում չկա։ Լռելյայն՝ բոլորը։ Անհայտ բորսա՝ 400 bad_request param: "venue"-ով, ոչ թե «բոլոր բորսաները» |
market |
spot, perp ստորակետով, ռեգիստրը կարևոր չէ։ Այլ արժեք՝ 400 bad_request |
instruments |
գործիքների ճշգրիտ հավաքածու ստորակետով, կանոնները՝ ներքևում։ Դրա հետ venue-ն ու market-ը չեն կարդացվում։ top_n-ը գործում է նաև այստեղ. 100-ից ավելի գործիքների հավաքածուի համար փոխանցեք top_n ոչ պակաս դրա չափից, այլապես պատասխանը լուռ կկրճատվի |
top_n |
առաջին N-ը՝ ըստ օրական ծավալի, 1–2000, լռելյայն՝ 100։ 0-ն և 2000-ից ավելի արժեքները սեղմվում են սահմանին |
names |
սյունակների անուններ. long (լռելյայն. volume_24h_usd, oi_change_usd_5m, …) կամ short՝ կարճ բանալիներ (v24, odu5, …)։ Այլ արժեք՝ 400 bad_request |
curl -s "https://market-api.lootx.trade/v1/screener?venue=binance&market=perp&top_n=2" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"ts": 1793750400000,
"columns": ["instrument", "ts", "last_price", "change_24h_pct", "volume_24h_usd", "funding_rate", "open_interest"],
"rows": [
["binance:perp:BTCUSDT", 1793750399870, 104250.5, 1.84, 18234455120.4, 0.0001, 8423311987.2],
["binance:perp:ETHUSDT", 1793750399912, 3712.44, -0.62, 9122870411.7, 0.000085, 4120098211.6]
],
"next_cursor": null
}Օրինակը կրճատված է. իրական պատասխանը կրում է բոլոր մետրիկաները, որ աղբյուրը գիտի գործիքի մասին։ Մետրիկաները, որոնք գործիքը չունի, գալիս են null:
Գործիքների հավաքածու
- Սիմվոլը ռեգիստրի հետ չի համեմատվում։ Անունը ստորև նշված ստուգումներն անցել է, բայց սքրիներում գործիքը չկա, այդ թվում՝ վրիպակի պատճառով, — նրա տողը չկա, պատասխանը՝
200։ Ոչ մեկը չգտնվեց —200դատարկrows-ով. ստուգվեք/v1/instruments-ով։ - Անվան սխալ ձև՝
400 bad_instrument, ամբողջ հարցումը։ 400 unsupported_instrumentparam: "instrument"-ով, ամբողջ հարցումը. շուկանspotկամperpչէ. սիմվոլի քոթարժույթը չի վերծանվում, ինչպեսokx:perp:BTC-USDT-SWAP-ում. պերպը քոթարժույթով ոչUSDT,USDCկամUSD-ից, ինչպեսbinance:perp:ETHBTC-ում։ Hyperliquid-ի պերպերին վերջին երկու ստուգումները չեն վերաբերում։- Բորսան անվան մեջ չի ստուգվում. անհայտ բորսան տալիս է ոչ թե մերժում, այլ տողի բացակայություն։
- Սքրիներում դեկ չկա. մոնետայի բոլոր դեկերի համար մեկ տող է, և պատասխանում այն նշվում է առանց դեկի։
hyperliquid:perp:AAPLUSDC.XYZ-ը ևhyperliquid:perp:AAPLUSDC-ն մեկ տող են՝hyperliquid:perp:AAPLUSDC: - Դատարկ
instruments=արժեքը նույնն է, ինչ առանց պարամետրի. ամբողջ շուկան՝ հաշվի առնելովvenue-ն ուmarket-ը։
Մետրիկաների տեղեկատու
/v1/screener/metricsԻնչ սյունակներ կան սքրիներում. կարճ բանալի, երկար անուն, միավոր, պատուհան, խումբ և նկարագրություն։ Ստատիկ է — կարող եք քեշավորել ձեզ մոտ։ Նույն screener խումբը։
{
"columns": ["key", "name", "unit", "window", "group", "description"],
"rows": [
["odu5", "oi_change_usd_5m", "usd", "5m", "oi", "Բաց հետաքրքրության փոփոխություն 5 րոպեում դոլարով. OI հիմա − OI 5 րոպե առաջ (հենակետը որոնվում է ըստ ժամանակի)։"]
]
}Եթե աղբյուրը նոր մետրիկա է ներդրել նախքան այն տեղեկատու մտնելը, այն գալիս է կարճ բանալիով՝ ինչպես կա — անծանոթ անունով սյունակները լուռ մի մերժեք։
Կենդանի սքրիների համար օգտագործեք screener ալիքը WebSocket-ում. թարմացումները գալիս են միայն փոփոխված մետրիկաներով։ Ամբողջ շուկային միանգամից հետևում է ամբողջ շուկայի բաժանորդագրությունը՝ ֆիլտրերով ըստ բորսաների, շուկաների և մետրիկաների։
https://docs.lootx.trade/hy/market-api/screener
12Маржинальное кредитование
Займы и возвраты пула маржи 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/hy/market-api/margin
13Опционы
Опционы Deribit, Binance, Bybit и OKX по цепочкам — базы с ликвидностью, каталог с правилом поставки, экспирации с max pain, GEX, ATM IV и ожидаемым ходом, цепочка минуты, ряд волатильности книги, экспозиция и уровни GEX, живой поток, история цепочки за диапазон минут, покрытие сбора.
Опционы четырёх площадок — deribit, binance, bybit, okx — по цепочкам базы: базы площадок с ликвидностью, каталог инструментов, экспирации с суммами объёма и OI и расчётом (max pain, GEX, ATM IV, ожидаемый ход), цепочка одной минуты (котировки, mark, подразумеваемая волатильность, OI, объёмы, форвард и индекс), история одной цепочки за диапазон минут, ряд волатильности книги, экспозиция GEX, DEX, VEX и CEX новейшей минуты по страйкам, история уровней книги (zero gamma, стены, max pain), покрытие сбора и живой поток цепочек по WebSocket. Все десять маршрутов и поток — одна группа тарифа options.
База — монета, на которую выписаны опционы: BTC, ETH, SOL. У базы бывает несколько цепочек — например, у Deribit BTC (inverse) и BTC_USDC (linear). Инструмента в виде venue:market:SYMBOL здесь нет: площадку выбирает venue, базу — base, цепочку — chain.
Доступ
- Группа тарифа —
options. Пока тариф не задаёт ей своих лимитов, запросы к ней расходуют общие лимиты ключа (лимиты групп). Тариф, закрывший группу, получает403 route_not_in_plan. - Область —
derivatives. API-ключу нужна областьmarket:read— та же, что у остальных маршрутов. Токен терминала должен нести областьderivatives: у бесплатного её нет, ответ —403 insufficient_scope, к источнику запрос не уходит. - Площадка по умолчанию —
deribit, кроме/v1/options/bases: безvenueон отдаёт все четыре площадки. Какие базы и цепочки есть у площадки, говорит/v1/options/bases; база без опционов или чужая цепочка —400 upstream_rejectedсparam: "base"или"chain".
Единицы и null
| Что | Как приходит | Где |
|---|---|---|
| Время | Unix-мс UTC, целым | expiry_ms, ts_min, snap_ts, oi_asof_ms, last_ts_min, from_ms, to_ms, from, to, ts_ms, asof_ms, expiries_ms, max_pain_expiry_ms |
| Деньги | *_usd_e8 — целым числом строкой, USD, USDT или USDC × 10⁸: "16400000" — 0,164 USDT у binance. Валюта и смысл — по площадке, цепочке и полю, в таблице ниже. Со знаком — только gamma_usd_e8, gex_usd_e8, dex_usd_e8, vex_usd_e8, cex_usd_e8, gex_put_usd_e8 и net_gex_usd_e8 |
volume_usd_e8, volume_notional_usd_e8 — объёмы за 24 ч в деньгах; volume_24h_usd_e8, oi_usd_e8 — ликвидность баз, max_pain_payout_usd_e8, gamma_usd_e8 — расчёт экспираций, gex_usd_e8, dex_usd_e8, vex_usd_e8, cex_usd_e8, gex_call_usd_e8, gex_put_usd_e8 — экспозиция, net_gex_usd_e8 — история уровней, валюта — рядом в ответе |
| Цены | точной десятичной записью строкой, за 1 монету базы в валюте котировки цепочки: у settle: inverse — в монете базы (0.005 — BTC), у linear — в USD, USDT или USDC |
bid, ask, mark, tick_size, tick_steps |
| Форвард и индекс | десятичной строкой | forward, index |
| Страйк и размеры | десятичной строкой | strike, contract_size, min_trade |
| Количества | в контрактах, десятичной строкой; контракты × contract_size — монеты базы. volume — за 24 ч |
oi_asof, volume, bid_size, ask_size, oi_calls, oi_puts |
| OI экспирации в монетах | десятичной строкой: (Σ oi_asof call + Σ oi_asof put) × contract_size |
oi_coins |
| Волатильность | iv_bp — целым, в 0,01 пункта: 4872 — 48,72 % |
iv_bp, atm_iv_bp, IV ряда волатильности, rr25_bp_30d, bf25_bp_30d |
| Ожидаемый ход | целым, в базисных пунктах от форварда F: 273 — 2,73 % от F. Это доля цены, а не пункты волатильности |
move_straddle_bp, move_sigma_bp |
Деньги опционов — премия или номинал. Номинал в ответе есть только у Bybit, остальные деньги — премия. Валюта денег — не всегда валюта цен цепочки: у Deribit *_USDC цены в USDC, а volume_usd_e8 — в USD. Номинал у Deribit и Binance оценивайте сами: volume × contract_size × index. Премию с номиналом не сравнивайте, а суммы разных площадок не складывайте без оговорки: USDT — не USD. Разбирайте *_usd_e8 как целое произвольной длины или десятичный тип: значение бывает больше 2⁵³, а в число с плавающей точкой его не переводите. Деньги не округляются к шагу цены ни у нас, ни в ваших расчётах не должны. Цены и количества тоже не превращайте в double, пока не нужно: строка — точное значение площадки.
null — «нет данных», а не ноль. Поле, которого площадка не шлёт, — null всегда, в каждой строке цепочки и в суммах экспираций. Деньги и пропуски по цепочкам:
| Площадка | Цепочка BTC | volume_usd_e8 |
volume_notional_usd_e8 |
Не шлёт — всегда null |
|---|---|---|---|---|
deribit |
BTC — inverse |
премия, USD | нет | bid_size, ask_size, volume_notional_usd_e8 |
deribit |
BTC_USDC — linear, USDC |
премия, USD | нет | bid_size, ask_size, volume_notional_usd_e8 |
binance |
BTC — linear, USDT |
премия, USDT | нет | forward, bid_size, ask_size, volume_notional_usd_e8 |
bybit |
BTC — linear, USDT |
нет | номинал, USDT | volume_usd_e8 |
bybit |
BTC_USDC — linear, USDC; сейчас Bybit таких не листит |
нет | номинал, USDC | volume_usd_e8 |
okx |
BTC — inverse |
нет | нет | index, volume_usd_e8, volume_notional_usd_e8 |
okx |
BTC_UM — linear, USD |
нет | нет | index, volume_usd_e8, volume_notional_usd_e8 |
Остальное бывает null по случаю: нет котировки — null в bid или ask, а у Bybit и OKX — и в размере этой стороны; у Binance и OKX минута бывает записана без части снимка (в покрытии это дыра stream: oi или quotes) — тогда null в oi_asof или в полях тикера: котировках, их размерах, volume, у Binance ещё в volume_usd_e8 и index; суммы объёма экспирации без кадра — null; instrument: null — имени инструмента в каталоге нет.
OI — на момент oi_asof_ms, а не минуты. oi_asof строки — OI на момент oi_asof_ms её цепочки. У Deribit он на 8 часов раньше снимка минуты.
JSON — тело источника как есть: у catalog и chain поле venue первое, у expiries и coverage ключи по алфавиту. Разбирайте поля по именам, а не по порядку.
Валюта цепочки
Валюта цепочки — в ответе. settle, price_ccy, volume_usd_ccy и volume_notional_ccy приходят у цепочек каталога и минуты (chain, chain/latest) и у экспираций, settle и price_ccy — ещё у баз; в кадрах OPC1 и в ряду chain/range их нет — берите их из каталога или bases. price_ccy — валюта цен bid, ask, mark (у inverse — монета базы), volume_usd_ccy — валюта volume_usd_e8, volume_notional_ccy — валюта volume_notional_usd_e8; null — такого поля у цепочки нет. Все четыре — у цепочки, а не у инструмента: null в settle или price_ccy — у инструментов цепочки не одно значение.
| Площадка | Цепочка базы BTC | settle |
price_ccy |
volume_usd_ccy |
volume_notional_ccy |
|---|---|---|---|---|---|
deribit |
BTC |
inverse |
BTC |
USD |
null |
deribit |
BTC_USDC |
linear |
USDC |
USD |
null |
binance |
BTC |
linear |
USDT |
USDT |
null |
bybit |
BTC |
linear |
USDT |
null |
USDT |
bybit |
BTC_USDC |
linear |
USDC |
null |
USDC |
okx |
BTC |
inverse |
BTC |
null |
null |
okx |
BTC_UM |
linear |
USD |
null |
null |
Премия в долларах. volume_usd_e8 / 10⁸ — сумма в валюте volume_usd_ccy: у Deribit — USD (BTC и BTC_USDC) и у Binance — USDT. Долларами она становится только при volume_usd_ccy: "USD"; USDT и USDC переводите в USD своим курсом, а не 1 : 1. Номинал — так же, по volume_notional_ccy: у Bybit без суффикса — USDT, на *_USDC — USDC. Валюту берите из ответа, а не из этой таблицы: таблица — то, что площадки шлют сейчас.
Базы
/v1/options/basesБазы опционов и их цепочки по площадкам — то, что листингуется сейчас: settle, price_ccy, версия каталога, сколько инструментов и экспираций, ликвидность новейшей минуты. Группа тарифа — options.
| Параметр | Что |
|---|---|
venue |
площадка: deribit, binance, bybit, okx; строчными. Без параметра — все четыре: умолчания deribit у этого маршрута нет |
curl -s "https://market-api.lootx.trade/v1/options/bases" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venues": [
{
"venue": "deribit",
"bases": [
{
"base": "BTC",
"volume_24h_usd_e8": "4810545000000000", "volume_ccy": "USD", "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795152664164,
"chains": [
{"chain": "BTC", "settle": "inverse", "price_ccy": "BTC", "catalog_ver": 13, "instruments": 950, "expiries": 12, "volume_24h_usd_e8": "4718235000000000", "volume_ccy": "USD", "oi_usd_e8": "1893412000000000000", "oi_ccy": "USD", "oi_asof_ms": 1795152664164},
{"chain": "BTC_USDC", "settle": "linear", "price_ccy": "USDC", "catalog_ver": 6, "instruments": 576, "expiries": 8, "volume_24h_usd_e8": "92310000000000", "volume_ccy": "USD", "oi_usd_e8": "61200000000000000", "oi_ccy": "USDC", "oi_asof_ms": 1795152665101}
]
}
]
},
{
"venue": "binance",
"bases": [
{
"base": "BTC",
"volume_24h_usd_e8": "51730000000000", "volume_ccy": "USDT", "oi_usd_e8": "38410000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181462000,
"chains": [
{"chain": "BTC", "settle": "linear", "price_ccy": "USDT", "catalog_ver": 6, "instruments": 688, "expiries": 11, "volume_24h_usd_e8": "51730000000000", "volume_ccy": "USDT", "oi_usd_e8": "38410000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181462000}
]
}
]
},
{
"venue": "bybit",
"bases": [
{
"base": "BTC",
"volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": "29870000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181413387,
"chains": [
{"chain": "BTC", "settle": "linear", "price_ccy": "USDT", "catalog_ver": 17, "instruments": 720, "expiries": 11, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": "29870000000000000", "oi_ccy": "USDT", "oi_asof_ms": 1795181413387}
]
}
]
},
{
"venue": "okx",
"bases": [
{
"base": "BTC",
"volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000,
"chains": [
{"chain": "BTC", "settle": "inverse", "price_ccy": "BTC", "catalog_ver": 12, "instruments": 770, "expiries": 13, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000},
{"chain": "BTC_UM", "settle": "linear", "price_ccy": "USD", "catalog_ver": 9, "instruments": 626, "expiries": 9, "volume_24h_usd_e8": null, "volume_ccy": null, "oi_usd_e8": null, "oi_ccy": null, "oi_asof_ms": 1795181461000}
]
}
]
}
]
}Пример — ответ без venue, сокращённый до одной базы на площадку. Состав цепочек — живой ответ 20.11, числа ликвидности показывают форму, а не снимок рынка.
| Поле | Что |
|---|---|
venues[] |
площадки: присланная venue или все четыре |
bases[] |
базы площадки по имени; база, у которой ничего не листингуется, в список не попадает |
chains[] |
цепочки базы, где что-то листингуется: chain, settle, price_ccy — как у каталога (выше), catalog_ver — та же версия, что у каталога, instruments — сколько инструментов листингуется, expiries — сколько у них разных экспираций |
Ликвидность новейшей минуты — у каждой цепочки и у базы: премия за сутки и OI в деньгах, у каждой суммы — своя валюта. null, а не 0: у цепочки нет кадра, площадка поле не шлёт, у инструментов цепочки не одна валюта или сумма не уместилась в e8. Суммы считаются по новейшей минуте каждой цепочки, поэтому ETag ответа меняется с каждой минутой.
| Поле ликвидности | Что |
|---|---|
volume_24h_usd_e8 |
премия за 24 ч — сумма volume_usd_e8 строк новейшей минуты, целым e8 строкой |
volume_ccy |
валюта volume_24h_usd_e8 — та же, что volume_usd_ccy цепочки: у Deribit — USD (BTC и BTC_USDC) и у Binance — USDT; Bybit и OKX премию не шлют — null |
oi_usd_e8 |
OI в деньгах — Σ oi_asof × contract_size × index строк с OI, целым e8 строкой; это не премия и не номинал оборота |
oi_ccy |
валюта oi_usd_e8 — валюта котировки книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; OKX индекс не шлёт — null |
oi_asof_ms |
на какой момент OI, Unix-мс: у Deribit — на 8 часов раньше снимка; у базы — самой старой цепочки |
Сумма базы — по всем её цепочкам и только когда значение есть у каждой и валюта одна, иначе null. У Deribit OI BTC — в USD, BTC_USDC — в USDC, поэтому oi_usd_e8 базы — null; премия у обеих — в USD, она сложена.
Список баз и цепочек — из каталога в памяти источника. ETag ответа — хэш тела: If-None-Match даёт 304, пока не пришла следующая минута или листинг.
Каталог
/v1/options/catalogИнструменты базы по цепочкам: страйк, экспирация, вид, расчёт, размер контракта, шаг цены и его ступени, наименьшая заявка, состояние на площадке; у цепочки — правило поставки. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный: база, 1–16 знаков из A-Z, 0-9 — BTC, ETH, SOL |
venue |
площадка: deribit, binance, bybit, okx, по умолчанию deribit; строчными |
chain |
одна цепочка базы: A-Z, 0-9, _, до 32 знаков — BTC_USDC. Без параметра — все цепочки |
curl -s "https://market-api.lootx.trade/v1/options/catalog?base=BTC&chain=BTC" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chains": [
{
"chain": "BTC",
"catalog_ver": 13,
"settle": "inverse",
"price_ccy": "BTC",
"volume_usd_ccy": "USD",
"volume_notional_ccy": null,
"settle_rule": {"kind": "twap", "window_s": 1800, "at_utc": "08:00"},
"instruments": [
{"instrument": "BTC-21NOV26-62500-C", "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "settle": "inverse", "contract_size": "1", "tick_size": "0.0001", "tick_steps": [["0.005", "0.0005"]], "min_trade": "0.1", "settlement_period": "day", "settlement_currency": "BTC", "price_index": "btc_usd", "state": "open"}
]
}
]
}| Поле | Что |
|---|---|
catalog_ver |
версия каталога цепочки: растёт при листинге и делистинге |
settle, price_ccy, volume_usd_ccy, volume_notional_ccy |
у цепочки, а не у инструмента — выше |
settle_rule |
как цепочка поставляется: kind — twap (средняя индекса за окно перед поставкой), window_s — окно в секундах, at_utc — время поставки ЧЧ:ММ UTC. Сейчас у всех четырёх площадок — twap за 1800 с; spot и auction зарезервированы. null — правило не известно, листингов нет или экспирации цепочки поставляются в разное время суток |
instrument |
имя инструмента у площадки |
type |
call или put |
settle у инструмента |
linear или inverse |
tick_steps |
ступени шага цены: [цена от, шаг]; пусто — шаг один, tick_size |
min_trade |
наименьшая заявка, в контрактах |
settlement_period |
day, week, month, quarter; пустая строка — площадка периода не называет (все, кроме Deribit) |
state |
состояние на площадке, open — торгуется |
Каталог BTC — около полумегабайта. Его ETag строится из catalog_ver цепочек: пришлите метку в If-None-Match — пока листингов не было, ответ 304 без тела. Метка начинается с "cat3-; старая, выданная до settle_rule, даёт 200 с новым телом.
Экспирации
/v1/options/expiriesЭкспирации базы по цепочкам: сколько call и put, суммы объёма и OI новейшей минуты. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
{
"base": "BTC",
"expiries": [
{"calls": 23, "chain": "BTC", "expiry_ms": 1795248000000, "oi_asof_ms": 1795152664164, "oi_calls": "1070.2", "oi_coins": "2871.5", "oi_puts": "1801.3", "oi_rows": 46, "price_ccy": "BTC", "puts": 23, "settle": "inverse", "settlement_period": "day", "volume_notional_ccy": null, "volume_notional_usd_e8": null, "volume_usd_ccy": "USD", "volume_usd_e8": "174016738000000"},
{"calls": 23, "chain": "BTC_USDC", "expiry_ms": 1795248000000, "oi_asof_ms": 1795152665101, "oi_calls": "76.41", "oi_coins": "229.93", "oi_puts": "153.52", "oi_rows": 46, "price_ccy": "USDC", "puts": 23, "settle": "linear", "settlement_period": "day", "volume_notional_ccy": null, "volume_notional_usd_e8": null, "volume_usd_ccy": "USD", "volume_usd_e8": "3401646000000"}
],
"venue": "deribit"
}Пример — живой ответ, сокращённый до экспирации на цепочку. volume_usd_e8 и volume_notional_usd_e8 — суммы по инструментам экспирации на новейшей минуте за 24 ч, валюта и смысл — как у строк цепочки (таблица выше). null — кадра ещё нет или площадка поле не шлёт.
| Поле | Что |
|---|---|
oi_calls, oi_puts |
OI call и put экспирации — сумма oi_asof строк новейшей минуты, в контрактах, точной десятичной строкой; null — OI нет ни у одной строки этой стороны, а не ноль |
oi_coins |
OI экспирации в монетах базы: (oi_calls + oi_puts) × contract_size |
oi_asof_ms |
к какому моменту относится OI — как у цепочки: у Deribit на 8 часов раньше снимка |
oi_rows |
сколько строк кадра вошло в суммы OI: меньше calls + puts — у части экспирации OI нет, суммы — по остальным |
settle, price_ccy, volume_usd_ccy, volume_notional_ccy |
как у каталога — выше |
Пока у цепочки нет ни одного кадра, все пять полей OI — null.
Расчёт экспирации — ещё шесть полей у каждой экспирации, по той же новейшей минуте: max pain, GEX, ATM IV и ожидаемый ход двумя способами.
{
"base": "BTC",
"expiries": [
{"atm_iv_bp": 5945, "chain": "BTC", "expiry_ms": 1795248000000, "gamma_usd_e8": "42000000000000", "max_pain": "62000", "max_pain_payout_usd_e8": "310000000000000", "move_sigma_bp": 327, "move_straddle_bp": 262, "price_ccy": "BTC", "settle": "inverse"},
{"atm_iv_bp": 5951, "chain": "BTC_USDC", "expiry_ms": 1795248000000, "gamma_usd_e8": "-3500000000000", "max_pain": "62000", "max_pain_payout_usd_e8": "21500000000000", "move_sigma_bp": 327, "move_straddle_bp": 259, "price_ccy": "USDC", "settle": "linear"}
],
"venue": "deribit"
}Пример — только поля расчёта, settle и price_ccy, остальные поля экспирации — как выше; числа показывают форму, а не снимок рынка.
Деньги расчёта — в валюте котировки книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC. Какая у экспирации — по её settle и price_ccy. Суффикс _usd_e8 в имени — по образцу volume_usd_e8, а не валюта: USDT — не USD, суммы разных цепочек без перевода курсом не складывайте.
| Поле расчёта | Что |
|---|---|
max_pain |
страйк, при котором держатели опционов экспирации получают меньше всего, — среди листингованных страйков; десятичной строкой в шкале страйка |
max_pain_payout_usd_e8 |
сколько продавцы заплатят держателям, если поставка пройдёт по max_pain; целым e8 строкой |
gamma_usd_e8 |
net GEX экспирации в режиме naive (знак по OI): Σ Γ × OI × F² × 0,01 — деньги на ход форварда в 1 %; call — плюсом, put — минусом. Целым e8 строкой со знаком |
atm_iv_bp |
ATM IV у форварда, целым в 0,01 пункта: 5945 — 59,45 % |
move_straddle_bp |
ожидаемый ход по рынку: ATMF-страддл по mark, интерполяция у форварда, / F — в базисных пунктах от F |
move_sigma_bp |
ожидаемый ход по модели: σ_ATM × √T, T — до поставки без поправки на окно поставки, в базисных пунктах от F |
null расчёта — «нет данных», а не 0. Нет OI в экспирации — max_pain и max_pain_payout_usd_e8; нет строк с греками — gamma_usd_e8; нет форварда или котировок у него — IV и ход; экспирации нет в новейшей минуте (листинг позже) или поставка уже прошла — все шесть полей; у цепочки нет кадра или у её инструментов не одна валюта — тоже все шесть; деньги, не уместившиеся в e8, — null.
Цепочка последней минуты
/v1/options/chain/latestНовейшая минута цепочек базы: строка на инструмент — котировки, mark, iv_bp, OI, объёмы, форвард и индекс. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
chain |
одна цепочка базы; без параметра — все |
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chains": [
{
"chain": "BTC",
"ts_min": 1795181400000,
"snap_ts": 1795181464164,
"oi_asof_ms": 1795152664164,
"catalog_ver": 13,
"settle": "inverse",
"price_ccy": "BTC",
"volume_usd_ccy": "USD",
"volume_notional_ccy": null,
"rows": [
{"expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0041", "ask": "0.0045", "mark": "0.00433933", "iv_bp": 5961, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61415.57", "index": "61437.37", "bid_size": null, "ask_size": null}
]
},
{
"chain": "BTC_USDC",
"ts_min": 1795181400000,
"snap_ts": 1795181465101,
"oi_asof_ms": 1795152665101,
"catalog_ver": 6,
"settle": "linear",
"price_ccy": "USDC",
"volume_usd_ccy": "USD",
"volume_notional_ccy": null,
"rows": [
{"expiry_ms": 1795248000000, "strike": "63500", "type": "call", "instrument": "BTC_USDC-21NOV26-63500-C", "bid": "80", "ask": "95", "mark": "88.33583281", "iv_bp": 5903, "oi_asof": "13.53", "volume": "13.24", "volume_usd_e8": "566902000000", "volume_notional_usd_e8": null, "forward": "61416.63", "index": "61435.68", "bid_size": null, "ask_size": null}
]
}
]
}Пример — живой ответ, сокращённый до строки на цепочку. Номинал в ответе есть только у Bybit:
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC&venue=bybit" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "bybit",
"base": "BTC",
"chains": [
{
"chain": "BTC",
"ts_min": 1795181340000,
"snap_ts": 1795181413387,
"oi_asof_ms": 1795181413387,
"catalog_ver": 17,
"settle": "linear",
"price_ccy": "USDT",
"volume_usd_ccy": null,
"volume_notional_ccy": "USDT",
"rows": [
{"expiry_ms": 1795248000000, "strike": "62000", "type": "call", "instrument": "BTC-21NOV26-62000-C-USDT", "bid": "470", "ask": "475", "mark": "470.28075375", "iv_bp": 6043, "oi_asof": "33.15", "volume": "146.47", "volume_usd_e8": null, "volume_notional_usd_e8": "905865257399944", "forward": "61517.00049217", "index": "61510.93639245", "bid_size": "1.82", "ask_size": "37.54"}
]
}
]
}Пример с номиналом — живой ответ Bybit, сокращённый до строки. volume_notional_usd_e8 — номинал, USDT: 9 058 652,57 USDT при volume × index = 146,47 × 61 510,94 ≈ 9 009 507 — оборот набран за сутки по цене BTC во время сделок, а индекс взят на снимке. Размеры котировок есть, OI — на момент снимка.
curl -s "https://market-api.lootx.trade/v1/options/chain/latest?base=SOL" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "SOL",
"chains": [
{
"chain": "SOL_USDC",
"ts_min": 1795181400000,
"snap_ts": 1795181465101,
"oi_asof_ms": 1795152665101,
"catalog_ver": 8,
"settle": "linear",
"price_ccy": "USDC",
"volume_usd_ccy": "USD",
"volume_notional_ccy": null,
"rows": [
{"expiry_ms": 1795248000000, "strike": "73", "type": "call", "instrument": "SOL_USDC-21NOV26-73-C", "bid": "0.17", "ask": "0.23", "mark": "0.20924689", "iv_bp": 7178, "oi_asof": "19", "volume": "211", "volume_usd_e8": "156548000000", "volume_notional_usd_e8": null, "forward": "70.722", "index": "70.7067", "bid_size": null, "ask_size": null}
]
}
]
}Пример по альту — живой ответ Deribit по SOL, сокращённый до строки. Количества и у альтов — в контрактах: у SOL_USDC контракт — 10 SOL (contract_size в каталоге, min_trade — "1"), монеты базы — volume или oi_asof × 10.
| Поле | Что |
|---|---|
ts_min |
начало минуты, мс |
snap_ts |
когда снят снимок площадки — сразу после закрытия минуты, мс |
oi_asof_ms |
к какому моменту относится oi_asof строк |
catalog_ver |
версия каталога цепочки, на которой собрана минута |
settle, price_ccy, volume_usd_ccy, volume_notional_ccy |
как у каталога — выше, по текущему каталогу источника, а не каталогу той минуты |
bid, ask, mark |
котировки и mark инструмента |
iv_bp |
подразумеваемая волатильность, 0,01 пункта |
volume, volume_usd_e8, volume_notional_usd_e8 |
объём за 24 ч: в контрактах и в деньгах, валюта и смысл денег — по площадке и цепочке в таблице выше |
forward, index |
форвард и индекс |
bid_size, ask_size |
объёмы лучших котировок, в контрактах |
Следующий ответ того же адреса — уже новая минута, поэтому chain/latest не кэшируется. Цепочки без минуты — в missing (неполная минута).
Цепочка минуты
/v1/options/chainЦепочки базы в минуту, закрытую в at или раньше; поля — как у chain/latest. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
chain |
одна цепочка базы; без параметра — все |
at |
обязательный: момент, Unix-мс UTC или ISO-8601. Ответ — минута, закрытая в at или раньше. Глубина тарифа меряется по началу этой минуты |
Какая минута придёт. Шлюз берёт новейшую минуту, которая к at уже закрыта: её начало T = ⌊(at − 60 000) / 60 000⌋ · 60 000, она идёт от T до T + 60 000. at=1795110000000 (17:40:00 UTC) и at=1795110030000 (17:40:30) дают одну и ту же минуту 17:39–17:40 с ts_min: 1795109940000: минута 17:40–17:41 к 17:40:30 ещё не закрыта. Время в секундах или микросекундах — 400 bad_request с param: "at".
curl -s "https://market-api.lootx.trade/v1/options/chain?base=BTC&chain=BTC&at=2026-11-19T17:40:00Z" \
-H "Authorization: Bearer $LOOTX_API_KEY"Минуты нет ни у одной цепочки базы или у присланной chain — 404 not_found; минута, которую не восстановить из кадров источника, — тоже 404 not_found, со словом gap в message. Где дыры, говорит покрытие.
Неполная минута
Минута бывает не у всех цепочек базы. Тогда ответ 200, а цепочки без минуты перечислены в missing тела и в заголовке x-options-missing:
| Где | Что |
|---|---|
missing[] |
chain, reason, detail: no_frame — кадра нет, это дыра сбора; gap — минута не восстанавливается |
заголовке x-options-missing |
те же цепочки строкой ЦЕПОЧКА:причина через запятую: BTC_USDC:no_frame. Приходит в любом формате, у OPC1 это единственное место, где о них сказано |
detail — пояснение источника по-английски, для человека, а не для разбора. Так выглядит missing ответа /v1/options/chain за минуту, у которой нет кадра BTC_USDC:
[
{"chain": "BTC_USDC", "reason": "no_frame", "detail": "minute 1795137660000: no frame (a hole: see /v1/options/coverage)"}
]У chain/latest detail другой: no frame yet — у цепочки ещё нет ни одной минуты, newest minute <мс> cannot be rebuilt (…) — новейшая минута не собирается (gap). Поля missing нет — на месте все цепочки. Неполная минута не бывает неизменной: Cache-Control: private, no-cache, и кэш шлюза её не держит — повторите позже, когда источник дособерёт.
История цепочки
/v1/options/chain/rangeИстория одной цепочки за [from, to) — до 360 минут: JSON и protobuf — ряд одного инструмента по минутам, format=opc1 — кадры всей цепочки по минутам. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
chain |
обязательный: одна цепочка базы, как у каталога. Диапазон — всегда одной цепочки |
from |
обязательный: начало, Unix-мс UTC или ISO-8601, целая минута. Глубина тарифа меряется по нему |
to |
обязательный: конец, в диапазон не входит; целая минута, from < to, не больше 360 минут после from — иначе 400 bad_request с param: "to" |
instrument |
инструмент цепочки — BTC-21NOV26-62500-C: A-Z, a-z, 0-9, -, _, ., до 64 знаков. Обязательный у JSON и protobuf: ответ — его ряд. У format=opc1 его нет — кадры всей цепочки; instrument с ним, как и JSON без него, — 400 bad_request с param: "instrument" |
curl -s "https://market-api.lootx.trade/v1/options/chain/range?base=BTC&chain=BTC&instrument=BTC-21NOV26-62500-C&from=2026-11-20T13:00:00Z&to=2026-11-20T13:03:00Z" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chain": "BTC",
"instrument": "BTC-21NOV26-62500-C",
"from": 1795179600000,
"to": 1795179780000,
"rows": [
{"ts_min": 1795179600000, "snap_ts": 1795179664261, "oi_asof_ms": 1795150864261, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0043", "ask": "0.0046", "mark": "0.00439472", "iv_bp": 5718, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61488.53", "index": "61517.02", "bid_size": null, "ask_size": null},
{"ts_min": 1795179660000, "snap_ts": 1795179720021, "oi_asof_ms": 1795150920021, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0046", "ask": "0.0049", "mark": "0.00475026", "iv_bp": 5719, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61555.04", "index": "61575.39", "bid_size": null, "ask_size": null},
{"ts_min": 1795179720000, "snap_ts": 1795179784781, "oi_asof_ms": 1795150984781, "catalog_ver": 13, "expiry_ms": 1795248000000, "strike": "62500", "type": "call", "instrument": "BTC-21NOV26-62500-C", "bid": "0.0045", "ask": "0.0048", "mark": "0.00469664", "iv_bp": 5720, "oi_asof": "64.7", "volume": "151.5", "volume_usd_e8": "6985576000000", "volume_notional_usd_e8": null, "forward": "61543.46", "index": "61565.5", "bid_size": null, "ask_size": null}
]
}Пример — живой ответ за три минуты. Строка минуты — шапка минуты /v1/options/chain (ts_min, snap_ts, oi_asof_ms, catalog_ver) и строка инструмента той минуты — поле в поле, как у /v1/options/chain?at= этой минуты. До листинга инструмента строк нет — это не пропуск.
| Поле | Что |
|---|---|
from, to |
диапазон запроса, мс; to не входит |
rows[] |
минуты, где инструмент есть, по порядку |
missing[] |
минуты, которых нет у цепочки: from_ms, to_ms (не входит), reason — no_frame (минута осела, кадра нет) или gap (кадр не связывается с отданным перед ним); соседние минуты одной причины — одним интервалом. Поля нет — на месте все. Минуты, ещё не закрытые к запросу (диапазон в настоящее), — не пропуск |
Вес запроса — час диапазона. Диапазон до 60 минут — 1 единица лимитов, 61–120 — 2, …, 301–360 — 6: столько запросов он списывает из ведра минуты и окон часа и суток (лимиты). Повтор из кэша шлюза (X-Cache: HIT) и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет chain, from или to, не целые минуты, from ≥ to, больше 360 минут — стоит 1; Глубже тарифа, CSV, JSON без instrument и format=opc1 с ним отказывают уже после списания полного веса.
Длинную историю читайте подряд диапазонами по 6 часов: to одного — from следующего. Кадры OPC1 (format=opc1) — вся цепочка за минуту, а ряд JSON — один инструмент: для всей цепочки берите кадры.
x-options-missing — одно имя, два синтаксиса. У /v1/options/chain и /v1/options/chain/latest — цепочки базы без минуты: ЦЕПОЧКА:причина через запятую (BTC_USDC:no_frame). У /v1/options/chain/range — интервалы минут без кадра: FROM_MS-TO_MS:причина через запятую, Unix-мс UTC, [FROM_MS, TO_MS), например 1795148100000-1795148220000:no_frame; заголовок не длиннее 1 КиБ, интервалы, которые не уместились, — последним элементом +N, полный список — в missing JSON. Разбирайте заголовок по маршруту, а не по виду строки. У кадров OPC1 о пропусках больше нигде не сказано.
Покрытие
/v1/options/coverageЦепочки базы — новейшая минута, отставание и минута, которую не собрать, — и дыры сбора окна. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
from |
начало окна дыр, Unix-мс UTC или ISO-8601. По умолчанию — сутки до «сейчас». Глубина тарифа меряется по нему |
to |
конец окна; по умолчанию — сейчас. Нужно from < to, окно — до 31 суток, иначе 400 upstream_rejected с param: "from" |
curl -s "https://market-api.lootx.trade/v1/options/coverage?base=BTC&from=2026-11-20T03:00:00Z&to=2026-11-20T05:00:00Z" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"base": "BTC",
"chains": [
{"chain": "BTC", "lag_ms": 15018, "last_ts_min": 1795181520000},
{"chain": "BTC_USDC", "lag_ms": 15018, "last_ts_min": 1795181520000}
],
"from": 1795143600000,
"gaps": [
{"chain": "BTC", "from_ms": 1795148109131, "reason": "disconnect", "source": "btc_usd", "stream": "live", "to_ms": 1795148109353}
],
"to": 1795150800000,
"venue": "deribit"
}Пример — живой ответ: 20.11 в 04:15:09 UTC поток Deribit оборвался на 0,2 секунды (disconnect). Дыра записана под индексом btc_usd — он в source, а chain — цепочка, чья книга идёт по этому индексу. chains — состояние на «сейчас», окно from–to к нему не относится.
| Поле | Что |
|---|---|
last_ts_min |
новейшая минута цепочки у источника, мс; null — минуты ещё нет |
lag_ms |
насколько она отстала от «сейчас», мс |
unbuilt |
новее хранится минута, которую не собрать: ts_min, reason и detail — как у missing, например "reason": "gap", "detail": "cannot be rebuilt (reference: no key frame)"; поля нет — такой нет |
gaps[] |
дыры сбора окна: chain, source, stream, from_ms, to_ms, reason |
chain дыры |
цепочка (книга), к которой относится дыра. null — записанное имя не удалось сопоставить ни одной цепочке: единица опроса (*, ALL и подобные) или индекс, которого нет в каталоге; имя — в source, и такая дыра приходит в ответе каждой базы площадки |
source |
записанное имя, когда дыра записана не под своей цепочкой: индекс (btc_usd), базовый актив OKX (BTC-USD) или единица опроса. Поля нет — дыра записана под самой цепочкой |
stream |
что прервалось: chain — минута цепочки не записана; oi, quotes — у Binance и OKX минута записана без OI (у Binance — иногда без OI только части экспираций) или без тикера: эта часть снимка не получена в окне минуты; live — поток Deribit, имя индекса — в source; catalog — каталога площадки нет, минута потеряна |
reason |
почему: ошибка запроса к площадке — transport, rate_limited, http_status, rpc_error, decode; window_passed — окно минуты прошло, snapshot_time — снимок не из окна минуты; у chain ещё restart и leader_change — сборщик перезапущен или лидерство перешло к другому узлу, missed — минуты без учёта до следующей дыры или кадра, encode — кадр не собрался; у live — disconnect, silence, subscribe_refused; у catalog — no_catalog или ошибка запроса каталога |
Ряд волатильности книги
/v1/options/vol/book-rangeРяд волатильности одной книги — цепочки базы — по границам часа или суток: ATM IV постоянного срока 7, 30 и 90 суток, крылья 25Δ на 30 суток, RR, BF и индекс. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
chain |
книга базы, как у каталога. Без параметра — книга с именем базы, а если её нет и книга у базы одна — она; иначе 404. Присылайте всегда: без неё ряд зависит от того, какие книги листингуются сейчас |
from |
обязательный: начало [from, to), Unix-мс UTC или ISO-8601; первая точка — первая граница шага не раньше него. Глубина тарифа — по нему |
to |
обязательный: конец, не входит; from < to, при step=1h — не больше 90 суток, при step=1d — не больше 365 суток |
step |
обязательный: 1h — границы часов, 1d — полночь UTC |
curl -s "https://market-api.lootx.trade/v1/options/vol/book-range?base=BTC&venue=deribit&chain=BTC&from=1795089600000&to=1795100400000&step=1h" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chain": "BTC",
"step": "1h",
"from": 1795089600000,
"to": 1795100400000,
"asof_ms": 1795096800000,
"coverage": {
"complete": false,
"gaps": [{"from_ms": 1795093200000, "to_ms": 1795093260000, "chain": "BTC", "stream": "chain", "reason": "no_frame"}]
},
"rows": [
{"ts_ms": 1795089600000, "index": "62480.15", "atm_iv_bp": {"d7": 4810, "d30": 5120, "d90": null}, "put25_iv_bp_30d": 5390, "call25_iv_bp_30d": 4980, "rr25_bp_30d": -410, "bf25_bp_30d": 65},
{"ts_ms": 1795096800000, "index": "62511.40", "atm_iv_bp": {"d7": null, "d30": 5105, "d90": null}, "put25_iv_bp_30d": null, "call25_iv_bp_30d": null, "rr25_bp_30d": null, "bf25_bp_30d": null}
]
}Пример — три часа шагом 1h: точка второго часа — дыра, у последней точки нет срока 7 суток и крыльев.
| Поле | Что |
|---|---|
venue, base, chain, step, from, to |
запрос, как его понял источник: chain — выбранная книга |
asof_ms |
ts_ms последней строки; строк нет — null |
rows[].ts_ms |
точка — минута, которая начинается ровно на границе шага: границы — кратные шага от 1970 года, сутки — по UTC |
rows[].index |
индекс минуты точной десятичной строкой; null — индекса нет (OKX его не шлёт) |
atm_iv_bp |
ATM IV постоянного срока: d7, d30, d90 — по полной дисперсии между экспирациями вокруг срока, по mark; срок раньше первой экспирации или позже последней — null, а не IV ближайшей |
put25_iv_bp_30d, call25_iv_bp_30d |
IV пута и колла с дельтой 25 % на сроке 30 суток; дельта — Black-76 по форварду |
rr25_bp_30d |
risk reversal: колл − пут |
bf25_bp_30d |
butterfly: (колл + пут) / 2 − ATM 30 суток |
coverage.complete |
true — ни одной дыры |
coverage.gaps[] |
дыры: точки подряд без строки с одной причиной — [from_ms, to_ms), to_ms — конец минуты последней точки; stream — chain; reason — no_frame (кадра нет), gap (кадр не восстанавливается), replay_limit (за один запрос не дошли — повторите запрос, точки догрузятся) |
IV, RR и BF — целым, в 0,01 пункта волатильности: 5120 — 51,2 %. Любое число строки бывает null — расчёту не хватило экспираций или котировок; дыра — это нет строки, а не строка из null. Границы после новейшей минуты книги ещё не настали — это не дыра: таких строк просто нет.
Вес ряда — границы шага на 64: число границ шага в [from, to) делится на 64 и округляется вверх, — от 1 до 34 единиц лимитов: сутки часами — 1, 90 суток часами — 34, год сутками — 6. Повтор из кэша шлюза и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет step, from или to, from ≥ to, окно длиннее предела — стоит 1; глубже тарифа (403 history_out_of_plan) и CSV (400 bad_format) отказывают уже после списания полного веса.
Экспозиция
/v1/options/exposure/latestGEX, DEX, VEX и CEX новейшей минуты одной книги — или всех книг базы разом — по страйкам группы экспираций: итоги группы, страйки и профиль net GEX по сетке цен. Знак дилера — naive. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога, или all — все книги базы на всех площадках (ниже); по умолчанию deribit |
chain |
книга базы, как у ряда волатильности: без параметра — книга с именем базы, а если её нет и книга у базы одна — она; иначе 404. С venue=all — 400 bad_request (param: "chain"): книги берутся все |
expiry |
группа экспираций от метки снимка: 0dte — поставка до конца текущих суток UTC, 1d, 7d, 31d, 91d — не позже снимка + N суток, all — все; по умолчанию all. Иная — 400 bad_request |
mode |
знак дилера: только naive — коллы плюсом, путы минусом; по умолчанию naive. Иной — 400 bad_request |
curl -s "https://market-api.lootx.trade/v1/options/exposure/latest?base=BTC&venue=deribit&chain=BTC&expiry=7d" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chain": "BTC",
"expiry": "7d",
"mode": "naive",
"asof_ms": 1795096800000,
"coverage": {"complete": true, "gaps": []},
"usd_ccy": "USD",
"spot": "62511.40",
"expiries_ms": [1795161600000, 1795507200000],
"totals": {"gex_usd_e8": "-4260000000000000", "dex_usd_e8": "18240000000000000", "vex_usd_e8": "-81200000000000", "cex_usd_e8": "-2735000000000"},
"strikes": [
{"strike": "62000", "gex_call_usd_e8": "1520000000000000", "gex_put_usd_e8": "-2810000000000000", "dex_usd_e8": "-4120000000000000", "vex_usd_e8": "-31500000000000", "cex_usd_e8": "1240000000000", "oi_call_coins": "1204.5", "oi_put_coins": "2310.1"},
{"strike": "65000", "gex_call_usd_e8": "980000000000000", "gex_put_usd_e8": "-120000000000000", "dex_usd_e8": "8730000000000000", "vex_usd_e8": "26400000000000", "cex_usd_e8": "-950000000000", "oi_call_coins": "3150", "oi_put_coins": "212.4"}
],
"profile": [
{"price": "53134.69", "gex_usd_e8": "3905000000000000"},
{"price": "53290.97", "gex_usd_e8": "3871000000000000"},
{"price": "71888.11", "gex_usd_e8": "-1532000000000000"}
]
}Пример сокращён: страйков — два, точек профиля — три из 121.
| Поле | Что |
|---|---|
venue, base, chain, expiry, mode |
запрос, как его понял источник: chain — выбранная книга, у venue=all — null |
asof_ms |
минута расчёта; минуты нет — null |
usd_ccy |
валюта всех *_usd_e8 ответа — котировка книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; у venue=all — валюта опорной книги (ниже) |
spot |
индекс точной десятичной строкой; у книги без индекса (OKX его не шлёт) — null, а профиль пуст |
expiries_ms |
экспирации группы, Unix-мс UTC |
totals |
итоги группы: gex_usd_e8 — net GEX, dex_usd_e8, vex_usd_e8, cex_usd_e8 — целым e8 строкой; книга без минуты, без расчёта или с переполнением — null |
strikes[] |
страйк группы: strike — десятичной строкой в шкале страйка; gex_call_usd_e8 и gex_put_usd_e8 — GEX коллов и путов, dex_usd_e8, vex_usd_e8, cex_usd_e8 — целым e8 строкой; oi_call_coins и oi_put_coins — OI коллов и путов в монетах базы десятичной строкой; у venue=all ещё venue_share |
profile[] |
net GEX группы, если бы цена была price: 121 точка, ±15 % от spot шагом 0,25 %; price — spot × (1 + x) в шкале цены |
coverage |
complete — ни одной дыры; gaps[] — {from_ms, to_ms, chain, stream: "chain", reason}: no_frame — у книги нет минуты, no_calc — расчёта нет, money_overflow — не уместилось в e8, иначе — причина сборки минуты |
Экспозиция — в деньгах котировки книги. D — позиция дилера в монетах по знаку naive (коллы плюсом, путы минусом), F — форвард строки. GEX = Γ × D × F² × 0,01 — хедж на ход цены в 1 %; DEX = Δ × D × F — дельта; VEX = vanna × D × F × 0,01 — сдвиг дельты на +1 пункт IV; CEX = charm × D × F / 365 — сдвиг дельты за сутки. Все *_usd_e8 — целым e8 строкой со знаком, кроме gex_call_usd_e8, в валюте usd_ccy: USDT — не USD, ответы книг разных котировок без перевода курсом не складывайте.
null и пусто — «нет данных», а не 0. Книга без минуты, без расчёта или с переполнением отвечает 200: totals: null, пустые strikes и profile и дыра в coverage.gaps. Группа 0dte с 08:00 до полуночи UTC пуста: expiries_ms: [], итоги — нули, strikes пуст.
Все площадки
venue=all — все книги базы на всех площадках разом: каждая книга переводится к индексу опорной — первой книги с индексом в порядке deribit, binance, bybit, okx, внутри площадки первой идёт книга с именем базы. Минута ответа — новейшая общая: пока последняя площадка не дописала новую минуту, приходит предыдущая у всех книг, а не часть книг.
У страйка — venue_share: доля каждой площадки в |net GEX| страйка по модулю, {deribit, binance, bybit, okx}, вместе — 1, четыре знака; площадка без вклада — 0, у страйка с нулевым GEX все доли — null.
Дыры книг у venue=all называют площадку: no_frame:okx, no_calc:binance, other_minute:deribit — книги нет в минуте ответа, no_index:okx — книга без индекса в ответ не входит. Дыры ответа целиком — без площадки, chain — база: no_index — ни одного индекса, sum_refused: …, money_overflow.
Ответ живой: Cache-Control: private, no-cache и ETag; пришлите метку в If-None-Match — та же минута придёт 304. Кэш шлюза его не держит. Вес экспозиции — 1 единица: окна и глубины тарифа у неё нет.
История уровней
/v1/options/levels/rangeИстория уровней одной книги по границам шага: индекс, форвард, zero gamma, стены коллов и путов, abs gamma, net GEX, max pain и ожидаемый ход ближайшей поставки группы. Знак дилера — naive. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit. all — 400 bad_request: уровни — одной книги, ряда по всем площадкам пока нет |
chain |
книга базы, как у ряда волатильности. Присылайте всегда: без неё ряд зависит от того, какие книги листингуются сейчас |
expiry |
группа экспираций, как у экспозиции; по умолчанию all |
mode |
только naive, как у экспозиции |
from |
обязательный: начало [from, to), Unix-мс UTC или ISO-8601; первая точка — первая граница шага не раньше него. Глубина тарифа — по нему |
to |
обязательный: конец, не входит; from < to, при step=1m — не больше 7 суток, при step=5m — не больше 30 суток, при step=1h — не больше 90 суток (ровно предел проходит) |
step |
обязательный: 1m, 5m или 1h — границы, кратные шагу от 1970 года |
curl -s "https://market-api.lootx.trade/v1/options/levels/range?base=BTC&venue=deribit&chain=BTC&from=1795089600000&to=1795100400000&step=1h" \
-H "Authorization: Bearer $LOOTX_API_KEY"{
"venue": "deribit",
"base": "BTC",
"chain": "BTC",
"expiry": "all",
"mode": "naive",
"step": "1h",
"from": 1795089600000,
"to": 1795100400000,
"asof_ms": 1795096800000,
"coverage": {
"complete": false,
"gaps": [{"from_ms": 1795093200000, "to_ms": 1795093260000, "chain": "BTC", "stream": "calc", "reason": "no_calc"}]
},
"usd_ccy": "USD",
"rows": [
{"ts_ms": 1795089600000, "spot": "62480.15", "fwd": "62528.7", "zero_gamma": "61850.3", "zero_gamma_sticky_delta": null, "unstable": false, "call_walls": ["65000", "70000"], "put_walls": ["60000", "58000"], "abs_gamma": "60000", "net_gex_usd_e8": "-4115000000000000", "max_pain": "62000", "max_pain_expiry_ms": 1795161600000, "move_straddle_bp": 121, "move_sigma_bp": 152},
{"ts_ms": 1795096800000, "spot": "62511.40", "fwd": "62560.1", "zero_gamma": null, "zero_gamma_sticky_delta": null, "unstable": false, "call_walls": ["65000", "70000"], "put_walls": ["60000", "55000"], "abs_gamma": "60000", "net_gex_usd_e8": "-4260000000000000", "max_pain": "62000", "max_pain_expiry_ms": 1795161600000, "move_straddle_bp": 118, "move_sigma_bp": 148}
]
}Пример — три часа шагом 1h: у точки второго часа нет строки расчёта, у последней точки профиль не меняет знак.
| Поле | Что |
|---|---|
venue, base, chain, expiry, mode, step, from, to |
запрос, как его понял источник: chain — выбранная книга |
asof_ms |
ts_ms последней строки; строк нет — null |
usd_ccy |
валюта net_gex_usd_e8 — котировка книги: у inverse — USD, у linear — price_ccy: USD — у OKX *_UM, USDT — у Binance и Bybit, USDC — у Deribit *_USDC; строк нет — null |
rows[].ts_ms |
точка — минута, которая начинается ровно на границе шага |
spot, fwd |
индекс и форвард ближайшей поставки группы точной десятичной строкой |
zero_gamma |
цена, где профиль net GEX меняет знак; смены знака на сетке нет — null |
zero_gamma_sticky_delta, unstable |
второй режим волатильности — пока всегда null и false |
call_walls, put_walls |
две стены: страйки с наибольшим GEX коллов выше индекса и путов ниже, главная первой; стены — null или [null, null] у книги без индекса |
abs_gamma |
страйк с наибольшей суммой модулей GEX коллов и путов |
net_gex_usd_e8 |
net GEX группы в валюте usd_ccy — целым e8 строкой со знаком; нет экспирации в группе (у 0dte — с 08:00 до полуночи UTC) — "0" |
max_pain, max_pain_expiry_ms |
max pain ближайшей поставки группы и её срок; нет экспирации в группе — null |
move_straddle_bp, move_sigma_bp |
ожидаемый ход ближайшей поставки группы с ATM IV, в базисных пунктах от форварда: модельный ATMF-страддл и σ√T, T — до поставки от снимка |
coverage.complete |
true — ни одной дыры |
coverage.gaps[] |
дыры: точки подряд без строки с одной причиной — [from_ms, to_ms), to_ms — конец минуты последней точки; stream — calc; reason — no_calc (граница не позже новейшей минуты книги, а строки расчёта нет), no_frame (у книги нет ни одной минуты) |
Цены и страйки — точной десятичной строкой в шкале инструмента, null — «нет данных», а не 0: дыра — это нет строки, а не строка из null. Границы после новейшей минуты книги ещё не настали — это не дыра: таких строк просто нет. Дыру с осевшими границами источник держит до 10 минут: дозалитая строка появится не позже чем через 10 минут.
Вес истории уровней — точки шага на 1440: число границ шага в [from, to) делится на 1440 и округляется вверх, — от 1 до 7 единиц лимитов: сутки минутами — 1, 7 суток минутами — 7, 30 суток по 5 минут — 6, 90 суток часами — 2. Повтор из кэша шлюза и 304 стоят столько же. Отказ формы запроса — чужой или повторённый параметр, нет step, from или to, from ≥ to, окно длиннее предела, venue=all, иные expiry или mode — стоит 1; глубже тарифа (403 history_out_of_plan) и CSV (400 bad_format) отказывают уже после списания полного веса.
Живой поток
/v1/options/streamWebSocket кадров цепочек базы: сначала текст hello, затем кадры OPC1 — по одному на сообщение. Группа тарифа — options.
| Параметр | Что |
|---|---|
base |
обязательный, как у каталога |
venue |
площадка, как у каталога; по умолчанию deribit |
chain |
цепочки базы через запятую, до 64 цепочек; каждая — A-Z, 0-9, _, до 32 знаков. Без параметра — все цепочки базы на момент соединения; набор держится всё соединение, новая цепочка — только в новом соединении |
resume |
продолжение после обрыва: <epoch>:<цепочка>:<seq> через запятую, по одному на цепочку — ниже |
Адрес — wss://market-api.lootx.trade/v1/options/stream, отдельный от /v1/ws. Ключ — как у /v1/ws: заголовком или подпротоколом ["lx.v1", "key.<ключ>"] (подключение). Команд у потока нет: сообщения клиента читаются и отбрасываются.
const ws = new WebSocket("wss://market-api.lootx.trade/v1/options/stream?base=BTC", ["lx.v1", `key.${apiKey}`]);
ws.binaryType = "arraybuffer";Первое сообщение — текст JSON hello:
{"type": "hello", "epoch": "3f9c0a1b2c3d4e5f", "venue": "deribit", "base": "BTC", "chains": [{"chain": "BTC", "seq": 41, "live": true}, {"chain": "BTC_USDC", "seq": 7, "live": false}]}Поле hello |
Что |
|---|---|
epoch |
процесс источника, 16 hex: другой процесс — другая эпоха |
chains[].seq |
кадр, на котором цепочка стоит: с него начнётся её поток; 0 — кадров ещё не было, первый придёт ключевым |
chains[].live |
у цепочки есть живой канал: кроме кадров минуты идут живые кадры |
Кадры — по одному на бинарное сообщение, без uvarint-длины: раскладка та же, формат предварительный — байт 4 кадра сверяйте. По каждой цепочке сначала ключевой кадр на hello.seq (с resume — пропущенные кадры), затем каждый новый по порядку:
- кадр минуты — новейшая минута цепочки, та же, что у
/v1/options/chain/latest: дельта к кадру перед ней, когда строки и шкалы те же, иначе ключевой — листинг, новая строка; - живой кадр — только у цепочек с
live: true: дельта, в которой меняются толькоmarkиiv_bpстрок, не чаще раза в секунду на цепочку;ts_min,catalog_verи прочие поля — от минуты.
seq заголовка кадра — счёт потока, а не минуты: u32 на цепочку, +1 на кадр. Дельта ссылается на кадр перед ней (ref_ts_min, ref_snap_ts). Сверяйте, что seq — прошлый + 1 и звено дельты совпало; разрыв — переподключитесь с resume. Источник пингует раз в 20 с.
Продолжение потока
resume — epoch из hello и seq последнего принятого кадра каждой цепочки, элементы — через запятую: resume=3f9c0a1b2c3d4e5f:BTC:41. Тот же процесс и seq ещё в его памяти — придут ровно пропущенные кадры; новая эпоха, seq, которого уже нет в памяти, или seq из будущего — ключевой кадр. В новом hello seq — кадр, на котором вы теперь стоите.
Отказы — до апгрейда, обычным HTTP-ответом с телом ошибки, как у REST, а не 101 и закрытием: 400 bad_request — параметр не той формы, больше 64 цепочек, format или table; 400 upstream_rejected — bad_resume → resume, bad_chain → chain; 404 not_found — нет присланной цепочки или у базы нет ни одной; 429 ws_limit — заняты все ws_conns тарифа; 503 upstream_unavailable с Retry-After — источник загружает цепочки после запуска или держит предельное число соединений потока.
Отметка «поток выключен» на узле — выкладка, а не окончательный отказ: приходит 503 upstream_unavailable с Retry-After: 30.
| Код закрытия | Причина | Что делать |
|---|---|---|
4008 |
slow consumer |
клиент не успевал читать: очередь 64 кадра или отправка дольше 5 с. Переподключитесь с resume |
1011 |
hello |
источник не собрал hello. Переподключитесь |
1001 |
— | источник останавливается. Переподключитесь с resume: у нового процесса другая эпоха — придёт ключевой кадр |
1013 |
upstream_unavailable |
источник оборвал соединение. Переподключитесь с паузой и resume |
1008 |
daily_quota_exceeded, revoked_key, plan_inactive, invalid_key, insufficient_scope, route_not_in_plan |
кончился суточный объём или доступ — как у /v1/ws, но кадра error перед закрытием нет: код — только в причине |
Учёт. Соединение — один запрос группы options и одно место из ws_conns тарифа на всё время соединения. Байты hello и кадров идут в суточный объём аккаунта и группы options; пинги — нет.
Форматы
- JSON (по умолчанию) — тело источника байт в байт.
- protobuf — общий конверт
lootx.v1.Response(форматы): поля верхнего уровня — вmeta, вложенное (цепочки, строки, экспирации, дыры) — JSON-текстом. - CSV нет: ответы — вложенные объекты, таблицей их не разложить.
format=csvиAccept: text/csv—400 bad_format, вmessage— форматы маршрута. format=opc1— только у/v1/options/chain,/v1/options/chain/latestи/v1/options/chain/range: кадры OPC1 источника насквозь,application/octet-stream. У баз, каталога, экспираций, покрытия, ряда волатильности, экспозиции и истории уровней —400 bad_format. По заголовку кадры не выбираются:Accept: application/octet-streamбез параметра —406 not_acceptable.
JSON и protobuf — стабильные формы ответа: они меняются только вместе с версией API. Поток /v1/options/stream — не ответ, а WebSocket: hello текстом JSON и кадры OPC1 (живой поток); format у него нет.
Чего нет в ответе OPC1, сказано только в заголовке x-options-missing (два синтаксиса). Ошибки приходят JSON и при format=opc1: сначала проверьте код ответа. Как устроен ответ кадрами, коротко сказано и в спецификации — ответ application/octet-stream этих трёх маршрутов в /v1/openapi.json.
Раскладка кадров OPC1
Тело минуты (chain, chain/latest) — на каждую цепочку минуты uvarint-длина и один ключевой кадр, встык до конца тела; дельт в нём нет. Тело диапазона (chain/range) — кадры одной цепочки по минутам, у каждого uvarint-длина, встык до конца тела: первый — ключевой, следующие — как их хранит источник, ключевой кадр часа или дельта к кадру перед ней, версии 1 и 2 вперемешку. Проигрывайте их по порядку и сверяйте звено каждой дельты (ref_ts_min, ref_snap_ts) с кадром перед ней: не совпало — цепочка разорвана, не читайте дальше наугад. Шлюз тело не сжимает: DEFLATE уже внутри кадра. Заголовок кадра:
| Байты | Что |
|---|---|
| 0–3 | магия OPC1 |
| 4 | версия раскладки: сейчас пишется 2, бывает и 1. Незнакомую — отвергайте |
| 5 | флаги: бит 0 — тело сжато сырым DEFLATE. Незнакомые биты — отвергайте |
| 6–7 | длина заголовка, u16 little-endian: с этого байта начинается тело |
| 8 | вид кадра: 0 — ключевой, 1 — дельта (только в теле диапазона). Незнакомый — отвергайте |
| 9 | площадка: 1 — Deribit, 2 — Binance, 3 — Bybit, 4 — OKX |
| дальше | varint-ы: цепочка (uvarint-длина и ASCII), catalog_ver, ts_min, snap_ts − ts_min (zigzag), сдвиг OI назад от snap_ts в мс, номер кадра, число строк; затем у ключевого — шкалы значений и множитель контракта, у дельты — опорный кадр: ref_ts_min и ref_snap_ts − ref_ts_min (zigzag) |
Значения в теле — целые в шкалах заголовка, деньги — в e8, как *_usd_e8 в JSON. Пределы: кадр — до 8 МиБ и после распаковки, строк — до 16 384, экспираций — до 1 024, имя цепочки — до 32 байт. Раскладка тела меняется вместе с версией: читайте кадр, только если знаете его байт 4.
Кэш и ETag
У каждого ответа 200 есть ETag; одна метка у JSON, protobuf и сжатого тела того же ответа.
- Пришлите метку в
If-None-Match— если ответ не изменился, придёт304без тела с теми жеETag,Cache-Controlиx-options-missing: запрос засчитывается, а в суточный объём не идёт. Сравнение слабое:W/"…", список меток и*тоже подходят. - Неизменны —
Cache-Control: private, max-age=31536000, immutable— четыре ответа:/v1/options/chainза целую осевшую минуту (все цепочки базы на месте, у каждой строки есть имя инструмента, после закрытия прошло 2 минуты),/v1/options/chain/rangeза целый осевший диапазон (ни одной минуты без кадра, послеtoпрошло 2 минуты)/v1/options/vol/book-rangeза целый осевший ряд (ни одной дыры, у книги есть расчёт, после минуты последней границы прошло 2 минуты) и/v1/options/levels/rangeза целый осевший ряд (строка у каждой границы, последняя граница осела). Повтор шлюз отдаёт из своего кэша (X-Cache: HIT). - Свежая или неполная минута
chain, диапазонchain/rangeв настоящее или с пропусками, рядvol/book-rangeилиlevels/rangeс неосевшей границей или с дырами,chain/latest,exposure/latest,bases,catalog,expiriesиcoverage—private, no-cache: кэшируйте с меткой и спрашивайте сIf-None-Match.
curl -s -o /dev/null -w "%{http_code}\n" "https://market-api.lootx.trade/v1/options/chain/latest?base=BTC" \
-H "Authorization: Bearer $LOOTX_API_KEY" -H 'If-None-Match: "f42b9c0e7d1a3b55"'Глубина истории
Глубину проверяет тариф — history_days: меньший из общего и группового (группы options), если у группы свой. Меряется не у всех маршрутов:
/v1/options/chain— по минуте ответа. Меряется начало минуты, закрытой вat. Глубже тарифа —403 history_out_of_planсparam: "at";earliest_allowed_msв отказе — первыйat, который пройдёт./v1/options/chain/range— поfrom. Глубже тарифа —403 history_out_of_planсparam: "from".earliest_allowed_msв этом отказе бывает не кратен минуте, аfrom— целая минута: округлите его вверх до минуты./v1/options/coverage— поfrom. Безfrom— по суткам до «сейчас». Глубже тарифа —403 history_out_of_planсparam: "from"./v1/options/vol/book-range— поfrom. Глубже тарифа —403 history_out_of_planсparam: "from", уже после списания полного веса (до 34 единиц)./v1/options/levels/range— поfrom. Глубже тарифа —403 history_out_of_planсparam: "from", уже после списания полного веса (до 7 единиц). Сколько истории есть у книги, говорит покрытие: дыры расчёта в нём не видны — они вcoverage.gapsсамого ряда.bases,catalog,expiries,chain/latest,exposure/latestи поток окна не имеют и глубиной не меряются.
Отказы
Источник отказывает телом {"error", "detail"} — кодом и пояснением. Клиенту оно не приходит как есть: шлюз отвечает своим телом ошибки, код и пояснение источника — в message, параметр — в param.
| Ответ | Когда | Что делать |
|---|---|---|
400 bad_request |
параметр, которого нет у маршрута, или повтор параметра — и в процентной записи имени (b%61se — тоже base); нет base, at, а у chain/range — chain, from или to; base, venue, chain, instrument не той формы; at, from, to не мс и не ISO-8601, в секундах или микросекундах; у chain/range — не целые минуты, from ≥ to, больше 360 минут, JSON или protobuf без instrument, format=opc1 с instrument; у vol/book-range — нет step или он не 1h и не 1d, from ≥ to, больше 90 суток при step=1h или 365 суток при step=1d (param: "to"); у exposure/latest и levels/range — expiry не из групп, mode не naive; у exposure/latest — chain при venue=all; у levels/range — venue=all, нет step или он не 1m, 5m, 1h, from ≥ to, больше 7 суток при step=1m, 30 при 5m, 90 при 1h (param: "to") — до источника. param — его имя |
исправьте запрос по param и expected |
400 bad_format |
format=csv или Accept: text/csv; format=opc1 у баз, каталога, экспираций, покрытия, ряда волатильности, экспозиции или истории уровней; неизвестный format |
message называет форматы маршрута: format=json или protobuf, у цепочек — format=json, protobuf или opc1 |
406 not_acceptable |
в Accept нет ни одного известного шлюзу типа — в том числе Accept: application/octet-stream без параметра. Accept: text/csv — не 406, а 400 bad_format |
Accept: application/json или application/x-protobuf — типы маршрута в expected; кадры OPC1 — только ?format=opc1 |
400 upstream_rejected |
источник отверг значение; param — по его коду: bad_base → base, bad_venue → venue, bad_chain → chain, bad_at → at, bad_format → format, bad_range → from, range_too_long → to, bad_instrument → instrument, bad_resume → resume |
исправьте названный параметр |
403 insufficient_scope |
токен без области derivatives — например, бесплатный токен терминала |
запрашивайте с API-ключом |
403 route_not_in_plan |
тариф закрыл группу options |
смените тариф |
403 history_out_of_plan |
минута at или from глубже тарифа — выше |
at или from не раньше earliest_allowed_ms |
404 not_found |
у chain и chain/latest нет минуты у базы или у присланной chain, либо минута не восстанавливается (gap); у chain/range нет цепочки у базы, инструмента у цепочки или в диапазоне не отдать ни одной минуты (gap — ни одна не восстанавливается); у vol/book-range, exposure/latest и levels/range нет книги у базы — присланной chain или книги по умолчанию, у exposure/latest с venue=all — ни одной книги базы; у потока нет присланной цепочки или у базы нет ни одной |
другая минута или диапазон; дыры — в покрытии |
429 rate_limited и другие 429 |
лимит тарифа; chain/range весит 1–6 единиц — вес запроса, vol/book-range — 1–34 (вес ряда), levels/range — 1–7 (вес истории уровней); у потока ещё 429 ws_limit — заняты все ws_conns |
повторите после Retry-After |
503 upstream_unavailable |
источник загружает цепочки после запуска или склад не читается; у vol/book-range — источник уже собирает предельное число рядов со склада, у levels/range — уже читает предельное число рядов уровней; у потока — предельное число соединений или «поток выключен» (Retry-After: 30). Приходит с Retry-After источника — обычно Retry-After: 1, не дольше 60 с |
повторите через Retry-After |
502 upstream_error |
источник ответил ошибкой или телом не той формы (деньги числом, не кадры на format=opc1), маршрутов опционов у источника нет |
повторите позже; не проходит — напишите в поддержку с request_id |
502 upstream_unavailable, 504 upstream_timeout |
источник недоступен или не ответил вовремя | повторите позже |
Все коды — на странице ошибок.
https://docs.lootx.trade/hy/market-api/options
14Форматы ответа, числа и деньги
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/hy/market-api/formats
15Потоки WebSocket
Одно соединение /v1/ws на несколько каналов — плотности, скринер, сделки, открытый интерес и секундные свечи; подписка по инструментам или на весь рынок с фильтрами, команды, кадры, пределы и коды закрытия.
wss://market-api.lootx.trade/v1/ws — одно соединение на несколько каналов и инструментов — в пределах тарифа и пределов соединения. Кадры — JSON с именами venue:market:SYMBOL и временем в Unix-мс, как у REST; написание имени в кадре может отличаться от вашего.
Поток опционов — отдельный адрес wss://market-api.lootx.trade/v1/options/stream со своим протоколом: текст hello и кадры OPC1, без команд и каналов, группа тарифа — options, а не ws (живой поток). Ключ передаётся так же, как здесь.
Подключение
Ключ — как у REST: Authorization: Bearer <ключ> или X-API-Key. Из браузера заголовок не задать, поэтому ключ передаётся подпротоколом: ["lx.v1", "key.<ключ>"] — сервер выберет lx.v1. В адрес ключ не кладётся.
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);
ws.onopen = () => {
ws.send(JSON.stringify({
op: "subscribe", id: 1, channel: "trades",
instruments: ["binance:perp:BTCUSDT"],
}));
};
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === "update" && m.channel === "trades") {
for (const t of m.data.trades) console.log(m.instrument, t.side, t.price, t.qty);
} else if (m.type === "error") {
console.warn(m.code, m.message);
}
};
ws.onclose = (e) => console.log("закрыто", e.code, e.reason);import asyncio, json, os
import websockets # pip install "websockets>=14"
async def main():
headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
additional_headers=headers) as ws:
await ws.send(json.dumps({"op": "subscribe", "id": 1, "channel": "densities",
"instruments": ["binance:perp:BTCUSDT"]}))
async for raw in ws:
m = json.loads(raw)
if m["type"] == "snapshot":
print("стен:", len(m["data"]["walls"]))
elif m["type"] == "update":
print("+", len(m["data"]["upsert"]), "-", len(m["data"]["remove"]))
asyncio.run(main())Сервер шлёт WS-ping каждые 5 секунд (одновременно с проверкой доступа) — библиотеки отвечают на него сами.
Команды
Текстовые JSON-кадры, не больше 64 КиБ:
{"op":"subscribe","id":1,"channel":"densities","instruments":["binance:perp:BTCUSDT","hyperliquid:perp:BTC"]}
{"op":"unsubscribe","id":2,"channel":"densities","instruments":["binance:perp:BTCUSDT"]}
{"op":"unsubscribe","id":3,"channel":"densities"}
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000}}
{"op":"unsubscribe","id":6,"channel":"densities","scope":"market"}
{"op":"ping","id":4}id— любое число или строка; сервер вернёт его в ответе на команду. На каждую команду сidприходит ответ с этимid, пока соединение открыто:subscribed,unsubscribed,pongилиerror.unsubscribeбез непустого массиваinstrumentsснимает все инструменты канала; рыночную подписку — нет, она снимается соscope: "market".paramsу подписки по инструментам, кромеnullи пустого объекта, даютbad_params. Фильтры есть у подписки на весь рынок.
Кадры сервера
type |
Когда | Поля |
|---|---|---|
subscribed |
подписка принята | id, channel, instruments — имена, под которыми пойдут кадры, с одним исключением |
unsubscribed |
снята | id, channel, instruments |
snapshot |
состояние инструмента целиком | channel, instrument, t, data |
update |
изменение | channel, instrument, t, data |
removed |
инструменты вышли из рыночной подписки | channel, scope, t, instruments |
status |
связь с источником | channel, state, instruments, message |
error |
отказ | id, code, message, instrument |
pong |
ответ на ping |
id |
У рыночной подписки кадры другой формы — см. ниже. По каждому инструменту сначала приходит ровно один snapshot, потом update (у trades снимка нет). snapshot может прийти снова — после обрыва источника: это «замените состояние целиком», а не дубль. После unsubscribed ещё могут дойти кадры, уже стоявшие в очереди.
Обрыв источника соединение не рвёт. Приходит status с state: "reconnecting" и списком задетых инструментов; шлюз сам переподключается к источнику и повторяет подписки, затем state: "live" и свежие снимки. state: "gap" — источник потерял кадры без восстановления (бывает у ленты сделок): дочитайте пропуск через REST.
Каналы
| Канал | snapshot.data |
update.data |
Группа тарифа |
|---|---|---|---|
densities |
{"walls": [стена…]} |
{"upsert": [стена…], "remove": [{"wall_id", "reason", "duration_ms"}]} |
densities |
screener |
метрики {"last_price": …, …} |
изменившиеся метрики; null — значение сброшено |
screener |
trades |
— | {"trades": [{"ts", "price", "qty", "quote_qty", "side", "fills", "aggregated"}]} |
trades |
oi |
бар текущей минуты или null |
бар минуты; незакрытый — с растущим samples |
oi |
candles |
{"candles": [до 600 секундных свечей]} |
{"candles": […]} |
candles_1s |
- Стена — те же поля, что у
/v1/densities:wall_idстрокой,side,price,qty(в монетах),usd(в долларах),dist_bp,first_ts(мс),age_ms,peak_usd,touched,aggи, где есть,size,score.reasonпри удалении —pulled(снята) илиeaten(съедена);null— служебное удаление. - Метрики скринера — длинные имена, как у
/v1/screener. - Сделка:
price(в валюте котировки),qty(в монетах),quote_qty(в валюте котировки, без округления к шагу цены),side— сторона агрессора. - Бар OI:
bucket_ts(мс, начало минуты),samples,native_unit(coins,usdилиcontracts),native_open…native_close,oi_coins_open…oi_coins_close,oi_usd_open…oi_usd_close,price_used_close. Живой поток OI есть у binance, bybit, okx, bingx, kucoin, mexc, bitget, hyperliquid, aster и gate. У kraken и coinbase потока нет: подписка даётunsupported_instrument, история — через REST/v1/oi. У остальных бирж OI в шлюзе нет: и подписка, и REST даютunsupported_instrument. - Свеча:
ts(мс),open,high,low,close,volume(в валюте котировки, у USDT-пар это доллары),trades;trades: 0— пустая секунда, OHLC равны прошлому закрытию. Это неvolumeиз REST: в/v1/candlesколонкаvolume— монеты, а сумма в котировке лежит вquote_volume. Значениеvolumeканала соответствуетquote_volumeREST; объёма в монетах в канале нет.
Канал, группа которого закрыта тарифом, отвечает на подписку error route_not_in_plan; соединение при этом живёт.
Имена в кадрах
Кадры подписки называются не так, как написал клиент, а по имени инструмента на этом канале. Разные написания одного инструмента — одна подписка и одно имя в кадрах. Обычные символы (binance:perp:BTCUSDT, hyperliquid:perp:BTC) это не меняет. Особые случаи:
hyperliquid:perp:kPEPEиhyperliquid:perp:KPEPEидут какhyperliquid:perp:KPEPEна всех каналах, кромеoi. Наoiимя монеты остаётся как у биржи:kPEPEиKPEPE, как иbtcиBTC, — разные подписки под этими же именами.binance:perp:btcusdtна каналахcandlesиdensitiesидёт какbinance:perp:BTCUSDT. Наtradesиoiрегистр не приводится, наscreenerтакое имя получаетunsupported_instrument.- Варианты монеты Hyperliquid
BTCUSDCиBTCUSDTв любом регистре хвоста идут какhyperliquid:perp:BTC. Уscreenerhyperliquid:perp:BTCUSDCчитается по его списку инструментов: монета без акции с таким именем идёт какhyperliquid:perp:BTC, остальное — как акция. - На
screenerдека нет:AAPLUSDC.XYZиAAPLUSDCидут какhyperliquid:perp:AAPLUSDC, кадр один на все деки монеты. - Имя, которое не собирается обратно из имени источника (опечатка, котировка вне списка шлюза), идёт как написал клиент. На
oiу bingxBT-CUSDTиBTCUSDT— разные имена источника, поэтому разные подписки и разные имена кадров.
Имя кадров называет subscribed, с одним исключением: несколько написаний такого имени, которые у источника совпадают, например hyperliquid:perp:AAPLUSDC.XYZUSDC и hyperliquid:perp:aaplusdc.xyzusdc на densities. subscribed отвечает каждому его написанием, а кадры идут под написанием первого подписчика, пока у инструмента есть подписчики. На одном соединении отписка одного написания останавливает кадры обоих, а второе считается подпиской, пока его не снимут или соединение не закроется. Настоящих символов это не касается.
unsubscribe принимает то имя, которым подписывались, а unsubscribed называет имя, под которым шла подписка.
Подписка не сверяет символ
unsupported_instrument в потоке значит, что у источника канала нет такого рынка или биржи, а на oi и screener ещё и что не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает.
- Котировка на
oiпроверяется только у okx, bingx, mexc и kucoin:okx:perp:BTC-USDT-SWAP,kucoin:perp:XBTUSDTM. - Канал
screenerбиржу не сверяет: неизвестная биржа подписку проходит. Он отказывает, если котировку не разобрать, и перпу с котировкой не изUSDT,USDCиUSD; перпов Hyperliquid это не касается.
Опечатка, имя которой шлюз смог перевести, подписку проходит: binance:perp:BTCUSDTT на candles, densities, trades и oi получит subscribed, а дальше в лучшем случае пустой snapshot. Данных не будет, ошибки тоже. Символ проверяют только REST /v1/candles и /v1/series, и не всегда. Молчание подписки не значит, что инструмент существует: имя берите из /v1/instruments.
Весь рынок
Подписка scope: "market" даёт весь рынок канала densities или screener без списка инструментов. Фильтры задаются в params, применяет их источник — тем же кодом, что и для терминала. У других каналов такой подписки нет: bad_params.
{"op":"subscribe","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000,"max_dist_pct":2}}
{"op":"subscribe","id":6,"channel":"screener","scope":"market","params":{"markets":["perp"],"fields":["last_price","volume_24h_usd"],"filters":[{"metric":"volume_24h_usd","op":"gt","value":1000000}]}}
{"op":"unsubscribe","id":7,"channel":"densities","scope":"market"}- Ответ — кадр
subscribedс нормализованнымиparams: что применено на самом деле. Он приходит раньше кадров подписки и не теряется, даже если следующая команда снимает её сразу. subscribedиunsubscribedэтой подписки идут через очередь к клиенту: в порядке команд и вслед за кадрами прежней подписки. Отказыerrorприходят сразу и могут их обогнать: сопоставляйте ответы поid.- В соединении одна рыночная подписка на канал. Повторный
subscribeзаменяет её: прежняя обрывается, после новогоsubscribedкадров старых фильтров нет. Неверная команда прежнюю подписку не трогает. Открывать подписку канала на соединении можно раз в секунду: чаще —rate_limited, прежняя подписка, если она есть, остаётся. unsubscribeсоscope: "market"снимает подписку и отвечаетunsubscribedсоscope, в том числе когда подписки не было.instrumentsв этой команде не читаются. Безscopeрыночная подписка не снимается.- Непустой массив
instrumentsвместе соscope: "market"в командеsubscribe—bad_params. - Рыночная подписка и подписка канала по инструментам друг другу не мешают. Рыночная не считается ни в 200 подписок на соединение, ни в долю
too_many_instruments. - Группа тарифа — та же, что у канала: закрытая группа даёт
route_not_in_plan.
Фильтры densities
| Параметр | Значение |
|---|---|
venues |
биржи массивом, тот же набор, что у /v1/densities. Нет параметра — все |
markets |
массив из spot и perp. Нет параметра — все |
min_usd |
номинал стены от этого значения, в долларах, не меньше 0 |
max_dist_pct |
дальше от середины стакана не идти, в процентах: 2 — это ±2 %. От 0.01 до 100, шаг 0.01: значение округляется до шага, в subscribed.params приходит округлённое. Округлилось в ноль — bad_params |
side |
bid или ask |
min_size |
класс стены не ниже указанного: weak, optimal или strong |
agg |
tick (по умолчанию) или natr |
hide_stables, hide_commodities, hide_stocks, hide_indices |
true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы |
tier1_only |
true — только Tier-1 |
Удержание 10 %. Вход в подписку строгий, выход мягче. Стена, которую источник уже показал этому соединению, остаётся, пока usd не меньше 90 % от min_usd, а расстояние не больше max_dist_pct, делённого на 0,9, в целых базисных пунктах с округлением вверх. При min_usd: 250000 стена снимается ниже 225 000 $, при max_dist_pct: 2 — дальше 223 б.п., то есть 2,23 %. До этого приходят обычные upsert со значениями вне фильтра: не считайте их ошибкой. Остальные фильтры, min_size тоже, удержания не имеют.
Фильтры screener
| Параметр | Значение |
|---|---|
venues |
биржи массивом, тот же набор, что у /v1/screener: Upbit у скринера нет. Нет параметра — все |
markets |
массив из spot и perp. Нет параметра — все |
fields |
какие метрики слать: длинные имена из GET /v1/screener/metrics массивом. Нет параметра — все |
filters |
до 32 условий, выполняться должны все: {"metric":"volume_24h_usd","op":"gt","value":1000000}. op — gt, gte, lt, lte, eq, ne или between (вторая граница — в value2) |
hide_stables, hide_commodities, hide_stocks, hide_indices |
true — скрыть класс актива: стейблкоины и фиат, сырьё, акции, индексы |
tier1_only |
true — только Tier-1 |
Остальные параметры — bad_params с именем параметра в тексте ошибки, в том числе имена из REST (venue, market, coins). Окна и сортировки нет: top_n, sort_by, limit, offset тоже дают bad_params. Окно заморозило бы набор инструментов до следующей подписки, а подписка отдаёт весь отфильтрованный набор живьём: сузьте его через filters и сортируйте у себя.
Кадры рыночной подписки
У всех кадров этой подписки есть scope: "market", а данные лежат в items: [{"instrument", "data"}]. data — те же, что в таблице каналов.
{"type":"subscribed","id":5,"channel":"densities","scope":"market","params":{"venues":["binance"],"markets":["perp"],"min_usd":250000.0,"max_dist_pct":2.0,"agg":"tick"}}
{"type":"snapshot","channel":"densities","scope":"market","t":1793750400000,"part":1,"parts":1,"complete":true,"items":[{"instrument":"binance:perp:BTCUSDT","data":{"walls":[…]}}]}
{"type":"update","channel":"densities","scope":"market","t":1793750401000,"items":[{"instrument":"binance:perp:ETHUSDT","data":{"upsert":[…],"remove":[…]}}]}
{"type":"removed","channel":"screener","scope":"market","t":1793750402000,"instruments":["binance:perp:BTCUSDT"]}
{"type":"unsubscribed","id":7,"channel":"densities","scope":"market"}snapshot— всё состояние. Он идёт частями не длиннее 1 МиБ:partизparts. Первая часть заменяет всё, что было. Стены одного инструмента могут лежать в нескольких элементахitems— сливайте их.complete: false— снимокdensitiesнеполон. Причин четыре: шлюз выбрал предел запросов к источнику; снимок вышел за предел по байтам; срез одной биржи, рынка и стороны упёрся в предел стен, и делить его дальше нечем; источник не ответил. Числа — в пределах. Только в последнем случае за снимком приходит ещёstatusсstate: "gap"иmessage. Дальше идут только изменения, новый снимок — повторной подпиской, а при упоре в предел — с более узкими фильтрами.update— изменения, как в таблице каналов.removed— инструменты вышли из фильтров скринера или символ снят.- Стена вышла из фильтров
densitiesс учётом удержания —removeсreason: nullвupdate.
Обрыв источника подписку не снимает. Приходит status с state: "reconnecting", шлюз сам переподключается, затем state: "live" и новый snapshot — у densities шлюз снимает его заново. status рыночной подписки — со scope: "market" и без instruments.
Пределы рыночной подписки
| Что | Предел | Сверх предела |
|---|---|---|
| Рыночных подписок на аккаунт | ws_market_subs тарифа — все ключи, соединения и каналы вместе. Ноль или нет поля — значение шлюза, одна подписка |
market_subs_limit с limit, remaining: 0, scope: "account", window: "concurrent" |
| Рыночных соединений шлюза | потолок на канал, общий для всех клиентов, по умолчанию 8: на каждую подписку шлюз держит своё соединение с источником | channel_unavailable с channel, scope: "market" и retry_after |
| Открытие подписки канала | на соединении раз в секунду. Считается открытие: и замена, и снятие с повторной подпиской | rate_limited с limit: 1, remaining: 0, scope: "connection", window: "second" и retry_after, прежняя подписка, если она есть, остаётся |
Снимок densities |
100 запросов к источнику, 5000 стен на срез одной биржи, рынка и стороны, потолок шлюза по объёму снимка | complete: false |
Снимков densities одновременно |
на шлюз 4, остальные подписки ждут очереди | снимок приходит позже, изменения за это время копятся |
| Накопленные изменения | шлюз копит их, пока подписка ждёт снимок или клиент забирает очередь; объём ограничен потолком шлюза | за время снимка шлюз заново подключается к источнику, за время записи клиенту — slow_consumer и закрытие 1008 |
| Очередь к клиенту | подписка занимает не больше половины очереди и ждёт, пока клиент заберёт кадры; ответу на команду хватает любого свободного места | slow_consumer и закрытие 1008 |
| Суточный объём | кадры идут в объём тарифа вместе с REST | на исчерпанном объёме новая подписка получает daily_quota_exceeded |
Снимок может быть длиннее очереди: клиент, который читает, получит его весь. slow_consumer приходит, если клиент за 10 секунд не освободил место под кадр подписки, если очередь забита целиком дольше 10 секунд и ответу на команду некуда встать либо если изменения, пришедшие за это время, вышли за потолок шлюза.
Место возвращается отпиской или закрытием соединения. Клиент, вернувшийся раньше, чем шлюз заметил обрыв старого сокета, может получить market_subs_limit: старое место ещё занято. Повторите подписку. channel_unavailable со scope: "market" без retry_after значит, что подписку остановил сбой шлюза: место уже свободно, подпишитесь заново.
Пример
const ws = new WebSocket("wss://market-api.lootx.trade/v1/ws", ["lx.v1", `key.${apiKey}`]);
const walls = new Map(); // инструмент → wall_id → стена
const table = (name) => walls.get(name) ?? walls.set(name, new Map()).get(name);
ws.onopen = () => {
ws.send(JSON.stringify({
op: "subscribe", id: 1, channel: "densities", scope: "market",
params: { venues: ["binance"], markets: ["perp"], min_usd: 250000, max_dist_pct: 2 },
}));
};
ws.onmessage = (e) => {
const m = JSON.parse(e.data);
if (m.type === "error") return console.warn(m.code, m.message);
if (m.scope !== "market") return;
if (m.type === "snapshot") {
if (m.part === 1) walls.clear();
for (const { instrument, data } of m.items) {
for (const w of data.walls) table(instrument).set(w.wall_id, w);
}
if (m.part === m.parts && !m.complete) console.warn("снимок неполон");
} else if (m.type === "update") {
for (const { instrument, data } of m.items) {
for (const w of data.upsert) table(instrument).set(w.wall_id, w);
for (const r of data.remove) table(instrument).delete(r.wall_id);
}
}
};import asyncio, json, os
import websockets # pip install "websockets>=14"
SUBSCRIBE = {
"op": "subscribe", "id": 1, "channel": "screener", "scope": "market",
"params": {
"markets": ["perp"],
"fields": ["last_price", "volume_24h_usd"],
"filters": [{"metric": "volume_24h_usd", "op": "gt", "value": 1000000}],
},
}
async def main():
headers = {"Authorization": f"Bearer {os.environ['LOOTX_API_KEY']}"}
rows = {} # инструмент → метрики
async with websockets.connect("wss://market-api.lootx.trade/v1/ws",
additional_headers=headers) as ws:
await ws.send(json.dumps(SUBSCRIBE))
async for raw in ws:
m = json.loads(raw)
if m["type"] == "error":
print(m["code"], m["message"])
elif m.get("scope") != "market":
continue
elif m["type"] == "snapshot":
if m["part"] == 1:
rows.clear()
for item in m["items"]:
rows[item["instrument"]] = item["data"]
elif m["type"] == "update":
for item in m["items"]:
rows.setdefault(item["instrument"], {}).update(item["data"])
elif m["type"] == "removed":
for name in m["instruments"]:
rows.pop(name, None)
asyncio.run(main())Пределы
| Что | Предел | Сверх предела |
|---|---|---|
| Одновременных соединений | ws_conns тарифа, на аккаунт — все ключи вместе |
429 ws_limit при подключении |
| Подписок на соединение | 200; подписка — пара «канал + инструмент»: binance:perp:BTCUSDT в двух каналах занимает два места |
too_many_subscriptions, команда отвергается целиком |
| Команд от клиента | 10 в секунду, запас 20 | rate_limited, команда пропущена |
| Размер кадра клиента | 64 КиБ | соединение закрывается |
| Очередь кадров к клиенту | 1024 кадра или 32 МиБ | slow_consumer и закрытие 1008 |
| Рыночные подписки | свои пределы | market_subs_limit, channel_unavailable, rate_limited |
Ещё два ответа связаны с общей ёмкостью каналов: соединения шлюза с источниками делятся между всеми клиентами.
channel_unavailableсinstrument— канал сейчас выбрал свой потолок соединений с источником. Повторите подписку позже. Соscope: "market"иretry_afterэто потолок рыночных соединений шлюза.too_many_instrumentsсinstrument— ваш аккаунт уже держит свою долю канала (по умолчанию — половину его ёмкости). Подписка на инструмент, который уже кто-то смотрит, места не занимает; отписка возвращает место.
Коды закрытия
| Код | Причина в reason |
Что делать |
|---|---|---|
1008 |
slow_consumer |
клиент не успевает читать: разбирайте кадры быстрее или подпишитесь на меньшее |
1008 |
daily_quota_exceeded |
кончился суточный объём: перед закрытием приходит кадр error с limit, remaining: 0, window: "bytes_day" и scope. Сброс в 00:00 UTC (подробно) |
1008 |
revoked_key, plan_inactive, invalid_key, insufficient_scope, route_not_in_plan |
доступ кончился посреди соединения: ключ отозван, тариф закончился или в нём больше нет группы ws. Переподключение не поможет, пока не исправлен доступ |
1013 |
ws_limit |
слот соединения потерян: у аккаунта открыто больше соединений, чем разрешает тариф. Закройте лишнее и переподключитесь через 5 с |
Причина закрытия — код ошибки, не длиннее 123 байт. Кадр error перед закрытием несёт те же поля, что тело ошибки REST, — docs_url и детали лимита (подробно).
Доступ перепроверяется каждые 5 секунд; отзыв ключа закрывает поток почти сразу, конец тарифа — не позже чем через два такта. Перед закрытием приходит кадр error с тем же кодом.
Если закрылась только группа одного канала, приходит error route_not_in_plan с channel, подписки этого канала снимаются — и рыночная тоже, — а соединение живёт.
Переподключение
Свой обрыв сети клиент восстанавливает сам: переподключитесь с паузой (0,5 с, затем удваивая до 30 с) и повторите подписки. После subscribed придут свежие snapshot — состояние до обрыва выбрасывайте. Рыночную подписку повторите так же; если придёт market_subs_limit, шлюз мог ещё не заметить обрыв старого сокета: повторите ещё раз с паузой.
В SDK feed() повторяет сам только подписки, ушедшие при подключении и переподключении: на market_subs_limit и rate_limited до 3 раз, с паузой retry_after или 1, 4 и 16 с, затем отдаёт кадр error. Команды живого соединения он не повторяет, а новая рыночная команда канала, новое подключение и закрытие feed() отменяют ожидающий повтор. Пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.
https://docs.lootx.trade/hy/market-api/websocket
16HMP1 և HMP2 ֆորմատներ
Ջերմաքարտեզի երկուական ֆորմատը բայթ առ բայթ՝ վերնագիր, կադրեր, HMP2 ծավալի կոդեր և գների շարքեր՝ Python ապակոդավորիչով։
GET /v1/heatmap?format=hmp1 կամ format=hmp2 վերադարձնում է ջերմաքարտեզը ոչ թե աղյուսակով, այլ երկուական ձևաչափով. այն շատ անգամ ավելի կարճ է, գալիս է հոսքով և քեշավորվում է։ Այն հեշտ է պատկերել. կարելի է վերլուծել կադր առ կադր՝ առանց մարմնի ավարտին սպասելու։ Հարցման պարամետրերը նույնն են, ինչ աղյուսակինը։
format |
Ինչ կա ներսում | Content-Type |
|---|---|---|
hmp1 |
ծավալները ճշգրիտ ամբողջականներ | application/octet-stream |
hmp2 |
ծավալը 6–9 բիթանոց կոդով, ավելի կարճ, քան HMP1-ը; qbits՝ մանտիսի բիթ (6–9, լռելյայն 6), layout՝ 0 կադրեր կամ 1 շարքեր |
application/x-hmp2 |
format=hmp1|hmp2 այլ երթուղիներում՝ 400 bad_format; qbits կամ layout առանց format=hmp2-ի՝ 400 bad_request։ Սխալները գալիս են JSON-ով, ինչպես միշտ։
Քեշ և ծավալ
Վերնագիրը սահմանում է ջերմաքարտեզի աղբյուրը, դարպասը փոխանցում է այն անփոփոխ.
Cache-Control |
Երբ |
|---|---|
no-store |
պատուհանն ավարտվում է վերջին րոպեում՝ կենդանի եզր |
public, max-age=600 |
պատուհանի ավարտը 50 ժամից ոչ հին է. արխիվից վերանորոգումը դեռ կարող է լցնել անցքերը |
public, max-age=86400, immutable |
ավելի հին է |
Փակ միջակայքերն ունեն ETag։ If-None-Match: <ETag>-ով կրկնվող հարցումը ստանում է 304 Not Modified առանց մարմնի. այն օրական ծավալ չի ծախսում։ Ընդհատված ներբեռնումը ծախսում է այնքան բայթ, որքան հասցրել է ստանալ։
Վերնագիր
Little-endian, 48 բայթ.
| Շեղում | Չափ | Դաշտ |
|---|---|---|
| 0 | 4 | magic՝ HMP1 կամ HMP2 |
| 4 | 2 | version՝ 1 HMP1-ում, 2 HMP2-ում |
| 6 | 2 | flags |
| 8 | 8 | bucket_size (i64)՝ բջջի բարձրությունը price_scale միավորներով |
| 16 | 1 | price_scale (u8) |
| 17 | 1 | qty_scale (u8) |
| 18 | 1 | HMP1: 0; HMP2: qty_bits (6–9) |
| 19 | 1 | HMP1: 0; HMP2: layout (0՝ կադրեր, 1՝ շարքեր) |
| 20 | 4 | time_step_ms (u32) |
| 24 | 8 | from_ms (i64) |
| 32 | 8 | to_ms (i64) |
| 40 | 4 | frame_count (u32)՝ ժամանակային սյունակների քանակ |
| 44 | 4 | stream_id (u32), REST-ում 0 |
flags. բիթ 0՝ արժեքները ագրեգացված են առավելագույնով (հակառակ դեպքում՝ միջինով); բիթ 1՝ պատասխանը հասել է աղբյուրի մարմնի առաստաղին (16 ՄԲ) և կտրված է աջից ըստ ժամանակի։ Շարունակությունը՝ նույն հարցումը from = վերջին կադրի ժամանակ + time_step_ms։
Պատասխանը վերլուծեք ըստ վերնագրի (magic, version, layout), ոչ թե ձեր հարցման։
Բջջի գինը և ծավալը.
price = idx * bucket_size / 10^price_scale բջջի ստորին սահմանը [price, price + քայլ)
qty = q / 10^qty_scale մոնետաներով
քայլ = bucket_size / 10^price_scaleԿադրեր՝ HMP1 և HMP2 layout=0-ով
Վերնագրից հետո՝ frame_count կադրեր անընդմեջ.
varint ts_delta_ms նախորդ կադրի ts-ից; առաջինի մոտ՝ from_ms-ից
u8 kind 1 = KEY (լրիվ վիճակ), 0 = DELTA (փոփոխություններ)
zigzag best_bid_d տարբերություն նախորդ կադրի best_bid-ից; առաջինի մոտ՝ 0-ից
zigzag best_ask_d նույնը best_ask-ի համար
varint bid_count
bid_count անգամ.
zigzag idx_delta նախորդ բջջի idx-ից; առաջինի մոտ՝ 0-ից
varint qty բջջի ԲԱՑԱՐՁԱԿ ծավալը (HMP2-ում՝ կոդ); 0 = մակարդակն անհետացել է
varint ask_count
ask_count անգամ. նույնըvarint՝ LEB128 առանց նշանի։ zigzag՝ LEB128 (n << 1) ^ (n >> 63)-ի վրա, ապակոդավորվում է որպես (u >> 1) ^ -(u & 1)։
Պահեք երկու բառարան idx → qty, bid-երի և ask-երի համար.
- KEY՝ բառարանները փոխարինվում են կադրի բովանդակությամբ;
- DELTA՝ վերադրվում է վերևից.
qty > 0՝ վերագրել,qty == 0՝ ջնջել բանալին։
Առաջին կադրը միշտ KEY է, հետագայում KEY-ը կրկնվում է յուրաքանչյուր 512 կադրը մեկ։ ts, best_bid, best_ask հաշվիչներն ապրում են մեկ պատասխանի սահմաններում։ Բառարանների վիճակը կադրից հետո՝ ջերմաքարտեզի մեկ սյունակ։
import struct
def uvarint(b, p):
out = shift = 0
while True:
x = b[p]; p += 1
out |= (x & 0x7F) << shift
if x < 0x80:
return out, p
shift += 7
def svarint(b, p):
u, p = uvarint(b, p)
return (u >> 1) ^ -(u & 1), p
def columns(b):
"""HMP1 -> [(ts, {price: qty} bid-եր, {price: qty} ask-եր)]."""
assert b[:4] == b"HMP1"
bucket, ps, qs = struct.unpack_from("<qBB", b, 8)
step_ms, from_ms, _to, frames = struct.unpack_from("<IqqI", b, 20)
if frames == 0:
return []
bid, ask, out, p, ts = {}, {}, [], 48, from_ms
for _ in range(frames):
d, p = uvarint(b, p); ts += d
kind = b[p]; p += 1
_, p = svarint(b, p); _, p = svarint(b, p) # best_bid_d, best_ask_d
for book in (bid, ask):
n, p = uvarint(b, p)
cells, idx = [], 0
for _ in range(n):
di, p = svarint(b, p); idx += di
q, p = uvarint(b, p)
cells.append((idx, q))
if kind == 1:
book.clear()
book.update((i, q) for i, q in cells if q > 0)
else:
for i, q in cells:
if q: book[i] = q
else: book.pop(i, None)
price = lambda i: i * bucket / 10**ps
out.append((ts,
{price(i): q / 10**qs for i, q in sorted(bid.items())},
{price(i): q / 10**qs for i, q in sorted(ask.items())}))
assert p == len(b), "կադրերից հետո բայթեր են մնացել"
return outformat=json աղյուսակը հենց այս վերլուծությունն է՝ տող յուրաքանչյուր ոչ զրոյական բջջի համար յուրաքանչյուր սյունակում։
HMP2. ծավալը կոդով
Կադրերը layout=0-ով՝ բայթ առ բայթ ինչպես HMP1-ում, բայց varint qty-ի փոխարեն կանգնած է varint code.
code = 0՝ մակարդակ չկա (DELTA-ում՝ «մակարդակն անհետացավ»);- հակառակ դեպքում
code-ը բջջի ծավալն է մոնետաներով՝m = qty_bitsմանտիսի բիթերով ձևաչափով։
DELTA-ն համեմատում է կոդերը. բջիջը, որի կոդը չի փոխվել, DELTA-ում չի ընկնում, նույնիսկ եթե հում ծավալը մի փոքր շարժվել է։
Ապակոդավորում (d = 23 − m). code = 0 → 0, հակառակ դեպքում v = from_bits(((code + (64 << m)) << d) as u32) որպես float32՝ ծավալը մոնետաներով, qty_scale-ն այլևս չի կիրառվում։ m = 9-ի դեպքում սխալը 2⁻¹⁰-ից ոչ ավելի է, միջակայքը՝ 2⁻⁶³-ից մինչև 2⁶⁵ մոնետա։
import struct
def hmp2_qty(code, m):
if code == 0:
return 0.0
bits = (code + (64 << m)) << (23 - m)
return struct.unpack("<f", struct.pack("<I", bits))[0]Վեկտորներ՝ ձեր իրականացումը ստուգելու համար.
| Ծավալ | Կոդ m=9 | Հակառակ | Կոդ m=6 | Հակառակ |
|---|---|---|---|---|
| 1e-8 | 18607 | 9.997166e-9 | 2326 | 1.0011718e-8 |
| 0.001 | 27148 | 0.0009994507 | 3394 | 0.0010070801 |
| 0.5 | 31744 | 0.5 | 3968 | 0.5 |
| 1 | 32256 | 1 | 4032 | 1 |
| 1023 | 37375 | 1023 | 4672 | 1024 |
| 12345.678 | 39172 | 12352 | 4896 | 12288 |
HMP2, layout=1. գների շարքեր
Նույն վերնագիրը 19-րդ բայթ = 1։ Մարմինը՝ չորս հոսք անընդմեջ, առանց kind-ի և կադրի հաշվիչների.
- Ժամանակ.
frame_countանգամvarint ts_delta,zigzag best_bid_d,zigzag best_ask_d՝ ինչպես կադրում։ - Շարքեր. bid-երի, ապա ask-երի համար՝
varint R, հետո R անգամzigzag idx_delta(առաջինը՝ 0-ից, հետագաները՝ այդ կողմի նախորդ շարքի idx-ից, խիստ աճման կարգով) ևvarint run_count։ - Երկարություններ. բոլոր bid-երի, ապա ask-երի շարքերը, յուրաքանչյուր սերիայի համար
varint (len − 1)։ Շարքի երկարությունների գումարը =frame_count։ - Կոդեր. նույն հերթականությամբ յուրաքանչյուր սերիայի համար
zigzag(code − prev),prev = 0յուրաքանչյուր շարքի սկզբում։code = 0՝ մակարդակ չկա այդ սյունակներում։
Շարքը, որը ոչ մի ոչ զրոյական կոդ չունի, չի գրվում։ Շարքերի սյունակը չի կարելի առանձին կարդալ ամբողջ մարմնից՝ հոսքային պատկերման համար վերցրեք layout=0։
https://docs.lootx.trade/hy/market-api/heatmap-binary
17Лимиты и тарифы
Что ограничивает API-тариф, почему лимиты общие на все ключи аккаунта, как читать заголовки X-RateLimit и RateLimit, живые лимиты /v1/usage и что делать при 429.
Лимиты задаёт API-тариф аккаунта. Он отдельный от подписки на терминал: можно иметь Pro терминала и не иметь API-тарифа, и наоборот. Какой тариф у вас и что в него входит — на странице API-ключи в кабинете.
Что ограничивает тариф
| Лимит | Как считается |
|---|---|
| Запросов в минуту | ведро с допустимым всплеском: короткая пачка запросов проходит, средний темп — не выше лимита |
| Запросов в час | окно UTC с начала часа, hh:00 |
| Запросов в сутки | окно UTC с 00:00 |
| Байт выдачи в сутки | по фактически отданному телу ответа и по кадрам WebSocket, сброс в 00:00 UTC |
| Глубина истории | сколько дней назад от «сейчас» можно спрашивать. Это предел, а не обещание глубины: раньше, чем лежат данные, ответ пустой (свечи, например, есть с 23.10.2026 — смотрите coverage), кроме price_step у тепловой карты |
| WebSocket-соединений | одновременно открытых |
| Рыночных WebSocket-подписок | scope: "market", поле тарифа ws_market_subs: на аккаунт — все ключи, соединения и каналы вместе. Ноль — значение шлюза, одна подписка |
| Ключей | действующих ключей на аккаунт |
Ноль в тарифе означает «без ограничения» — кроме рыночных подписок: там ноль значит значение шлюза, одну подписку.
Лимиты групп маршрутов
Тариф может дать группе маршрутов свои, более строгие лимиты — например, тепловой карте или секундным свечам — или закрыть группу совсем: тогда ответ 403 route_not_in_plan. Лимит группы действует вместе с общим, а не вместо него: запрос к тепловой карте тратит и запас группы heatmap, и общий запас аккаунта.
| Группа | Маршруты |
|---|---|
instruments |
/v1/instruments |
candles |
/v1/candles с шагом от минуты |
candles_1s |
/v1/candles с шагом меньше минуты; канал candles в WebSocket |
series |
/v1/series |
footprint |
/v1/footprint, /v1/hyperliquid/footprint |
delta |
/v1/delta |
trades |
/v1/trades |
heatmap |
/v1/heatmap, /v1/book/bands |
oi |
/v1/oi |
funding |
/v1/funding, /v1/funding/events |
ls_ratio |
/v1/ls-ratio, /v1/ls-ratio/latest |
mark |
/v1/mark с шагом 1m и /v1/mark/latest |
mark_1s |
/v1/mark с шагом 1s |
margin |
/v1/margin/*: все шесть маршрутов маржинального кредитования |
options |
/v1/options/*: все десять маршрутов опционов и поток /v1/options/stream — соединение, его кадры и объём; группы ws у потока нет. /v1/options/chain/range весит час диапазона — от 1 до 6 единиц (вес запроса), /v1/options/vol/book-range — границы шага на 64, вверх, от 1 до 34 единиц (вес ряда), /v1/options/levels/range — точки шага на 1440, вверх, от 1 до 7 единиц (вес истории уровней), /v1/options/exposure/latest — 1 единица |
densities |
/v1/densities |
densities_history |
/v1/densities/history |
icebergs |
/v1/icebergs |
screener |
/v1/screener, /v1/screener/metrics |
ws |
подключение к /v1/ws и /v1/ws/*; поток опционов — в группе options |
/v1/status не входит ни в одну группу и расходует только общие лимиты; /v1/usage — тоже.
Заголовки
Каждый ответ на запрос с ключом — и успешный, и с ошибкой — несёт состояние лимитов. Две записи одного и того же: короткая X-RateLimit-* — по самому тесному окну, где осталось меньше всего, и RateLimit-Policy с RateLimit по черновику IETF (draft-ietf-httpapi-ratelimit-headers) — по всем окнам тарифа сразу.
200 OK
X-Request-Id: 9f2c4a1be07d4e55a1c3b2d4e5f60718
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1793793601
X-RateLimit-Scope: account
X-RateLimit-Window: minute
RateLimit-Policy: "minute";q=600;w=60, "day";q=50000;w=86400, "bytes_day";q=10737418240;w=86400;qu="content-bytes"
RateLimit: "minute";r=99;t=1, "day";r=45000;t=43200, "bytes_day";r=10733418240;t=43200| Заголовок | Смысл |
|---|---|
X-RateLimit-Limit |
потолок самого тесного окна; у минуты — запросов в минуту, у bytes_day — байт в сутки |
X-RateLimit-Remaining |
сколько в нём осталось |
X-RateLimit-Reset |
когда это окно сбросится — момент, Unix-секунды UTC. У минуты — когда ведро снова полное |
X-RateLimit-Scope |
account — общий лимит аккаунта, route:<группа> — лимит группы |
X-RateLimit-Window |
minute, hour, day или bytes_day |
RateLimit-Policy |
все окна тарифа для этого запроса: q — потолок, w — длина окна в секундах, у байтов — qu="content-bytes". Окна группы называются "route:<группа>:<окно>" |
RateLimit |
остаток r и секунд до сброса t по каждому окну с потолком |
Retry-After |
только у 429 и 503: через сколько секунд повторить |
Окно без потолка (0 в тарифе) в RateLimit-Policy и RateLimit не попадает. Все эти заголовки, как и X-Request-Id, X-Next-Cursor, Link и X-Cache, открыты браузеру (Access-Control-Expose-Headers): fetch со страницы их читает.
Предохранитель по адресу
Перед шлюзом стоит край сети, и у него свой предохранитель — по IP-адресу, до проверки ключа: около 50 запросов в секунду с одного адреса, короткий залп — до 100. Сверх него — 429 rate_limited со scope: "ip", window: "second" и retry_after: 1. Это защита от залпов, а не тариф: обычному клиенту, который держится в лимите тарифа, до него не дойти. Несколько сервисов за одним NAT делят этот предохранитель между собой.
Ответы края сети — того же вида, что ошибки шлюза: JSON с code. Кроме 429 это 413 payload_too_large (тело запроса больше 64 КБ) и 503 unavailable / 504 upstream_timeout с Retry-After: 5, если шлюз недоступен или не ответил.
Когда лимит исчерпан
| Код | HTTP | Что случилось | Когда пройдёт |
|---|---|---|---|
rate_limited |
429 | темп в минуту — аккаунта или группы | через Retry-After секунд |
hourly_limit |
429 | запросы за час | в начале следующего часа UTC |
daily_limit |
429 | запросы за сутки | в 00:00 UTC |
daily_quota_exceeded |
429 | суточный объём выдачи | в 00:00 UTC |
ws_limit |
429 | открыто слишком много WebSocket | закройте лишнее соединение |
market_subs_limit |
кадр потока | рыночных подписок столько, сколько разрешает тариф | снимите лишнюю: unsubscribe со scope: "market" |
rate_limited |
кадр потока | сверх 10 команд в секунду и запаса 20 на соединение или рыночная подписка канала открывается чаще раза в секунду. Считается открытие: снятие с повторной подпиской паузу не обходит | через retry_after секунд; прежняя подписка, если она есть, остаётся |
history_out_of_plan |
403 | запрошено глубже разрешённой истории | сдвиньте from не раньше earliest_allowed_ms; у /v1/margin/assets, /compare и /events глубину меряет окно — возьмите window короче; у /v1/options/chain — минута at: at не раньше earliest_allowed_ms; у /v1/options/chain/range — from, округлённый вверх до минуты; у /v1/options/vol/book-range и /v1/options/levels/range отказ приходит уже после списания полного веса |
route_not_in_plan |
403 | группа маршрута не входит в тариф | смените тариф |
В теле 429 — детали лимита: limit, remaining, window, scope, retry_after и reset_at_ms. У 403 history_out_of_plan — history_days, earliest_allowed_ms и scope, у 403 route_not_in_plan — только scope (тело ошибки).
Что отказ делает со счётчиками:
429по окнам часа и суток и по объёму, как правило, не двигает ни одного счётчика: запрос не засчитан, повторять послеRetry-Afterбезопасно. Исключение — гонка параллельных запросов: окна часа и суток сверяются до вёдер минуты, а засчитываются после них, и если между сверкой и зачётом окно заполнил соседний запрос, отказ придёт уже после того, как этот запрос потратил жетон минутного ведра аккаунта (и группы, если у неё свой темп). Сами окна часа и суток он при этом не засчитывает. Объём суток так не гоняется: он сверяется только до вёдер.429 rate_limitedпо ведру группы не двигает ничего. По ведру аккаунта — тоже, кроме одного: жетон ведра группы этого запроса уже списан. Потеря — не больше ёмкости ведра группы и только когда вы и так упёрлись в общий лимит.403 history_out_of_plan— уже засчитанный запрос: он расходует окна минуты, часа и суток, как обычный.403 route_not_in_planсчётчиков не двигает.
И ещё:
- Объём учитывается после ответа: запрос, начатый до исчерпания, отдаётся целиком, следующий получит
429. - Ответ из кэша шлюза (
X-Cache: HIT) считается в лимитах и объёме как обычный. - Объём считается по телу до сжатия: со сжатием и без запрос стоит одинаково (сжатие).
503 upstream_busy— не ваш лимит, а очередь шлюза к источнику: она защищает источники от всплесков. Повторите черезRetry-After(обычно 1 с).
import time, requests
WAIT_FOR_RESET = ("daily_limit", "daily_quota_exceeded", "hourly_limit", "ws_limit")
def get(url, **kw):
for attempt in range(4):
r = requests.get(url, **kw)
if r.status_code in (429, 503):
err = r.json()["error"]
if err["code"] in WAIT_FOR_RESET:
raise RuntimeError(f"лимит {err['code']}: окно сбросится в {err.get('reset_at_ms')}")
time.sleep(min(int(err.get("retry_after") or r.headers.get("Retry-After", 1)), 30))
continue
return r
return rТакой же цикл есть в SDK, но пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.
WebSocket в суточном объёме
Байты кадров, которые сервер шлёт клиенту, идут в суточный объём вместе с REST: данные любых каналов /v1/ws, ответы на команды, кадры сырых потоков /v1/ws/* и hello с кадрами OPC1 потока /v1/options/stream. Считается длина кадра без служебных заголовков WebSocket. WS-ping и кадр error, с которым шлюз закрывает соединение, не считаются.
Учёт тот же, что у REST: общий объём аккаунта, группа соединения ws и группа данных канала (densities, screener, trades, oi, candles_1s); у потока опционов — общий объём и группа options, те же письма на 80 и 100 %. Лимит объёма группы действует и на кадры: лимит ws тратят все эти кадры соединения, лимит группы канала — только кадры этого канала. В разбивке расхода по группам ответы на команды, subscribed рыночной подписки тоже, стоят в ws, данные — в группе канала.
Кадры копятся и списываются раз в такт соединения (5 с) и при закрытии, поэтому перерасход — не больше одного такта потока.
Когда объём кончился:
/v1/ws— кадрerrorс кодомdaily_quota_exceeded(limit,remaining: 0,window: "bytes_day",scope—accountилиroute:<группа>) и закрытие1008с тем же кодом в причине;- сырой поток
/v1/ws/*и поток опционов — закрытие с кодом в причине; - новое соединение —
429 daily_quota_exceeded, как у REST; - новая рыночная подписка на открытом соединении — отказ кадром
errorс тем же кодом.
Если счётчики объёма временно недоступны, поток не рвётся, а прибавка за это время теряется.
Живые лимиты: GET /v1/usage
/v1/usageТариф ключа, его лимиты, расход за сутки UTC и состояние каждого окна прямо сейчас. Сам запрос — обычный: он расходует общие окна аккаунта (минуту, час, сутки и байты), но не лимиты групп — ни в одну группу он не входит.
curl -s "https://market-api.lootx.trade/v1/usage" -H "Authorization: Bearer $LOOTX_API_KEY"{
"plan": { "id": "6f1c…", "slug": "pro", "name": "Pro" },
"tier": "pro",
"limits": { "rpm": 600, "burst": 100, "rph": 0, "rpd": 50000, "daily_bytes": 10737418240, "history_days": 365, "ws_conns": 5 },
"routes": { "heatmap": { "rpd": 5000, "rpm": null, "rph": null, "daily_bytes": null, "history_days": null, "enabled": true } },
"today": { "day": "2026-11-04", "requests": 5000, "bytes": 4000000 },
"now": {
"at_ms": 1793793600000,
"windows": [
{ "scope": "account", "window": "minute", "limit": 600, "burst": 100, "used": 37, "remaining": 63, "reset_at_ms": 1793793603700 },
{ "scope": "account", "window": "hour", "limit": null, "used": 1234, "remaining": null, "reset_at_ms": 1793797200000 },
{ "scope": "account", "window": "day", "limit": 50000, "used": 5000, "remaining": 45000, "reset_at_ms": 1793836800000 },
{ "scope": "account", "window": "bytes_day", "limit": 10737418240, "used": 4000000, "remaining": 10733418240, "reset_at_ms": 1793836800000 },
{ "scope": "route:heatmap", "window": "day", "limit": 5000, "used": 10, "remaining": 4990, "reset_at_ms": 1793836800000 }
],
"throttled_today": 3,
"last_limited": { "at_ms": 1793793500000, "code": "rate_limited", "scope": "account", "window": "minute" }
}
}| Поле | Что |
|---|---|
plan, tier |
тариф ключа |
limits |
общие лимиты аккаунта; 0 — без ограничения. ws_market_subs приходит, только если тариф задал его не нулём; нет поля — значение шлюза, одна подписка |
routes |
группы тарифа так, как их применяет шлюз: enabled — открыта ли группа на деле (false — закрыта: запросы к ней получают 403 route_not_in_plan); в лимите null — как в общем, 0 — без ограничения в группе |
today |
за сутки UTC: засчитанные запросы (429 и 403 route_not_in_plan не входят, 403 history_out_of_plan входит) и отданные байты до сжатия |
now.windows |
окна сейчас: общие — всегда, окна группы — только у групп со своим лимитом |
now.throttled_today |
сколько раз за сутки UTC запрос отбит по лимиту (429 и лимитные 403) |
now.last_limited |
последний такой отказ за сутки или null |
Окно в now.windows:
| Поле | Минута | Час, сутки, байты |
|---|---|---|
limit |
установившаяся скорость, запросов в минуту | потолок окна; у bytes_day — байт |
burst |
ёмкость ведра: сколько запросов можно подряд | нет |
remaining |
целые жетоны в ведре сейчас, с пополнением | сколько осталось до потолка |
used |
burst − remaining |
сколько уже засчитано |
reset_at_ms |
когда ведро снова полное | когда окно сбросится |
limit: null и remaining: null — у окна нет потолка. Заполнение минуты считайте как used / burst, а не used / limit: минута — ведро, а не счётчик.
Счётчики лимитов временно недоступны — 503 usage_unavailable с Retry-After, а не ответ с пустыми окнами или нулями: повторите позже. На ваши запросы к остальным маршрутам это не влияет.
Уведомления о расходе
Когда расход за сутки или за час доходит до 80 % и до 100 % лимита — общего или лимита группы, — на почту аккаунта приходит письмо. Следим за суточным объёмом, запросами в сутки и запросами в час. Одно письмо на порог: на суточные лимиты — раз в сутки, на часовой — раз в час.
Где смотреть расход
- запросы и объём по дням за 7 или 30 суток UTC, с долей ошибок и отказов
429. Подключение WebSocket считается запросом, поток — нет: его кадры дают только объём. До 06.11.2026 17:17 UTC запросами считались и такты соединения, эти итоги не пересчитаны; - разбивка по ключам или по группам маршрутов;
- расход за сегодня (UTC) против лимитов тарифа: от 80 % — предупреждение, на 100 % — лимит исчерпан.
Живой остаток в своём коде — из заголовков X-RateLimit-* и RateLimit любого ответа или целиком из /v1/usage.
https://docs.lootx.trade/hy/market-api/limits
18Ошибки
Тело ошибки с деталями, все коды REST и WebSocket — что значит каждый и что с ним делать.
Тело ошибки
Любая ошибка шлюза — HTTP-код и JSON, в каком бы формате вы ни просили ответ: и отказ маршрута, и неизвестный путь, и неподдержанный Accept, и внутренний сбой.
{
"error": {
"code": "rate_limited",
"message": "лимит 600 запросов в минуту исчерпан",
"request_id": "9f2c4a1be07d4e55a1c3b2d4e5f60718",
"docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
"limit": 600,
"remaining": 0,
"window": "minute",
"scope": "account",
"retry_after": 1,
"reset_at_ms": 1793750461000
}
}| Поле | Что |
|---|---|
code |
машинный код, snake_case, стабильный. Разбирайте его |
message |
объяснение для человека; может меняться, не разбирайте его |
request_id |
тот же номер, что в заголовке X-Request-Id. Пришлите его в поддержку |
docs_url |
этот код на этой странице: https://docs.lootx.trade/ru/market-api/error-codes#<код> |
Детали
Рядом с code лежат поля, которые помогают исправить запрос. Каждое есть, только когда оно к месту:
| Когда | Поля | Что в них |
|---|---|---|
400 — параметр не разобрался |
param, expected |
какой параметр и что в нём ожидалось: "param": "from", "expected": "целое: Unix-миллисекунды UTC" |
406 not_acceptable |
param, expected |
"param": "Accept" и список типов, которые отдаёт этот маршрут |
429 |
limit, remaining, window, scope, retry_after, reset_at_ms |
потолок окна и остаток; окно — minute, hour, day, bytes_day (у края сети — second); чьё — account, route:<группа> или ip; через сколько секунд повторить; когда окно сбросится, Unix-мс UTC |
403 history_out_of_plan |
history_days, earliest_allowed_ms, scope, param, expected |
глубина истории тарифа в сутках (с учётом группы); самый ранний допустимый from, Unix-мс UTC; чей предел — account или route:<группа>; "param": "from", а у маршрутов маржи с окном — "param": "window", у /v1/options/chain — "param": "at" |
403 route_not_in_plan |
scope |
закрытая группа — route:<группа> |
405 method_not_allowed |
allow |
разрешённые методы — как в заголовке Allow |
У bytes_day limit и remaining — в байтах. Как устроены окна — Лимиты и тарифы.
Заголовки ошибки
| Заголовок | Когда |
|---|---|
X-Request-Id |
у каждого ответа |
Retry-After |
у каждого 429 и 503 — через сколько секунд повторить; у 503 без своего срока — 5 |
WWW-Authenticate |
у 401: Bearer realm="lootx", а с негодным ключом — Bearer realm="lootx", error="invalid_token" |
Allow |
у 405 и у OPTIONS: GET, HEAD, OPTIONS |
X-RateLimit-*, RateLimit-Policy, RateLimit |
у ответов с ключом, и с ошибкой тоже — подробно |
Ключ и доступ
| Код | HTTP | Что значит | Что делать |
|---|---|---|---|
missing_key |
401 | ключа нет | передайте Authorization: Bearer <ключ> или X-API-Key |
invalid_key |
401 | такого ключа нет | проверьте, что ключ скопирован целиком: lx_live_ и 43 знака. Повтор с тем же ключом не поможет |
invalid_token |
401 | токен входа не прошёл проверку | для API используйте ключ, а не токен терминала |
token_expired |
401 | срок токена входа истёк | то же |
key_in_query |
400 | ключ передан в адресе | уберите ключ из адреса — только заголовок. Ключ, засветившийся в адресе, лучше отозвать |
revoked_key |
403 | ключ отозван | выпустите новый в кабинете |
plan_inactive |
403 | у аккаунта нет действующего API-тарифа | продлите или выберите тариф |
insufficient_scope |
403 | у ключа нет нужной области доступа. У /v1/options/* нужна область derivatives: токен терминала без неё (бесплатный) получает этот отказ |
выпустите ключ с нужными областями; к опционам — с API-ключом |
route_not_in_plan |
403 | группа маршрута не входит в тариф | смените тариф; что в него входит — в кабинете |
history_out_of_plan |
403 | история глубже, чем разрешает тариф (общий лимит или лимит группы). У /v1/margin/assets, /compare и /events глубину меряет окно window — param: "window"; у /v1/options/chain — начало минуты, закрытой в at, — param: "at" |
сдвиньте from не раньше earliest_allowed_ms из тела ошибки; у маржи с окном — возьмите window короче; у опционов — at не раньше earliest_allowed_ms |
forbidden |
403 | доступ запрещён по иной причине | проверьте ключ и тариф; не проходит — напишите в поддержку с request_id |
auth_unavailable |
503 | проверка ключа временно недоступна | повторите через Retry-After |
Лимиты
| Код | HTTP | Что значит | Что делать |
|---|---|---|---|
rate_limited |
429 | превышен лимит запросов в минуту — аккаунта или группы маршрутов (scope); со scope: "ip" — предохранитель края сети по адресу |
подождите Retry-After секунд; держите темп ниже RateLimit-Policy |
hourly_limit |
429 | исчерпан лимит запросов в час | сброс в начале следующего часа UTC — reset_at_ms |
daily_limit |
429 | исчерпан лимит запросов в сутки | сброс в 00:00 UTC — reset_at_ms |
daily_quota_exceeded |
429 | исчерпан суточный объём выдачи — аккаунта или группы; кадры WebSocket считаются в него же | сброс в 00:00 UTC; protobuf и бинарь тепловой карты короче JSON |
ws_limit |
429 | слишком много одновременных WebSocket | закройте лишнее соединение |
Подробно про лимиты, заголовки и живой остаток — Лимиты и тарифы.
Параметры запроса
| Код | HTTP | Что значит | Что делать |
|---|---|---|---|
bad_request |
400 | параметры не разобрались | исправьте параметр из param по expected |
bad_instrument |
400 | инструмент не в виде venue:market:SYMBOL |
как называть инструменты |
unsupported_instrument |
400 | инструмента нет у источника: param: "instrument" — биржа, рынок или котировка, param: "symbol" — символ, только на /v1/candles и /v1/series и не всегда. На остальных маршрутах символ не сверяется: пустой 200 не значит, что инструмент есть. Условия и пределы |
проверьте имя и колонку sources в /v1/instruments |
bad_cursor |
400 | курсор не разобрался: он повреждён. С параметрами запроса он не сверяется | передавайте next_cursor (или ссылку из Link) из прошлого ответа без изменений, с теми же остальными параметрами |
bad_format |
400 | неизвестный format, или CSV для ответа из нескольких таблиц, или формат не этого маршрута: CSV у ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) — и format=csv, и Accept: text/csv, opc1 вне /v1/options/chain, /chain/latest и /chain/range — в том числе у /v1/options/vol/book-range, /exposure/latest и /levels/range |
message называет форматы маршрута: format=json, protobuf или csv, у ответов без таблицы — format=json или protobuf; для футпринта — table=levels или windows |
not_acceptable |
406 | в Accept нет ни одного известного шлюзу типа — ни JSON, ни protobuf, ни text/csv, ни маски вроде */*. Accept: text/csv у ответа без таблицы — не 406, а 400 bad_format |
Accept: application/json, application/x-protobuf или text/csv — или ?format=. У ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) в expected типы без text/csv; кадры OPC1 цепочек опционов — только ?format=opc1, по Accept их не попросить |
method_not_allowed |
405 | метод не GET, HEAD или OPTIONS |
метод из Allow (GET, HEAD, OPTIONS) |
request_timeout |
408 | запрос не дошёл до шлюза вовремя | повторите запрос |
payload_too_large |
413 | тело запроса больше 64 КБ | запросам API тело не нужно — отправляйте GET без тела |
too_large |
413 | ответ слишком велик | сузьте окно, укрупните шаг или возьмите бинарный формат |
not_found |
404 | нет такого маршрута. У /v1/ls-ratio/latest и /v1/mark/latest — по инструменту нет ни одной строки: у long/short за 35 суток, у mark за 7 суток. У /v1/options/chain и /chain/latest — нет минуты у базы или у присланной chain либо она не восстанавливается (gap в message); у /chain/range — нет цепочки, инструмента или ни одной минуты диапазона; у /vol/book-range, /exposure/latest и /levels/range — нет книги у базы; у потока опционов — нет присланной цепочки или у базы нет ни одной, отказ до апгрейда |
список маршрутов — /v1/openapi.json; замолчавший ряд читайте /v1/ls-ratio или /v1/mark с окном |
not_available |
404 | маршрут есть, но таких данных шлюз не отдаёт: их ещё не собирают или они не включены у источника. Это не ошибка запроса и не сбой источника | повтор не поможет; какие маршруты отвечают так — в описании ответов /v1/openapi.json |
Неизвестный инструмент
unsupported_instrument приходит в двух случаях, в REST их различает поле param. В потоке различителя нет: подписка символ не сверяет.
param: "instrument"— биржа, рынок или котировка. Отказ приходит сразу, до запроса к источнику:binance:future:BTCUSDT, спот у/v1/oi, биржа, которой нет у маршрута./v1/oi,/v1/funding,/v1/funding/events,/v1/ls-ratioи/v1/ls-ratio/latestу okx, bingx, mexc и kucoin, а/v1/markи/v1/mark/latestу okx и mexc собирают имя для источника из базы и котировки, поэтому так же отказывают символу, котировку которого не разобрать:okx:perp:BTC-USDT-SWAP,kucoin:perp:XBTUSDTM. Свои правила у/v1/screener?instruments=: биржу он не сверяет, а котировку сверяет.param: "symbol"— символ. Только/v1/candlesи/v1/series: биржа и рынок есть, а символ не найден, напримерbinance:perp:BTCUSDTT. Вmessage— что не найдено и ссылка на/v1/instruments?venue=…&market=….
На остальных маршрутах пустой ответ не значит, что инструмент существует. /v1/trades, /v1/footprint, /v1/delta, /v1/heatmap, /v1/oi, /v1/funding, /v1/funding/events, /v1/ls-ratio, /v1/mark, /v1/densities, /v1/densities/history, /v1/icebergs и /v1/screener?instruments= на символ, по которому нет данных, отвечают 200 с пустым ответом, на опечатку тоже, если имя прошло проверки выше. Исключение — /v1/heatmap с price_step: без данных книги в минуте перед to шаг не во что перевести, ответ 400 bad_request, запрашивайте без него. Условие и оговорка — в пределах тепловой карты. Живые списки источников не знают снятые символы с историей, поэтому отказ по ним был бы ложным.
Отказ с param: "symbol" не гарантирован. Он приходит, только когда сошлось всё:
- Строк нет, в запросе нет
cursor, а в ответе не было быnext_cursor. Есть строки — они отдаются, даже если инструмент снят с торгов и ни в одном списке его больше нет. - Источник подтвердил, что по символу нет ни одного бара за всю историю, а не только в окне запроса. Не смог подтвердить или запись баров у него выключена — отказа нет.
- Рынок вообще есть у источника свечей. Рынков HIP-3 там нет, см. ниже.
- Символа нет ни в одном списке источников, и шлюз не видел его в них с момента своего запуска. Имена сравниваются по базе без учёта регистра:
BTC,BTCUSDCиbtcusdtодной биржи и рынка — один инструмент. ПоэтомуBTCEURна бирже сBTCUSDT, но без такой пары, отказа не получит. - Все источники списков исправны: каждый недавно отдал непустой список, хотя бы в одном есть эта биржа и рынок, и с первого списка источника прошло достаточно времени. Источник только поднялся или вернулся после долгого сбоя — отказ включится не сразу.
Иначе ответ — 200 с пустым списком. Поэтому при сбое одного источника или вскоре после перезапуска шлюза опечатка на /v1/candles и /v1/series тоже может получить 200. Глубина истории проверяется раньше: 403 history_out_of_plan приходит до запроса к источнику, и отказ по символу его не заменяет.
400 бывает и у настоящего инструмента. Когда условия выше сошлись, это:
- Новый листинг. Пока символа нет ни в одном списке, а первая сделка не дошла до баров,
/v1/candlesи/v1/seriesотвечают400. Повторите позже. - Символа нет в барах, а в других данных он есть. Снятый с торгов, когда свечей по этой бирже ещё не писали, или с истёкшими барами.
400здесь говорит о свечах и рядах: у/v1/footprint,/v1/tradesи других маршрутов данные по нему могут быть. - Имя не в том виде, что в реестре.
PF_XBTUSD,BTC-USDT-SWAP,XBTUSDTM,BTC_USDTк имени источника не приводятся. Имя берите из/v1/instruments: там это, например,kraken:perp:BTCUSD,okx:perp:BTCUSDT,kucoin:perp:BTCUSDT.
Акции Hyperliquid (рынки HIP-3) пишутся как в /v1/instruments: hyperliquid:perp:AAPLUSDC.XYZ, короткое hyperliquid:perp:AAPL.XYZ — то же самое. Данные по ним есть у /v1/footprint, /v1/delta, /v1/trades и /v1/heatmap (только деки xyz и io), у /v1/densities и /v1/screener. У /v1/candles, /v1/series, /v1/oi, /v1/funding и /v1/funding/events этих рынков нет: ответ — пустой 200, отказа нет. Имя Hyperliquid xyz:AAPL не подходит: двоеточие в символе — 400 bad_instrument.
Источники данных и шлюз
| Код | HTTP | Что значит | Что делать |
|---|---|---|---|
upstream_rejected |
400 | источник отверг параметры запроса. У /v1/margin/* текст источника начинается с имени параметра — оно же в param; у /v1/options/* param — по коду источника (bad_base → base, bad_range → from, range_too_long → to, bad_instrument → instrument, bad_resume → resume, …), код — в конце message |
проверьте окно и шаг; message подскажет |
upstream_error |
502 | источник ответил ошибкой. У /v1/margin/* и /v1/options/* так же приходит и 404 источника без кода минуты: маршрутов у него нет, это не not_found |
повторите позже; если повторяется — напишите в поддержку с request_id |
upstream_unavailable |
502 | источник недоступен. У /v1/margin/* — ещё и 503 с Retry-After: 2: источник прогревается или перегружен (подробно); у /v1/options/* — 503 с Retry-After источника, обычно 1 с, не дольше 60 с: источник загружает цепочки после запуска, у /v1/options/vol/book-range уже собирает предельное число рядов со склада, у /v1/options/levels/range — читает предельное число рядов уровней, у потока опционов держит предельное число соединений; поток выключен на узле — 503 с Retry-After: 30, это выкладка, а не окончательный отказ (подробно) |
повторите позже; состояние — /v1/status |
upstream_timeout |
504 | источник или шлюз не ответил вовремя | сузьте окно или повторите через Retry-After |
upstream_busy |
503 | очередь шлюза к источнику полна | повторите через Retry-After, обычно 1 с |
upstream_not_configured |
503 | источник ещё не подключён к шлюзу | маршрут в бете — следите за обновлениями |
usage_unavailable |
503 | /v1/usage: счётчики лимитов временно недоступны |
повторите через Retry-After |
unavailable |
503 | сервис временно недоступен (в том числе край сети не достучался до шлюза) | повторите через Retry-After, у края сети — 5 с |
internal |
500 | внутренняя ошибка шлюза | напишите в поддержку с request_id |
Поток (WS)
Ошибки потока приходят кадром error того же вида, что тело ошибки REST: code, message, docs_url, id команды, если он был, и детали лимита, когда они к месту. Соединение при этом живёт, кроме отмеченных «закрытие».
{"type": "error", "id": 7, "code": "rate_limited",
"message": "не больше 10 сообщений в секунду на соединение (запас 20); сообщение пропущено",
"docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
"limit": 10, "remaining": 0, "window": "second", "scope": "connection", "retry_after": 1}| Код | Что значит |
|---|---|
bad_request |
кадр не JSON или не текстовый, нет channel, неизвестный op, в subscribe без scope нет непустого массива instruments |
unknown_channel |
такого канала нет |
channel_unavailable |
канал пока не работает или, с instrument, выбрал потолок соединений с источником — повторите позже. Со scope: "market" и channel — потолок рыночных соединений шлюза (retry_after — через сколько секунд повторить); без retry_after — рыночную подписку остановил сбой шлюза, подпишитесь заново |
too_many_instruments |
аккаунт уже держит свою долю ёмкости канала — отпишитесь от лишнего |
bad_instrument |
имя не в виде venue:market:SYMBOL. Кадр несёт instrument, если имя пришло строкой; остальные имена команды обрабатываются дальше |
unsupported_instrument |
у источника канала нет такого рынка или биржи, а на oi и screener ещё и не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает. Символ подписка не сверяет (подробно) |
bad_params |
неверные params или scope, что не так — в тексте ошибки: params у подписки по инструментам, кроме null и пустого объекта, scope не market и не null, subscribe со scope: "market" у канала без рыночной подписки или вместе с непустым массивом instruments, параметр рыночной подписки вне списка или с неверным значением |
market_subs_limit |
аккаунт уже держит столько рыночных подписок, сколько разрешает тариф (ws_market_subs, все ключи и соединения вместе). limit, remaining: 0, scope: "account", window: "concurrent". Снимите лишнюю — unsubscribe со scope: "market" — или смените тариф |
route_not_in_plan |
группа канала не в тарифе; без instrument и channel — тариф лишился группы ws: закрытие 1008 |
too_many_subscriptions |
больше 200 подписок на соединение; команда отвергнута целиком. limit и remaining — сколько можно и сколько осталось |
rate_limited |
сверх 10 команд в секунду и запаса 20; команда пропущена. scope: "connection", window: "second". То же у рыночной подписки канала, открытой на соединении чаще раза в секунду, заменой или снятием с повторной подпиской: limit: 1, remaining: 0, retry_after — секунд до следующего открытия, прежняя подписка, если она есть, остаётся |
ws_limit |
слот соединения потерян: у аккаунта открыто больше соединений, чем ws_conns тарифа. window: "concurrent", retry_after: 5; закрытие 1013 |
slow_consumer |
клиент не успевает читать: очередь переполнена, кадр рыночной подписки не встал в очередь за 10 секунд, очередь забита целиком дольше 10 секунд и ответу на команду некуда встать или накопленные изменения вышли за потолок шлюза. Закрытие 1008 |
daily_quota_exceeded |
кончился суточный объём: limit, remaining: 0, window: "bytes_day", scope — account или route:<группа>. Открытое соединение закрывается 1008, новая рыночная подписка получает отказ тем же кодом |
revoked_key, plan_inactive, invalid_key, insufficient_scope |
доступ кончился посреди соединения: закрытие 1008 с кодом в причине |
Поток опционов /v1/options/stream кадров error не шлёт: отказы приходят HTTP-ответом до апгрейда, закрытия — кодом и причиной (4008, 1011, 1001, 1013, 1008), подробно — живой поток.
Подробно — Потоки WebSocket.
https://docs.lootx.trade/hy/market-api/error-codes