On-Chain Whale Alerts Tell You About Yesterday

Most "whale tracking" watches exchange deposits and wallet transfers — useful, but lagging. By the time coins hit an exchange the position decision was made hours earlier, and a transfer doesn't tell you whether the whale is net long or net short right now.

Hyperliquid changes that. Because positions are on-chain, you can read the live margin book of every large account directly. The /api/v1/quant/whales endpoint rolls the entire ≥$100k account universe into a single positioning read, refreshed about every 5 minutes.

What the Whale Activity Endpoint Returns

One call returns two blocks — an aggregate summary and per-coin top_coins:

FieldMeaning
summary.accountsNumber of ≥$100k accounts tracked
summary.by_classSplit into market_maker / whale / other
summary.long_usd / short_usdAggregate notional each side
summary.net_biasWhole-book risk-on / risk-off read
top_coins[].directional_net_usdNet excluding market makers — the conviction read

Scope is Hyperliquid perpetuals (meta.segment = perp); meta.spot_status flags that spot-wallet balances aren't collected yet.

Are Whales Risk-On or Risk-Off Right Now?

That's exactly what net_bias answers in one field:

curl -H "X-API-Key: cdk_live_your_key" \
  "https://cryptodataapi.com/api/v1/quant/whales"
{
  "summary": {
    "accounts": 1184,
    "by_class": {"market_maker": 96, "whale": 412, "other": 676},
    "long_usd": 5840000000, "short_usd": 4910000000,
    "long_short_ratio": 1.19, "net_bias": "risk_on"
  },
  "top_coins": [
    {"coin": "BTC", "net_usd": 612000000,
     "dominant_side": "long", "directional_net_usd": 318000000}
  ]
}

Read it plainly: 1,184 large accounts, 19% more long than short notional, net risk-on, with BTC the most-held coin and real directional conviction once market-maker flow is stripped out.

Why We Strip Out Market-Maker Flow

A raw long/short total is polluted by market makers, who hold large two-sided inventory that says nothing about direction. directional_net_usd removes the market-maker bucket so what's left is conviction positioning — whales and directional traders actually taking a side.

A big net_usd with a small directional_net_usd is mostly liquidity, not a bet. The gap is the tell.

Tracking the Trend: /quant/whales/history

A snapshot is a moment; the move is in the trend. /quant/whales/history returns a daily series of aggregate whale positioning:

curl -H "X-API-Key: cdk_live_your_key" \
  "https://cryptodataapi.com/api/v1/quant/whales/history?days=90"

Each point carries the day's long_usd / short_usd / net_usd / gross_usd plus its top coins by net. Full-universe collection is recent, so early points are modeled: every point has source = seed or live and an estimated flag, and meta.seeded_count / live_count report the split so you can trust-but-verify.

What Counts as a Whale Here?

The universe is precise, not vibes-based. Three things define the scope:

Unlike on-chain "whale alert" feeds that fire on a single large transfer, this is the standing position book — who is holding what, right now, not who just moved coins.

How AI Agents Use Whale Activity

Use it as a directional confirmation layer:

import httpx
w = httpx.get("https://cryptodataapi.com/api/v1/quant/whales",
              headers={"X-API-Key": "cdk_live_your_key"}).json()
s = w["summary"]

if s["net_bias"] == "risk_on" and s["long_short_ratio"] > 1.1:
    bias = "favor_longs"
elif s["net_bias"] == "risk_off":
    bias = "favor_shorts"

The endpoint returns 503 while warming up (the first liqmap poll cycle, ~45–60 min after a deploy) — handle it and retry.