Tessera Analytics
← Data catalog

Positioning & flow (hourly)

Pro

gold_positioning_1h hourly snapshots, partitioned per (coin, month)

gold_positioning_1h is hourly Hyperliquid open-interest and positioning data, derived from the full two-sided perp ledger — total open interest, long-vs-short account skew, per-side concentration, whale-cohort net position, and the taker flow behind each change. Download the history as Parquet or query it through the Tessera API.

Because the perp ledger is a closed system — every long is someone's short — the signal lives in asymmetries, not in a net total that is always zero. These aggregates measure who is crowded (head-count skew), who is concentrated (per-side share), and who is big (the whale cohort), plus the taker flow that moved each of those since the last snapshot.

What you'd use it for: Tracking open-interest trends, gauging crowded or concentrated positioning, and spotting squeezes and capitulations from whale and taker-flow shifts.

Timing · time (1h)

`time` is the instant the positioning snapshot was taken (~top of the hour, UTC). The snapshot aggregates (open interest, concentration, whale, head-counts) are point-in-time AS OF `time`. The attribution and taker-flow fields are BACKWARD-looking: they sum over the interval (previous snapshot, time] — the hour ENDING at `time` — so the whole row is knowable at `time` and is safe to act on without look-ahead. This is the OPPOSITE labelling to gold_ohlcv_1m, whose bars are start-labelled; align the two by lagging OHLCV one bar.

Get a free API key API reference

What it looks like

Sample data for BTC, charted from the same Parquet the API serves.

Open interest (BTC) · BTC · sample

Whale net position · BTC · sample

Data dictionary

29 columns, every one documented. The same table is served by describe_dataset to an MCP client and by /v1/catalog/gold_positioning_1h over HTTP.

Core aggregates

snapshot · as of timestamp
Column Type What it means
time timestamp[us] The hour this positioning snapshot was taken (UTC).
coin string Which market this row is for.
open_interest float64 Total size of open positions in the market — how much risk is on the table. Rising OI means new money committing; falling OI means positions being unwound. How it's computed: Two-sided open interest = (long_oi + short_oi)/2. long_oi == short_oi by the ledger identity, so this is the single OI figure.
n_long_positions uint32 How many wallets are currently holding a long.
n_short_positions uint32 How many wallets are currently holding a short.
n_unique_users uint32 How many distinct wallets have a position at all — the breadth of participation.
account_ls_ratio nullable float64 Long accounts divided by short accounts. Above 1 means more wallets are long than short (crowd leaning long by head-count). Extreme readings often mark crowded, vulnerable positioning. How it's computed: n_long_positions / n_short_positions — the long/short *account* ratio (crowd direction by head-count). NULL when no shorts.
top10_long_share nullable float64 How much of the long side is held by its ten biggest accounts — high means the longs are a few whales, not a broad crowd.
top10_short_share nullable float64 The same concentration measure for the short side.
concentration_skew nullable float64 Whether shorts or longs are the more concentrated side (short share minus long share). Positive means the shorts are the whale-heavy side — the ones more prone to a squeeze. How it's computed: top10_short_share - top10_long_share; >0 when shorts are more concentrated than longs. NULL when either side is empty.
hhi_gross nullable float64 A standard market-concentration score over all exposure — high when a handful of accounts dominate the whole book. How it's computed: Herfindahl–Hirschman concentration index over gross exposure.
whale_net_position float64 The net direction of the biggest accounts (top 10% by size). Positive means the whales are net long. This survives the zero-sum ledger because it's a sub-group, so it's a genuine 'smart money' tilt signal. How it's computed: Net signed szi of the top 10% of accounts by |szi| (the whale cohort). Signed: >0 = whales net long. Non-degenerate because it sums over a sub-population, not the whole zero-sum ledger. Divide by open_interest for an OI-relative skew.
whale_long_account_share nullable float64 What fraction of the whale cohort is on the long side, by head-count. How it's computed: Fraction of the whale cohort net long, by head-count. NULL when empty.
n_whale_accounts uint32 How many accounts make up the whale cohort this hour (the top 10% by position size). How it's computed: Whale cohort size = ceil(0.10 * n_unique_users), floored at 1 when non-empty.

Attribution — what changed since the previous snapshot

window ending at timestamp

Head-count deltas versus the prior hour: how many wallets opened, closed, or flipped sides. This is the raw churn behind the positioning change — useful for telling a quiet drift apart from a violent reshuffle.

Column Type What it means
d_open_interest float64 Change in open interest since the previous snapshot — net risk added or removed over the hour.
n_new_longs uint32 Wallets that opened a fresh long this hour.
n_new_shorts uint32 Wallets that opened a fresh short this hour.
n_closed_longs uint32 Wallets that closed a long this hour.
n_closed_shorts uint32 Wallets that closed a short this hour.
n_flipped_l2s uint32 Wallets that flipped from long to short — a sentiment reversal, one wallet at a time.
n_flipped_s2l uint32 Wallets that flipped from short to long.

Taker-flow rollup — aggressive flow over the hour

window ending at timestamp
Column Type What it means
aggressor_delta_1h nullable float64 Net aggressive buy-minus-sell pressure summed over the hour — the hourly version of CVD's slope. How it's computed: Σ aggressor_delta over the window — net taker buy−sell pressure (windowed CVD).
net_taker_open_1h nullable float64 Net new aggressive directional risk: long opens minus short opens by takers. The single headline 'which way is the aggressive money leaning' number for the hour. How it's computed: Σtaker_open_long_vol − Σtaker_open_short_vol — net aggressive new directional risk. The headline signed positioning-flow figure.
oi_opened nullable float64 Aggressive volume that opened positions this hour — flow-implied risk coming on. How it's computed: Σtaker_open_long_vol + Σtaker_open_short_vol — flow-implied OI added.
oi_closed nullable float64 Aggressive volume that closed positions this hour — flow-implied risk coming off. How it's computed: Σtaker_close_long_vol + Σtaker_close_short_vol — flow-implied OI removed.
flow_vs_snapshot_oi_residual nullable float64 The gap between the OI change we saw and the OI change taker flow can explain. What's left is mostly the maker side — passive positioning you can't see directly in the trade tape. How it's computed: d_open_interest − (oi_opened − oi_closed). Reconciles snapshot ΔOI against flow-implied ΔOI (flips folded in); residual ≈ maker-driven OI, unobservable from taker fills.
taker_flip_l2s_1h nullable float64 Aggressive long-to-short flip volume — a capitulation tell (longs giving up and flipping). How it's computed: Aggressive 'Long > Short' flip volume (close-long + open-short legs) — capitulation signal.
taker_flip_s2l_1h nullable float64 Aggressive short-to-long flip volume — a squeeze tell (shorts giving up and flipping). How it's computed: Aggressive 'Short > Long' flip volume (close-short + open-long legs) — short-squeeze signal.

Provenance

key / provenance
Column Type What it means
bootstrap_source string Housekeeping flag for how the first row of the month was seeded from the prior month. Ignore unless auditing continuity.