Market Top Holders (Polymarket)

Top position holders in a single Polymarket market, ranked by current position size. Filter by outcome with side=yes|no. Each holder includes shares held and estimated current position value; per-wallet cost-basis PnL fields are not yet computed and are returned as null.

GET/v2/polymarket/market/{condition_id}/top-holders

Plans All plansPlan rate limits apply

Parameters

offsetinteger

Zero-based offset. Use pagination.next_offset to advance. Pagination covers the top 20 holders per outcome; total_count counts this window.

condition_idstring (path)required

Market condition ID - must match ^0x[0-9a-f]{64}$.

sidestring

Optional. Filter by outcome side: 'yes' or 'no'. Omit for all holders.

min_sharesnumber

Optional. Only return holders with at least this many shares.

include_countboolean

Optional. When true, include total_count of matching holders. Default false.

limitinteger

Optional. Rows returned, ranked by size. 1–100, default 100.

Response

condition_idstring

Market condition ID (echoes the path).

titlestring

Market title (null if not resolved).

market_slugstring

Market slug for URL construction (null if not resolved).

sidestring

Outcome side filter applied ('yes', 'no', or null for all).

total_countinteger

Total holders matching the filters - only present when include_count=true.

entriesarray

Top holder rows, ranked by current position size (shares), descending.

Show 18 fields

rankinteger

Position in the list (1-indexed).

userstring

Holder wallet (Polymarket proxy wallet).

token_idstring

Outcome token ID held.

position_sharesnumber

Shares currently held (normalized).

position_value_usdnumber

Estimated current value of the position (shares × current price). Null if a price is momentarily unavailable.

sidestring

Outcome side of the position (Yes / No / outcome label).

outcome_indexinteger

Outcome index (0 for Yes/first outcome, 1 for No/second).

avg_pricenumber

Average entry price. Not yet computed - returned as null (see _meta.unavailable_fields).

realized_pnlnumber

Realized PnL (USD). Not yet computed - returned as null.

unrealized_pnlnumber

Unrealized PnL (USD). Not yet computed - returned as null.

total_pnlnumber

Total PnL (USD). Not yet computed - returned as null.

trade_countinteger

Number of trades. Not yet computed - returned as null.

first_trade_atinteger

Unix timestamp of first trade. Not yet computed - returned as null.

last_trade_atinteger

Unix timestamp of last trade. Not yet computed - returned as null.

pseudonymstring

Holder display pseudonym, if public.

namestring

Holder display name, if set.

profile_imagestring

Holder profile image URL, if set.

verifiedboolean

Whether the holder is a verified account.

paginationobject

Result window metadata.

Show 6 fields

limitinteger

Requested page size.

countinteger

Number of entries returned.

pagination_keystring

Reserved (null). Use next_offset with the offset query parameter.

offsetinteger

Current offset into the ranked holder window.

next_offsetinteger | null

Pass as offset for the next page; null at the end.

has_moreboolean

True when another page exists in the top-20-per-outcome window. Rankings can change after the 30-second cache refresh.

_metaobject

Source, cache, and field-availability metadata.

Show 4 fields

sourcestring

Data source identifier.

cache_secondsinteger

Cache window in seconds.

unavailable_fieldsarray

Fields returned as null because they require per-wallet cost-basis accounting not yet computed by this endpoint.

notestring

Plain-language explanation of which fields are exact vs. not yet available.

Try it

Sample data

Condition ID*

Sample mode returns a fixed recorded example; input changes apply to live requests. Switch it off to query live data with these parameters.

{
  "condition_id": "0x0e4a0c937b8934c2475613b6322b3f8edc8dedc24762e01e42b0e6f87424a089",
  "title": "US x Iran permanent peace deal by May 31, 2026?",
  "market_slug": "us-x-iran-permanent-peace-deal-by-may-31-2026-333-871-241-192-799-449-125",
  "side": null,
  "total_count": 16,
  "entries": [
    {
      "rank": 1,
      "user": "0xb2a3623364c33561d8312e1edb79eb941c798510",
      "token_id": "42918220085288219341491829385501246298233444593663440094436147850542032590016",
      "position_shares": 4206706.961999,
      "position_value_usd": 3596734.45,
      "side": "No",
      "outcome_index": 1,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Amused-Debtor",
      "name": "aekghas",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 2,
      "user": "0x0f0223dc4b5c68f345ac4f0444f2955740b85bfb",
      "token_id": "42918220085288219341491829385501246298233444593663440094436147850542032590016",
      "position_shares": 3424851.270573,
      "position_value_usd": 2928247.84,
      "side": "No",
      "outcome_index": 1,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Thorny-Fir",
      "name": "0x0F0223dC4b5C68f345Ac4F0444f2955740B85bfB-1779940201096",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 3,
      "user": "0xde7be6d489bce070a959e0cb813128ae659b5f4b",
      "token_id": "72094069823942324362885404801938332659316240217382754851102758232469673300092",
      "position_shares": 2308736.24558,
      "position_value_usd": 334766.76,
      "side": "Yes",
      "outcome_index": 0,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "True-Grandparent",
      "name": "wan123",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 4,
      "user": "0xc6587b11a2209e46dfe3928b31c5514a8e33b784",
      "token_id": "72094069823942324362885404801938332659316240217382754851102758232469673300092",
      "position_shares": 1719552.633332,
      "position_value_usd": 249335.13,
      "side": "Yes",
      "outcome_index": 0,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Glamorous-Stitcher",
      "name": "Erasmus.",
      "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-642445-92826f3c-3576-4719-880c-027883552860.png",
      "verified": false
    },
    {
      "rank": 5,
      "user": "0xfd2b117412a698f322b0cd18d6827dad262b8e50",
      "token_id": "72094069823942324362885404801938332659316240217382754851102758232469673300092",
      "position_shares": 1067804.517062,
      "position_value_usd": 154831.65,
      "side": "Yes",
      "outcome_index": 0,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Humongous-Fannypack",
      "name": "surf",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 6,
      "user": "0x5d0f03cf1243a3e21262d6cf844795afd9fff0ad",
      "token_id": "42918220085288219341491829385501246298233444593663440094436147850542032590016",
      "position_shares": 938362.52882,
      "position_value_usd": 802299.96,
      "side": "No",
      "outcome_index": 1,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Ethical-Caribou",
      "name": "EB99999",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 7,
      "user": "0xbaa2bcb5439e985ce4ccf815b4700027d1b92c73",
      "token_id": "72094069823942324362885404801938332659316240217382754851102758232469673300092",
      "position_shares": 937034.232335,
      "position_value_usd": 135869.96,
      "side": "Yes",
      "outcome_index": 0,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Illustrious-Spectacles",
      "name": "denizz",
      "profile_image": null,
      "verified": false
    },
    {
      "rank": 8,
      "user": "0x1cc16713196d456f86fa9c7387dd326a7f73b8df",
      "token_id": "72094069823942324362885404801938332659316240217382754851102758232469673300092",
      "position_shares": 838565.802624,
      "position_value_usd": 121592.04,
      "side": "Yes",
      "outcome_index": 0,
      "avg_price": null,
      "realized_pnl": null,
      "unrealized_pnl": null,
      "total_pnl": null,
      "trade_count": null,
      "first_trade_at": null,
      "last_trade_at": null,
      "pseudonym": "Foolish-Contrail",
      "name": "Wickier",
      "profile_image": "https://polymarket-upload.s3.us-east-2.amazonaws.com/profile-image-609636-9487ff88-f320-449f-8a82-11cf53836031.webp",
      "verified": false
    }
  ],
  "pagination": {
    "limit": 8,
    "count": 8,
    "pagination_key": null,
    "has_more": true
  },
  "_meta": {
    "source": "polymarket",
    "cache": "miss",
    "cache_seconds": 30,
    "unavailable_fields": [
      "avg_price",
      "realized_pnl",
      "unrealized_pnl",
      "total_pnl",
      "trade_count",
      "first_trade_at",
      "last_trade_at"
    ],
    "note": "Per-wallet cost basis (average entry price; realized / unrealized / total PnL) and trade-history counters are not yet computed for this endpoint and are returned as null. Holdings and current position value are exact."
  }
}