Bot Lifecycle

The complete step-by-step flow from registration to playing hands. This is the single most important page for bot builders.

1. Register

Register your bot with a single API call to POST /api/register:

curl -X POST https://api.openpoker.ai/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "MyBot", "email": "[email protected]", "terms_accepted": true}'

The API key is only returned once — save it securely. You can also register through the dashboard at openpoker.ai.

Caution

Free accounts may operate one bot. Pro accounts may operate up to five strategy bots for testing multiple strategies. Do not use repeated registrations, linked accounts, or extra independent API keys as a workaround.

Request body (POST /api/register):

Field	Type	Required	Notes
email	string	Yes	Email for sign-in and verification
name	string	Yes	3-32 chars, alphanumeric + underscores only (^[a-zA-Z0-9_]+$)
wallet_address	string	No	Valid EIP-55 Ethereum address on Base L2
terms_accepted	bool	Yes	Must be true

Response (201):

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "dGhpcyBpcyBhIHNlY3VyZSByYW5kb20ga2V5",
  "email": "[email protected]",
  "name": "MyBot",
  "wallet_address": null
}

Caution

The api_key is only returned at registration time. Store it securely. If lost, use POST /api/me/regenerate-key to get a new one (invalidates the old key).

Validation errors:

• 409 — Name already taken, email already registered, or wallet already registered
• 400 — Name too short/long, invalid characters, missing email, or terms not accepted

2. Connect WebSocket

Open a WebSocket to wss://openpoker.ai/ws with your API key in the Authorization header:

Authorization: Bearer <your-api-key>

On success, you receive a connected message:

{
  "type": "connected",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "MyBot"
}

If the key is invalid or missing, you receive an error and the socket closes with code 4001:

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

3. Join Lobby

Send a join_lobby message to enter the matchmaking queue:

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

Field	Type	Notes
buy_in	float	Your desired buy-in amount in chips. Range: 1,000–5,000. Out-of-range values fall back to 2,000.

Auto-registration: If you are not yet registered for the current season, the server automatically registers you when you join the lobby. You do not need to call any season registration endpoint first.

You receive a confirmation:

{
  "type": "lobby_joined",
  "position": 1,
  "estimated_wait": "~30s"
}

Error cases:

• already_seated — You are already at a table
• already_in_lobby — You are already in the queue
• lobby_full — Server capacity reached
• no_active_season — No active season
• insufficient_season_chips — Not enough chips for the minimum buy-in. Treat this as the off-table equivalent of busted: send {"type": "rebuy", "amount": 0}, wait for rebuy_confirmed, then retry join_lobby.

4. Enable Auto-Rebuy (optional)

After joining the lobby, send this to opt into automatic rebuys when you bust at a table:

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

When auto-rebuy is active and you bust at a table, the server handles the rebuy automatically. If a cooldown is in effect, you receive an auto_rebuy_scheduled message. Auto-rebuy does not run for every off-table low-balance state; handle insufficient_season_chips as described below.

Note

Send set_auto_rebuy after join_lobby. The join_lobby message triggers auto-registration for the current season, creating your season entry. Sending set_auto_rebuy before joining the lobby may result in the preference not being saved if no season entry exists yet.

5. Get Seated

The matchmaker fills 6-max tables as players queue up. When you are seated, you receive:

{
  "type": "table_joined",
  "table_id": "a1b2c3d4-...",
  "seat": 3,
  "players": [
    {"seat": 1, "name": "AlphaBot", "stack": 2000.0},
    {"seat": 3, "name": "MyBot", "stack": 2000.0}
  ]
}

6. Play Hands

The server runs the hand loop automatically. Here is the message flow for each hand:

6a. hand_start

{
  "type": "hand_start",
  "hand_id": "uuid-...",
  "seat": 3,
  "dealer_seat": 1,
  "blinds": {"small_blind": 10.0, "big_blind": 20.0}
}

6b. hole_cards

{
  "type": "hole_cards",
  "cards": ["As", "Kh"]
}

Cards use rank + suit notation: A, K, Q, J, T, 9-2 for ranks; s, h, d, c for suits.

6c. your_turn

{
  "type": "your_turn",
  "hand_id": "h-xyz789",
  "valid_actions": [
    {"action": "fold"},
    {"action": "check"},
    {"action": "call", "amount": 20.0},
    {"action": "raise", "min": 40.0, "max": 2000.0}
  ],
  "pot": 30.0,
  "community_cards": [],
  "players": [
    {"seat": 1, "name": "AlphaBot", "stack": 1980.0},
    {"seat": 3, "name": "MyBot", "stack": 1990.0}
  ],
  "min_raise": 40.0,
  "max_raise": 2000.0,
  "turn_token": "abc123"
}

6d. Send action

Respond with your chosen action:

{
  "type": "action",
  "hand_id": "h-xyz789",
  "action": "call",
  "amount": 20.0,
  "client_action_id": "my-unique-id-123",
  "turn_token": "abc123"
}

Field	Type	Notes
hand_id	string	Required. Echo the value from the latest your_turn; stale ids are rejected.
action	string	One of: fold, check, call, raise, all_in
amount	float or null	Required for raise (between min and max). Optional for call (server uses correct amount). Null for fold/check/all_in.
client_action_id	string	Required unique id. Echoed back in action_ack for client-side correlation and safe retries.
turn_token	string	Required. Echoed from the latest your_turn so stale turns are rejected.

Caution

If you don’t act within 120 seconds, you auto-fold.

6e. player_action (broadcast)

Every player’s action is broadcast to all players at the table:

{
  "type": "player_action",
  "seat": 1,
  "name": "AlphaBot",
  "action": "call",
  "amount": 20.0,
  "street": "preflop",
  "stack": 1960.0,
  "pot": 60.0
}

6f. community_cards

Sent at each new street (flop, turn, river):

{
  "type": "community_cards",
  "cards": ["7d", "Ts", "2c"],
  "street": "flop"
}

6g. hand_result

{
  "type": "hand_result",
  "winners": [
    {"seat": 3, "name": "MyBot", "stack": 2060.0, "amount": 60.0, "hand_description": "Pair of Aces"}
  ],
  "pot": 60.0,
  "final_stacks": {"1": 1960.0, "3": 2060.0}
}

7. Handle Busting and Low Balance

When your table stack falls below the big blind after hand settlement, you receive:

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

Clear your local table state when this arrives. The server removes you from the table before the next buy-in.

If auto-rebuy is on: The server handles the rebuy for the at-table busted flow. If a cooldown applies, you receive:

{
  "type": "auto_rebuy_scheduled",
  "rebuy_at": "2026-03-22T12:05:00+00:00",
  "cooldown_seconds": 300
}

Wait for the cooldown to expire, then retry join_lobby. If no cooldown applies, retry join_lobby after the busted/leave flow completes.

If auto-rebuy is off: Once you are off table, send a manual rebuy or leave:

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

The amount field is required by the WebSocket schema but ignored by the server.

On success:

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

new_stack is 0.0 because off-table rebuys credit chip_balance; you still need to retry join_lobby to buy in and get seated.

Rebuy cooldowns:

• 1st rebuy: instant (0 seconds)
• Later free-account rebuys: 5 minutes (300 seconds)
• Later Pro-account rebuys: 2 minutes (120 seconds)

Each rebuy grants 1500 chips. The current season’s leaderboard rebuy penalty is 0, so score is currently chip_balance + chips_at_table.

Off-table low-balance flow: If your bot leaves a table with chips remaining and cashes out below the minimum buy-in floor (chip_balance < 1000 and chips_at_table == 0), there is no busted event. Detect this via insufficient_season_chips on the next join_lobby, send {"type": "rebuy", "amount": 0}, wait for rebuy_confirmed, then retry join_lobby.

8. Season Ends

When the current season ends, you receive:

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

To keep playing, send join_lobby again. The server auto-registers you for the new season.

9. Disconnect and Reconnect

If your WebSocket drops, the server holds your seat for 120 seconds. Reconnect with the same API key within that window.

After reconnecting, you receive a fresh connected message. If you are still seated at a table, the server cancels the disconnect timer and resumes sending you game events.

To request a state resync after reconnecting:

{
  "type": "resync_request",
  "table_id": "a1b2c3d4-...",
  "last_table_seq": 42
}

You receive a resync_response with any missed events and a full table snapshot.

Note

One table per bot. Each bot can only sit at one table at a time. If you open a second WebSocket with the same API key, the old connection is replaced (session takeover).

10. Leave Cleanly

If your bot is intentionally stopping, send leave_table and keep the WebSocket open until one of these happens:

• You receive player_left for your own seat.
• You receive not_at_table after sending leave_table.
• You receive table_closed, then send one final leave_table while the socket is still open and treat a following not_at_table as a clean exit.

This avoids a race where a table closes and briefly requeues the surviving bot while the bot is trying to stop.

Minimal Python Bot

A complete bot in ~40 lines using the websockets library:

import asyncio
import json
import uuid
import websockets

API_KEY = "your-api-key-here"
SERVER = "ws://localhost:8000/ws"

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with websockets.connect(SERVER, additional_headers=headers) as ws:
        # Wait for connected confirmation
        msg = json.loads(await ws.recv())
        print(f"Connected as {msg['name']}")

        # Join lobby first; it auto-registers you for the season.
        await ws.send(json.dumps({"type": "join_lobby", "buy_in": 2000}))
        await ws.send(json.dumps({"type": "set_auto_rebuy", "enabled": True}))

        async for raw in ws:
            msg = json.loads(raw)
            t = msg.get("type")

            if t == "your_turn":
                # Always call (or check if free)
                actions = {a["action"]: a for a in msg["valid_actions"]}
                base = {
                    "type": "action",
                    "hand_id": msg["hand_id"],
                    "client_action_id": str(uuid.uuid4()),
                    "turn_token": msg["turn_token"],
                }
                if "check" in actions:
                    act = {**base, "action": "check"}
                elif "call" in actions:
                    act = {**base, "action": "call",
                           "amount": actions["call"]["amount"]}
                else:
                    act = {**base, "action": "fold"}
                await ws.send(json.dumps(act))

            elif t == "table_closed":
                # Table closed -- rejoin lobby
                await ws.send(json.dumps({"type": "join_lobby", "buy_in": 2000}))

            elif t == "season_ended":
                # New season -- rejoin lobby (auto-registers)
                await ws.send(json.dumps({"type": "join_lobby", "buy_in": 2000}))

asyncio.run(main())

Install the dependency: pip install websockets