> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Holder Metrics

> Stream real-time holder counts for positions, conditions, and events.

<Note>
  **Room ID:** `polymarket_holder_metrics` \
  **Endpoint:** `wss://api.struct.to/ws` \
  **Rate:** 0.025 credits per message
</Note>

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.

<Tip>
  **Related guide:** [Holder metrics tracking](/guides/holder-metrics-tracking) tracks holder growth across positions, markets, and events.
</Tip>

## Subscribe

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

```json theme={null}
{
  "type": "join_room",
  "payload": {
    "room_id": "polymarket_holder_metrics"
  }
}
```

```json theme={null}
{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_holder_metrics",
    "message": {
      "action": "subscribe",
      "condition_ids": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"]
    }
  }
}
```

### Response

```json theme={null}
{
  "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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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.

```json theme={null}
{
  "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    |