Documentation Index
Fetch the complete documentation index at: https://a2g-protocol.org/llms.txt
Use this file to discover all available pages before exploring further.
Protocol messages handle connection lifecycle, identity verification, session management, and balance queries. They do not carry gameType or tableId.
Message Reference
| Type | Direction | Description |
|---|
hello | S → C | Server capabilities and supported games |
authenticate | C → S | Client presents auth token |
authenticated | S → C | Auth confirmed, session established |
session_extend | C → S | Request session extension |
session_extended | S → C | Session extended confirmation |
session_expiring | S → C | Warning: session expires soon |
heartbeat | Both | Keep-alive (direction: “ping” or “pong”) |
reconnect | C → S | Resume disconnected session |
reconnect_state | S → C | State replay for reconnected client |
balance_query | C → S | Request current balance |
balance_response | S → C | Current balance |
ack | S → C | Message acknowledgment (optional) |
error | S → C | Protocol-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
}
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
}
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
}
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
}
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
}
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
}
