{
 "venue": "hyperliquid",
 "generated_at": "2026-10-22T12:56:48Z",
 "license": {
  "name": "CC BY 4.0",
  "url": "https://creativecommons.org/licenses/by/4.0/",
  "attribution": "Hyperliquid archive (c) Vike (vike.io/data), CC BY 4.0",
  "note": "Applies to the DATA files this manifest indexes. It grants no rights to any Vike source code."
 },
 "note": "Free samples of the Hyperliquid Parquet archive, no key needed: `BTC` on one published day (`sample.date`), `sample_covers` per dataset (fills: every fill of the first UTC hour; positions: every open position at the day's first snapshot, one instant, all wallets). Cut by the same SQL as the daily files, so the columns, their order and types and the sort order are the daily files'. Rebuilt about once a week. Per-day row and snapshot counts and the rebuilt hours are in GET /v1/hyperliquid/archive/datasets.",
 "full_files": "The full daily files need an API key: GET /v1/hyperliquid/archive/url?dataset=<fills|positions>&date=YYYY-MM-DD answers with a temporary download link for one file.",
 "sample": {
  "date": "2026-10-21",
  "asset": "BTC",
  "files": [
   "fills-sample.parquet",
   "positions-sample.parquet"
  ]
 },
 "datasets": {
  "fills": {
   "description": "Every fill of every wallet on the day, one row per (wallet, fill).",
   "note": "A fill is identified by (wallet, fill_ts, trade_id). The two counterparties of a trade share trade_id, so a trade appears twice, once per wallet.",
   "sorted_by": "asset, fill_ts, trade_id, wallet",
   "published": {
    "from": "2026-05-01",
    "to": "2026-10-21",
    "days": 174
   },
   "sample_file": "fills-sample.parquet",
   "sample_covers": "one hour: every BTC row with `fill_ts` in 00:00-01:00 UTC",
   "schema": [
    {
     "name": "fill_ts",
     "type": "DateTime64(3, 'UTC')",
     "description": "Execution time of the fill, UTC, millisecond precision."
    },
    {
     "name": "wallet",
     "type": "String",
     "description": "Trader address, lowercase 0x-hex."
    },
    {
     "name": "asset",
     "type": "String",
     "description": "Instrument as Hyperliquid names it: `BTC` on the main dex, `dex:NAME` (e.g. `xyz:SP500`) for a builder-deployed perp."
    },
    {
     "name": "side",
     "type": "String",
     "description": "`buy` or `sell`: the direction of THIS wallet's order."
    },
    {
     "name": "size_token",
     "type": "Float64",
     "description": "Fill size in base-asset units, unsigned (the direction is `side`)."
    },
    {
     "name": "price",
     "type": "Float64",
     "description": "Execution price, USD."
    },
    {
     "name": "size_usd",
     "type": "Float64",
     "description": "Notional of the fill, `size_token * price`, USD."
    },
    {
     "name": "fee",
     "type": "Float64",
     "description": "Fee charged in `fee_token`; negative is a maker rebate."
    },
    {
     "name": "fee_token",
     "type": "String",
     "description": "Token the fee is denominated in, e.g. `USDC`."
    },
    {
     "name": "is_maker",
     "type": "Bool",
     "description": "True when this wallet's order was resting on the book."
    },
    {
     "name": "order_id",
     "type": "UInt64",
     "description": "Hyperliquid order id (oid) of this wallet's order."
    },
    {
     "name": "trade_id",
     "type": "UInt64",
     "description": "Hyperliquid trade id (tid). Both counterparties of one trade carry the same value; a fill is identified by (wallet, fill_ts, trade_id)."
    },
    {
     "name": "crossed",
     "type": "Bool",
     "description": "True when this fill crossed the book (the taker side)."
    },
    {
     "name": "closed_pnl",
     "type": "Float64",
     "description": "Realized PnL in USD the node booked on this fill; 0 for a fill that opens or adds to a position."
    },
    {
     "name": "dex_name",
     "type": "String",
     "description": "Perp dex the asset trades on: `HL` for the main dex, else the builder dex (e.g. `XYZ`)."
    },
    {
     "name": "start_position",
     "type": "Float64 (nullable)",
     "description": "Signed position in the asset immediately BEFORE this fill (negative is short). NULL for fills before 2026-09-29, when the column was added; 0.0 is a real value (flat before the fill)."
    }
   ]
  },
  "positions": {
   "description": "Every open position at every snapshot of the day (about every 5-7 minutes), one row per (wallet, asset, snapshot).",
   "note": "Snapshots are not evenly spaced, and a source outage that could not be rebuilt leaves a gap that is published as it is: `snapshots` on the day's entry counts them. A position held across snapshots appears in each. `account_value` and `pnl_cohort` are as of the START of the row's clock hour (equity and fills strictly before it; `pnl_cohort` is one hour earlier than the API's point-in-time label; meanings under `schema.positions`). Hours the source rebuilt by replaying fills instead of reading a node state file are listed in `reconstructed_hours` on the day's entry (reconstructed, not measured: `margin_used` and `liquidation_price` are 0, `state_ts` is 1970-01-01). Sizes matched the next real snapshot at 97 % or better, except the hours also listed in `reconstructed_lower_match_hours`, which matched at 83-97 %.",
   "sorted_by": "asset, wallet, snapshot_ts",
   "published": {
    "from": "2026-05-08",
    "to": "2026-10-21",
    "days": 167
   },
   "sample_file": "positions-sample.parquet",
   "sample_covers": "one instant: every BTC row of the day's first snapshot (the first `snapshot_ts` in 00:00-01:00 UTC), all wallets",
   "schema": [
    {
     "name": "snapshot_ts",
     "type": "DateTime('UTC')",
     "description": "Snapshot instant, UTC, whole minutes: the START of the ingestion cycle that wrote the row, not the instant of the node state it reads (typically 5-10 minutes earlier). Cycles are usually 5-7 minutes apart and irregular; a source outage leaves a longer gap. The day's `snapshots` count in the manifest says how many there are."
    },
    {
     "name": "wallet",
     "type": "String",
     "description": "Trader address, lowercase 0x-hex."
    },
    {
     "name": "asset",
     "type": "String",
     "description": "Instrument as Hyperliquid names it: `BTC` on the main dex, `dex:NAME` (e.g. `xyz:SP500`) for a builder-deployed perp. Called `symbol` in /v1/hyperliquid/positions. The prefix is authoritative: judge the dex by it, not by `dex_name`."
    },
    {
     "name": "direction",
     "type": "Int8",
     "description": "`1` long, `-1` short. The only place the side is stored: `size_token` and `size_usd` are never negative."
    },
    {
     "name": "size_token",
     "type": "Float64",
     "description": "Position size in base-asset units, unsigned (the side is `direction`)."
    },
    {
     "name": "size_usd",
     "type": "Float64",
     "description": "Notional of the position at `mark_price`, `size_token * mark_price`, USD, unsigned."
    },
    {
     "name": "entry_price",
     "type": "Float64",
     "description": "Average entry price of the position, USD."
    },
    {
     "name": "mark_price",
     "type": "Float64",
     "description": "Mark price when the row was written, USD."
    },
    {
     "name": "liquidation_price",
     "type": "Float64",
     "description": "Liquidation price, USD; 0 when the position has none (e.g. a well-collateralised cross-margin position)."
    },
    {
     "name": "unrealized_pnl",
     "type": "Float64",
     "description": "Unrealized PnL in USD, `direction * (mark_price - entry_price) * size_token`."
    },
    {
     "name": "leverage",
     "type": "Float32",
     "description": "Leverage of the position as a multiple (10 = 10x). 0 when none was recorded, which happens on cross-margin rows."
    },
    {
     "name": "margin_used",
     "type": "Float64",
     "description": "Margin the position ties up, USD: `size_usd / leverage`, or `size_usd` itself where `leverage` is 0."
    },
    {
     "name": "size_cohort",
     "type": "String",
     "description": "Account-value size tier of the wallet WHEN THE ROW WAS WRITTEN (`shrimp`, `2x shrimp`, `fish`, ... up to `4x whale`: 12 absolute-dollar thresholds assigned at ingestion), as stored: a point-in-time label, not today's grading. The same field and vocabulary as `size_cohort` in /v1/hyperliquid/positions."
    },
    {
     "name": "leverage_type",
     "type": "String",
     "description": "`cross` or `isolated`."
    },
    {
     "name": "dex_name",
     "type": "String",
     "description": "Perp dex the asset trades on: `HL` for the main dex, else the builder dex (e.g. `XYZ`). Rows written while a clearinghouse was not yet registered hold the literal `clsN` (e.g. `cls10`) and keep it; the `asset` prefix is authoritative."
    },
    {
     "name": "state_ts",
     "type": "DateTime('UTC')",
     "description": "The instant the state-derived columns (size, entry, mark, unrealized_pnl, leverage, margin_used, direction) describe, read from the node's state file; `snapshot_ts` is the WRITE time of the ingestion cycle, typically 5-10 minutes later (`liquidation_price` is re-read from the node at write time and belongs to `snapshot_ts`). `1970-01-01 00:00:00` means the row came from no state file (the per-wallet API fallback) or was written before 2026-08-22, when the column was added. Do not anchor a projection of the row on it: use `snapshot_ts`."
    },
    {
     "name": "liq_progress",
     "type": "Float64",
     "description": "How far the mark has moved from entry toward liquidation, clamped to 0..1: 0 at or in profit versus entry (or no liquidation price), 1 at or through the liquidation price. When a cross-margin liquidation price has drifted past entry it falls back to liquidation_price / mark_price (long) or mark_price / liquidation_price (short). The same SQL as `liq_progress` in /v1/hyperliquid/positions."
    },
    {
     "name": "account_value",
     "type": "Float64 (nullable)",
     "description": "Native Hyperliquid perp account value of the wallet, USD (the quantity /v1/hyperliquid/wallets/{address} serves as `equity.account_value`), AS OF THE START OF THE ROW'S CLOCK HOUR: the wallet's last snapshot of the previous hour (a row at 10:37 carries the 09:5x value). Builder-DEX account equity is NOT included, so a wallet trading only `dex:NAME` assets usually reads 0. In `latest`, as of the start of the hour of the file's newest snapshot (an older hour while the hourly rollup lags), so on the rows of positions that closed in the last 15 minutes it can be up to 15 minutes later than the row. NULL when unknown: the wallet had no snapshot in that previous hour (e.g. its first position opened in the row's hour); the stored value is a reconstruction, not a measurement (hours rebuilt from fills, and the values the 2026-08-10 repair rewrote); or the row is a builder-DEX position (`dex_name` other than `HL`) whose value comes from an hour up to 2026-08-10 00:48 UTC (the repair seam): until then a builder-DEX-only wallet's empty native account was stored as a non-equity figure the repair did not catch every time, and a genuine balance cannot be told apart from a fabricated one, so genuine values are withheld on those rows too. The same wallet's `HL` rows in the same snapshot keep the value; only its builder-DEX rows read NULL."
    },
    {
     "name": "pnl_cohort",
     "type": "String",
     "description": "Realized-PnL percentile cohort of the wallet AS OF THE START OF THE ROW'S CLOCK HOUR: graded on fills strictly before the row's hour (the hourly label of the previous hour). This is ONE HOUR EARLIER than the label /v1/hyperliquid/positions returns for the same row in historical mode (`start` given), where a row graded from the hourly label table carries `pnl_cohort_basis` = `point_in_time`: that label is the row's own hour and so counts the fills of up to 59 minutes after the row. In `latest`, as of the start of the hour of the file's newest snapshot (an older hour while the label rollup lags), so on the rows of positions that closed in the last 15 minutes it can count up to 15 minutes of fills after the row. `unknown` for a wallet with fewer than 10 closed trades then, or with no realized record that hour; never empty."
    }
   ]
  }
 }
}