• why whale positions matter on prediction markets
• what you need
• install
• what happens on a free-tier call
• what happens on a Pro call
• why each field is computed the way it is
• extending the recipe
• Pro plan limits and behavior
• one common failure mode

a recipe. the goal: when your coding agent asks “who is the biggest position holder on the upcoming Fed decision market right now”, it returns the top wallets, their position sizes, the side they took, and how long they have held. not the candy-bar charts the public dashboard shows.

this is what polymarket_whale_positions does inside the falsifylab alpha MCP. it lives behind the Pro plan at $19 per month. free-tier callers hit a gate response that names the upgrade path. the recipe below is what the call looks like with a Pro key, plus what the gate response looks like without one.

§why whale positions matter on prediction markets

a prediction market resolves at a discrete time. a binary outcome at expiry is the truth. between now and expiry, the price is the market’s odds estimate. it is not always efficient.

whale positions are not the only signal. they are a specific signal. a wallet with a six-figure position on a binary outcome is not betting for entertainment. they have a thesis. the thesis is sometimes wrong, but the thesis is researched.

the public Polymarket dashboard shows order book depth and recent trades. it does not show the distribution of position sizes across wallets, nor does it show whether the same wallet is concentrated on one side or hedged across markets. the data exists on-chain on Polygon, but extracting it requires reading market contract events, deduplicating wallets across related markets, and ranking by size.

most agent workflows that touch prediction markets stop at “what is the current price”. the next layer is “who is the price reflecting, and how concentrated is the conviction”.

§what you need

• an MCP-compatible coding agent (any client that supports the protocol)

• python 3.10+

• 5 minutes

§install

pip install falsifylab-alpha-mcp==0.3.2add this to your agent’s MCP config. config path varies by client; the shape is the same:

{ "mcpServers": { "falsifylab-alpha": { "command": "python", "args": ["-m", "falsifylab_alpha_mcp"] } } }restart your client. the MCP loads. a free-tier key is issued on first call.

§what happens on a free-tier call

if you call polymarket_whale_positions on a free key, the response is the structured gate envelope:

{"error":"pro_feature", "message":"'polymarket_whales' is a Pro feature. Free tier: top_yield_farms / hl_vault_leaderboard / macro_tape. Upgrade $19/mo to unlock all 13 tools. https://falsifylab.com/pro?ref=tool-gate", "upgrade_url":"https://falsifylab.com/pro?ref=tool-gate", "free_tools":["top_yield_farms","hl_vault_leaderboard","macro_tape"], "_pro_only_tool":"polymarket_whales"}an installed agent will surface the message string verbatim in its answer. it names what is free, names the upgrade price, and gives the upgrade URL. the workflow continues, just on a different tool.

§what happens on a Pro call

in your coding agent, type a question:

show me the top wallets on the next Fed FOMC decision market by position size, with side and dollar value

the agent calls polymarket_whale_positions with the right filters. a Pro response returns the wallet list:

{ "wallets": [ { "wallet": "0xabc...123", "market_slug": "fomc-2026-06-decision", "side": "yes", "position_usd": 142800, "entry_avg_price": 0.62, "current_market_price": 0.66, "opened_at": "2026-05-19T14:02:33Z", "wallet_history_score": "established" } ], "as_of": "2026-05-23T01:00:00Z", "tier": "pro" }the position size is in dollars, not share count, so direct comparison across markets is straightforward. the wallet history score is a categorical bucket (fresh / recent / established) based on the wallet age and prior market participation count.

§why each field is computed the way it is

wallet is the on-chain address that opened the position. for established traders this is often a wallet that shows up across multiple markets. the tool deduplicates the same wallet across related markets so an aggregated picture is possible if your agent loops.

side is the binary outcome the wallet is long. for a market with more than two outcomes the field returns the specific bucket name.

position_usd is computed as share_count multiplied by entry_avg_price. it is the dollar capital that bought the position, not the current notional. this lets you compare conviction across markets where current price has drifted.

entry_avg_price is the volume-weighted average price of the share buys that built the position. partial fills are aggregated.

wallet_history_score looks at the wallet’s market participation history. fresh wallets that show up only on the target market are different signal than wallets that have closed positive positions on prior markets. the bucket is categorical because a precise score would invite gaming.

§extending the recipe

once the tool is live, your agent can combine it with:

• polymarket_whale_positions itself called across multiple markets and joined on wallet address to find traders running consistent themes (for example: every dollar-strength market, or every Fed-related market).

• confluence_today (Pro plan $19/mo) stacks signals across sources. a polymarket whale concentration on the same week as an insider cluster on an equity name tied to the same macro outcome is a stronger posture than either alone.

• macro_tape (free) gives you the broader macro snapshot to contextualize the whale position. a wallet betting on a dovish Fed decision while two-year yields are rising is taking a different posture than a wallet doing the same trade when yields are falling.

§Pro plan limits and behavior

• up to 100 results per query

• no hourly rate cap

• real-time refresh, no cache lag

for prediction-market work, the lag matters most as a market gets close to resolution. positions can shift in the final hours. the Pro refresh interval is the right tier for agents that decide entries inside an action window of minutes. research workflows that answer “what was the structure of the book yesterday” can still use one of the three free tools as a context layer and reason about the prediction-market piece separately.

§one common failure mode

agents that treat whale concentration as a directional signal will get fooled by sophisticated hedging. a wallet long on the yes side of one market and short on a correlated market is not betting yes. the fix is to rank wallets by the spread between concentrated positions and offsetting positions across the wallet’s portfolio. the tool returns the single-market view, so the agent has to do the cross-market aggregation itself if that distinction matters.

pip install falsifylab-alpha-mcp==0.3.2falsifylab.com/pro

research and educational content only. not investment, legal, or tax advice. do your own research.

#OnchainAlpha #BTCFlow #ETHFlow

Originally published on FalsifyLab Substack.