WebSocket authentication

Use the same API key as REST. Authenticate during connect via query string, or send an auth message as the first frame.

Query parameter (recommended)

Pass the key in the WebSocket URL. The server validates before your client sends subscription messages.

connection url

text

wss://ws.predictionhunt.com?api_key=pmx_your_api_key_here

Python

python

import websockets

async with websockets.connect(
    "wss://ws.predictionhunt.com?api_key=" + api_key
) as ws:
    # authenticated — send subscribe messages
    ...

Post-connect auth message

Open the socket without a key, then send exactly one auth frame as the first message. If the first message is not auth, the server responds with an error and closes the connection.

auth message

json

{
  "action": "auth",
  "api_key": "pmx_your_api_key_here"
}

Warning

Authenticate within 5 seconds of connecting. Otherwise the connection closes with WebSocket code 1008.

Authentication flow

Connect to wss://ws.predictionhunt.com with ?api_key=... or plain URL for post-connect auth.
Server validates the key against the database (same as REST).
On failure: JSON error then close. On success: send subscribe / unsubscribe / heartbeat.

Tip

WebSocket access requires a paid API key (Dev tier and above for prices, smart_money, and fade_finder; Pro for all channels). View plans.

Typical error codes

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.

Overview

WebSocket API

Quick start, channels, and limits.

Access

Get an API Key

Free tier starts at 1,000 req/month. Paid plans unlock WebSocket streaming.