How to Use Whale Hunter

Read open interest spikes, avoid the most common misread, and see how the official strategy trades it in reverse.

A big block lights up on the overview heatmap. Are whales piling into longs? Whale Hunter tells you how unusual the open interest and volume move is. Direction is a separate question, and it is where most people misread the indicator.

What is Whale Hunter?

Whale Hunter (WH) is Blave's proprietary positioning-shift indicator. It measures how unusual perpetual futures open interest (OI) and volume are within the timeframe you choose, compared with the coin's usual level. It has two scores:

No upper or lower bound: around 0 is the normal level, and the larger the absolute value, the more unusual. Beyond ±2 is rare and beyond ±3 extreme, on the same scale for every coin. Scan your thresholds with a backtest. For a coin that keeps adding positions for a long time, adding is its usual, so the value does not stay high. Data Studio's status badges use these thresholds (score_oi as the example):

The critical nuance: high WH ≠ whales going long

The sign of Whale Hunter only tells you how unusual the OI or volume move is. It has no direction. Rising OI means new positions were opened, but those can be longs or shorts. To judge direction, go back to price, or pair WH with a directional indicator such as Holder Concentration.

The "whale" in the name is a metaphor. It looks at the market-wide total and cannot see individual accounts, so it cannot tell a few big players from a crowd of retail traders.

How do you build strategies with Whale Hunter?

Of the three uses below, only the first maps to a listed official strategy that passed the library checks. The other two are sketches of how to combine signals: not backtested, so verify every threshold yourself.

1. Contrarian threshold: enter when OI is flushed out

The logic is simple. When the 24h net OI decrease becomes unusual (score_oi < −0.7), a large share of positions was closed in that window. The strategy goes long, then exits to flat once the score recovers above 0.2. This is the signal function of the official btc_whale_1h strategy:

ENTRY_TH = -0.7
EXIT_TH  = 0.2

def compute_signals(df, entry_th=ENTRY_TH, exit_th=EXIT_TH):
    # df['WH'] = BTCUSDT 24h score_oi, read on every 1h bar
    signal = pd.Series(np.nan, index=df.index)
    signal[df['WH'] < entry_th] = 1.0   # OI flushed out -> go long
    signal[df['WH'] > exit_th]  = 0.0   # score recovers -> go flat
    return signal

ENTRY_TH = -0.7 and EXIT_TH = 0.2 come from a parameter scan plateau, not a guess: entry thresholds from −1.3 to −0.6 and exit thresholds from 0.0 to 0.3 all sit in the robust zone, and the plateau Sharpe is 0.884 of the chosen point's Sharpe.

2. Dual condition: OI and volume spike together

Blave's own site alerts use this condition: when the 1h score_oi and score_volume are both above 2, the alert reads "open interest and trading volume surged". Use it as a screen for coins where something is happening:

oi  = fetch_whale_hunter(SYMBOL, INTERVAL, START, END, hdrs,
                         timeframe='1h', score_type='score_oi')
vol = fetch_whale_hunter(SYMBOL, INTERVAL, START, END, hdrs,
                         timeframe='1h', score_type='score_volume')
# both scores > 2: same condition as the site alert
active = (oi['alpha'] > 2) & (vol['alpha'] > 2)

This is a screen, not an entry signal: it gives no direction and has no backtest. To trade it, add at least one directional check and run your own backtest.

3. Filter: WH flags the move, a directional indicator decides

Since WH carries no direction, a natural pairing is to let it answer "is something unusual happening?" and hand the entry decision to a directional indicator, such as Holder Concentration. The structure below is a sketch; replace compute_direction_filter with your own condition:

wh_active = df['WH'] > 2
direction_ok = compute_direction_filter(df)   # e.g. a Holder Concentration condition
signal = pd.Series(np.nan, index=df.index)
signal[wh_active & direction_ok] = 1.0
signal[~wh_active] = 0.0

This combination is not backtested, and the threshold of 2 is simply borrowed from the site alert. Scan the parameters and check performance after fees before you use it.

How do you choose the timeframe and score?

WH has two settings that are easy to mix up. The timeframe is how long a stretch of OI change or volume it looks at: 15min, 1h, 4h, 8h, 24h or 3d, defaulting to 24h and score_oi. The bar interval (5min to 1d on Data Studio charts, the interval in a strategy) only sets how often you read the value. The official strategy reads the 24h-window score on 1h bars.

Blave measured BTC, ETH and 1000PEPE from 2024-09 to 2026-09: on the default 24h window, the OI score's 1st and 99th percentiles sit near −2.6 and +3, with extremes around ±10. Shorter windows have fatter tails: on 1h, extremes already exceed ±20. The volume score skews right (negative readings rarely go below −2), so don't borrow the OI score's symmetric thresholds. Thresholds don't carry across setups: rescan when you change the timeframe or the coin. Don't reuse −0.7 elsewhere as is.

Where do you read it in Data Studio?

Which indicators pair well with it?

These are ideas for combining signals, not verified results:

What should you know when pulling it via API or Blave Agent?

The API endpoint is GET /whale_hunter/get_alpha with symbol, period, timeframe (default 24h), score_type (score_oi or score_volume) and start/end dates; in Blave Agent the helper is fetch_whale_hunter. Only closed bars are returned. Without a start date you get the last 365 days, and ranges longer than 365 days are truncated. History starts on 2021-12-01 (or the coin's listing). The response also carries one stat object describing the latest reading, and its field names don't quite match what they compute: