> ## 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.

# Position Metrics

> Get notified when a position's volume or price metrics cross a threshold.

<Note>
  **Event:** `position_metrics` \
  **Endpoint:** `wss://api.struct.to/ws/alerts` \
  **Cost:** 0.1 credits per event
</Note>

Get notified when a position's volume or price metrics cross a threshold. This event supports a wide range of filters for volume, fees, trader counts, and price or probability changes.

## Filters

| Filter                       | Type      | Required | Description                                                                    |
| ---------------------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `position_ids`               | string\[] | No       | Restrict to specific positions (max 500)                                       |
| `condition_ids`              | string\[] | No       | Restrict to specific conditions (max 500)                                      |
| `outcomes`                   | string\[] | No       | Filter by outcome name, e.g. `["Yes", "No"]` (max 500)                         |
| `min_volume_usd`             | number    | No       | Minimum volume in USD                                                          |
| `max_volume_usd`             | number    | No       | Maximum volume in USD                                                          |
| `min_buy_usd`                | number    | No       | Minimum buy volume in USD                                                      |
| `min_sell_volume_usd`        | number    | No       | Minimum sell volume in USD                                                     |
| `min_fees`                   | number    | No       | Minimum fees in USD                                                            |
| `min_txns`                   | number    | No       | Minimum transaction count                                                      |
| `min_unique_traders`         | number    | No       | Minimum unique trader count                                                    |
| `min_price_change_pct`       | number    | No       | Minimum price change percentage                                                |
| `min_probability_change_pct` | number    | No       | Minimum probability change percentage                                          |
| `timeframes`                 | string\[] | No       | Timeframe windows: `1m`, `5m`, `30m`, `1h`, `6h`, `24h`, `7d`, `30d` (max 500) |

## Subscribe

```json theme={null}
{
  "op": "subscribe",
  "event": "position_metrics",
  "min_volume_usd": 500,
  "outcomes": ["Yes"],
  "timeframes": ["5m", "30m"]
}
```

## Response

<Info>
  **Volume on Polymarket vs. Struct.** Polymarket's UI reports "volume" as notional (the count of shares or contracts traded), which corresponds to `shares_volume` in Struct payloads. `usd_volume` is the dollar value of those trades. Use `shares_volume` to match figures shown on Polymarket and `usd_volume` for true USD throughput.
</Info>

```json theme={null}
{
  "event": "position_metrics",
  "timestamp": 1775913505260,
  "data": {
    "position_id": "0xabc123",
    "outcome": "Yes",
    "outcome_index": 0,
    "timeframe": "5m",
    "volume_usd": 3420.75,
    "buy_volume_usd": 2100.00,
    "sell_volume_usd": 1320.75,
    "shares_volume": 5260.0,
    "shares_buy_volume": 3230.0,
    "shares_sell_volume": 2030.0,
    "builder_usd_volume": 860.0,
    "builder_usd_buy_volume": 540.0,
    "builder_usd_sell_volume": 320.0,
    "builder_shares_volume": 1320.0,
    "builder_shares_buy_volume": 830.0,
    "builder_shares_sell_volume": 490.0,
    "fees": 34.20,
    "builder_fees": 8.6,
    "txns": 18,
    "buys": 12,
    "sells": 6,
    "builder_txns": 5,
    "builder_buys": 3,
    "builder_sells": 2,
    "unique_traders": 9,
    "unique_builder_traders": 3,
    "price_open": 0.62,
    "price_close": 0.65,
    "price_high": 0.67,
    "price_low": 0.60,
    "probability_open": 0.61,
    "probability_close": 0.64,
    "probability_high": 0.66,
    "probability_low": 0.59,
    "avg_trade_shares": 292.22,
    "avg_buy_shares": 269.17,
    "avg_sell_shares": 338.33
  }
}
```

Each payload includes builder-attributed counterparts for volume, fees, transactions, and unique traders, with separate buy and sell breakdowns. `avg_trade_shares`, `avg_buy_shares`, and `avg_sell_shares` report the average size of trades, buys, and sells in the window.