Social Fetch
Start for freeStart free
Polymarket hub

Polymarket Holders API

The largest holders of each outcome, with optional cost and PnL fields.

GET /v1/polymarket/markets/{conditionId}/holders

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

GET /v1/polymarket/markets/{conditionId}/holders returns data.outcomes, one group per outcome token. Each group has tokenId, outcomeIndex and holders, largest first. A holder row carries trader (wallet, name, pseudonym, image), verified and shares. With includePnl=true it also carries averagePrice, entryCost, currentValue, realizedPnl, unrealizedPnl and totalPnl.

minBalance keeps holders with at least that many shares. limit is 1 to 1000 and defaults to 20; with includePnl the maximum is 100. An unknown condition id, or a market with no holders, returns lookupStatus: not_found.

Polymarket Holders API FAQ

Why is the limit lower with includePnl?

Polymarket allows at most 100 holders a page when profit fields are included. The route rejects a larger limit with that combination, so lower the limit or drop includePnl.

Are holders grouped by outcome?

Yes. data.outcomes has one entry per outcome token, and each entry has its own holders list. A binary market usually has two groups, one for Yes and one for No.

What do the PnL fields mean?

entryCost is dollars paid in, currentValue is the position's value now, and totalPnl is realized plus unrealized profit. averagePrice is the average entry price. These fields are null or absent without includePnl.

What does lookupStatus mean on this route?

found means the object or list was returned. not_found means no matching object exists. HTTP 200 only means the request finished, so branch on data.lookupStatus before storing a row.

How much does this route cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged: that field is the billing source of truth.

Other Polymarket endpoints