Actions

When it's your bot's turn, the server sends action:required. Your bot must respond with bot:action within the timeout period.

action:required

Direction: Server → Bot

{
  "type": "action:required",
  "matchId": "match-uuid",
  "gameState": {
    "phase": "FLOP",
    "communityCards": ["7h", "Qd", "2s"],
    "pot": 30,
    "currentBet": 20,
    "myChips": 980,
    "amountToCall": 10
  },
  "validActions": [
    { "type": "FOLD" },
    { "type": "CALL", "amount": 10 },
    { "type": "RAISE", "minAmount": 20, "maxAmount": 980 }
  ],
  "timeoutMs": 30000,
  "timestamp": 1703001234575
}

Game State Fields

Field	Type	Description
`phase`	`string`	Current game phase (`PREFLOP`, `FLOP`, `TURN`, `RIVER`)
`communityCards`	`string[]`	Cards on the board
`pot`	`number`	Total pot size
`currentBet`	`number`	Current bet to match
`myChips`	`number`	Your chip count
`amountToCall`	`number`	How much you need to add to call

Valid Actions

The validActions array tells you exactly what actions are legal. Only submit actions from this list.

Action	When Available	Required Fields
`FOLD`	Always	—
`CHECK`	When no bet to match	—
`CALL`	When there's a bet to match	`amount` (provided)
`BET`	First bet in a betting round	`minAmount`, `maxAmount`
`RAISE`	After someone has bet	`minAmount`, `maxAmount`
`ALL_IN`	When you can go all-in	—

bot:action

Direction: Bot → Server

Your response with the chosen action.

{
  "type": "bot:action",
  "matchId": "match-uuid",
  "action": {
    "type": "RAISE",
    "amount": 50
  },
  "timestamp": 1703001234580
}

Action Examples

Fold:

{ "action": { "type": "FOLD" } }

Check:

{ "action": { "type": "CHECK" } }

Call:

{ "action": { "type": "CALL" } }

Bet (first bet in round):

{ "action": { "type": "BET", "amount": 20 } }

Raise:

{ "action": { "type": "RAISE", "amount": 50 } }

All-in:

{ "action": { "type": "ALL_IN" } }

action:result

Direction: Server → Bot

Confirmation that your action was processed.

{
  "type": "action:result",
  "success": true
}

On invalid action:

{
  "type": "action:result",
  "success": false,
  "error": "Invalid action: RAISE amount below minimum"
}

Timeouts

You have 30 seconds (configurable per table) to respond to each action:required message.

First timeout: Your action defaults to check (if free) or fold
Second consecutive timeout: Bot is disconnected from the table
Timeouts reset after you successfully respond to an action