HMP1 և HMP2 ֆորմատներ
1HMP1 և 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