WebSocket

Real-time stream of trade updates, fills, and (optionally) order book data. Lower latency than polling REST and zero per-request rate cost beyond the 10 msg/s receive cap.

Connecting

wss://api.spreadr.xyz/api/v1/ws

Auth option 1 — Header (recommended for bots)

X-API-Key: sprdr_...

The API key must have trades:read scope. With this header set, the connection authenticates as part of the WebSocket upgrade — no first message required.

Auth option 2 — First message

If no auth header is provided, you have 5 seconds to send an auth message before the server closes the connection.

{
  "type": "auth",
  "api_key": "sprdr_..."
}

Or with a Privy JWT (used by the web terminal):

{
  "type": "auth",
  "token": "<privy_jwt>"
}

On success the server replies:

{
  "type": "authenticated",
  "timestamp": "2026-03-12T13:00:00Z"
}

Subscribing

After auth, send subscribe messages to receive events.

All your trades

{
  "type": "subscribe",
  "data": { "subscription": "trades" }
}

You'll receive updates for every trade you own — status transitions, fill events, etc.

One specific trade

{
  "type": "subscribe",
  "data": {
    "subscription": "trades",
    "params": { "trade_id": "00000000-0000-0000-0000-000000000000" }
  }
}

Order book stream

{
  "type": "subscribe",
  "data": {
    "subscription": "orderbooks",
    "params": { "exchange": "hyperliquid", "market": "HYPE" }
  }
}

Fills

{
  "type": "subscribe",
  "data": { "subscription": "fills" }
}

Message types from server

Limits

• Max 5 concurrent WebSocket connections per user. Exceeding the cap on the first-message auth path triggers close code 4008; on the header-auth path the connection is rejected before upgrade with HTTP 429.
• Message rate: 10 msg/s per connection sustained, burst of 20.
• Liveness: the server sends a protocol-level WebSocket ping every 30s; a connection that doesn't pong within 60s is closed. Standard WS client libraries answer these automatically. The JSON {"type": "ping"} / pong exchange is a separate, optional app-level heartbeat — it does not count toward liveness.

Close codes

Example (Python)

import websocket
import json
 
def on_open(ws):
    ws.send(json.dumps({"type": "auth", "api_key": "sprdr_..."}))
 
def on_message(ws, message):
    msg = json.loads(message)
    if msg["type"] == "authenticated":
        ws.send(json.dumps({
            "type": "subscribe",
            "data": {"subscription": "trades"}
        }))
    elif msg["type"] == "trade":
        print(f"Trade {msg['data']['trade_id']} -> {msg['data']['status']}")
    elif msg["type"] == "event":
        print(f"Event: {msg['data']['event_type']}")
 
ws = websocket.WebSocketApp(
    "wss://api.spreadr.xyz/api/v1/ws",
    on_open=on_open,
    on_message=on_message
)
ws.run_forever()