> ## Documentation Index > Fetch the complete documentation index at: https://docs.predexon.com/llms.txt > Use this file to discover all available pages before exploring further. # Position Top Holders > Top holders of a specific Polymarket token, ranked by position size Get the largest holders of a single Polymarket CTF token (one outcome side of a market), ranked by position size. Use this when you have a specific `token_id` rather than a `condition_id` — for whole-market top holders across both Yes and No, use [Market Top Holders](/api-reference/analytics/top-holders). **Requires Dev or Pro tier.** This endpoint is not available on the Free tier. ### Pagination Pass `include_count=true` to get the total holder count alongside the page. Use the `pagination_key` cursor from each response to fetch the next page. | Constraint | Value | | ---------------- | ----------------------------------------- | | `limit` | Results per page. | | `pagination_key` | Cursor returned by the previous response. | ## OpenAPI ````yaml GET /v2/polymarket/position/{token_id}/top-holders openapi: 3.1.0 info: title: Predexon API description: Prediction market data aggregation and matching API version: 2.0.0 servers: - url: https://api.predexon.com security: - apiKey: [] paths: /v2/polymarket/position/{token_id}/top-holders: get: tags: - polymarket - smart-wallet summary: Get Position Top Holders description: >- Get top holders for a specific Polymarket token, ranked by position size. operationId: >- get_position_top_holders_v2_polymarket_position__token_id__top_holders_get parameters: - name: token_id in: path required: true schema: type: string description: Polymarket CTF token ID title: Token Id description: Polymarket CTF token ID - name: include_count in: query required: false schema: type: boolean description: Include total holder count default: false title: Include Count description: Include total holder count - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 description: Results per page default: 100 title: Limit description: Results per page - name: pagination_key in: query required: false schema: anyOf: - type: string - type: 'null' description: Cursor for pagination title: Pagination Key description: Cursor for pagination responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TopHoldersResponse' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Service Unavailable components: schemas: TopHoldersResponse: properties: condition_id: type: string title: Condition Id description: Market condition ID title: anyOf: - type: string - type: 'null' title: Title description: Market title market_slug: anyOf: - type: string - type: 'null' title: Market Slug description: Market slug side: anyOf: - type: string - type: 'null' title: Side description: Position side filter applied ('yes', 'no', or null for all) total_count: anyOf: - type: integer - type: 'null' title: Total Count description: >- Total number of holders matching filters (only if include_count=true) entries: items: $ref: '#/components/schemas/TopHolderEntry' type: array title: Entries description: Top holder entries pagination: $ref: '#/components/schemas/CursorPagination' description: Pagination info type: object required: - condition_id - entries - pagination title: TopHoldersResponse description: Response for market top holders endpoint. ErrorResponse: properties: error: type: string title: Error message: type: string title: Message type: object required: - error - message title: ErrorResponse description: Standard error response. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TopHolderEntry: properties: rank: type: integer title: Rank description: Position in list (1-indexed) user: type: string title: User description: Wallet address token_id: type: string title: Token Id description: Token ID for this position position_shares: type: number title: Position Shares description: Total shares held (normalized) position_value_usd: type: number title: Position Value Usd description: Estimated position value in USD side: type: string title: Side description: Position side (Yes/No or custom label) outcome_index: type: integer title: Outcome Index description: 'Outcome index: 0 for Yes/first outcome, 1 for No/second outcome' avg_price: type: number title: Avg Price description: Average entry price (0-1) realized_pnl: type: number title: Realized Pnl description: Realized PnL in USD unrealized_pnl: type: number title: Unrealized Pnl description: Unrealized PnL in USD total_pnl: type: number title: Total Pnl description: Total PnL in USD (realized + unrealized) trade_count: type: integer title: Trade Count description: Number of trades first_trade_at: anyOf: - type: integer - type: 'null' title: First Trade At description: Unix timestamp of first trade last_trade_at: anyOf: - type: integer - type: 'null' title: Last Trade At description: Unix timestamp of last trade type: object required: - rank - user - token_id - position_shares - position_value_usd - side - outcome_index - avg_price - realized_pnl - unrealized_pnl - total_pnl - trade_count title: TopHolderEntry description: Single entry in the top holders list. CursorPagination: properties: limit: type: integer title: Limit description: Requested limit count: type: integer title: Count description: Number of items in current response pagination_key: anyOf: - type: string - type: 'null' title: Pagination Key description: Base64-encoded cursor for next page has_more: type: boolean title: Has More description: Whether there are more items available type: object required: - limit - count - has_more title: CursorPagination description: Cursor-based pagination for endpoints that don't support offset. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````