Recipe 19 of 33
Backtest following smart money with point-in-time cohort labels from the positions archive
Download a day of the positions archive; every 5-minute position row carries pnl_cohort, size_cohort and account_value as they stood at the start of its hour, so a backtest never reads a label from the future.
GET /v1/hyperliquid/archive/url answers it in one call: ask for one day of positions and the link is a Parquet
file with every 5-minute snapshot of every open position that day. Three of its columns are point-in-time:
pnl_cohort is the wallet's realized-PnL cohort graded on fills strictly before the row's clock hour,
size_cohort is its account-size tier as stored when the row was written, and account_value is its native perp
account value at the start of the row's hour. The full parameter list is on
Archive download link.
Quick answer
Name the dataset and the UTC day.
# a temporary link to every 5-minute position snapshot of 2026-10-23
curl -H "X-API-Key: $VIKE_API_KEY" \
"https://data.vike.io/v1/hyperliquid/archive/url?dataset=positions&date=2026-10-23"Example response
Captured from the live API on 2026-10-24 at 17:14 UTC. The token between /dl/ and the next / is replaced with <exp>.<kid>.<sig>, because
a live link works as a credential for 300 seconds.
The link needs no key and is accepted for expires_in seconds; the file is 1.9 GB and 122.7 million rows. To follow
smart money, keep the rows whose pnl_cohort is 3x smart, 2x smart or smart and sum direction * size_usd per
asset and snapshot_ts: that is the cohort's net book at each snapshot, labelled with what was known at the time.
Join it to the next hours' candles from /v1/hyperliquid/ohlcv to score the strategy.
{
"url": "https://data.vike.io/dl/<exp>.<kid>.<sig>/venue=hyperliquid/date=2026-10-23/positions.parquet",
"expires_at": "2026-10-24T17:19:44Z",
"expires_in": 300,
"dataset": "positions",
"date": "2026-10-23",
"bytes": 1932590004,
"rows": 122700235
}Variations
Which days exist. The archive index lists every published day, newest first, with each positions day's snapshot count and the hours
that were rebuilt from fills (reconstructed_hours).
# the newest day that has a positions file
curl -s -H "X-API-Key: $VIKE_API_KEY" \
"https://data.vike.io/v1/hyperliquid/archive/datasets" \
| jq '[.dates[] | select(.streams.positions)][0]'Ask and download in one command. redirect=1 answers 302 with the link in Location, and -L follows it.
# save the day's file locally
curl -s -L -H "X-API-Key: $VIKE_API_KEY" -o positions-2026-10-23.parquet \
"https://data.vike.io/v1/hyperliquid/archive/url?dataset=positions&date=2026-10-23&redirect=1"Spot-check one hour through the API. /v1/hyperliquid/positions with a start returns historical rows filtered by the cohort they had then, without a
download, and pnl_cohort_as_of names the hour each label belongs to. A capture on 2026-10-24 at 17:16 UTC
returned a row stamped 12:13 with pnl_cohort_as_of 12:00.
# BTC positions held by 3x smart wallets in the 12:00 hour of 2026-10-22, one row per wallet and hour
curl -H "X-API-Key: $VIKE_API_KEY" \
"https://data.vike.io/v1/hyperliquid/positions?symbol=BTC&axis=pnl&cohort=3x_smart&start=2026-10-22T12:00:00Z&end=2026-10-22T12:59:59Z&resolution=1h&limit=3"Before you rely on it
The API's label is one hour later than the archive's
In the archive, pnl_cohort is graded on fills strictly before the row's clock hour. /v1/hyperliquid/positions in
history mode labels the same row with its own hour, which counts fills up to 59 minutes after the row: a row stamped
12:13 carries the 12:00 label. For a backtest with no lookahead at all, use the archive file, or take the API's label
from the hour before.
Rebuilt hours and missing equity
Hours listed in a day's reconstructed_hours were rebuilt from fills, not measured: 2026-10-23 lists 11:00 and 12:00.
Drop them from a backtest or treat them as approximate. account_value is null when it is unknown, for example on a
wallet's first hour, and the positions files start on 2026-05-08.
Ask your agent
Connected to the Vike MCP server (https://vike.io/mcp) in Claude, ChatGPT or Cursor, ask it in plain words.
The hl_market tool answers (view positions), at 1 credit a call.
Which BTC positions did 3x smart wallets hold in the 12:00 UTC hour of 2026-10-22, with the label they had then?