Welcome to the complete guide for integrating and using BoltOdds. This documentation will help you get up and running quickly so you can access real-time sports betting odds.
Quick Start
Get connected in just a few steps:
Step 1: Obtain Your API Key
First, sign up for an account and retrieve your API key. This should be sent to the email you signed up with. You'll need this for authentication.
Step 2: Establish Connection
async def run_client():
uri = "wss://spro.agency/api?key=YOUR_TOKEN"
while True:
try:
async with websockets.connect(uri) as websocket:
ack_message = await websocket.recv()
print(ack_message)
Step 3: Send Subscription Data
To see all the sports and sportsbooks you could subscribe to, see the GET request below. NOTE: sports and sportsbooks MUST be subscribed to in the exact format seen in the response from the GET request below. Any deviation will be ignored.
GET https://spro.agency/api/get_info?key=YOUR_TOKEN
subscribe_message = {
"action": "subscribe",
"filters": {
"sports": ["NBA", "MLB", "Wimbledon (M)"],
"sportsbooks": ["draftkings", "betmgm"]
}
}
await websocket.send(json.dumps(subscribe_message))
# You are now connected and subscribed to your specified stream of data
while True:
message = await websocket.recv()
Authentication
All WebSocket connections must be authenticated using your API key.
Authentication Flow
- Establish WebSocket connection using a valid API key.
- Once ack_message is received, you have been validated
Connection Management
Automatic Reconnection
async def run_client():
uri = "wss://spro.agency/api?key=YOUR_TOKEN"
while True:
try:
async with websockets.connect(uri) as websocket:
ack_message = await websocket.recv()
print(ack_message)
subscribe_message = {
"action": "subscribe",
"filters": {
"sports": ["NBA", "MLB", "Wimbledon (M)"],
"sportsbooks": ["draftkings", "betmgm"]
}
}
await websocket.send(json.dumps(subscribe_message))
# You are now connected and subscribed to your specified stream of data
while True:
message = await websocket.recv()
except websockets.ConnectionClosed as e:
print("Connection closed — reason:", e)
print('Reconnecting...')
await asyncio.sleep(5)
continue
#can add other exception handling as needed
Message Format
All messages sent through the WebSocket are JSON formatted and follow a consistent structure.
Standard Message Structure
# Note: message format is very likely to change or be modified in the future.
{
'action': 'line_update',
'data': {'sport': 'MLB',
'sportsbook': 'draftkings',
'game': 'Arizona Diamondbacks vs San Francisco Giants, 2025-07-01, 09',
'info': # Game-specific data
'outcomes': # Outcome-specific data
}
}
Message Types
The foundation of all messages is an action, which will tell you what the message entails. These are the actions BoltOdds sends.
- socket_connected - Initial authentication successfull
- initial_state - After subscribing, you will be sent the state of all odds at that very moment
- game_update - All odds for a specific game have been updated
- game_removed - Entire game removed (finished, suspended, etc)
- game_added - New game added to sportsbook
- line_update - A line update. If odds provided are None or '', it means there are no odds available for this line i.e its currently suspended, deleted etc
- book_clear - All games for specified book have been cleared. This may happen in the case of connection drops on our backend
- ping - Keep-alive message
Basic Example
Here's a complete basic example of connecting to and using BoltOdds:
import asyncio
import websockets
import json
async def run_client():
uri = "wss://spro.agency/api?key=YOUR_TOKEN"
while True:
try:
async with websockets.connect(uri) as websocket:
ack_message = await websocket.recv()
print(ack_message)
# Send the subscription message
subscribe_message = {
"action": "subscribe",
"filters": {
"sports": ["NBA", "MLB", "Wimbledon (M)"],
"sportsbooks": ["draftkings", "betmgm"]
}
}
await websocket.send(json.dumps(subscribe_message))
# Listen for incoming messages
while True:
message = await websocket.recv()
data = json.loads(message)
if data['action'] == 'ping':
continue
#sent upon connection, initial state of odds subbed to
if data['action'] == 'initial_state':
...
#entire game odds update
elif data['action'] == 'game_update':
...
#games done
elif data['action'] == 'game_removed':
...
#game added
elif data['action'] == 'game_added':
...
#singular line odd update
#if odds r None or '', no odds available for line i.e its deleted, suspended etc
elif data['action'] == 'line_update':
...
#all games for this book have been cleared
elif data['action'] == 'book_clear':
...
except websockets.ConnectionClosed as e:
print("Connection closed — reason:", e)
print('Reconnecting...')
await asyncio.sleep(5)
continue
if __name__ == "__main__":
asyncio.run(run_client())
Troubleshooting
Common issues and their solutions:
Connection Fails
- Verify your API key is correct
- Check that you're using the correct WebSocket URL
- Ensure your firewall allows WebSocket connections
Authentication Errors
- Double-check your API key format
Support
Need help? We're here for you:
- Email: support@boltodds.com
- Documentation: Available 24/7 online