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, MAIN_REALTIME, STATS, ODDS, STATS_REALTIME, ODDS_REALTIME)
scope	string	Yes	Subscription scope: "all", "match", or "league"
id	string	Conditional	Required when scope is "match" or "league"

Success Response

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

When subscribing with a specific scope:

{
  "type": "subscribed",
  "channel": "STATS",
  "scope": "match",
  "id": "12345",
  "topicKey": "STATS:match:12345",
  "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", "id": "12345"}

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

// Subscribe to real-time stats updates (MEGA plan only)
{"action": "subscribe", "channel": "STATS_REALTIME", "scope": "match", "id": "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: "all", "match", or "league"
id	string	Conditional	Required when scope is "match" or "league"

Success Response

{
  "type": "unsubscribed",
  "channel": "MAIN",
  "scope": "all",
  "id": null,
  "topicKey": "MAIN: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