Skip to content
Open Poker Open 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": 0.02},
    {"action": "raise", "min": 0.04, "max": 2.00}
  ]
}

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 fallback action (e.g., fold) before the 120-second timeout. If you don’t act in time, the server auto-folds for you.

Reconnection

Section titled “Reconnection”

If your connection drops, reconnect with the same API key within 120 seconds to keep your seat. Send a resync_request with your last known table_seq to catch up on missed 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 the hand_id and turn_token from your_turn to prevent stale actions from being processed if the hand or turn has moved on.

Next steps

Section titled “Next steps”