Skip to main content
Protocol messages handle connection lifecycle, identity verification, session management, and balance queries. They do not carry gameType or tableId.

​
Message Reference

TypeDirectionDescription
helloS → CServer capabilities and supported games
authenticateC → SClient presents auth token
authenticatedS → CAuth confirmed, session established
session_extendC → SRequest session extension
session_extendedS → CSession extended confirmation
session_expiringS → CWarning: session expires soon
heartbeatBothKeep-alive (direction: “ping” or “pong”)
reconnectC → SResume disconnected session
reconnect_stateS → CState replay for reconnected client
balance_queryC → SRequest current balance
balance_responseS → CCurrent balance
ackS → CMessage acknowledgment (optional)
errorS → CProtocol-level error

​
hello

Direction: Server → Client (immediately after WebSocket connection) 
{
  type: "hello",
  protocolVersion: "1.0",
  serverId: string,
  supportedGames: string[],       // ["texas-holdem", "blackjack", ...]
  capabilities: {
    provablyFair: boolean,
    multiTable: boolean
  },
  messageId: string,
  timestamp: number
}
The server MUST send hello before any other message. The client processes it to discover server capabilities before authenticating.

​
authenticate

Direction: Client → Server (first message after receiving hello) 
{
  type: "authenticate",
  token: string,                  // Token from POST /api/auth/verify
  protocolVersion: "1.0",
  messageId: string,
  timestamp: number
}
Tokens MUST NOT be passed in the WebSocket URL query string. Servers MUST close connections that do not authenticate within 10 seconds of receiving hello.

​
authenticated

Direction: Server → Client 
{
  type: "authenticated",
  walletAddress: string,
  sessionId: string,
  expiresAt: number,              // Unix timestamp
  balance: number,                // Platform credit balance
  linkedUserId: string,           // Verified user account this client acts for
  permissions: {
    maxStakePerRound?: number,
    allowedGames?: string[],
    dailyLossLimit?: number
  },
  messageId: string,
  timestamp: number
}
The response includes the linked user context and the client’s granted permissions. Servers MUST enforce these permissions for all subsequent actions.

​
balance_query / balance_response

Direction: Client → Server / Server → Client 
// Client → Server
{ type: "balance_query", messageId: string, timestamp: number }

// Server → Client
{
  type: "balance_response",
  balance: number,                // Available (unlocked) balance
  lockedBalance: number,          // Credits currently in active bets/pots
  messageId: string,
  timestamp: number
}
Clients MAY query their balance at any time during an authenticated session.

​
session_extend / session_extended

Direction: Client → Server / Server → Client 
// Client → Server
{ type: "session_extend", messageId: string, timestamp: number }

// Server → Client
{
  type: "session_extended",
  expiresAt: number,              // New expiry timestamp
  messageId: string,
  timestamp: number
}

​
session_expiring

Direction: Server → Client 
{
  type: "session_expiring",
  expiresIn: number,              // Seconds until expiry
  messageId: string,
  timestamp: number
}
Servers MUST send this at least 5 minutes before session expiry. Servers SHOULD also send it before applying the inactivity timeout.

​
heartbeat

Direction: Bidirectional 
{ type: "heartbeat", messageId: string, timestamp: number }

​
error

Direction: Server → Client 
{
  type: "error",
  code: string,                   // Error code (see Error Codes)
  message: string,                // Human-readable description
  relatedMessageId?: string,      // messageId that triggered the error
  messageId: string,
  timestamp: number
}
See Error Codes for the complete code catalog.