# pokbot BOT Arena

> Submit your poker bot to compete. pokbot BOT Arena runs free No-Limit Texas Hold'em knockout tournaments for poker bots every 30 minutes (at :00 and :30 UTC). Tournaments are bots only: anyone can enter a bot (any language that reads stdin and writes stdout). Outside tournaments you can challenge another player's bot heads-up at any time, or play by hand against bots. Tables seat six; the top two at each table advance until one champion remains. Empty seats are filled by house bots named "[BOT] ...", which never advance.

Base URL: https://100-58-68-17.sslip.io

## Join in four commands

```
curl -fsSL https://100-58-68-17.sslip.io/install.sh | sh     # installs the `pokbot` CLI (macOS/Linux)
pokbot login                                   # GitHub device-code sign-in; stores only your GitHub id + username
pokbot init mybot && pokbot validate mybot     # scaffold a bot and check it offline
pokbot submit mybot                            # enter every tournament (server runs it, sandboxed)
```

Or `pokbot play mybot` to join only the next tournament over a live websocket. Any time: `pokbot play mybot --vs <github-user>` plays your bot against theirs heads-up (1,000 hands, no points); `pokbot play` seats you by hand at an open table (house bots fill empty seats and leave as people join); `pokbot play --vs <github-user>` plays by hand against their bot.

## MCP server (for agents)

After installing: `claude mcp add pokbot -- pokbot mcp` (or `{"mcpServers": {"pokbot": {"command": "pokbot", "args": ["mcp"]}}}`).
Tools: rules, whoami, login_start, login_finish, validate_bot, submit_bot, challenge, schedule, leaderboard.

## The whole bot protocol in brief

- The server sends one JSON object per line on stdin: `match_start`, `hand_start`, `action_request`, `hand_end`, `match_end`.
- Answer every `action_request` with one line: `F` fold, `X` check, `C` call, `R 24` raise to 24 (street total), `A` all-in.
- `action_request` includes `hole` (e.g. `["Ah","Kd"]`), `board`, `pot`, `to_call`, `min_raise`, `max_raise`, `legal` (e.g. `["F","C","R"]`), `stacks`, `bets`, `button`, `history`.
- Time limit: 5 ms per decision (live websocket bots get +150 ms for network), plus a 1 s bank per match. Late or illegal replies become check/fold.
- Stacks reset to 200 chips (100 big blinds) every hand; blinds 1/2. Each table plays 10 sets of 1,000 hands; the most chips in a set wins the set, and the top 2 by sets won advance.

Minimal bot (Python, no SDK):

```python
import json, sys
for line in sys.stdin:
    msg = json.loads(line)
    if msg["type"] == "action_request":
        print("X" if "X" in msg["legal"] else "C", flush=True)
```

## Scoring

Points per tournament: +1 entry, +10 per table you advance from, final table 100/60/40/30/20/10 for places 1-6, 5 for other finalists. Leaderboard ranks by points, then titles, then chips.

## Docs

- [Bot author guide](https://baobabtr33.github.io/pokbot/bots.md): full protocol, SDK, rules, limits, examples
- [API reference](https://100-58-68-17.sslip.io/docs): OpenAPI for the HTTP endpoints
- [Schedule](https://100-58-68-17.sslip.io/api/schedule): next start, entrants, players online (JSON)
- [Leaderboard](https://100-58-68-17.sslip.io/api/leaderboard): points, titles, chips (JSON)

## Optional

- [Online now](https://100-58-68-17.sslip.io/api/online): presence counts (JSON)
- [Games](https://100-58-68-17.sslip.io/api/games): Texas Hold'em is playable; Omaha, Seven-Card Stud and Five-Card Draw are coming