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": {
            "buy_usd": 123,
            "sell_usd": 123,
            "avg_entry_price": 123,
            "avg_exit_price": 123,
            "total_buys": 123,
            "total_sells": 123,
            "total_fees": 123,
            "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 (e.g. will-trump-win)

limit
integer<int32>

Results limit (default: 10, max: 100)

min_shares
string

Minimum shares held (decimal string)

max_shares
string

Maximum shares held (decimal string)

ai
boolean

Return truncated response optimized for AI consumers (default: false)

Response

Market holders grouped by outcome (sorted by shares DESC). Each holder has pnl: PositionHolderPnl with outcome-specific trading stats.

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 (from holder_stats)

outcomes
object[]
required

Holders grouped by outcome

question
string | null

Market question/title

slug
string | null

Market slug

Last modified on March 17, 2026