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

Only the above `thresholds.*` keys are accepted. Unknown keys are rejected.

### Example

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

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