Sign in

v1

latestOpenAPI 3.1.02026-07-243035381.4 MB
Prediction API

Get top holders of a market

/v4/data/prediction/markets/{id}/positions

100 credits per API call

Top holders of a market grouped by outcome token. Each top-level row in the response is one outcome (e.g. YES, NO); under it sits the list of wallets currently holding that outcome, ordered by the chosen sortBy metric. Useful for "who's on each side of this bet" leaderboards on a market-detail page.

Platform support

  • Polymarket only. Calling this endpoint against a Kalshi market id returns 400.

Filtering, sorting and pagination

  • user narrows the response to a single wallet — useful for "does this user have a position in this market" checks.
  • status filters holders by their position state: OPEN (size > 0.01), CLOSED (size ≤ 0.01), ALL (default).
  • sortBy chooses the metric used to order holders inside each outcome group: TOKENS, CASH_PNL, REALIZED_PNL, TOTAL_PNL. Combine with sortDirection (ASC or DESC).
  • Pagination is offset-based. limit and offset apply per outcome group — e.g. on a binary market with limit=50 the response carries up to 100 holders total (50 YES + 50 NO).
get/v4/data/prediction/markets/{id}/positions

Path parameters

idstring required
Example:0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917

Platform-native market identifier. Must be a Polymarket condition id; Kalshi market ids return 400.

Query parameters

userstring
Example:0x56687bf447db6ffa42ffe2204a05edaa20f55839

Filter the response to a single holder wallet (0x + 40 hex).

status'OPEN' | 'CLOSED' | 'ALL'

Position-status filter for the ?status= parameter on /markets/{id}/positions. OPEN = size > 0.01, CLOSED = size ≤ 0.01, ALL = no filter.

Example:ALL

Filter holders by position lifecycle state. Defaults to ALL.

sortBy'TOKENS' | 'CASH_PNL' | 'REALIZED_PNL' | 'TOTAL_PNL'

Metric used to order holders inside each outcome group.

Example:TOTAL_PNL

Metric used to order holders inside each outcome group. Defaults to TOTAL_PNL.

sortDirection'ASC' | 'DESC'

Sort direction.

Example:DESC

Sort direction. Defaults to DESC.

limitinteger
Example:50

Maximum number of holders to return per outcome group. Defaults to 50.

offsetinteger

Starting offset per outcome group. Defaults to 0.

Response

OK

Example response

{
  "data": [
    {
      "token": "71321045679252212594626385532706912750332728571942612009397583165281712267356",
      "positions": [
        {
          "proxyWallet": "0x56687bf447db6ffa42ffe2204a05edaa20f55839",
          "name": "JaneDoe",
          "profileImage": "https://polymarket.com/avatars/jane.png",
          "asset": "71321045679252212594626385532706912750332728571942612009397583165281712267356",
          "conditionId": "0xdd22472e552920b8438158ea7238bfadfa4f736aa4cee91a6b86c39ead110917",
          "avgPrice": 0.38,
          "size": 12500,
          "currPrice": 0.42,
          "currentValue": 5250,
          "cashPnl": 500,
          "totalBought": 4750,
          "totalPnl": 500,
          "outcome": "YES"
        }
      ]
    }
  ],
  "pagination": {
    "pageSize": 100
  }
}