{"openapi": "3.1.0", "info": {"title": "HYPERLIQUIDATED \u2014 /api/v2", "version": "2.0.0", "description": "A read-only Hyperliquid terminal's machine lane. Every route is a bounded, indexed, ascending keyset walk of one table. Nothing here calls Hyperliquid and nothing here writes. THE THREE WORDS: tracked = the wallets we watch (anyone who has printed since meta.feed_started_ms), never the venue's total. anchored = the position was read from Hyperliquid's clearinghouseState and is exact. inferred = our own running net since the tape started, which is NOT a position. anchoring = we have not read it yet. UNITS: a field ending _ms is milliseconds since the Unix epoch UTC, _usd is dollars, _pct is percent, _s is seconds. HORIZON: the `tape` table is pruned at 48h; tape_ctx, coin_min, fills, coin_snap and wallet_snap are kept for ever. No field here is a badge, a score or a forecast."}, "servers": [{"url": "http://127.0.0.1:8791"}], "paths": {"/api/v2/books": {"get": {"summary": "Every tracked wallet's WHOLE OPEN BOOK, one row, ordered by how much of the market it leans on.", "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..500 (default 25)"}, {"name": "min_gross", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only books worth at least this many dollars of open notional; default 5,000,000"}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows to skip -- page with `next.offset`"}, {"name": "sort", "in": "query", "required": false, "schema": {"type": "string"}, "description": "influence (default) / gross / net_short / net_long / unrealized. `sorts` in the reply says what each one means."}, {"name": "tier", "in": "query", "required": false, "schema": {"type": "string"}, "description": "whale / large / small. Omit for every tier."}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "the units, the ordering and the read-age semantics"}, "sort": {"type": "string", "description": "the sort actually applied"}, "sorts": {"type": "object", "description": "every sort this route accepts and what each means, so a caller can name the one in force"}, "min_gross_usd": {"type": "number", "description": "the floor actually applied, in dollars"}, "tier": {"type": "string", "description": "the tier filter applied, or null"}, "limit": {"type": "integer", "description": "the clamped limit actually used"}, "offset": {"type": "integer", "description": "the offset actually used"}, "n": {"type": "integer", "description": "rows returned"}, "now_ms": {"type": "integer", "description": "the moment this answer was built, milliseconds UTC"}, "books": {"type": "array", "description": "the books, in the sort named above", "items": {"type": "object", "properties": {"addr": {"type": "string", "description": "the wallet's address"}, "label": {"type": "string", "description": "our label for it, or null. Never guessed."}, "tier": {"type": "string", "description": "whale / large / small -- by the size it trades"}, "account_value_usd": {"type": "number", "description": "the account value Hyperliquid reported at the last read, or null if we have never read it"}, "long_usd": {"type": "number", "description": "open notional held LONG across every coin"}, "short_usd": {"type": "number", "description": "open notional held SHORT across every coin"}, "gross_usd": {"type": "number", "description": "long plus short: the whole open book"}, "net_usd": {"type": "number", "description": "long minus short. Negative is a net short book."}, "net_lean": {"type": "number", "description": "net_usd / gross_usd, between -1 and +1: how one-sided the book is"}, "influence_usd": {"type": "number", "description": "gross x (1 + |net_lean|) = gross + |net|. One-sided open notional, in dollars. A size, not a score."}, "long_share_pct": {"type": "number", "description": "the share of the book that is long"}, "n_coins": {"type": "integer", "description": "how many coins the book is spread across"}, "lev_max": {"type": "number", "description": "the highest leverage on any one leg"}, "unrealized_usd": {"type": "number", "description": "unrealised p/l across the whole book at the mark. A bet, not a win."}, "biggest": {"type": "object", "description": "the largest leg: coin, side, usd"}, "nearest_liq": {"type": "object", "description": "the leg whose mark is closest to its own liquidation price: coin, side, liq_px, mark, dist_to_liq_pct"}, "change_24h_usd": {"type": "number", "description": "how the NET moved over 24h, from the book snapshots. null when we have not snapped it twice -- unknown, not zero."}, "change_1h_usd": {"type": "number", "description": "how the NET moved over the last hour, from the same source"}, "change_24h_span_s": {"type": "integer", "description": "the seconds the 24h change was actually measured over -- the oldest snapshot inside 24h to the newest"}, "change_1h_span_s": {"type": "integer", "description": "the seconds the 1h change was measured over"}, "read_ms": {"type": "integer", "description": "when this wallet's positions were last read from the venue, milliseconds UTC"}, "read_age_s": {"type": "integer", "description": "seconds since that read"}, "stale": {"type": "boolean", "description": "true when the read is over 2h old"}, "phrase": {"type": "string", "description": "the book in six words: \"$37.6m short, 6 coins\""}}}}, "more": {"type": "boolean", "description": "true when the page was full: ask for the next one"}, "next": {"type": "object", "description": "the offset to send next, or null"}}, "required": ["books", "limit", "min_gross_usd", "more", "n", "next", "note", "now_ms", "offset", "sort", "sorts", "tier"]}}}}}}}, "/api/v2/books/{addr}": {"get": {"summary": "One wallet's book position by position, the events it generated, and how well we have actually been reading it.", "parameters": [{"name": "addr", "in": "path", "required": true, "schema": {"type": "string"}, "description": "the wallet, 0x\u2026, lower-cased"}, {"name": "addr", "in": "query", "required": false, "schema": {"type": "string"}, "description": "the wallet, lower-cased, in the path"}, {"name": "events", "in": "query", "required": false, "schema": {"type": "string"}, "description": "24h (default) or 7d -- the event window"}, {"name": "min_leg", "in": "query", "required": false, "schema": {"type": "number"}, "description": "hide positions smaller than this many dollars"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "the units and the read-age semantics"}, "events_note": {"type": "string", "description": "the PROVISIONAL event rules, in full"}, "addr": {"type": "string", "description": "the wallet asked for"}, "label": {"type": "string", "description": "our label for it, or null"}, "tier": {"type": "string", "description": "whale / large / small"}, "account_usd": {"type": "number", "description": "the account value at the last read"}, "read_ms": {"type": "integer", "description": "when the positions were read, milliseconds UTC"}, "age_s": {"type": "integer", "description": "seconds since that read"}, "read_age_s": {"type": "integer", "description": "the same, under the name every other v2 row uses"}, "stale": {"type": "boolean", "description": "true when the read is over 2h old"}, "notional_usd": {"type": "number", "description": "the whole open book, long plus short"}, "long_usd": {"type": "number", "description": "open notional held long"}, "short_usd": {"type": "number", "description": "open notional held short"}, "net_side": {"type": "string", "description": "long or short -- which way the book leans"}, "n_coins": {"type": "integer", "description": "how many coins it is spread across"}, "unreal_usd": {"type": "number", "description": "unrealised p/l across the whole book"}, "influence_usd": {"type": "number", "description": "gross + |net|, in dollars, as on the board. A size, not a score -- and not the same quantity as `influence` on an event row"}, "now_ms": {"type": "integer", "description": "the moment this answer was built, milliseconds UTC"}, "positions": {"type": "array", "description": "one row per coin, biggest first", "items": {"type": "object", "properties": {"coin": {"type": "string", "description": "the perpetual this position is in"}, "side": {"type": "string", "description": "long or short"}, "szi": {"type": "number", "description": "the signed size in coin units"}, "entry_px": {"type": "number", "description": "the average price it was built at"}, "mark": {"type": "number", "description": "the price the venue marks it at now"}, "notional_usd": {"type": "number", "description": "open notional, in dollars"}, "unreal_usd": {"type": "number", "description": "unrealised p/l at the mark"}, "margin_usd": {"type": "number", "description": "the margin the venue reports behind this leg"}, "margin_mode": {"type": "string", "description": "cross or isolated, as the venue says; null on reads taken before it was captured"}, "roe_pct": {"type": "number", "description": "the venue's own return on equity x 100. In a CROSS book this can pass -100% without a liquidation, because the whole account stands behind the leg"}, "pct_margin": {"type": "number", "description": "unrealised p/l over the leg's margin, ONLY for an isolated leg (where -100% is the liquidation); null for cross"}, "pct_account": {"type": "number", "description": "unrealised p/l over the account value at that read, ONLY for a cross leg; null for isolated"}, "account_value_usd": {"type": "number", "description": "the account value that denominator used"}, "pct_notional": {"type": "number", "description": "unrealised p/l as a percent of the notional"}, "liq_px": {"type": "number", "description": "the price at which this leg is liquidated"}, "dist_to_liq_pct": {"type": "number", "description": "how far the mark is from that, percent"}, "leverage": {"type": "number", "description": "the leverage on this leg"}, "delta_24h_usd": {"type": "number", "description": "how this leg's signed notional moved over the window, from the leg snapshots. null when we have not snapped it -- unknown, not zero."}, "delta_span_s": {"type": "integer", "description": "the seconds that change was ACTUALLY measured over -- the oldest to the newest snapshot of this leg inside the window; a 22-minute span is a 22-minute change, whatever the window"}, "read_ms": {"type": "integer", "description": "when this leg was read, milliseconds UTC"}, "read_age_s": {"type": "integer", "description": "seconds since that read"}, "stale": {"type": "boolean", "description": "true when the read is over 2h old"}}}}, "events_24h": {"type": "array", "description": "the events this book generated in the window"}, "n_events": {"type": "integer", "description": "how many that was"}, "events_window": {"type": "string", "description": "the window the events cover"}, "coverage": {"type": "object", "description": "reads_24h and oldest_read_ms: fewer reads is fewer events, not a quieter wallet"}}, "required": ["account_usd", "addr", "age_s", "coverage", "events_24h", "events_note", "events_window", "influence_usd", "label", "long_usd", "n_coins", "n_events", "net_side", "note", "notional_usd", "now_ms", "positions", "read_age_s", "read_ms", "short_usd", "stale", "tier", "unreal_usd"]}}}}}}}, "/api/v2/coin_books": {"get": {"summary": "Who holds one coin and where they got in. `entry_gte` answers \"who is short XRP above 1.40\" in one call.", "parameters": [{"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "the perp, upper-cased. Required."}, {"name": "entry_gte", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only legs whose ENTRY price is at or above this"}, {"name": "entry_lte", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only legs whose ENTRY price is at or below this"}, {"name": "event_type", "in": "query", "required": false, "schema": {"type": "string"}, "description": "comma list of offload,build,flip,open,close -- which events `last_event` may report"}, {"name": "events", "in": "query", "required": false, "schema": {"type": "string"}, "description": "1h / 24h (default) / 7d -- the window `last_event` looks back over"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..200 (default 50)"}, {"name": "min_book", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only wallets whose WHOLE book is at least this big"}, {"name": "min_notional", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only legs worth at least this many dollars; default 100,000"}, {"name": "side", "in": "query", "required": false, "schema": {"type": "string"}, "description": "long or short. Omit for both."}, {"name": "sort", "in": "query", "required": false, "schema": {"type": "string"}, "description": "notional (default) / entry / pct_margin / influence"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "the units and the read-age semantics"}, "events_note": {"type": "string", "description": "the PROVISIONAL event rules, in full"}, "coin": {"type": "string", "description": "the coin asked for"}, "mark": {"type": "number", "description": "the price the venue marks this coin at now"}, "as_of_ms": {"type": "integer", "description": "the moment this answer was built, ms UTC"}, "side": {"type": "string", "description": "the side filter applied, or null"}, "sort": {"type": "string", "description": "the sort actually applied"}, "min_notional": {"type": "number", "description": "the leg floor applied, in dollars"}, "min_book": {"type": "number", "description": "the whole-book floor applied, in dollars"}, "entry_gte": {"type": "number", "description": "the entry-price floor applied, or null"}, "entry_lte": {"type": "number", "description": "the entry-price ceiling applied, or null"}, "limit": {"type": "integer", "description": "the clamped limit actually used"}, "n": {"type": "integer", "description": "rows returned"}, "coverage": {"type": "object", "description": "books_read / books_total / pct: how many of the legs in this coin belong to a wallet we have read in the last 2h"}, "legs": {"type": "array", "description": "the legs, in the sort named above", "items": {"type": "object", "properties": {"addr": {"type": "string", "description": "the wallet's address"}, "label": {"type": "string", "description": "our label for it, or null"}, "tier": {"type": "string", "description": "whale / large / small"}, "side": {"type": "string", "description": "long or short"}, "szi": {"type": "number", "description": "the signed size in coin units"}, "entry_px": {"type": "number", "description": "the average price this leg was built at"}, "mark": {"type": "number", "description": "the price the venue marks it at now"}, "notional_usd": {"type": "number", "description": "open notional of this leg, in dollars"}, "unreal_usd": {"type": "number", "description": "unrealised p/l on this leg at the mark"}, "margin_usd": {"type": "number", "description": "the margin actually behind this leg"}, "pct_margin": {"type": "number", "description": "unrealised p/l as a percent of that margin"}, "pct_notional": {"type": "number", "description": "unrealised p/l as a percent of notional"}, "liq_px": {"type": "number", "description": "the price at which this leg is liquidated"}, "dist_to_liq_pct": {"type": "number", "description": "how far the mark is from that, percent"}, "leverage": {"type": "number", "description": "the leverage on this leg"}, "book_notional_usd": {"type": "number", "description": "the wallet's WHOLE book, so a $6m leg inside a $600m book is not read as a $6m wallet"}, "last_event": {"type": "object", "description": "the newest event this wallet had in this coin inside the window, or null"}, "read_ms": {"type": "integer", "description": "when the position was read, milliseconds UTC"}, "read_age_s": {"type": "integer", "description": "seconds since that read"}, "stale": {"type": "boolean", "description": "true when the read is over 2h old"}}}}, "totals": {"type": "object", "description": "long_usd, short_usd, net_usd and n_legs over the rows actually returned"}, "whale_lean": {"type": "object", "description": "whale-tier wallets long against short in this coin, by count and by dollars, with the 24h change in the dollar split"}}, "required": ["as_of_ms", "coin", "coverage", "entry_gte", "entry_lte", "events_note", "legs", "limit", "mark", "min_book", "min_notional", "n", "note", "side", "sort", "totals", "whale_lean"]}}}}}}}, "/api/v2/book_events": {"get": {"summary": "The whale tape: what the big books DID between two position reads. Never from fills.", "parameters": [{"name": "addr", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one wallet, lower-cased"}, {"name": "after_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "the id of the row at after_ts_ms you already hold, so rows sharing that millisecond are not re-sent"}, {"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "walk FORWARDS: only events newer than this ts_ms (with after_id), oldest first. The \"what is new since\" call for an agent."}, {"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one coin, upper-cased. Omit for every coin."}, {"name": "cursor", "in": "query", "required": false, "schema": {"type": "string"}, "description": "`next` from the previous page: ts_ms:id of the last row you saw. Walks BACKWARDS (older). sort=time only."}, {"name": "dir", "in": "query", "required": false, "schema": {"type": "string"}, "description": "long or short -- the side the leg ended on"}, {"name": "ev", "in": "query", "required": false, "schema": {"type": "string"}, "description": "comma list of offload,build,flip,open,close"}, {"name": "group", "in": "query", "required": false, "schema": {"type": "string"}, "description": "hour or none (default). DISPLAY ONLY -- every event is still returned; `group` is filled in."}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..500 (default 100)"}, {"name": "min_book", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only books at least this big after the move; default 5,000,000"}, {"name": "min_leg", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only moves of at least this many dollars; default 500,000, which is the STORED floor"}, {"name": "min_pct", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only moves of at least this fraction of the leg; default 0.10, which is the STORED floor"}, {"name": "sort", "in": "query", "required": false, "schema": {"type": "string"}, "description": "time (default, newest first) or influence"}, {"name": "window", "in": "query", "required": false, "schema": {"type": "string"}, "description": "1h / 24h (default) / 7d"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "the units and the read-age semantics"}, "events_note": {"type": "string", "description": "the PROVISIONAL rules and their thresholds"}, "kinds": {"type": "object", "description": "every event kind and the rule that fires it"}, "window": {"type": "string", "description": "the window actually used"}, "coin": {"type": "string", "description": "the coin filter applied, or null"}, "dir": {"type": "string", "description": "the side filter applied, or null"}, "ev": {"type": "array", "description": "the event kinds actually filtered on"}, "addr": {"type": "string", "description": "the wallet filter applied, or null"}, "min_book": {"type": "number", "description": "the book floor applied, in dollars"}, "min_leg": {"type": "number", "description": "the move floor applied, in dollars"}, "min_pct": {"type": "number", "description": "the move floor applied, as a fraction"}, "group": {"type": "string", "description": "hour or none"}, "sort": {"type": "string", "description": "the sort actually applied"}, "limit": {"type": "integer", "description": "the clamped limit actually used"}, "n": {"type": "integer", "description": "rows returned"}, "now_ms": {"type": "integer", "description": "the moment this answer was built, ms UTC"}, "events": {"type": "array", "description": "the events", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "the event's own row id, and the cursor tie-break"}, "ts_ms": {"type": "integer", "description": "the later read, milliseconds UTC"}, "read_prev_ms": {"type": "integer", "description": "the earlier read this was measured against"}, "read_ms": {"type": "integer", "description": "the later read -- the same as ts_ms, named so a reader never has to assume it"}, "addr": {"type": "string", "description": "the wallet whose book moved"}, "label": {"type": "string", "description": "our label for it, or null"}, "tier": {"type": "string", "description": "whale / large / small"}, "event": {"type": "string", "description": "OFFLOADING / BUILDING / FLIPPED / OPENED / CLOSED"}, "coin": {"type": "string", "description": "the leg that moved"}, "side": {"type": "string", "description": "long / short / flat, after the move"}, "delta_usd": {"type": "number", "description": "the SIZE change priced at one mark: positive is bigger, negative is smaller. A mark move on an unchanged position is zero here. On a FLIPPED row it is what was TRADED -- the old leg plus the new one -- signed by the side it ended on."}, "delta_pct": {"type": "number", "description": "that change as a percent of the leg's own size at the earlier read; null on a FLIPPED row"}, "mark": {"type": "number", "description": "the mark at the later read -- not now"}, "szi_prev": {"type": "number", "description": "signed size in coin units at the earlier read"}, "szi_after": {"type": "number", "description": "signed size in coin units at the later read"}, "notional_prev": {"type": "number", "description": "the leg's notional at the earlier read"}, "notional_after": {"type": "number", "description": "the leg's notional at the later read"}, "mark_prev": {"type": "number", "description": "the mark at the earlier read"}, "mark_after": {"type": "number", "description": "the mark at the later read"}, "book_after": {"type": "object", "description": "net_side, notional_usd, long_usd, short_usd, n_coins -- the whole book straight afterwards"}, "book_before": {"type": "object", "description": "the same five for the book at the EARLIER read, so influence can be replayed from the row; null on rows written before it was stored"}, "coin_notional_usd": {"type": "number", "description": "tracked open notional in that coin at the scan (reads under 2h old) -- the share denominator behind influence"}, "pnl_at_event": {"type": "object", "description": "unreal_usd (the VENUE's own unrealised p/l at that read, never a later mark), margin_usd, margin_mode, roe_pct (the venue's ROE x 100), pct_margin (isolated legs only), pct_account (cross legs only), account_value_usd, pct_notional"}, "influence": {"type": "number", "description": "|delta_usd| x min(1, the leg's share of tracked notional in that coin, larger of the two reads) x min(1, the larger book of the two reads / $100m). Ties break by ts_ms desc, addr, id desc. A size in dollars, not a score."}, "group_key": {"type": "string", "description": "address + hour bucket, so a screen can collapse a wallet's hour without inventing a grouping"}, "group": {"type": "object", "description": "n, span_ms and coins for that hour when group=hour; null otherwise. DISPLAY ONLY."}, "anchored": {"type": "boolean", "description": "true: a book event can only come from a clearinghouseState read, never from our tape"}, "text": {"type": "string", "description": "the event in one plain-English line"}, "read_gap_s": {"type": "integer", "description": "seconds between the two reads the event was measured between -- the change happened somewhere inside that gap"}, "wallet_read_age_s": {"type": "integer", "description": "seconds since this WALLET's positions were last read, now -- the freshness of the book, as opposed to the age of the event"}, "wallet_stale": {"type": "boolean", "description": "true when that latest read is over 2h old, or we never read it"}, "read_age_s": {"type": "integer", "description": "seconds since the later read"}, "stale": {"type": "boolean", "description": "true when that read is over 2h old -- which most rows of a 24h or 7d feed are, by construction. It is the age of the read, not a fault."}}}}, "more": {"type": "boolean", "description": "true when the page was full"}, "cursor": {"type": "string", "description": "the cursor that was sent, or null"}, "next": {"type": "string", "description": "the cursor to send for the next page, or null"}, "after_ts_ms": {"type": "integer", "description": "the forward cursor that was sent, or null"}, "after_id": {"type": "integer", "description": "the forward tie-break that was sent, or null"}, "cursor_note": {"type": "string", "description": "which way each cursor walks"}, "thresholds_note": {"type": "string", "description": "which floors are STORED and which merely filter the stored set down"}}, "required": ["addr", "after_id", "after_ts_ms", "coin", "cursor", "cursor_note", "dir", "ev", "events", "events_note", "group", "kinds", "limit", "min_book", "min_leg", "min_pct", "more", "n", "next", "note", "now_ms", "sort", "thresholds_note", "window"]}}}}}}}, "/api/v2/tape": {"get": {"summary": "Every print on the venue, ascending, keyset-cursored. wait= long-polls for the next one.", "parameters": [{"name": "after_tid", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: tid of the last row you saw. Send it with after_ts_ms or prints sharing that millisecond are re-sent."}, {"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: ts_ms of the last row you saw. 0 = start at the oldest retained print."}, {"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one coin, upper-cased. Omit for every coin."}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..500 (default 200)"}, {"name": "min_usd", "in": "query", "required": false, "schema": {"type": "number"}, "description": "only prints worth at least this many dollars"}, {"name": "wait", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "seconds to hold the request open when there is nothing new, clamped 0..25"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "window, units and the tracked/anchored semantics"}, "coin": {"type": "string", "description": "the coin filter that was applied, or null"}, "limit": {"type": "integer", "description": "the clamped limit actually used"}, "n": {"type": "integer", "description": "rows returned"}, "rows": {"type": "array", "description": "the prints, oldest first", "items": {"type": "object", "properties": {"tid": {"type": "integer", "description": "Hyperliquid's own trade id; unique, and the tie-break"}, "ts_ms": {"type": "integer", "description": "print time, milliseconds UTC"}, "coin": {"type": "string", "description": "the perpetual this print was in"}, "side": {"type": "string", "description": "buy or sell -- the AGGRESSOR's side"}, "px": {"type": "number", "description": "the price the print traded at"}, "sz": {"type": "number", "description": "the size of the print, in coin units"}, "usd": {"type": "number", "description": "dollar value of the print"}, "addr": {"type": "string", "description": "the aggressor's address"}, "label": {"type": "string", "description": "our label for that address, or null"}, "tier": {"type": "string", "description": "whale / large / small"}, "bot": {"type": "boolean", "description": "flagged as a machine by the behaviour test"}, "buyer": {"type": "string", "description": "the buying address"}, "seller": {"type": "string", "description": "the selling address"}, "buyer_tier": {"type": "string", "description": "the buyer's tier"}, "seller_tier": {"type": "string", "description": "the seller's tier"}, "kind": {"type": "string", "description": "open / add / reduce / close / flip / none, for the aggressor. null until the walk reaches the print."}, "effect": {"type": "string", "description": "what the print did, in English. null until walked."}, "pos_after_usd": {"type": "number", "description": "the aggressor's position in this coin after the print, in dollars. null until walked."}, "anchored": {"type": "boolean", "description": "the position behind this row came from Hyperliquid's own clearinghouseState"}, "anchor_state": {"type": "string", "description": "exactly one of anchored / inferred / anchoring"}, "walked": {"type": "boolean", "description": "the context walk has reached this print"}, "vs_24h": {"type": "number", "description": "percent from the nearer 24h extreme"}, "vs_ref": {"type": "string", "description": "which extreme vs_24h is measured from"}, "level": {"type": "string", "description": "AT-HIGH / AT-LOW / ROUND / null, within 0.5 percent"}, "pnl": {"type": "number", "description": "realised dollars on this print, when it closed size"}, "cp_kind": {"type": "string", "description": "the counterparty's own position effect kind"}, "cp_effect": {"type": "string", "description": "the counterparty's own effect, in English"}}}}, "next": {"type": "object", "description": "the cursor to send next: after_ts_ms, after_tid"}, "more": {"type": "boolean", "description": "true when the page was full: ask again immediately"}, "waited_s": {"type": "number", "description": "seconds this request was held open"}}, "required": ["coin", "limit", "more", "n", "next", "note", "rows", "waited_s"]}}}}}}}, "/api/v2/history": {"get": {"summary": "The permanent record: tape_ctx alone, unaffected by the 48h tape prune.", "parameters": [{"name": "addr", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one wallet, lower-cased. Omit for every wallet."}, {"name": "after_addr", "in": "query", "required": false, "schema": {"type": "string"}, "description": "cursor: addr of the last row you saw -- one print can be two rows"}, {"name": "after_tid", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: tid of the last row you saw"}, {"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: ts_ms of the last row you saw"}, {"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one coin, upper-cased. Omit for every coin."}, {"name": "from_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window start, milliseconds UTC"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..500 (default 200)"}, {"name": "to_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window end, milliseconds UTC"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "which fields die with the 48h prune, and the units"}, "coin": {"type": "string", "description": "the coin filter, or null"}, "addr": {"type": "string", "description": "the wallet filter, or null"}, "from_ms": {"type": "integer", "description": "window start actually used, milliseconds UTC"}, "to_ms": {"type": "integer", "description": "window end actually used, milliseconds UTC"}, "span_capped": {"type": "boolean", "description": "true when your window was longer than the 24h per-call maximum and was cut"}, "n": {"type": "integer", "description": "rows returned"}, "rows": {"type": "array", "description": "the context rows, oldest first", "items": {"type": "object", "properties": {"tid": {"type": "integer", "description": "the trade id this context row belongs to"}, "ts_ms": {"type": "integer", "description": "print time, milliseconds UTC"}, "coin": {"type": "string", "description": "the perpetual this row is about"}, "addr": {"type": "string", "description": "the wallet this row is about"}, "kind": {"type": "string", "description": "open / add / reduce / close / flip / none"}, "effect": {"type": "string", "description": "what the print did to this wallet, in English"}, "pos_before": {"type": "number", "description": "position in coin units before the print, signed"}, "pos_after": {"type": "number", "description": "position in coin units after the print, signed"}, "pos_after_usd": {"type": "number", "description": "position after the print, in dollars"}, "anchored": {"type": "boolean", "description": "Hyperliquid's own number stood behind the walk"}, "anchor_state": {"type": "string", "description": "anchored or inferred; a row exists only because the walk reached the print, so `anchoring` cannot appear here"}, "vs_24h": {"type": "number", "description": "percent from the nearer 24h extreme at the print"}, "vs_ref": {"type": "string", "description": "which extreme vs_24h is measured from"}, "level": {"type": "string", "description": "AT-HIGH / AT-LOW / ROUND / null"}, "pnl": {"type": "number", "description": "realised dollars on this print"}, "minute_ms": {"type": "integer", "description": "start of the print's minute, milliseconds UTC"}, "minute_o": {"type": "number", "description": "that minute's open, from coin_min"}, "minute_h": {"type": "number", "description": "that minute's high, from coin_min"}, "minute_l": {"type": "number", "description": "that minute's low, from coin_min"}, "minute_c": {"type": "number", "description": "that minute's close, from coin_min"}, "minute_n": {"type": "integer", "description": "prints in that minute, from coin_min"}}}}, "next": {"type": "object", "description": "the cursor: after_ts_ms, after_tid, after_addr"}, "more": {"type": "boolean", "description": "true when the page was full"}}, "required": ["addr", "coin", "from_ms", "more", "n", "next", "note", "rows", "span_capped", "to_ms"]}}}}}}}, "/api/v2/coin_history": {"get": {"summary": "One coin's minutes or five-minute buckets, off our own tape. Kept for ever.", "parameters": [{"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: ts_ms of the last bucket you saw"}, {"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "the perp, upper-cased"}, {"name": "from_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window start, milliseconds UTC"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "buckets, clamped 1..2000 (default 500)"}, {"name": "res", "in": "query", "required": false, "schema": {"type": "string"}, "description": "1m or 5m; anything else resolves to 1m"}, {"name": "to_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window end, milliseconds UTC"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "units, the tracked semantics of long_share, and the 7-day per-call cap"}, "coin": {"type": "string", "description": "the coin, or null when none was given"}, "res": {"type": "string", "description": "the resolution actually used"}, "from_ms": {"type": "integer", "description": "window start actually used, milliseconds UTC"}, "to_ms": {"type": "integer", "description": "window end actually used, milliseconds UTC"}, "span_capped": {"type": "boolean", "description": "true when your window exceeded 7 days and was cut"}, "n": {"type": "integer", "description": "buckets returned"}, "rows": {"type": "array", "description": "the buckets, oldest first", "items": {"type": "object", "properties": {"ts_ms": {"type": "integer", "description": "the bucket's START, milliseconds UTC"}, "o": {"type": "number", "description": "the first price in the bucket"}, "h": {"type": "number", "description": "the highest price in the bucket"}, "l": {"type": "number", "description": "the lowest price in the bucket"}, "c": {"type": "number", "description": "the last price in the bucket"}, "buy_usd": {"type": "number", "description": "dollars of aggressor buying in the bucket"}, "sell_usd": {"type": "number", "description": "dollars of aggressor selling in the bucket"}, "n": {"type": "integer", "description": "how many prints landed in the bucket"}, "wallets": {"type": "integer", "description": "distinct addresses in the bucket"}, "long_share": {"type": "number", "description": "TRACKED long share of the coin at the bucket, 0..1, from coin_snap. res=5m only; null when no snapshot exists. Never the venue's total."}}}}, "next": {"type": "object", "description": "the cursor to send next: after_ts_ms"}, "more": {"type": "boolean", "description": "true when there is another page"}}, "required": ["coin", "from_ms", "more", "n", "next", "note", "res", "rows", "span_capped", "to_ms"]}}}}}}}, "/api/v2/wallet/{addr}/fills": {"get": {"summary": "One tracked wallet's fills, ascending, keyset-cursored.", "parameters": [{"name": "addr", "in": "path", "required": true, "schema": {"type": "string"}, "description": "the wallet, 0x\u2026, lower-cased"}, {"name": "after_id", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: id of the last fill you saw"}, {"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: ts_ms of the last fill you saw"}, {"name": "coin", "in": "query", "required": false, "schema": {"type": "string"}, "description": "one coin, upper-cased"}, {"name": "from_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window start, milliseconds UTC"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..500 (default 200)"}, {"name": "spot", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "1 to include spot and tokenised equities; perps only by default"}, {"name": "to_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window end, milliseconds UTC"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "units, provisional semantics, perps-only default"}, "addr": {"type": "string", "description": "the wallet, lower-cased"}, "coin": {"type": "string", "description": "the coin filter, or null"}, "from_ms": {"type": "integer", "description": "window start actually used, milliseconds UTC"}, "to_ms": {"type": "integer", "description": "window end actually used, milliseconds UTC"}, "spot": {"type": "boolean", "description": "whether spot rows were included"}, "n": {"type": "integer", "description": "rows returned"}, "rows": {"type": "array", "description": "the fills, oldest first", "items": {"type": "object", "properties": {"id": {"type": "integer", "description": "our own row id, the cursor's tie-break"}, "tid": {"type": "integer", "description": "Hyperliquid's trade id"}, "ts_ms": {"type": "integer", "description": "fill time, milliseconds UTC"}, "coin": {"type": "string", "description": "the instrument the fill was in"}, "side": {"type": "string", "description": "buy or sell, this wallet's own side"}, "px": {"type": "number", "description": "the price the fill traded at"}, "sz": {"type": "number", "description": "the size of the fill, in coin units"}, "usd": {"type": "number", "description": "dollar value of the fill"}, "dir": {"type": "string", "description": "HYPERLIQUID's own description of the fill"}, "start_position": {"type": "number", "description": "the venue's own position before the fill"}, "closed_pnl": {"type": "number", "description": "the venue's own realised dollars on the fill"}, "fee": {"type": "number", "description": "the fee charged, in dollars"}, "fee_token": {"type": "string", "description": "the token the fee was charged in"}, "provisional": {"type": "boolean", "description": "came off our own tape, not yet confirmed by the venue's fills"}, "spot": {"type": "boolean", "description": "a spot or tokenised-equity fill, not a perp"}, "asset": {"type": "string", "description": "the asset class we classified it as"}}}}, "next": {"type": "object", "description": "the cursor to send next: after_ts_ms, after_id"}, "more": {"type": "boolean", "description": "true when the page was full"}}, "required": ["addr", "coin", "from_ms", "more", "n", "next", "note", "rows", "spot", "to_ms"]}}}}}}}, "/api/v2/wallet/{addr}/snapshots": {"get": {"summary": "One wallet's hourly account snapshots.", "parameters": [{"name": "addr", "in": "path", "required": true, "schema": {"type": "string"}, "description": "the wallet, 0x\u2026, lower-cased"}, {"name": "after_ts_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "cursor: ts_ms of the last snapshot you saw"}, {"name": "from_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window start, milliseconds UTC"}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "rows, clamped 1..1000 (default 500)"}, {"name": "to_ms", "in": "query", "required": false, "schema": {"type": "integer"}, "description": "window end, milliseconds UTC"}], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"note": {"type": "string", "description": "units, and that a snapshot is never re-marked"}, "addr": {"type": "string", "description": "the wallet, lower-cased"}, "from_ms": {"type": "integer", "description": "window start actually used, milliseconds UTC"}, "to_ms": {"type": "integer", "description": "window end actually used, milliseconds UTC"}, "n": {"type": "integer", "description": "rows returned"}, "rows": {"type": "array", "description": "the snapshots, oldest first", "items": {"type": "object", "properties": {"ts_ms": {"type": "integer", "description": "snapshot time, milliseconds UTC"}, "tier": {"type": "string", "description": "whale / large / small at that moment"}, "account_value_usd": {"type": "number", "description": "account value in dollars"}, "notional_usd": {"type": "number", "description": "open notional in dollars"}, "n_pos": {"type": "integer", "description": "open positions"}, "unrealized_usd": {"type": "number", "description": "unrealised dollars as of ts_ms, never re-marked since"}, "long_usd": {"type": "number", "description": "dollars of long exposure"}, "short_usd": {"type": "number", "description": "dollars of short exposure"}}}}, "next": {"type": "object", "description": "the cursor to send next: after_ts_ms"}, "more": {"type": "boolean", "description": "true when the page was full"}}, "required": ["addr", "from_ms", "more", "n", "next", "note", "rows", "to_ms"]}}}}}}}, "/api/v2/openapi.json": {"get": {"summary": "This registry, as OpenAPI. Generated, never hand-written.", "parameters": [], "responses": {"200": {"description": "ok", "content": {"application/json": {"schema": {"type": "object", "properties": {"openapi": {"type": "string", "description": "the OpenAPI version"}, "info": {"type": "object", "description": "title, version, the three words and the units"}, "servers": {"type": "array", "description": "where this API is served"}, "paths": {"type": "object", "description": "one entry per v2 route"}}, "required": ["info", "openapi", "paths", "servers"]}}}}}}}, "/llms.txt": {"get": {"summary": "What this product is and which route answers which question. Plain text, not JSON.", "parameters": [], "responses": {"200": {"description": "ok", "content": {"text/plain": {"schema": {"type": "string"}}}}}}}}}