CURRENT HOLDERS of ONE Polymarket outcome — who is holding "Yes" (or "No", or any
named outcome) in a market right now, largest position first, with each holder's
share balance, its % of the outstanding shares, and when they first acquired it.
NOT who traded the most → use polymarket_top_traders.
NOT the price / implied probability of the outcome → use polymarket_market_odds.
NOT one wallet's own trade history → use polymarket_trader_activity.
NOT the individual fills of a market → use polymarket_market_trades.
Polymarket on Polygon; positions measured from on-chain share movements, history from
September 2025 onward.
HOW TO CALL IT: pass `question_id` (from polymarket_find_markets, or
polymarket_market_info) plus the outcome you care about — either `outcome` as the
label shown for that market ("Yes", "No", a team or candidate name;
case-insensitive), or `outcome_asset_id`, the exact id polymarket_market_info
returns for each outcome. Give neither and the market's FIRST outcome is used;
every row names the outcome it actually reports.
Balances are rebuilt from every recorded movement of that one outcome share —
purchases, sales, shares created when a full set is minted, shares destroyed on
redemption, AND plain wallet-to-wallet transfers, which order data alone cannot
see and which dominate the very largest positions.
WHO THESE ADDRESSES ARE: the holder of record is very often a PROXY CONTRACT
operated on a user's behalf, or a market-making wallet — in a typical market
several of the biggest holders are two wallets of the same operator passing
shares between themselves. Do not present them as individual bettors. Label them
with labels_for_addresses first, and use matic_transfers_in / matic_transfers_out
to see where a position came from.
READ WITH THE ROW: `Supply_Outstanding` is every share of that outcome currently
in existence, so `Share_Pct` is a genuine concentration figure. `Holder_Count` is
how many addresses hold a positive balance. `Scanned_From` is the point the
history was rebuilt from — the market's registration, unless you overrode it.
`Negative_Balances` should be 0; a value above 0 means that many addresses show
more shares leaving than arriving, so the balances and the total are only
approximate for this market — say so instead of quoting exact figures. If it is
large, `Supply_Outstanding` and `Share_Pct` can even come back NEGATIVE: that is
the unmistakable sign the figures are net flow over a shortened history rather
than holdings, and it happens when `after_time` was set past the market's start.
AFTER A MARKET RESOLVES the winners redeem, which destroys their shares, so the
list shrinks over time and increasingly shows only holders who have not redeemed
yet. For a live picture of conviction, ask about an open market.
SPEED: the position history is rebuilt from the market's creation, so the call
costs more the OLDER the market is — near-instant for a market a few days old,
tens of seconds for one that has been open for months, where it may time out
(retry, or ask about a younger market). `limit` does not change the cost.