> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Get position holders

> Retrieve holders of a specific position (ERC1155 token), sorted by shares held. Set `include_pnl=true` to include a per-holder `pnl` object. Uses cursor-based pagination.



## OpenAPI

````yaml https://api.struct.to/openapi.json get /polymarket/holders/positions/{position_id}
openapi: 3.1.0
info:
  title: Polymarket API
  description: >-
    RESTful API for querying Polymarket prediction markets data including
    events, markets, traders, holders, and real-time metrics
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.struct.to/v1
security: []
paths:
  /polymarket/holders/positions/{position_id}:
    get:
      tags:
        - Holders
      summary: Get position holders
      description: >-
        Retrieve holders of a specific position (ERC1155 token), sorted by
        shares held. Set `include_pnl=true` to include a per-holder `pnl`
        object. Uses cursor-based pagination.
      operationId: get_position_holders
      parameters:
        - name: position_id
          in: path
          description: Position ID (ERC1155 token ID)
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: 'Results limit (default: 10, max: 100)'
          required: false
          schema:
            type: integer
            format: int32
        - name: pagination_key
          in: query
          description: Cursor-based pagination key
          required: false
          schema:
            type: string
        - name: min_shares
          in: query
          description: Minimum shares held (decimal string)
          required: false
          schema:
            type: string
        - name: max_shares
          in: query
          description: Maximum shares held (decimal string)
          required: false
          schema:
            type: string
        - name: include_pnl
          in: query
          description: 'Include nested holder PnL data (default: false)'
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: >-
            Position holders (sorted by shares DESC). Holder `pnl` is included
            only when `include_pnl=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionHoldersResponse'
        '404':
          description: Position not found
components:
  schemas:
    PositionHoldersResponse:
      type: object
      description: Response for position (position_id) holders endpoint.
      required:
        - position_id
        - total_holders
        - holders
      properties:
        position_id:
          type: string
          description: Position ID (ERC1155 token ID).
        condition_id:
          type:
            - string
            - 'null'
          description: Condition ID this position belongs to.
        outcome_name:
          type:
            - string
            - 'null'
          description: Outcome name (Yes, No, etc.).
        outcome_index:
          type:
            - integer
            - 'null'
          format: int32
          description: Outcome index.
        price:
          type:
            - number
            - 'null'
          format: double
          description: Current price / probability.
        total_holders:
          type: integer
          format: int64
          description: Total holders of this position.
        holders:
          type: array
          items:
            $ref: '#/components/schemas/PositionHolder'
          description: Top holders.
    PositionHolder:
      type: object
      description: Position holder.
      required:
        - trader
        - shares
      properties:
        trader:
          $ref: '#/components/schemas/Trader'
          description: Trader profile.
        shares:
          type: string
          description: Position shares held (raw balance as decimal string for precision).
        shares_usd:
          type:
            - string
            - 'null'
          description: USD value of shares (shares × latest price).
        usd_balance:
          type:
            - string
            - 'null'
          description: USD balance of the holder's wallet.
        pnl:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PositionHolderPnl'
              description: Position-level PnL for this holder.
    Trader:
      type: object
      description: |-
        Trader profile info embedded in API responses.

        Used in:
        - holders endpoints (market/event holders)
        - trades endpoints
        - leaderboard endpoints
      required:
        - address
      properties:
        address:
          type: string
        name:
          type:
            - string
            - 'null'
        pseudonym:
          type:
            - string
            - 'null'
        profile_image:
          type:
            - string
            - 'null'
        x_username:
          type:
            - string
            - 'null'
        verified_badge:
          type: boolean
    PositionHolderPnl:
      type: object
      description: Position-level PnL for a holder, included when `include_pnl=true`.
      properties:
        total_buys:
          type:
            - integer
            - 'null'
          format: int64
          description: Total buys.
        total_sells:
          type:
            - integer
            - 'null'
          format: int64
          description: Total sells.
        total_shares_bought:
          type:
            - number
            - 'null'
          format: double
          description: Total shares bought.
        total_shares_sold:
          type:
            - number
            - 'null'
          format: double
          description: Total shares sold.
        total_buy_usd:
          type:
            - number
            - 'null'
          format: double
          description: Total buy in USD.
        total_sell_usd:
          type:
            - number
            - 'null'
          format: double
          description: Total sell in USD.
        redemption_usd:
          type:
            - number
            - 'null'
          format: double
          description: Redemption in USD.
        merge_usd:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Merge proceeds (combining outcome tokens back to collateral).
            Counted toward realized PnL alongside sells and redemptions.
        convert_collateral_usd:
          type:
            - number
            - 'null'
          format: double
          description: Convert collateral in USD.
        converted_count:
          type:
            - integer
            - 'null'
          format: int64
          description: Converted count.
        converted_shares_gained:
          type:
            - number
            - 'null'
          format: double
          description: Converted shares gained.
        converted_shares_lost:
          type:
            - number
            - 'null'
          format: double
          description: Converted shares lost.
        avg_entry_price:
          type:
            - number
            - 'null'
          format: double
          description: Average entry price.
        avg_exit_price:
          type:
            - number
            - 'null'
          format: double
          description: Average exit price.
        avg_price:
          type:
            - number
            - 'null'
          format: double
          description: Volume-weighted average trade price across buys + sells.
        realized_pnl_usd:
          type: number
          format: double
          description: Realized PnL in USD.
        total_pnl_usd:
          type: number
          format: double
          description: Total PnL in USD.
        unrealized_pnl_usd:
          type: number
          format: double
          description: Unrealized PnL in USD.
        total_fees:
          type:
            - number
            - 'null'
          format: double
          description: Total fees.
        first_trade_at:
          type:
            - integer
            - 'null'
          format: int64
          description: First trade at timestamp.
        last_trade_at:
          type:
            - integer
            - 'null'
          format: int64
          description: Last trade at timestamp.
        last_traded_price:
          type:
            - number
            - 'null'
          format: double
          description: Last traded price.
        realized_pnl_pct:
          type:
            - number
            - 'null'
          format: double
          description: Realized PnL percent.
        total_pnl_pct:
          type:
            - number
            - 'null'
          format: double
          description: Total PnL percent.
        won:
          type:
            - boolean
            - 'null'
          description: Won.
        redeemable:
          type:
            - boolean
            - 'null'
          description: Redeemable.
        mergeable:
          type:
            - boolean
            - 'null'
          description: Mergeable.

````