The Whale Reversal Index: A Method for Backtesting Smart-Money Flow

Everyone agrees whales "move markets." Almost nobody states it as something you can test. This post defines a single number — the Whale Reversal Index — and gives you the method and the code to backtest it on Polymarket yourself.

The results table and the downloadable CSV below are an illustrative sample run, not a verified historical study. The market names are labelled Sample… and Example… on purpose. Use the method and the script to produce your own numbers on live data.

The idea

The market_whales endpoint already tells you how whale money splits on a market: yes_pct and no_pct of total whale exposure. When that split is lopsided but the market price hasn't followed, the smart money and the crowd disagree. The Reversal Index measures how lopsided the whale side is:

reversal_index = | yes_pct − no_pct | / 100

A value near 0 means whales are evenly split. A value near 1 means whales are piled onto one side. The hypothesis: when the index is high and the market price hasn't caught up, the market tends to resolve in the whales' direction.

For context, a real market_whales snapshot of "US x Iran permanent peace deal by May 31, 2026?" showed 8 whales, 13.1% YES / 86.9% NO — a reversal index of 0.74, with the top whale holding 25.8% of the exposure. That's the kind of lopsided lean the index is built to catch.

Method

1. •Pull whale exposure per market with the actor's market_whales action.
2. •Read yes_pct / no_pct from market_metadata and compute the index.
3. •Keep snapshots above a threshold (the sample below uses 0.55).
4. •Record the whale side and, once the market resolves, whether it hit.
5. •Tally hit-rate against the count of qualifying snapshots.

Sample run

Running the method over a sample set of 12 markets:

| Metric | Value (sample) | | :-- | --: | | Markets in set | 12 | | Hits | 9 | | Hit-rate | 75% | | Mean reversal index | 0.44 | | Filtered to index ≥ 0.55 | 4 / 5 (80%) |

Download the sample dataset (CSV) → — every row is a labelled Sample/Example market with the real market_whales columns (whale_count, total_exposure_usdc, yes_pct, no_pct, top_whale_concentration_pct). It's unmistakably a template, not a claim.

Read it as a worked template: the shape of the output and a structure you can fill with real, resolved markets. A 75% sample hit-rate is not a result you should trade on — it's a placeholder showing what a real study would report.

Reproduce it on live data

import requests

APIFY_TOKEN = "your_apify_token_here"
ACTOR = "N5u8wVgS1bKzibZdf"
INDEX_THRESHOLD = 0.55

def market_whales(market_id):
    r = requests.post(
        f"https://api.apify.com/v2/acts/{ACTOR}/run-sync-get-dataset-items",
        params={"token": APIFY_TOKEN},
        json={"action": "market_whales", "market_id": market_id},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

def reversal_index(market):
    m = market["market_metadata"]
    idx = abs(m["yes_pct"] - m["no_pct"]) / 100
    side = "YES" if m["yes_pct"] > m["no_pct"] else "NO"
    return idx, side

# For each market you track: snapshot now, store index + whale side,
# then check the resolved outcome later to score the hit.
idx, side = reversal_index(market_whales("EXAMPLE_MARKET_ID"))
if idx >= INDEX_THRESHOLD:
    print(f"index={idx:.2f} → whales lean {side}")

The honest version of this study needs resolved markets and the whale snapshots that preceded them. The actor gives you the snapshots; resolution gives you the label. Collect enough pairs and you have a real hit-rate — yours, not a sample.

What this won't tell you

A high index is a disagreement, not a certainty. Whales hedge, whales are sometimes wrong, and a single dominant wallet can skew the split — watch top_whale_concentration_pct and discount markets where one wallet is most of the exposure. Treat the index as one input and always validate on out-of-sample markets before you believe it.

Want to build your own version? The whale exposure splits come straight from the actor — see the API. The free tier is enough to start collecting pairs.