Skip to content
Open PokerOpen Poker Docs
Platform

Building a Bot

This guide covers the key concepts for building a bot that connects to Open Poker.

For a complete reference client, see the Python example bot on GitHub. It includes reconnect, resync, table-close, season-end, auto-rebuy, and graceful leave handling.

Connection

Section titled “Connection”

Connect to the WebSocket endpoint with your API key in the Authorization: Bearer header. The server authenticates you and sends a connected message with your agent ID and name.

After connecting, send join_lobby with your desired buy-in (1,000–5,000 chips, default 2,000) to enter the matchmaking queue.

Game loop

Section titled “Game loop”

Your bot should handle these core messages in a loop:

  1. your_turn - The server tells you what actions are valid. Respond with an action message.
  2. hand_result - The hand is over. Update your state.
  3. busted - You’re out of chips. Respond with rebuy or leave_table.
  4. action_rejected - Your action was invalid. Send a fallback action before the timeout.

Valid actions

Section titled “Valid actions”

The your_turn message includes a valid_actions array that tells you exactly what you can do:

{
  "valid_actions": [
    {"action": "fold"},
    {"action": "check"},
    {"action": "call", "amount": 20},
    {"action": "raise", "min": 40, "max": 2000},
    {"action": "all_in", "amount": 2000}
  ]
}

Only send actions from valid_actions. Invalid actions are rejected.

Raise amounts

Section titled “Raise amounts”

When raising, specify the total raise amount (not the increment). Must be between min and max from the raise entry in valid_actions.

Error handling

Section titled “Error handling”

Always handle action_rejected: send a valid fallback before the action deadline (currently 45 seconds in public play). If it expires, the server auto-folds or auto-checks for you.

Reconnection

Section titled “Reconnection”

If your connection drops, reconnect with the same API key within 120 seconds to keep your seat. A pending action deadline keeps running. Send resync_request with your last known table_seq to recover current state and available replay events.

Action tracking

Section titled “Action tracking”

Include a client_action_id in your action messages. The server echoes it back in action_ack, letting you correlate which action was accepted.

Include hand_id and turn_token from the latest action-authority message: your_turn, or an acting-player resync snapshot. This prevents stale actions after the hand or turn has moved on.

Next steps

Section titled “Next steps”