---
title: "Get top holders of a market"
method: GET
path: "/v4/data/prediction/markets/{id}/positions"
tags: ["Prediction API"]
---

# Get top holders of a market

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

/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).

## Path parameters

- `id` string, required

## Query parameters

- `user` string
- `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.
- `sortBy` 'TOKENS' | 'CASH_PNL' | 'REALIZED_PNL' | 'TOTAL_PNL' — Metric used to order holders inside each outcome group.
- `sortDirection` 'ASC' | 'DESC' — Sort direction.
- `limit` integer
- `offset` integer

## Response `200`

OK

- PredictionMarketPositionsResponse — Top-holders response. `pagination.pageSize` / `pageNumber` apply per outcome group (so a binary market with `limit=50` returns up to 100 rows total — 50 per outcome).
  - `data` PredictionMarketPositionsGroup[], required
    - `token` string, required — Outcome-token asset id.
    - `positions` PredictionMarketPositionHolder[], required — Holders of this outcome, ordered by the requested `sortBy` / `sortDirection`.
      - `proxyWallet` string, required — Holder wallet (0x + 40 hex, lowercased).
      - `name` string, nullable, required — Holder display name, when set on their profile.
      - `profileImage` string, nullable, required — Holder profile image URL, when set.
      - `verified` boolean, required — Whether the holder has a verified-badge on their profile.
      - `asset` string, required — Polymarket outcome-token asset id this holder owns.
      - `conditionId` string, required — Market condition id (0x + 64 hex).
      - `avgPrice` number, required — Volume-weighted average entry price.
      - `size` number, required — Current position size (outcome tokens).
      - `currPrice` number, required — Current market price of the outcome.
      - `currentValue` number, required — Current USD mark-to-market value of the position.
      - `cashPnl` number, required — Unrealised PnL in USD.
      - `totalBought` number, required — Lifetime USD spent acquiring this position.
      - `realizedPnl` number, required — Realised PnL in USD.
      - `totalPnl` number, required — Sum of cashPnl and realizedPnl.
      - `outcome` string, nullable, required — Outcome label (e.g. `YES` / `NO`).
      - `outcomeIndex` integer, required — Outcome index (0 / 1 on binary markets).
  - `pagination` PredictionOffsetPagination, required — Offset-based pagination metadata, returned by every wallet endpoint and by `/markets/{id}/positions`. `pageNumber` is the zero-indexed page derived from `offset / limit` on the request.
    - `pageSize` integer, required — Page size of the call that produced this response.
    - `pageNumber` integer, required — Zero-indexed page number (`offset / limit`).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403` — Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500` — Internal server error. There was an error on the server during the processing of the request.

---

[API](https://skmtc.dev/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.dev/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tatum/blockchain-data/revisions/8622ee4b8fae/schema)