Holder Metrics

Room ID: polymarket_holder_metrics
Endpoint: wss://api.struct.to/ws
Rate: 0.025 credits per message

Stream real-time holder counts for positions, conditions (markets), and events, batched per block. Subscribe with at least one identifier array. Only the families you filter on are delivered.

Related guide: Holder metrics tracking tracks holder growth across positions, markets, and events.

At least one identifier array is required. Each array accepts up to 500 entries, and the combined total across all arrays may not exceed 500. You receive only the families whose filter you supply.

Filters

Filter	Type	Description
`position_ids`	`string[]`	Position token IDs, delivering position holder metrics
`condition_ids`	`string[]`	Condition IDs, delivering condition holder metrics
`event_slugs`	`string[]`	Event slugs, delivering event holder metrics
`subscribe_all`	`boolean`	Firehose: receive every holder metrics update. Filters are ignored when set

Example

{
  "type": "join_room",
  "payload": {
    "room_id": "polymarket_holder_metrics"
  }
}

{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_holder_metrics",
    "message": {
      "action": "subscribe",
      "condition_ids": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"]
    }
  }
}

Response

{
  "type": "holder_metrics_stream_subscribe_response",
  "room_id": "polymarket_holder_metrics",
  "data": {
    "position_ids": [],
    "condition_ids": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"],
    "event_slugs": [],
    "rejected": [],
    "error": null
  }
}

Events

`holder_metrics_position_batch`

Holder metrics per position.

{
  "type": "holder_metrics_position_batch",
  "room_id": "polymarket_holder_metrics",
  "block": 68420001,
  "data": [
    {
      "ts": 1743500000,
      "block": 68420001,
      "position_id": "12345678901234567",
      "holder_count": 1820,
      "total_balance": 4250000.0,
      "total_cost_basis": 2870000.0,
      "condition_holder_count": 3100,
      "event_holder_count": 5400
    }
  ]
}

Field	Type	Description
`ts`	`int`	Timestamp (Unix seconds)
`block`	`int`	Block number
`position_id`	`string`	Position token ID
`holder_count`	`int`	Holders of this position
`total_balance`	`number`	Total shares held across holders
`total_cost_basis`	`number`	Total cost basis across holders, in USD
`condition_holder_count`	`int \| null`	Holders of the owning condition
`event_holder_count`	`int \| null`	Holders of the owning event

`holder_metrics_condition_batch`

Holder metrics per condition (market).

{
  "type": "holder_metrics_condition_batch",
  "room_id": "polymarket_holder_metrics",
  "block": 68420001,
  "data": [
    {
      "ts": 1743500000,
      "block": 68420001,
      "condition_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "holder_count": 3100
    }
  ]
}

Field	Type	Description
`ts`	`int`	Timestamp (Unix seconds)
`block`	`int`	Block number
`condition_id`	`string`	Condition ID
`holder_count`	`int`	Holders of this condition

`holder_metrics_event_batch`

Holder metrics per event.

{
  "type": "holder_metrics_event_batch",
  "room_id": "polymarket_holder_metrics",
  "block": 68420001,
  "data": [
    {
      "ts": 1743500000,
      "block": 68420001,
      "event_slug": "bitcoin-price-markets",
      "holder_count": 5400
    }
  ]
}

Field	Type	Description
`ts`	`int`	Timestamp (Unix seconds)
`block`	`int`	Block number
`event_slug`	`string`	Event slug
`holder_count`	`int`	Holders of this event

Introduction

Rooms

Alerts

Filters

Example

Response

Events

`holder_metrics_position_batch`

`holder_metrics_condition_batch`

`holder_metrics_event_batch`

​Subscribe

​Filters

​Example

​Response

​Events

​holder_metrics_position_batch

​holder_metrics_condition_batch

​holder_metrics_event_batch

Subscribe

Filters

Example

Response

Events

`holder_metrics_position_batch`

`holder_metrics_condition_batch`

`holder_metrics_event_batch`