Connect & authenticate

Endpoints

Open a WebSocket to /ws on the same host as the REST API:

wss://api.drazill.com/ws        # production (live)
wss://staging.drazill.com/ws    # staging (paper) — use this with a drzl_test_ key

Authenticate

Authentication is the first message you send, not a query parameter or header. The socket accepts either a first-party JWT or an API key:

1
{ "type": "auth", "token": "<jwt-access-token>" }

1
{ "type": "auth", "api_key": "<your-api-key>" }

You have a few seconds to send the auth frame after the socket opens. An anonymous connection (no auth frame, or an auth frame with no credentials) is allowed — it can subscribe to the public market-data channels but not to your private stream.

On success the server sends a connected frame; if you authenticated, your private user:{your_id} channel is auto-subscribed:

1
{ "type": "connected", "session": "…", "authenticated": true, "channels": ["user:018f…"] }

Subscribe

Send a subscribe frame with up to 50 channels. Public channels need no auth; private channels are authorized on subscribe and rejected (never silently dropped) if you may not read them.

1
{ "type": "subscribe", "channels": ["prices:018f-outcome", "trades:018f-market"] }

The server acknowledges with the accepted channels, any rejects with a reason, and a replay summary per channel:

1
{
2
  "type": "subscribed",
3
  "channels": ["prices:018f-outcome", "trades:018f-market"],
4
  "rejected": [],
5
  "errors": {},
6
  "replayed": {}
7
}

A rejected private channel comes back in errors with a structured reason (AUTH_REQUIRED, FORBIDDEN, UNKNOWN_CHANNEL, or TIER_NOT_ENTITLED).

A minimal client (Python)

The official Python SDK ships a tested async WebSocket client that defaults to staging and handles the auth frame, ping/pong, and reconnects for you (from sdks/python/drazill/_websocket.py, exercised by sdks/python/tests/test_websocket.py):

1
import asyncio
2
from drazill import DrazillWebSocket
3
4
async def main():
5
    # Defaults to wss://staging.drazill.com/ws — pass url=... for production.
6
    ws = DrazillWebSocket(api_key="drzl_test_...")   # key must have the websocket scope
7
    await ws.subscribe("prices:018f-outcome")
8
    async for message in ws.listen():                # auto-reconnects; replies to pings
9
        print(message["type"], message.get("data"))
10
11
asyncio.run(main())