Skip to content
← Data catalog

Hyperliquid hourly positioning data

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.

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

Grain
1h
Columns
29
Partition
coin × month
History
October 2025 →
Price
Free, trailing month

Timing · time marks the snapshot

`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.

A day of BTC, bar by bar

2026-11-16 00:00–23:00 UTC. Read straight out of the Parquet a free key downloads, at the dataset's own grain.

Open interest (BTC)

Whale net position

Bars in the day
24
Open interest (BTC)
17,743 – 19,302
Accounts at close
39,615
Whale accounts
3,962

The hours behind it

The first four hours of 2026-11-16, exactly as the Parquet returns them. The file holds all 24 hourly bars of the day for BTC.

timeopen_interestaccount_ls_ratiowhale_net_positionn_whale_accountsd_open_interest
00:0018,401.911.928-535.163,895-45.55
01:0018,295.051.913-534.393,906-106.86
02:0018,110.461.890-516.553,904-184.59
03:0018,073.391.886-515.953,911-37.07

Scroll the table sideways for the rest of the columns.

Download it, or read it

One call returns a presigned URL per day object for the open month, and a single URL for a closed one. The file is Parquet: partition columns, one row per hour, every column in the dictionary below.

  • REST reference for the route, the error shapes and the pagination.
  • Python and Rust clients stream it into Polars or DuckDB without a local copy.
  • MCP serves this schema through describe_dataset, so an agent can read the columns before it queries.

HTTP

curl -s -H "Authorization: Bearer $TESSERA_API_KEY" \
  https://tesseralytics.dev/v1/datasets/gold_positioning_1h/BTC/2026-11/download

Python

import tessera

client = tessera.TesseraClient()          # reads $TESSERA_API_KEY
df = client.read("gold_positioning_1h", "BTC", "2026-11")
print(df.head())

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 What it means
time The hour this positioning snapshot was taken (UTC).
coin Which market this row is for.
open_interest 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 How many wallets are currently holding a long.
n_short_positions How many wallets are currently holding a short.
n_unique_users How many distinct wallets have a position at all: the breadth of participation.
account_ls_ratio nullable 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 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 The same concentration measure for the short side.
concentration_skew nullable 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 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 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 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 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, which is how you tell a quiet drift apart from a violent reshuffle.

Column What it means
d_open_interest nullable Change in open interest across the completed hour: net risk added or removed. NULL if the previous hour's snapshot is missing, so the figure is never a change spanning several hours presented as one hour's move.
n_new_longs nullable Wallets that opened a fresh long during the completed hour. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.
n_new_shorts nullable Wallets that opened a fresh short during the completed hour. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.
n_closed_longs nullable Wallets that closed a long during the completed hour. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.
n_closed_shorts nullable Wallets that closed a short during the completed hour. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.
n_flipped_l2s nullable Wallets that flipped from long to short during the completed hour: a sentiment reversal, one wallet at a time. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.
n_flipped_s2l nullable Wallets that flipped from short to long during the completed hour. NULL if the previous hour's snapshot is missing, so the count never spans more than one hour.

Taker-flow rollup: aggressive flow over the hour

window ending at timestamp
Column What it means
aggressor_delta_1h nullable 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 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, the net aggressive new directional risk. The headline signed positioning-flow figure.
oi_opened nullable 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 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 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 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): the capitulation signal.
taker_flip_s2l_1h nullable 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): the short-squeeze signal.

Provenance

key / provenance
Column What it means
bootstrap_source Housekeeping flag for how the first row of the month was seeded from the prior month. Ignore unless auditing continuity.
Join it to the other two datasets

Same markets, same month partition, same timestamp convention on the hourly pair.

Free now, or buy the history once

Every dataset and every market is free over the trailing month. The full history from October 2025 is bought once as a Parquet bundle, with no subscription.