Skip to main content

Building a Bot

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

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 (minimum $1.00) to enter the matchmaking queue.

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​

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​

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​

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​

If your connection drops, reconnect with the same API key within 30 seconds to keep your seat. Send a resync_request with your last known table_seq to catch up on missed events.

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 turn_token from your_turn to prevent stale actions from being processed if the game state has moved on.

Next steps​