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

# Alerts WS

> Typed subscriptions on the alerts websocket with StructAlertsWebSocket.

`StructAlertsWebSocket` connects to the alerts endpoint (`wss://api.struct.to/ws/alerts`) and surfaces per-event typed filters and payloads. Unlike rooms, alerts use a single flat subscribe-by-event protocol with no join step.

## Connect

```typescript theme={null}
import { StructAlertsWebSocket } from "@structbuild/sdk";

const alerts = new StructAlertsWebSocket({ apiKey: "sk_live_xxx" });
await alerts.connect();
```

The config shape, reconnect behaviour, and lifecycle events match `StructWebSocket`. See [WebSockets](/sdk/websockets) for shared configuration.

## Subscribe

Each alert event has its own filter type. Pass the event name as the first argument; the second argument is typechecked against the matching schema.

```typescript theme={null}
await alerts.subscribe("trader_whale_trade", {
  wallet_addresses: ["0xd91..."],
  min_usd_value: 10_000,
});

await alerts.subscribe("price_spike", {
  spike_direction: "up",
  min_price_change_pct: 5,
});

await alerts.subscribe("market_volume_milestone", {
  condition_ids: ["0xabc..."],
  timeframes: ["1h", "24h"],
  milestone_amounts: [100_000, 1_000_000],
});
```

`subscribe` returns a promise that resolves with `{ op: "subscribed", event, subscription_id }` once the server acknowledges. Subsequent subscribes on the same event replace the previous filter.

## Listen for events

Payloads arrive as `{ event, timestamp, data }`. The `data` shape is narrowed by the event name you listened to.

```typescript theme={null}
alerts.on("trader_whale_trade", (payload) => {
  payload.data.trader;
  payload.data.amount_usd;
});

alerts.on("price_spike", (payload) => {
  payload.data.spike_direction;
  payload.data.spike_pct;
});

alerts.on("market_created", (payload) => {
  payload.data.condition_id;
  payload.data.market_slug;
});
```

## Unsubscribe

```typescript theme={null}
alerts.unsubscribe("trader_whale_trade");
alerts.disconnect();
```

## Lifecycle events

`StructAlertsWebSocket` emits the same lifecycle events as the rooms socket: `connected`, `disconnected`, `reconnecting`, `reconnect_failed`, `auth_failed`, `error`, `warning`.

```typescript theme={null}
alerts.on("connected", () => console.log("alerts live"));
alerts.on("auth_failed", (err) => console.error(err));
```

## Available alerts

See [Alerts](/websockets/alerts/getting-started) for the full list of events, filters, and payload schemas. Every event documented there is supported by `StructAlertsWebSocket.subscribe` with full TypeScript types.

Common alerts include:

* `trader_first_trade`, `trader_new_market`, `trader_new_trade`, `trader_trade_event`, `trader_whale_trade`
* `trader_global_pnl`, `trader_market_pnl`, `trader_event_pnl`
* `condition_metrics`, `event_metrics`, `position_metrics`, `tag_metrics`
* `market_volume_milestone`, `event_volume_milestone`, `position_volume_milestone`
* `price_spike`, `market_volume_spike`, `event_volume_spike`, `position_volume_spike`
* `close_to_bond`, `market_created`, `oracle_events`
* `asset_price_tick`, `asset_price_window_update`