WebSocket API

Connect with your API key (query string or first-frame auth), then send subscribe messages for the channels you need. Messages arrive as JSON with a consistent envelope (see below).

import asyncio, json, websockets, os

async def main():
    uri = "wss://ws.predictionhunt.com?api_key=" + os.environ["PREDICTION_HUNT_API_KEY"]
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "action": "subscribe",
            "channel": "prices",
            "market_ids": ["12345", "67890"]
        }))
        async for message in ws:
            data = json.loads(message)
            print(data.get("channel"), data.get("type"), data)

asyncio.run(main())

Want to test messages interactively? Use the WebSocket Playground.

Production endpoint: wss://ws.predictionhunt.com. Health check (HTTP): GET /health on the same port.

1. Authenticate — Query parameter or auth message.
2. Subscribe with market_ids and/or group_ids per channel rules.
3. Receive streaming updates and optional snapshot messages after subscribe.

Unlike APIs that use subscription IDs (sid), Prediction Hunt uses a single JSON stream per connection. Client sends action messages; the server replies with type.

Client → server

• auth — api_key (first message only if not using query auth)
• subscribe — channel, optional market_ids, group_ids
• unsubscribe — same fields; omit ids to drop the entire channel subscription
• heartbeat — application-level ping

Server → client

• subscribed, unsubscribed
• error, warning (see error table)
• pong
• Data payloads: channel, type, ts, data

{
  "type": "subscribed",
  "channel": "prices",
  "market_ids": ["12345"],
  "group_ids": null
}

{
  "type": "error",
  "code": "CHANNEL_FORBIDDEN",
  "message": "Your tier does not have access to the arb channel.",
  "channel": "arb"
}

Each channel has its own subscription rules and payload types. Follow the links for requirements, subscribe examples, and field reference.

Inbound messages are rate-limited to 10 per second per connection. Pricing · api@predictionhunt.com for Enterprise.

Streaming updates use one JSON object per message. The data object repeats the payload fields from Redis (including a nested type for some channels).

{
  "channel": "prices",
  "type": "price_update",
  "ts": 1712847600.123,
  "data": { }
}

After subscribe, prices, orderbook, smart_money, and fade_finder send cached snapshots as the same message types as live updates. Unresolved market_ids or group_ids produce a warning with code UNKNOWN_ID.

1. Open WebSocket with valid API key (query or first-frame auth).
2. Send subscribe for each channel scope you need.
3. Process subscribed, then data messages and optional warning.
4. On disconnect, reconnect with exponential backoff; resubscribe after connect.

• Subscribe only to markets and groups you need — reduces load and noise.
• Handle error and warning without crashing; reconnect on auth failures.
• Keep API keys server-side; never embed them in public client apps.
• For orderbook, merge snapshot and incremental updates in order (see channel docs).