WebSocket Authentication
Authenticate your WebSocket connection using the same API key you use for REST requests. Two methods are supported.
Query Parameter (Recommended)
Pass your API key as a query parameter when opening the connection. This is the simplest approach and authenticates immediately on connect.
connection url
textwss://www.predictionhunt.com/ws?api_key=pmx_your_api_key_here
python
pythonimport websockets
ws = await websockets.connect(
"wss://www.predictionhunt.com/ws?api_key=" + api_key
)
# Connection is authenticated — start subscribingAuth Message (Post-Connect)
Alternatively, connect without a key and send an authentication message as your first frame. This is useful when you need to establish the WebSocket connection before you have the API key available.
auth message
json{
"action": "auth",
"api_key": "pmx_your_api_key_here"
}Warning
You must authenticate within 5 seconds of connecting. Connections that don't authenticate in time are automatically closed with code
1008.Authentication Flow
1Client opens WebSocket to
wss://www.predictionhunt.com/ws2Server validates the API key (query param or auth message)
3If valid: connection is established. If invalid or timed out: server sends an error message and closes the connection.
4Client can now send
subscribe / unsubscribe / heartbeat messages.Tip
WebSocket access requires a paid API key. Free tier keys cannot connect. View plans to see which channels are included with each tier.
Error responses
AUTH_FAILEDInvalid API key.AUTH_FAILEDAPI key is inactive or revoked.AUTH_FAILEDAPI key has expired.AUTH_FAILEDAuthentication timeout.TIER_FORBIDDENYour tier does not have WebSocket access.CONNECTION_LIMITMax N concurrent connections for your tier.