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 position-change indicator. It sums the 5-minute open interest (OI) change and volume of Binance USDT-margined perpetuals over the window you pick (the timeframe), then converts the sum into a z-score against that coin's past 30 days. It comes in two scores:

Because it is a z-score, the value has no fixed bounds and every coin sits on the same scale. But "high" is always relative to the coin's own past 30 days: a coin whose OI grows steadily for months gets absorbed into its own average. Studio's status badges use these thresholds (score_oi shown):

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. The data is a market-wide total for Binance perpetuals: no individual accounts, no way to tell a few large traders from a crowd of small ones, and nothing from other exchanges.

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 the window over which OI change or volume is summed: 15min, 1h, 4h, 8h, 24h or 3d, defaulting to 24h and score_oi. The bar interval (5min to 1d on 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 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: