Get combo holders

Retrieve holders of one combo side position from the Polymarket holders engine. Pass the combo row’s yes_position_id or no_position_id from /polymarket/combos or /polymarket/combos/metrics; do not pass a leg position_id or condition_id. Set include_pnl=true to include a per-holder pnl object for this combo side. Combo holder state is stored separately from normal position holder state and is sorted by combo position balance descending.

GET /polymarket/combos/{position_id}/holders

Get combo holders

cURL

curl --request GET \
  --url https://api.struct.to/v1/polymarket/combos/{position_id}/holders

200

{
  "position_id": "<string>",
  "total_holders": 1,
  "holders": [
    {
      "wallet": "<string>",
      "balance": 123,
      "balance_raw": "<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
}

Path Parameters

position_id · string · required

Combo side position ID: the yes_position_id or no_position_id returned by /polymarket/combos or /polymarket/combos/metrics (ERC1155 token ID, decimal or 0x-prefixed hex). Do not use leg position IDs.

Query Parameters

limit · integer<int32>

Results limit (default: 50, max: 500)

pagination_key · string

Cursor from the previous response

min_shares · string

Minimum combo balance held, in decimal shares

max_shares · string

Maximum combo balance held, in decimal shares

include_pnl · boolean

Include nested holder PnL data for this combo side (default: false)

Response

200

application/json

Combo holders sorted by balance descending

position_id · string · required

Combo side position ID that was queried (yes_position_id or no_position_id).

total_holders · integer · required

Total unique holders for this combo position.

Required range: x >= 0

holders · object[] · required

Holders sorted by combo position balance descending.

Show child attributes

condition_id · string | null

Combo condition ID this side position belongs to.

outcome_name · string | null

Outcome name (Yes or No).

outcome_index · integer<int32> | null

Outcome index (0 = Yes, 1 = No).