List a market's top holders

Top holders of a market, netted per user and grouped by outcome token.

?condition= (CSV of condition_id) is required (400 otherwise). ?limit= (default 100, max 1000; v2 family-uniform) sizes the page per outcome token; ?min_balance= filters the served amount.

?include_pnl=true opts each holder row into the position economics (entry price and cost, current price and value, realized, unrealized and total profit) and switches the amounts to per-side gross balances, so a wallet holding both outcomes appears under both tokens. The default response is unchanged. This mode serves one market’s table at a time: exactly one condition and limit at most 100 (400 otherwise, including via a cursor that carries a wider window).

A malformed condition id is a 400 naming the value; a well-formed one that resolves to no holdings serves an empty data array, which is the meaningful zero-state.

Deeper pages come only from ?cursor= (which carries the page window and overrides limit).

Page walks advance every token group together, so a group leaves data once its token is exhausted while others keep paging; no rows are lost, but merge pages by token_id, not by array position.

GET /v2/holders

List a market's top holders

cURL

curl --request GET \
  --url https://data-api.polymarket.com/v2/holders \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "holders": [
        {
          "amount": 123,
          "bio": "<string>",
          "display_username_public": true,
          "name": "<string>",
          "outcome_index": 123,
          "profile_image": "<string>",
          "profile_image_optimized": "<string>",
          "proxy_wallet": "<string>",
          "pseudonym": "<string>",
          "token_id": "<string>",
          "verified": true,
          "avg_price": 123,
          "current_price": 123,
          "current_value": 123,
          "entry_cost_usdc": 123,
          "realized_pnl": 123,
          "total_pnl": 123,
          "unrealized_pnl": 123
        }
      ],
      "token_id": "<string>"
    }
  ],
  "pagination": {
    "has_more": true,
    "limit": 1,
    "offset": 1,
    "next_cursor": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

condition · string | null

Comma-separated condition_ids (at most 20 distinct values; exactly one with include_pnl=true). Required. condition is the unified key across v2 (same as the feeds and /v2/oi); condition_id / conditionId are accepted aliases.

limit · integer<int32> | null

Rows per outcome token; defaults to 100, maximum 1000 (100 with include_pnl=true).

Required range: 0 <= x <= 1000

cursor · string | null

Opaque pagination cursor from a prior response's next_cursor; carries the per-token (limit, offset) window and overrides limit. Paging past the first page is cursor-only.

min_balance · number<double> | null

Minimum net balance in shares (default 0), applied post-netting. With include_pnl=true it applies to the served per-side gross amount instead.

include_pnl · boolean | null

Opt into per-holder position economics (default false; includePnl is an accepted alias). Adds avg_price, entry_cost_usdc, current_price, current_value, realized_pnl, unrealized_pnl and total_pnl to every holder row, and switches the served amounts to per-side gross balances: a wallet holding both outcomes appears under both tokens with per-side sizes and that side's economics, matching /v2/positions for the same wallet and token. This mode serves one market's table at a time: exactly one condition, limit at most 100.

Response

200

application/json

A page of top holders per outcome token

{ data, pagination } envelope for /v2/holders; an offset-cursor feed (per outcome token): the offset lives behind the opaque token, never on the wire.

data · object[] · required

The page's rows.

Show child attributes

pagination · object · required

Paging envelope: follow next_cursor until null.

Show child attributes