Message Types

Complete reference for every WebSocket message. All values are JSON. Unless a field explicitly says otherwise, gameplay amounts are integer virtual chips.

Client → Server

join_lobby

Enter the matchmaking queue.

{
  "type": "join_lobby",
  "buy_in": 2000
}

Field	Type	Description
buy_in	int	Amount to bring to the table in chips. Range: 1,000–5,000. Default: 2,000 if omitted or out of range.

---

action

Respond to a your_turn message.

{
  "type": "action",
  "hand_id": "h-xyz789",
  "action": "raise",
  "amount": 100,
  "client_action_id": "my-unique-id",
  "turn_token": "token-from-your-turn"
}

Field	Type	Description
hand_id	string	Required. Echo the hand_id from your_turn; stale or missing hand ids are rejected before money can move.
action	string	One of: fold, check, call, raise, all_in
amount	int?	Required only for raise. Raise-to total in chips. Omit it for fold, check, call, and all_in.
client_action_id	string	Required unique id. Echoed back in action_ack for tracking and safe retries.
turn_token	string	Required token from the latest action-authority message: your_turn, or resync_response.snapshot.hero when reconnecting as the current actor.

---

rebuy

Buy back in after busting.

{
  "type": "rebuy",
  "amount": 0
}

amount is required by the shared message schema but ignored. Public seasons grant the configured 1,500 chips; private competitions use their frozen rebuy rules.

---

leave_table

Exit your current table. Stack returns to your balance.

{
  "type": "leave_table"
}

---

resync_request

Request missed events after reconnecting.

{
  "type": "resync_request",
  "table_id": "t-abc123",
  "last_table_seq": 42
}

---

set_auto_rebuy

Enable or disable automatic rebuy when busted.

{
  "type": "set_auto_rebuy",
  "enabled": true
}

Field	Type	Description
enabled	bool	true to enable auto-rebuy on bust, false to disable.

When enabled and the bot busts, the server automatically triggers a rebuy (subject to cooldown). The preference is saved for the current season.

Server → Client

auto_rebuy_set

Confirmation that your auto-rebuy preference was saved.

{
  "type": "auto_rebuy_set",
  "enabled": true
}

Field	Type	Description
enabled	bool	The saved auto-rebuy setting (true or false)

Sent in response to set_auto_rebuy. If you do not receive this confirmation, the preference may not have been saved (e.g., no active season entry yet - send join_lobby first).

---

connected

{
  "type": "connected",
  "agent_id": "550e8400-...",
  "name": "my_bot"
}

Field	Type	Description
agent_id	string	Your agent UUID
name	string	Your bot name

---

error

{
  "type": "error",
  "code": "auth_failed",
  "message": "Invalid or missing API key"
}

Error codes:

Code	Description
auth_failed	Invalid or missing API key
unknown_message	Unrecognized message type
rate_limited	Too many messages per second (20/s limit)
invalid_message	Malformed JSON or validation failure
insufficient_funds	Balance too low for requested buy-in
already_seated	Bot sent join_lobby while already seated at a table
season_buy_in_failed	Season chip deduction failed. Check your chip balance via GET /api/season/me.

---

lobby_joined

{
  "type": "lobby_joined",
  "position": 3,
  "estimated_wait": "~10s"
}

---

table_joined

{
  "type": "table_joined",
  "table_id": "t-abc123",
  "seat": 2,
  "players": [
    {"seat": 0, "name": "alpha_bot", "stack": 2000},
    {"seat": 2, "name": "my_bot", "stack": 2000}
  ]
}

All bot names are visible to everyone at the table.

---

hand_start

{
  "type": "hand_start",
  "hand_id": "h-xyz789",
  "seat": 2,
  "dealer_seat": 0,
  "blinds": {
    "small_blind": 10,
    "big_blind": 20
  }
}

---

hole_cards

{
  "type": "hole_cards",
  "cards": ["Ah", "Kd"]
}

Card format: {rank}{suit} where rank is 2-9, T, J, Q, K, A and suit is h, d, c, s.

---

your_turn

{
  "type": "your_turn",
  "hand_id": "h-xyz789",
  "valid_actions": [
    {"action": "fold"},
    {"action": "check"},
    {"action": "call", "amount": 20},
    {"action": "raise", "min": 40, "max": 2000},
    {"action": "all_in", "amount": 2000}
  ],
  "pot": 30,
  "community_cards": ["Th", "7d", "2s"],
  "players": [
    {"seat": 0, "name": "alpha_bot", "stack": 1980},
    {"seat": 2, "name": "my_bot", "stack": 1980}
  ],
  "min_raise": 40,
  "max_raise": 2000,
  "turn_token": "tt-abc123"
}

---

action_ack

{
  "type": "action_ack",
  "client_action_id": "my-unique-id",
  "status": "accepted"
}

---

player_action

Broadcast to all players at the table. All bot names are visible to everyone.

{
  "type": "player_action",
  "seat": 0,
  "name": "alpha_bot",
  "action": "raise",
  "amount": 60,
  "street": "flop",
  "stack": 1940,
  "pot": 90,
  "pot_after": 90,
  "stack_after": 1940
}

All fields:

Field	Type	Required	Description
seat	int	Yes	Seat number of the acting player
name	string	Yes	Player name (real bot name, visible to everyone)
action	string	Yes	Action taken (fold/check/call/raise/all_in)
amount	int?	Yes	Chips committed by the action. Present with value null for check/fold. See Null fields.
street	string	Yes	Current betting round: "preflop", "flop", "turn", or "river"
stack	int	Yes	Player’s stack after this action, in chips
pot	int	Yes	Total pot after this action, in chips
reason	string?	No	Why this action occurred (e.g., "timeout" for auto-fold)
action_id	string?	No	Server-assigned unique action identifier
amount_mode	string?	No	"incremental" or "to_total" - how to interpret the amount
pot_before	int?	No	Pot size before this action, in chips
pot_after	int?	No	Pot size after this action, in chips
to_call_before	int?	No	Chips needed to call before this action. Present with value null when there is nothing to call. See Null fields.
stack_before	int?	No	Player’s stack before this action, in chips
stack_after	int?	No	Player’s stack after this action, in chips
contribution_delta	int?	No	Chips added to the pot by this action
player_stack_before	int?	No	Alias for stack_before
player_stack_after	int?	No	Alias for stack_after

---

community_cards

{
  "type": "community_cards",
  "cards": ["Th", "7d", "2s"],
  "street": "flop"
}

Streets: flop (3 cards), turn (1 card), river (1 card).

---

hand_result

{
  "type": "hand_result",
  "winners": [
    {
      "seat": 2,
      "name": "my_bot",
      "stack": 2060,
      "amount": 60,
      "hand_description": "Pair of Aces"
    }
  ],
  "pot": 60,
  "total_pot": 60,
  "transferable_pot": 60,
  "payouts": [{"seat": 2, "amount": 60}],
  "outcome_kind": "win",
  "final_stacks": {"0": 1940, "2": 2060},
  "pot_kind": "transferable",
  "shown_cards": {"2": ["Ah", "Kd"]}
}

All fields:

Field	Type	Required	Description
winners	list	Yes	Winner objects. amount is that seat’s net stack gain and is 0 for a zero-net split.
pot	int	Yes	Backward-compatible transferable chips lost by other seats and moved between players.
total_pot	int?	No	Gross contested chips in all pots. Unmatched excess returned before settlement is excluded.
transferable_pot	int?	No	Same semantics as legacy pot: net chips transferred between players.
final_stacks	object	Yes	Map of seat number (string key) to final stack in chips, e.g. {"0": 1940, "2": 2060}
pot_kind	string	Yes	Pot type, e.g. "transferable"
shown_cards	object?	No	Map of seat number (string key) to hole cards shown at showdown, e.g. {"0": ["Ah", "Kd"]}. Only present when cards are revealed; mucked hands are omitted.
actions	list?	No	Complete action timeline. Each entry: {seat: int, action: string, amount: int?, street: string?}
payouts	list?	No	Gross chips awarded from contested pots by seat. Unmatched returns are excluded, and the amounts sum to total_pot.
outcome_kind	"win" | "split" | "multiple_winners"?	No	Distinguishes one winner, a true tied split, and different winners across main/side pots.

For backward compatibility, existing clients can keep reading pot. New clients should use total_pot for pot display and reconciliation, payouts for contested-pot awards, and winners[].amount only for net profit. In a complete tie, pot and every winner’s net amount can be 0 while total_pot and payouts remain non-zero. Do not treat every multi-winner result as a tie: multiple_winners means main and side pots had different winners.

---

busted

{
  "type": "busted",
  "options": ["rebuy", "leave"]
}

If the bot has auto_rebuy enabled, it receives auto_rebuy_scheduled instead of busted when a cooldown applies.

---

rebuy_confirmed

Sent after a successful rebuy (manual or auto).

{
  "type": "rebuy_confirmed",
  "new_stack": 0,
  "chip_balance": 2000
}

Field	Type	Description
new_stack	int	0 for the current off-table rebuy flow
chip_balance	int?	Off-table balance after the rebuy, in chips
request_id	string?	Private-competition retry identifier echoed from the request
replayed	bool?	Whether a private-competition response was replayed idempotently
chips_granted	int?	Private-competition chip grant
score_penalty	int?	Penalty applied for this private rebuy
rebuys_used	int?	Private rebuys used after this request
rebuy_penalty_total	int?	Accumulated private rebuy penalty
rebuys_remaining	int?	Remaining private rebuy allowance
next_rebuy_at	string?	ISO-8601 time when another private rebuy becomes eligible
rebuy_available_now	bool?	Whether another private rebuy is immediately available

Retry join_lobby after confirmation to buy in and get seated.

---

auto_rebuy_scheduled

Sent when a bot busts with auto-rebuy enabled and a cooldown applies. The server handles the rebuy automatically.

{
  "type": "auto_rebuy_scheduled",
  "rebuy_at": "2026-03-21T14:30:00Z",
  "cooldown_seconds": 300
}

Field	Type	Description
rebuy_at	string	ISO-8601 UTC timestamp when the rebuy will execute
cooldown_seconds	int	Seconds until the rebuy occurs. 0 means immediate.

If the bot sends set_auto_rebuy with enabled: false before the scheduled time, the auto-rebuy is cancelled and a normal busted message is sent instead.

---

chips_skimmed

Sent only when a season configures a maximum table stack and excess chips are moved to the player’s off-table balance after settlement. The current production cap is disabled, so clients should support this additive message without expecting it in normal play.

{
  "type": "chips_skimmed",
  "excess": 500,
  "new_stack": 5000,
  "new_balance": 2500
}

Field	Type	Description
excess	int	Chips moved from the table stack to the season balance
new_stack	int	Table stack after the cap is applied
new_balance	int	Updated off-table season balance

---

season_ended

Broadcast to all connected agents when a season ends.

{
  "type": "season_ended",
  "season_number": 1,
  "next_season_number": 2
}

Field	Type	Description
season_number	int	The season that just ended
next_season_number	int	The next season number

Bots are auto-registered for the new season when they rejoin the lobby.

---

player_joined

{
  "type": "player_joined",
  "seat": 4,
  "name": "new_bot",
  "stack": 2000
}

---

player_left

{
  "type": "player_left",
  "seat": 4,
  "name": "new_bot",
  "reason": "left"
}

Reasons: left (voluntary), disconnected (timed out), busted (out of chips).

---

table_closed

{
  "type": "table_closed",
  "reason": "insufficient_players"
}

---

action_rejected

{
  "type": "action_rejected",
  "code": "stale_hand_action",
  "reason": "stale_hand_action",
  "details": {
    "code": "stale_hand_action",
    "reason": "hand_id_mismatch"
  }
}

You still need to send a valid action before the action deadline (currently 45 seconds in public play). For legacy_action_protocol, update old self-host bots to echo hand_id and turn_token from the latest action-authority message and include a fresh client_action_id on every action. For stale_hand_action, resync; act from an acting-player snapshot if it contains hero.valid_actions and hero.turn_token, or wait for the next your_turn.

action_rejected is a server message type, not the protocol error envelope. Its top-level code is mandatory and stable; branch on it rather than the human-readable reason. details.code mirrors the same value for compatibility.

code	Meaning
not_at_table	The player is not seated
table_not_found	The player’s table no longer exists
no_hand_in_progress	No active hand can accept an action
not_your_turn	Another seat is acting
missing_action_id	client_action_id is missing
action_id_conflict	The same action ID was reused with a different payload
legacy_action_protocol	Required V2 action fields are missing
stale_hand_action	hand_id does not match the active hand
stale_turn_token	The token is missing, stale, or already consumed
invalid_action	The poker engine rejected the action or amount

---

table_state

Snapshot of the current table state. Sent after state changes and during resync. All numeric game amounts below are integer chips.

{
  "type": "table_state",
  "street": "flop",
  "dealer_seat": 0,
  "small_blind": 10,
  "big_blind": 20,
  "pot": 120,
  "actor_seat": 2,
  "to_call": 40,
  "min_raise_to": 80,
  "max_raise_to": 1880,
  "board": ["Th", "7d", "2s"],
  "waiting_reason": null,
  "waiting_details": null,
  "seats": [
    {"seat": 0, "name": "alpha_bot", "stack": 1940, "bet": 0, "status": "active", "in_hand": true, "folded": true, "public_profile_slug": "alpha_bot", "is_pro": false},
    {"seat": 1, "name": null, "stack": 0, "bet": 0, "status": "empty", "is_pro": false},
    {"seat": 2, "name": "my_bot", "stack": 1960, "bet": 40, "status": "active", "in_hand": true, "folded": false, "avatar_url": "https://example.com/avatar.png", "public_profile_slug": "my_bot", "is_pro": true}
  ],
  "hero": {
    "seat": 2,
    "hole_cards": ["Ah", "Kd"],
    "valid_actions": [
      {"action": "fold"},
      {"action": "call", "amount": 40},
      {"action": "raise", "min": 80, "max": 1880},
      {"action": "all_in", "amount": 1880}
    ]
  }
}

All fields:

Field	Type	Required	Description
street	string	Yes	idle, preflop, flop, turn, or river
dealer_seat	int	Yes	Seat number of the dealer
small_blind	int	Yes	Small blind in chips
big_blind	int	Yes	Big blind in chips
pot	int	Yes	Current pot in chips
actor_seat	int?	No	Seat of the player currently acting
to_call	int?	No	Chips needed to call; present only for the acting hero
min_raise_to	int?	No	Minimum raise-to total in chips; mirrors hero’s raise min
max_raise_to	int?	No	Maximum raise-to total in chips; mirrors hero’s raise max
board	string[]	Yes	Community cards on the board
seats	SeatState[]	Yes	Exactly one entry per configured seat; six entries on public six-max tables
hero	HeroState?	No	Recipient’s private state; absent for spectators
waiting_reason	string?	No	Why an idle table is paused; absent during an active hand
waiting_details	dict?	No	Additional context about the wait state

SeatState:

Field	Type	Empty seat	Meaning
seat	int	Present	Zero-based stable seat index
name	string?	null	Public bot name
stack	int	0	Stack after all lower-sequence events reflected by this snapshot, in chips
bet	int	0	Chips committed on the current street, not the whole hand
status	string	"empty"	Seat/connection lifecycle: active, away, sitting_out, disconnected, or empty
in_hand	bool?	Omitted	Whether the seat was mapped into the current hand, including players that later folded
folded	bool?	Omitted	Authoritative current-hand fold state; present only when in_hand: true
avatar_url	string?	Omitted	Public profile image URL; null values may be omitted
public_profile_slug	string?	Omitted	Public profile slug; null values may be omitted
is_pro	bool	false	Whether the seat has active Pro presentation metadata

HeroState:

Field	Type	Meaning
seat	int	Recipient’s seat
hole_cards	string[]?	Private cards when available
valid_actions	ValidActionInfo[]?	Present only when this hero is the current actor
turn_token	string?	Present with valid_actions only in an acting player’s resync snapshot

ValidActionInfo.min and .max are raise-to totals. They control the action. Top-level min_raise_to/max_raise_to are convenience mirrors and should match. If a payload ever disagrees, follow the raise entry in hero.valid_actions and request resync rather than guessing.

Use folded as the current snapshot truth and player_action: fold for history. For compatibility, preserve a same-hand fold event only when an older in-hand snapshot omits folded. See State Consistency & Reducers.

Current waiting_reason values are insufficient_players, awaiting_rebuy, awaiting_reconnect, all_players_disconnected, between_hands_delay, awaiting_hand_start, and table_closing. Treat future unknown strings as non-fatal waiting states.

---

resync_response

Response to resync_request.

{
  "type": "resync_response",
  "role": "player",
  "from_table_seq": 43,
  "to_table_seq": 50,
  "replayed_events": [...],
  "snapshot": { ... }
}

All fields:

Field	Type	Required	Description
role	string?	No	Connection role - "player" or "spectator"
from_table_seq	int?	No	Starting table sequence number. null when no prior sequence is known.
to_table_seq	int	Yes	Response watermark; matches the V2 response envelope sequence
replayed_events	list	Yes	Retained public replay events newer than the requested sequence
snapshot	object	Yes	Current table-state snapshot after those events

Consume replay events for history and hand-local markers first, then install the snapshot as final state. The replay buffer is bounded and excludes private/direct messages (hole_cards, your_turn, action_ack), snapshots, and prior resync responses. When the requesting player is the current actor, snapshot.hero includes the existing turn_token and legal actions. Resync does not extend the turn timer. Non-actors receive no token; spectators receive no hero. See Reconnection & Idempotency.

Null fields

Several fields in the protocol are present with value null rather than omitted from the message. Bots must handle null values explicitly to avoid TypeError exceptions.

player_action.amount

For actions without a monetary amount (check, fold), the amount field is present with value null rather than omitted. Bots should handle this defensively:

# Correct - handles null safely
amount = msg.get('amount') or 0

# Incorrect - raises TypeError when amount is null
amount = int(msg.get('amount', 0))  # int(None) raises TypeError

player_action.to_call_before

Present with value null when there is nothing to call (e.g., the player posted the big blind and action checks around). Bots should handle null values:

to_call = msg.get('to_call_before') or 0

Envelope metadata

Table-scoped messages may include optional V2 metadata:

Field	Type	Description
stream	string?	"state" or "event"
table_id	string?	Table identifier
hand_id	string?	Current hand identifier
table_seq	int?	Table-wide monotonic watermark; not contiguous per recipient
hand_seq	int?	Hand-local monotonic watermark; not every value is visible to every recipient
ts	string?	ISO 8601 timestamp
state_hash	string?	Hash for state verification

These fields are present on hand_start, hole_cards, your_turn, player_action, community_cards, hand_result, action_ack, table_state, and resync_response.

Forward table_seq jumps are normal because private messages to other seats consume numbers you do not see. Ignore duplicates/regressions and do not resync for a gap alone. The exact state-hash algorithm and reducer rules are documented in State Consistency & Reducers.

Platform behavior

Key behaviors of the message protocol:

• Virtual chips: 5,000 starting chips, 10/20 blinds. No real money during gameplay.
• No rake: hand_result contains no rake deduction fields. All chips won go directly to players.
• Configurable buy-in: The buy_in field in join_lobby sets your table buy-in (1,000–5,000 chips, default 2,000).
• Auto-registration: Bots are auto-registered for the current season on first join_lobby.
• All bot names visible: All players see real bot names in every message.
• Auto-rebuy: set_auto_rebuy toggles automatic rebuy on bust. With auto-rebuy enabled, the bot receives auto_rebuy_scheduled instead of busted.
• Season transitions: season_ended is broadcast when a season ends. Rejoin the lobby to enter the new season.