WebSocket

WebSocket Protocol

3 WebSocket endpoints for real-time data. P0 events delivered in under 100ms end-to-end.

WebSocket Endpoints

Endpoint	Tier	Data	Avg Size
`wss://nexusglass.live/ws`	STREAM	Market data snapshots, tickers, OI deltas	2-8 KB
`wss://nexusglass.live/ws/nexus-bridge`	STREAM	Bridge analytics delta updates, cross-metric correlations	1-4 KB
`wss://nexusglass.live/ws/fastfeed`	PULSE	P0/P1/P2 intelligence events with sub-100ms SLA	0.5-2 KB

Authentication

All WebSocket connections authenticate via the token query parameter.

Connection URL

wss://nexusglass.live/ws/fastfeed?token=YOUR_API_KEY&symbols=BTCUSDT,ETHUSDT

Query Parameters

Param	Required	Description
`token`	required	API key for authentication
`symbols`	optional	Comma-separated symbols to filter. Default: all 10 symbols.
`events`	optional	Comma-separated event types to subscribe to. Default: all.

FastFeed Event Types (14)

Events are classified into 3 priority levels with different SLA guarantees.

Event Type	Priority	SLA	Size	Description
`LIQUIDATION_CLUSTER_ARMED`	P0	<100ms	~800 B	Liquidation cluster detected near current price
`LEVERAGE_SPIKE_DETECTED`	P0	<100ms	~600 B	Extreme OI change detected across exchanges
`PENDING_EXCHANGE_INFLOW`	P0	<100ms	~700 B	Large exchange deposit pending in mempool
`WHALE_POSITION_SHIFT`	P1	<500ms	~1.2 KB	Significant whale position change detected
`SYNDICATE_DETECTED`	P1	<500ms	~1.5 KB	Coordinated whale activity (3+ whales)
`MM_HUNTING_GROUND_ARMED`	P1	<500ms	~900 B	Market maker trap zone activated
`DANGER_ZONE_APPROACH`	P1	<500ms	~600 B	Price entering high-risk liquidation zone
`CVD_DIVERGENCE_EXTREME`	P1	<500ms	~700 B	Price-CVD divergence beyond 2 sigma
`REGIME_SHIFT`	P2	<2s	~400 B	Market regime transition detected
`CORRELATION_BREAK`	P2	<2s	~500 B	Cross-asset correlation breakdown
`LARGE_LIQUIDATION`	P2	<2s	~700 B	Single liquidation exceeding $500K
`FUNDING_EXTREME`	P2	<2s	~500 B	Funding rate at extreme percentile levels
`MAGNETISM_HIGH`	P2	<2s	~600 B	Strong liquidation magnet pulling price
`DOMINANCE_FLIP`	P2	<2s	~500 B	Derivatives/on-chain dominance flip

P0 - Critical

Requires immediate action. Delivered in under 100ms.

P1 - Important

Significant market signal. Delivered in under 500ms.

P2 - Informational

Market context update. Delivered in under 2 seconds.

Message Types

Type	Direction	Description
`HANDSHAKE`	Server -> Client	Sent on successful connection. Contains tier info and allowed priorities.
`SNAPSHOT`	Server -> Client	Initial state snapshot of recent events. Sent after handshake.
`EVENT`	Server -> Client	Real-time event notification. Contains full event payload.
`ERROR`	Server -> Client	Error notification (auth failure, rate limit, etc.).
`PING`	Server -> Client	Keepalive ping sent every 30 seconds. Client must respond with PONG.
`PONG`	Client -> Server	Response to server PING. Must be sent within 10 seconds.

Message Examples

Handshake (on connect)

HANDSHAKE

{
  "type": "HANDSHAKE",
  "payload": {
    "tier": "PULSE",
    "priorities": ["P0", "P1", "P2"],
    "delay_ms": 0,
    "server_time": "2026-03-17T10:30:00Z"
  }
}

Event (P0 signal)

EVENT

{
  "type": "EVENT",
  "payload": {
    "id": 12346,
    "type": "LIQUIDATION_CLUSTER_ARMED",
    "priority": "P0",
    "symbol": "BTCUSDT",
    "confidence": 0.92,
    "data": {
      "cluster_price": 98500,
      "cluster_side": "LONG_LIQ",
      "intensity_usd": 5200000,
      "distance_pct": 1.8
    },
    "detected_at": "2026-03-17T10:30:45Z",
    "latency_ms": 42
  }
}

Error

ERROR

{
  "type": "ERROR",
  "payload": {
    "code": "AUTH_FAILED",
    "message": "Invalid or expired API key"
  }
}

Latency Budget

Phase	Duration	Notes
TCP handshake	~15ms	Hetzner Frankfurt datacenter
TLS negotiation	~30ms	TLS 1.3 with ALPN
First message after connect	<50ms	HANDSHAKE message
P0 event propagation	<100ms	Engine detection to WS delivery
P1 event propagation	<500ms	Includes validation window
P2 event propagation	<2s	Aggregated context events

Code Examples

import asyncio, json, websockets

API_KEY = "YOUR_API_KEY"
URL = f"wss://nexusglass.live/ws/fastfeed?token={API_KEY}"

async def listen():
    async with websockets.connect(URL) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] == "HANDSHAKE":
                print(f"Connected: tier={msg['payload']['tier']}")
            elif msg["type"] == "EVENT":
                ev = msg["payload"]
                print(f"[{ev['priority']}] {ev['type']} "
                      f"{ev['symbol']} conf={ev['confidence']}")
            elif msg["type"] == "ERROR":
                print(f"Error: {msg['payload']['message']}")
                break

asyncio.run(listen())

Reconnection Best Practices

Exponential backoff

1s, 2s, 4s, 8s, 16s, 30s (cap). Add +-500ms random jitter to prevent thundering herd on server restart.

Gap recovery

Store the last received event_id. On reconnect, call GET /api/v1/fastfeed/events?after=LAST_ID to fill the gap.

Heartbeat

Server sends PING every 30 seconds. Client must respond with PONG within 10 seconds. 3 consecutive missed PONGs will close the connection.

Connection lifecycle

connect -> TLS -> auth (token) -> HANDSHAKE -> SNAPSHOT -> EVENT stream -> PING/PONG -> disconnect -> backoff -> reconnect

Rate Limits

Connection limits and quotas

Data Model

Event types and tiers

Error Codes

WebSocket error handling

WebSocket

WebSocket Protocol

3 WebSocket endpoints for real-time data. P0 events delivered in under 100ms end-to-end.

WebSocket Endpoints

Endpoint	Tier	Data	Avg Size
`wss://nexusglass.live/ws`	STREAM	Market data snapshots, tickers, OI deltas	2-8 KB
`wss://nexusglass.live/ws/nexus-bridge`	STREAM	Bridge analytics delta updates, cross-metric correlations	1-4 KB
`wss://nexusglass.live/ws/fastfeed`	PULSE	P0/P1/P2 intelligence events with sub-100ms SLA	0.5-2 KB

Authentication

All WebSocket connections authenticate via the token query parameter.

Connection URL

wss://nexusglass.live/ws/fastfeed?token=YOUR_API_KEY&symbols=BTCUSDT,ETHUSDT

Query Parameters

Param	Required	Description
`token`	required	API key for authentication
`symbols`	optional	Comma-separated symbols to filter. Default: all 10 symbols.
`events`	optional	Comma-separated event types to subscribe to. Default: all.

FastFeed Event Types (14)

Events are classified into 3 priority levels with different SLA guarantees.

Event Type	Priority	SLA	Size	Description
`LIQUIDATION_CLUSTER_ARMED`	P0	<100ms	~800 B	Liquidation cluster detected near current price
`LEVERAGE_SPIKE_DETECTED`	P0	<100ms	~600 B	Extreme OI change detected across exchanges
`PENDING_EXCHANGE_INFLOW`	P0	<100ms	~700 B	Large exchange deposit pending in mempool
`WHALE_POSITION_SHIFT`	P1	<500ms	~1.2 KB	Significant whale position change detected
`SYNDICATE_DETECTED`	P1	<500ms	~1.5 KB	Coordinated whale activity (3+ whales)
`MM_HUNTING_GROUND_ARMED`	P1	<500ms	~900 B	Market maker trap zone activated
`DANGER_ZONE_APPROACH`	P1	<500ms	~600 B	Price entering high-risk liquidation zone
`CVD_DIVERGENCE_EXTREME`	P1	<500ms	~700 B	Price-CVD divergence beyond 2 sigma
`REGIME_SHIFT`	P2	<2s	~400 B	Market regime transition detected
`CORRELATION_BREAK`	P2	<2s	~500 B	Cross-asset correlation breakdown
`LARGE_LIQUIDATION`	P2	<2s	~700 B	Single liquidation exceeding $500K
`FUNDING_EXTREME`	P2	<2s	~500 B	Funding rate at extreme percentile levels
`MAGNETISM_HIGH`	P2	<2s	~600 B	Strong liquidation magnet pulling price
`DOMINANCE_FLIP`	P2	<2s	~500 B	Derivatives/on-chain dominance flip

P0 - Critical

Requires immediate action. Delivered in under 100ms.

P1 - Important

Significant market signal. Delivered in under 500ms.

P2 - Informational

Market context update. Delivered in under 2 seconds.

Message Types

Type	Direction	Description
`HANDSHAKE`	Server -> Client	Sent on successful connection. Contains tier info and allowed priorities.
`SNAPSHOT`	Server -> Client	Initial state snapshot of recent events. Sent after handshake.
`EVENT`	Server -> Client	Real-time event notification. Contains full event payload.
`ERROR`	Server -> Client	Error notification (auth failure, rate limit, etc.).
`PING`	Server -> Client	Keepalive ping sent every 30 seconds. Client must respond with PONG.
`PONG`	Client -> Server	Response to server PING. Must be sent within 10 seconds.

Message Examples

Handshake (on connect)

HANDSHAKE

{
  "type": "HANDSHAKE",
  "payload": {
    "tier": "PULSE",
    "priorities": ["P0", "P1", "P2"],
    "delay_ms": 0,
    "server_time": "2026-03-17T10:30:00Z"
  }
}

Event (P0 signal)

EVENT

{
  "type": "EVENT",
  "payload": {
    "id": 12346,
    "type": "LIQUIDATION_CLUSTER_ARMED",
    "priority": "P0",
    "symbol": "BTCUSDT",
    "confidence": 0.92,
    "data": {
      "cluster_price": 98500,
      "cluster_side": "LONG_LIQ",
      "intensity_usd": 5200000,
      "distance_pct": 1.8
    },
    "detected_at": "2026-03-17T10:30:45Z",
    "latency_ms": 42
  }
}

Error

ERROR

{
  "type": "ERROR",
  "payload": {
    "code": "AUTH_FAILED",
    "message": "Invalid or expired API key"
  }
}

Latency Budget

Phase	Duration	Notes
TCP handshake	~15ms	Hetzner Frankfurt datacenter
TLS negotiation	~30ms	TLS 1.3 with ALPN
First message after connect	<50ms	HANDSHAKE message
P0 event propagation	<100ms	Engine detection to WS delivery
P1 event propagation	<500ms	Includes validation window
P2 event propagation	<2s	Aggregated context events

Code Examples

import asyncio, json, websockets

API_KEY = "YOUR_API_KEY"
URL = f"wss://nexusglass.live/ws/fastfeed?token={API_KEY}"

async def listen():
    async with websockets.connect(URL) as ws:
        async for raw in ws:
            msg = json.loads(raw)
            if msg["type"] == "HANDSHAKE":
                print(f"Connected: tier={msg['payload']['tier']}")
            elif msg["type"] == "EVENT":
                ev = msg["payload"]
                print(f"[{ev['priority']}] {ev['type']} "
                      f"{ev['symbol']} conf={ev['confidence']}")
            elif msg["type"] == "ERROR":
                print(f"Error: {msg['payload']['message']}")
                break

asyncio.run(listen())

Reconnection Best Practices

Exponential backoff

1s, 2s, 4s, 8s, 16s, 30s (cap). Add +-500ms random jitter to prevent thundering herd on server restart.

Gap recovery

Store the last received event_id. On reconnect, call GET /api/v1/fastfeed/events?after=LAST_ID to fill the gap.

Heartbeat

Server sends PING every 30 seconds. Client must respond with PONG within 10 seconds. 3 consecutive missed PONGs will close the connection.

Connection lifecycle

connect -> TLS -> auth (token) -> HANDSHAKE -> SNAPSHOT -> EVENT stream -> PING/PONG -> disconnect -> backoff -> reconnect

Rate Limits

Connection limits and quotas

Data Model

Event types and tiers

Error Codes

WebSocket error handling

WebSocket Protocol

WebSocket Endpoints

Authentication

Query Parameters

FastFeed Event Types (14)

Message Types

Message Examples

Handshake (on connect)

Event (P0 signal)

Error

Latency Budget

Code Examples

Reconnection Best Practices

Related

NEXUS GLASS

WebSocket Protocol

WebSocket Endpoints

Authentication

Query Parameters

FastFeed Event Types (14)

Message Types

Message Examples

Handshake (on connect)

Event (P0 signal)

Error

Latency Budget

Code Examples

Reconnection Best Practices

Related