Skip to main content
GET
/
polymarket
/
holders
/
markets
Get market holders
curl --request GET \
  --url https://api.struct.to/v1/polymarket/holders/markets
{
  "condition_id": "<string>",
  "total_holders": 123,
  "outcomes": [
    {
      "outcome_index": 123,
      "outcome_name": "<string>",
      "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": {
            "realized_pnl_usd": 123,
            "total_pnl_usd": 123,
            "unrealized_pnl_usd": 123,
            "total_volume_usd": 123,
            "buy_volume_usd": 123,
            "sell_volume_usd": 123,
            "redemption_volume_usd": 123,
            "merge_volume_usd": 123,
            "convert_collateral_usd": 123,
            "total_fees": 123,
            "total_buys": 1,
            "total_sells": 1,
            "total_splits": 1,
            "total_shares_bought": 123,
            "total_shares_sold": 123,
            "buy_count": 1,
            "sell_count": 1,
            "redeem_count": 1,
            "merge_count": 1,
            "split_count": 1,
            "split_volume_usd": 123,
            "converted_count": 1,
            "converted_shares_gained": 123,
            "converted_shares_lost": 123,
            "outcomes_traded": 1,
            "resolved": true,
            "realized_pnl_pct": 123,
            "total_pnl_pct": 123,
            "won": true,
            "first_trade_at": 123,
            "last_trade_at": 123
          }
        }
      ],
      "price": 123
    }
  ],
  "question": "<string>",
  "slug": "<string>"
}

Query Parameters

condition_id
string

Market condition ID (0x-prefixed hex)

market_slug
string

Market slug

limit
integer<int32>

Results limit per outcome (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

Market holders grouped by outcome (sorted by shares DESC).

Response for market (condition_id) holders endpoint.

condition_id
string
required

Market condition ID.

total_holders
integer<int64>
required

Total unique holders across all outcomes of this market.

outcomes
object[]
required

Holders grouped by outcome.

question
string | null

Market question / title.

slug
string | null

Market slug.

Last modified on June 17, 2026