Getting Started - Struct Docs

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.

Perfect for In-App Alert Systems

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.

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.

{
  "op": "subscribe",
  "event": "trader_whale_trade",
  "wallet_addresses": ["0xabc..."],
  "min_usd_value": 10000
}

The server acknowledges with:

{
  "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:

{
  "op": "unsubscribe",
  "event": "trader_whale_trade",
  "wallet_addresses": ["0xabc..."],
  "min_usd_value": 10000
}

Response:

{
  "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:

{
  "event": "trader_whale_trade",
  "timestamp": 1775913505260,
  "data": { ... }
}

Available Events

Trader Events

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

Holders

Event	Description
`position_holder_metrics`	Holder metrics update for a position
`condition_holder_metrics`	Holder metrics update for a market
`event_holder_metrics`	Holder metrics update for an event

Metrics

Event	Description
`condition_metrics`	Market volume or transaction metrics cross a threshold
`event_metrics`	Event aggregated metrics cross a threshold
`position_metrics`	Position metrics cross a threshold

Volume Milestones

Event	Description
`market_volume_milestone`	Market volume crosses a USD milestone
`event_volume_milestone`	Event volume crosses a USD milestone
`position_volume_milestone`	Position volume crosses a USD milestone

Spikes

Event	Description
`price_spike`	Position price changes rapidly
`price_threshold`	Outcome price crosses a target level (edge-triggered)
`market_volume_spike`	Market volume exceeds baseline by spike ratio
`event_volume_spike`	Event volume exceeds baseline by spike ratio
`position_volume_spike`	Position volume exceeds baseline by spike ratio

Market Lifecycle

Event	Description
`close_to_bond`	Trade at a near-certain-outcome price
`market_created`	New prediction market detected on-chain
`oracle_events`	Typed UMA oracle lifecycle event affecting a market
`market_resolved`	Market reaches a terminal resolution
`market_disputed`	Proposed resolution challenged on-chain

Asset Prices

Event	Description
`asset_price_tick`	Raw Chainlink price tick for a crypto asset
`asset_price_window_update`	Crypto asset candle open or close

Errors

Invalid messages return a JSON error:

{
  "error": "unknown event type"
}

Keepalive

Send a periodic ping to keep the connection alive:

{ "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 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

​Overview

Perfect for In-App Alert Systems

​Endpoint

​Subscribing

​Unsubscribing

​Message Format

​Available Events

​Trader Events

​Holders

​Metrics

​Volume Milestones

​Spikes

​Market Lifecycle

​Asset Prices

​Errors

​Keepalive

​Pricing

​Rooms vs. Alerts