Commands

Client Commands

This document describes the commands that clients can send to the WebSocket server.

Command Format

All commands are JSON objects with an action field:

{
  "action": "command_name",
  ...additional fields
}

Available Commands

Command	Description
subscribe	Subscribe to a channel
unsubscribe	Unsubscribe from a channel
ping	Keep connection alive

---

Subscribe

Subscribe to a channel to start receiving events.

Request

{
  "action": "subscribe",
  "channel": "MAIN",
  "scope": "all"
}

Parameters

Field	Type	Required	Description
action	string	Yes	Must be "subscribe"
channel	string	Yes	Channel name (MAIN, STATS, ODDS, STATS_REALTIME, ODDS_REALTIME)
scope	string	Yes	Subscription scope

Scope Options

Scope	Format	Example	Description
All	all	"all"	All events on the channel
Match	match:{id}	"match:12345"	Events for a specific match
League	league:{id}	"league:67890"	Events for all matches in a league

Success Response

{
  "type": "subscribed",
  "channel": "MAIN",
  "scope": "all",
  "message": "Successfully subscribed"
}

Error Response

{
  "type": "error",
  "code": "CHANNEL_NOT_ALLOWED",
  "message": "Channel STATS_REALTIME is not available for your plan"
}

Error Codes

Code	Description
CHANNEL_NOT_ALLOWED	Your plan doesn't include this channel
SUBSCRIPTION_LIMIT	Maximum subscriptions reached
INVALID_CHANNEL	Channel name is not valid
INVALID_SCOPE	Scope format is not valid

Examples

// Subscribe to all main events
{"action": "subscribe", "channel": "MAIN", "scope": "all"}

// Subscribe to stats for a specific match
{"action": "subscribe", "channel": "STATS", "scope": "match:12345"}

// Subscribe to odds for an entire league
{"action": "subscribe", "channel": "ODDS", "scope": "league:67890"}

// Subscribe to real-time stats updates (MEGA plan only)
{"action": "subscribe", "channel": "STATS_REALTIME", "scope": "match:12345"}

---

Unsubscribe

Unsubscribe from a channel to stop receiving events.

Request

{
  "action": "unsubscribe",
  "channel": "MAIN",
  "scope": "all"
}

Parameters

Field	Type	Required	Description
action	string	Yes	Must be "unsubscribe"
channel	string	Yes	Channel name to unsubscribe from
scope	string	Yes	Scope to unsubscribe from

Success Response

{
  "type": "unsubscribed",
  "channel": "MAIN",
  "scope": "all",
  "message": "Successfully unsubscribed"
}

Error Response

{
  "type": "error",
  "code": "NOT_SUBSCRIBED",
  "message": "Not subscribed to this channel/scope"
}

Notes

• Unsubscribing frees up a subscription slot

• You must specify the exact channel and scope used when subscribing

• Unsubscribing from a non-existent subscription returns an error but doesn't affect other subscriptions

---

Ping

Send a ping to keep the connection alive and verify connectivity.

Request

{
  "action": "ping"
}

Response

{
  "type": "pong",
  "ts": 1705312800000
}

Response Fields

Field	Type	Description
type	string	Always "pong"
ts	integer	Server timestamp in milliseconds

Best Practices

• Send a ping every 30 seconds to maintain the connection

• Use the response timestamp to measure latency

• If no pong is received within 10 seconds, consider the connection dead and reconnect

Example Implementation

// JavaScript ping implementation
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ action: 'ping' }));
  }
}, 30000);

# Python ping implementation
async def keep_alive(ws):
    while True:
        await asyncio.sleep(30)
        await ws.send(json.dumps({"action": "ping"}))

---

Invalid Command Handling

If you send an unrecognized command, the server responds with:

{
  "type": "error",
  "code": "INVALID_ACTION",
  "message": "Unknown action: foobar"
}

Rate Limiting

• Commands are rate-limited to prevent abuse

• Maximum 10 commands per second per connection

• Exceeding the limit results in temporary throttling