Skip to main content
GET
/
polymarket
/
holders
/
positions
/
{position_id}
Get position holders
curl --request GET \
  --url https://api.struct.to/v1/polymarket/holders/positions/{position_id}
{
  "position_id": "<string>",
  "total_holders": 123,
  "holders": [
    {
      "trader": {
        "address": "<string>",
        "name": "<string>",
        "pseudonym": "<string>",
        "profile_image": "<string>",
        "x_username": "<string>",
        "verified_badge": true
      },
      "shares": "<string>",
      "shares_usd": "<string>",
      "usd_balance": "<string>",
      "pnl": {
        "total_buys": 123,
        "total_sells": 123,
        "total_shares_bought": 123,
        "total_shares_sold": 123,
        "total_buy_usd": 123,
        "total_sell_usd": 123,
        "redemption_usd": 123,
        "merge_usd": 123,
        "convert_collateral_usd": 123,
        "converted_count": 123,
        "converted_shares_gained": 123,
        "converted_shares_lost": 123,
        "avg_entry_price": 123,
        "avg_exit_price": 123,
        "avg_price": 123,
        "realized_pnl_usd": 123,
        "total_pnl_usd": 123,
        "unrealized_pnl_usd": 123,
        "total_fees": 123,
        "first_trade_at": 123,
        "last_trade_at": 123,
        "last_traded_price": 123,
        "realized_pnl_pct": 123,
        "total_pnl_pct": 123,
        "won": true,
        "redeemable": true,
        "mergeable": true
      }
    }
  ],
  "condition_id": "<string>",
  "outcome_name": "<string>",
  "outcome_index": 123,
  "price": 123
}

Path Parameters

position_id
string
required

Position ID (ERC1155 token ID)

Query Parameters

limit
integer<int32>

Results limit (default: 10, max: 100)

pagination_key
string

Cursor-based pagination key

min_shares
string

Minimum shares held (decimal string)

max_shares
string

Maximum shares held (decimal string)

include_pnl
boolean

Include nested holder PnL data (default: false, +1 credit)

Response

Position holders (sorted by shares DESC). Holder pnl is included only when include_pnl=true.

Response for position (position_id) holders endpoint.

position_id
string
required

Position ID (ERC1155 token ID).

total_holders
integer<int64>
required

Total holders of this position.

holders
object[]
required

Top holders.

condition_id
string | null

Condition ID this position belongs to.

outcome_name
string | null

Outcome name (Yes, No, etc.).

outcome_index
integer<int32> | null

Outcome index.

price
number<double> | null

Current price / probability.

Last modified on June 17, 2026