Real-Time Risk Alerts (WebSocket)

GET /v1/alerts/ws — WebSocket upgrade for real-time risk alert streaming.

Overview

Connect via WebSocket to receive push notifications when risk thresholds are breached for monitored wallets. Alerts are emitted whenever the /v1/monitor/{wallet} endpoint detects threshold violations.

Connection Flow

1. Connect to wss://api.canonprotocol.org/v1/alerts/ws
2. Send an AlertConfig JSON message to subscribe
3. Receive a {"subscribed": "0x..."} confirmation
4. Receive RiskAlert JSON messages when thresholds breach
5. Server sends WebSocket pings every 15s for keepalive

AlertConfig (send on connect)

Field	Type	Default	Description
wallet	string	required	Ethereum wallet address to monitor
thresholds.max_risk_score	u8	70	Alert when risk score exceeds this
thresholds.min_liquidation_distance_pct	f64	5.0	Alert when liq distance drops below this %
thresholds.max_portfolio_var_pct	f64	50.0	Alert when portfolio VaR exceeds this %
thresholds.max_funding_drag_daily_pct	f64	1.0	Alert when daily funding drag exceeds this %

Example

{
  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "thresholds": {
    "max_risk_score": 60,
    "min_liquidation_distance_pct": 8.0
  }
}

RiskAlert (received from server)

Field	Type	Description
alert_type	string	liquidation_proximity, high_risk_score, portfolio_var_breach, funding_drag_excessive, regime_shift
wallet	string	Wallet address
asset	string?	Asset symbol (null for portfolio-level alerts)
severity	string	warning or critical
message	string	Human-readable alert description
timestamp	string	ISO 8601 timestamp
current_value	f64	Current metric value that triggered the alert
threshold	f64	Threshold that was breached

Example Alert

{
  "alert_type": "liquidation_proximity",
  "wallet": "0x1234...",
  "asset": "ETH",
  "severity": "critical",
  "message": "Liquidation distance 1.8% below threshold 8.0%",
  "timestamp": "2026-03-21T18:30:00Z",
  "current_value": 1.8,
  "threshold": 8.0
}

Severity Levels

• critical: Risk score >= 85 or liquidation distance < 2% or regime shift to crisis
• warning: All other threshold breaches

Notes

• This endpoint does not require authentication (WebSocket connections are stateless)
• Alerts are only emitted when the monitor endpoint is called (pull-based triggering)
• Disconnected clients are automatically unsubscribed