Skip to main content

​
Login (minimum)

To authenticate with the WebSocket gateway, send a login message including your apiKey. 
{
  "type": "login",
  "apiKey": "YOUR_API_KEY"
}

​
Login with Subscriptions and Filters

In addition to authenticating, you can define what data you want to receive by specifying channels and filters. The server will subscribe you to the intersection of:
  • The channels you request
  • The channels your apiKey is allowed to access
If you omit channels, you are automatically subscribed to all channels permitted for your apiKey. 
{
  "type": "login",
  "apiKey": "YOUR_API_KEY",
  "lang": "es",
  "receiveType": "json",
  "channels": ["fixtures","futures","bookmakers","bookmakersFutures","odds","oddsFutures","scores","currencies","stats","events","injuries","lineups"],
  "pregame": true,
  "live": true,
  "sportIds": [10, 11, 12, 13, , , , 68],
  "tournamentIds": [7, 8, 17, 31, , , 132],
  "fixtureIds": ["id1100013266225800", "id1100013266618048", , , "id1400003160574737"],
  "futureIds": ["id10000007131129", "id11000132131631", , , "id14000031127985"],
  "bookmakers": ["stake", "pinnacle", "bet365", , , "polymarket"],
}

​
Subscribing to Channels

You can control which data channels you’re subscribed to using the channels field. If excluded, the server will subscribe you to all available channels for your apiKey.

​
Available Channels

  • fixtures
  • futures
  • bookmakers
  • bookmakersFutures
  • odds
  • oddsFutures
  • scores
  • currencies (global)
  • stats
  • events
  • injuries
  • lineups
Note: Global channels such as currencies ignore filters like sportIds or tournamentIds.

​
Filters

You can further refine your subscription using filters:
FieldDescription
sportIdsFilter by sport ID
tournamentIdsFilter by tournament ID
fixtureIdsFilter by specific fixtures (per-channel)
futureIdsFilter by specific futures (per-channel)
bookmakersRequired for bookmaker-gated channels (odds, oddsFutures, bookmakers, bookmakersFutures)
langLanguage for translated fields (en, de, es, fr, pt, it, ru, zh)
receiveTypeFormat of incoming messages: json or binary
pregameIf false, excludes pregame data
liveIf false, excludes live data

​
Example: Bookmaker-Gated Channels

Bookmaker-gated channels require specifying which bookmakers you want access to. 
{
  "type": "login",
  "apiKey": "YOUR_API_KEY",
  "channels": ["odds", "bookmakers"],
  "bookmakers": ["stake", "pinnacle"]
}

​
🐍 Python Example: Basic Auth & Subscription

This minimal Python example connects, authenticates, and subscribes with filters. 
import asyncio
import json
import websockets

# --- Configuration ---
WS_URL = "wss://v5-test.oddspapi.io"
API_KEY = "your-api-key"

LANG = "en"
CHANNELS = ["fixtures", "scores", "bookmakers", "odds"]
SPORT_IDS = [10, 11, 12, 13]
BOOKMAKERS = ["stake"]

# --- WebSocket Client ---
async def main():
    async with websockets.connect(WS_URL) as ws:
        login_msg = {
            "type": "login",
            "apiKey": API_KEY,
            "lang": LANG,
            "channels": CHANNELS,
            "sportIds": SPORT_IDS,
            "bookmakers": BOOKMAKERS
        }

        await ws.send(json.dumps(login_msg))

        while True:
            raw = await ws.recv()
            if isinstance(raw, (bytes, bytearray)):
                raw = raw.decode("utf-8", "replace")
            print(json.loads(raw))

asyncio.run(main())
This script connects to the test gateway, logs in using your config, subscribes to selected channels, and prints real-time updates.

​
💬 Ask an AI Assistant

Want to explore or ask questions about this page using your favorite AI? Click one of the links below — each one opens this page in the selected tool with a pre-filled prompt: