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

# Getting Started

> Receive webhook-style events over a websocket connection.

## Overview

The Alerts endpoint lets you receive the same events as Struct's webhooks (trader whale trades, PnL crossings, price spikes, volume milestones, and more) pushed directly over a websocket connection instead of HTTP POSTs.

This is useful when you want the low-latency push model of webhooks without having to host a public HTTP endpoint.

<Card title="Perfect for In-App Alert Systems" icon="bell">
  Alerts are especially well-suited for building in-app notification systems on trading platforms, letting your users track specific wallets, listen for price spikes on markets they care about, get notified when volume milestones are hit, or follow whale activity in real time.

  Because subscriptions are scoped to a single connection, you can open a dedicated socket per logged-in user and dynamically subscribe and unsubscribe as they adjust their alert preferences, without touching any server-side webhook configuration.
</Card>

## Endpoint

```
wss://api.struct.to/ws/alerts?api-key=YOUR_API_KEY
```

Alerts use the same API key authentication as the Rooms endpoint. Subscriptions are ephemeral: they live only for the duration of the connection and are dropped on disconnect.

## Subscribing

Subscribe to an alert type by sending a JSON message. The `op` and `event` fields identify the subscription; all filter fields are flat on the top level of the message.

```json theme={null}
{
  "op": "subscribe",
  "event": "trader_whale_trade",
  "wallet_addresses": ["0xabc..."],
  "min_usd_value": 10000
}
```

The server acknowledges with:

```json theme={null}
{
  "op": "subscribed",
  "event": "trader_whale_trade",
  "subscription_id": "b9c0e4b0-1a2d-4e3f-9c0a-111122223333"
}
```

## Unsubscribing

Send an `unsubscribe` message whose filter fields match the original subscription exactly:

```json theme={null}
{
  "op": "unsubscribe",
  "event": "trader_whale_trade",
  "wallet_addresses": ["0xabc..."],
  "min_usd_value": 10000
}
```

Response:

```json theme={null}
{
  "op": "unsubscribed",
  "event": "trader_whale_trade"
}
```

## Message Format

Each alert is pushed as JSON with the event name, a millisecond Unix timestamp, and the payload:

```json theme={null}
{
  "event": "trader_whale_trade",
  "timestamp": 1775913505260,
  "data": { ... }
}
```

## Available Events

### Trader Events

| Event                                                                     | Description                                                    |
| ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`trader_first_trade`](/websockets/alerts/trader-first-trade)             | First-ever trade by a trader on Polymarket                     |
| [`trader_new_market`](/websockets/alerts/trader-new-market)               | Trader's first trade in a specific market                      |
| [`trader_new_trade`](/websockets/alerts/trader-new-trade)                 | Every order-filled trade, with optional filters                |
| [`trader_trade_event`](/websockets/alerts/trader-trade-event)             | Typed trade-event union covering every confirmed trade variant |
| [`trader_whale_trade`](/websockets/alerts/trader-whale-trade)             | Trade exceeds configured size and probability thresholds       |
| [`trader_global_pnl`](/websockets/alerts/trader-global-pnl)               | Trader's global PnL crosses a threshold                        |
| [`trader_market_pnl`](/websockets/alerts/trader-market-pnl)               | Trader's per-market PnL crosses a threshold                    |
| [`trader_category_pnl`](/websockets/alerts/trader-category-pnl)           | Trader's per-category PnL crosses a threshold                  |
| [`trader_position_resolved`](/websockets/alerts/trader-position-resolved) | A trader's position resolves win or loss                       |
| [`trader_pnl_exits`](/websockets/alerts/trader-pnl-exits)                 | A trader closes a position, with the realized result           |

### Holders

| Event                                                                     | Description                          |
| ------------------------------------------------------------------------- | ------------------------------------ |
| [`position_holder_metrics`](/websockets/alerts/position-holder-metrics)   | Holder metrics update for a position |
| [`condition_holder_metrics`](/websockets/alerts/condition-holder-metrics) | Holder metrics update for a market   |
| [`event_holder_metrics`](/websockets/alerts/event-holder-metrics)         | Holder metrics update for an event   |

### Metrics

| Event                                                       | Description                                            |
| ----------------------------------------------------------- | ------------------------------------------------------ |
| [`condition_metrics`](/websockets/alerts/condition-metrics) | Market volume or transaction metrics cross a threshold |
| [`event_metrics`](/websockets/alerts/event-metrics)         | Event aggregated metrics cross a threshold             |
| [`position_metrics`](/websockets/alerts/position-metrics)   | Position metrics cross a threshold                     |

### Volume Milestones

| Event                                                                       | Description                             |
| --------------------------------------------------------------------------- | --------------------------------------- |
| [`market_volume_milestone`](/websockets/alerts/market-volume-milestone)     | Market volume crosses a USD milestone   |
| [`event_volume_milestone`](/websockets/alerts/event-volume-milestone)       | Event volume crosses a USD milestone    |
| [`position_volume_milestone`](/websockets/alerts/position-volume-milestone) | Position volume crosses a USD milestone |

### Spikes

| Event                                                               | Description                                           |
| ------------------------------------------------------------------- | ----------------------------------------------------- |
| [`price_spike`](/websockets/alerts/price-spike)                     | Position price changes rapidly                        |
| [`price_threshold`](/websockets/alerts/price-threshold)             | Outcome price crosses a target level (edge-triggered) |
| [`market_volume_spike`](/websockets/alerts/market-volume-spike)     | Market volume exceeds baseline by spike ratio         |
| [`event_volume_spike`](/websockets/alerts/event-volume-spike)       | Event volume exceeds baseline by spike ratio          |
| [`position_volume_spike`](/websockets/alerts/position-volume-spike) | Position volume exceeds baseline by spike ratio       |

### Market Lifecycle

| Event                                                   | Description                                         |
| ------------------------------------------------------- | --------------------------------------------------- |
| [`close_to_bond`](/websockets/alerts/close-to-bond)     | Trade at a near-certain-outcome price               |
| [`market_created`](/websockets/alerts/market-created)   | New prediction market detected on-chain             |
| [`oracle_events`](/websockets/alerts/oracle-events)     | Typed UMA oracle lifecycle event affecting a market |
| [`market_resolved`](/websockets/alerts/market-resolved) | Market reaches a terminal resolution                |
| [`market_disputed`](/websockets/alerts/market-disputed) | Proposed resolution challenged on-chain             |

### Asset Prices

| Event                                                                       | Description                                 |
| --------------------------------------------------------------------------- | ------------------------------------------- |
| [`asset_price_tick`](/websockets/alerts/asset-price-tick)                   | Raw Chainlink price tick for a crypto asset |
| [`asset_price_window_update`](/websockets/alerts/asset-price-window-update) | Crypto asset candle open or close           |

## Errors

Invalid messages return a JSON error:

```json theme={null}
{
  "error": "unknown event type"
}
```

## Keepalive

Send a periodic ping to keep the connection alive:

```json theme={null}
{ "type": "ping" }
```

The server responds with `{ "type": "pong" }`.

## Pricing

Alerts are billed **per delivered event** depending on the event type (0.025, 0.1, or 0.2 credits), with a standard 1 credit connection hold on connect. See each alert's page for its specific cost, or visit [Pricing](/websockets/pricing) for details.

## Rooms vs. Alerts

|               | Rooms (`/ws`)                              | Alerts (`/ws/alerts`)              |
| ------------- | ------------------------------------------ | ---------------------------------- |
| **Shape**     | Raw data streams (trades, prices, metrics) | Event-triggered notifications      |
| **Filtering** | Room-specific filter fields                | Same filters as webhooks           |
| **Billing**   | Per-message rate by room                   | Per-event rate by event type       |
| **Use case**  | Dashboards, trading UIs, analytics         | Notifications, agents, automations |