Skip to main content
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

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 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. 
await alerts.subscribe("trader_whale_trade", {
  wallet_addresses: ["0xd91..."],
  min_usd_value: 10_000,
});

await alerts.subscribe("probability_spike", {
  spike_direction: "up",
  min_probability_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. 
alerts.on("trader_whale_trade", (payload) => {
  payload.data.trader;
  payload.data.amount_usd;
});

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

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

​
Unsubscribe

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. 
alerts.on("connected", () => console.log("alerts live"));
alerts.on("auth_failed", (err) => console.error(err));

​
Available alerts

See Alerts 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
  • market_volume_milestone, event_volume_milestone, position_volume_milestone
  • probability_spike, 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
Last modified on April 25, 2026