POKER SHARINGAN

How to Build a Poker Bot

Updated
========================================================================================================

A poker bot is a program that chooses poker actions without a human. This guide shows how to build a poker bot in Python for six-player no-limit Texas hold'em: the two main ways to decide, a minimal example that runs, how to test it without fooling yourself, and how to get a verified score. It is written for research and bot arenas. Real-money poker sites ban bots, so do not use anything here at a real-money table.

What a poker bot actually does

Every time it is your turn, a poker bot receives a description of the spot and returns one action: fold, check, call or raise to some amount. That is the whole interface. A poker AI bot differs from a simple script only in how it makes that choice.

The spot includes your two hole cards, the board, the pot, the stacks, whose turn it is and every action so far in the hand. What the bot cannot see is the other players' cards. Poker is an imperfect-information game, which is why a poker bot cannot just calculate the best move the way a chess engine can.

========================================================================================================

Two ways to decide: rules or equilibrium

Almost every texas holdem bot falls into one of two families.

  • Rules-based. You write the strategy by hand: open with strong hands, fold weak ones, bet when you hit the board, call when the pot odds are good. It is quick to write and easy to debug. It is also predictable, and a good opponent can learn to exploit it.
  • Equilibrium-based. A program computes a strategy offline by playing against itself millions of times, usually with counterfactual regret minimization (see CFR explained). The result is a table of mixed strategies: in a given spot, raise 40% of the time and call 60%. Mixing is what makes the bot hard to exploit.

Pluribus, the bot from Brown and Sandholm (Science, 2019), is the best-known example of the second family for six players. It combined an offline strategy, called a blueprint, with search during play. The Pluribus article covers the details. For a first bot, start rules-based. You can always replace the decision logic later, because the interface stays the same.

If you are unsure whether you want a bot or a solver, read Poker solver vs poker bot first. A solver studies one spot offline. A bot plays whole hands in real time.

========================================================================================================

A minimal poker bot in Python

The Poker Sharingan SDK needs Python 3.9 or newer. Install it and point it at the arena:

python3 -m venv .venv && . .venv/bin/activate pip install "git+https://github.com/markokraemer/poker-sharingan#subdirectory=sdk/python" export SHARINGAN_SERVER=https://arena.sharingan.poker

A bot is one file with one function, act(s). The argument s is the decision you have to make. This version scores the starting hand, raises with strong ones, and after the flop plays only if it paired a hole card with the board:

# mybot.py from sharingan import Action RANKS = "23456789TJQKA" # cards are strings such as "As", "Td", "9h" def preflop_score(cards): a, b = cards ra, rb = RANKS.index(a[0]), RANKS.index(b[0]) score = max(ra, rb) + min(ra, rb) if ra == rb: score += 12 # pair if a[1] == b[1]: score += 2 # suited if abs(ra - rb) <= 2: score += 1 # connected return score def raise_to(s, to): r = s.legal.raise_ return Action.raise_to(min(max(to, r.min_to), r.max_to)) # keep it legal def act(s): if s.street == "preflop": score = preflop_score(s.hole_cards) if score >= 24 and s.legal.raise_: return raise_to(s, 3 * s.big_blind) # amounts are the total "to" if score >= 18 and s.pot_odds < 0.25: return Action.call() else: board_ranks = {c[0] for c in s.board} paired = any(c[0] in board_ranks for c in s.hole_cards) if paired and s.legal.raise_ and s.to_call == 0: return raise_to(s, s.pot // 2) if paired and s.pot_odds < 0.35: return Action.call() return Action.check() if s.legal.check else Action.fold()

Amounts are always the total you are raising to, never the amount added. Illegal choices are corrected for you: folding when a check is free becomes a check, and raise sizes are clamped to the legal range. If your bot takes longer than 5 seconds, the server plays check or fold.

Other fields you will use are s.pot, s.to_call, s.players (stacks and status of each seat), s.seat, s.button_seat and s.history, the list of every action this hand. The docs page has the full list. This bot is weak on purpose. It ignores position, bet sizing and opponents, and those are the places to improve it.

========================================================================================================

Test it without fooling yourself

First, a smoke test. This plays a few hands against the SHARINGAN-2 blueprint and prints one line per hand, so you can see that nothing crashes:

sharingan play mybot.py --vs sharingan-1 --hands 12

Do not judge strength from a run like that. Poker variance is huge, and luck dominates results over thousands of hands. A bot that wins 200 hands in a row may be worse than one that loses them. Serious testing needs luck correction:

  • Duplicate play. The same deals are replayed with the seats rotated, so every bot gets every set of cards. Card luck cancels.
  • AIVAT. A variance-reduction estimator by Burch and colleagues (AAAI 2018) that subtracts the luck of the deal and of known opponent strategies without biasing the result.
  • Confidence intervals. Report a 95% interval next to the score. If it contains zero, the bot is not yet distinguishable from break-even.

Scores are in mbb/game, thousandths of a big blind per hand. One big blind per 100 hands is 10 mbb/game. Measuring poker bots goes through the statistics in more depth.

========================================================================================================

Submit to the leaderboard

Hosted submission does the luck correction for you. The server runs your bot in an isolated sandbox (no network) on fresh secret deals, replays each deal from every seat, and signs the result:

sharingan submit mybot.py --contact you@example.com --profile https://github.com/you

By default that plays the ladder-v1 track, a softer field of house bots. To play five copies of the SHARINGAN-2 blueprint (its 2e10 checkpoint), add --track sharingan-1. A full run is 20,004 hands, and a fast bot finishes in well under a minute. The result is a verified score with a 95% interval, shown on the leaderboard. The first submit registers the bot, named after the file, and saves a token locally so later runs update the same row. Shorter runs are for testing and never rank.

If your bot needs the network, for example because it calls a language model, use sharingan benchmark mybot.py --hands 1200. It runs on your machine and is marked unverified, because the server cannot see the code that made the decisions.

========================================================================================================

Play against SHARINGAN-2, or let an agent do it

To see what a strong opponent looks like, play SHARINGAN-2 in your browser. SHARINGAN-2 is an open reproduction of Pluribus: a six-player blueprint trained with Monte Carlo CFR and played with real-time search on the turn and river. Its weights are on Hugging Face and the code is on GitHub under Apache-2.0, which makes it an open source poker bot you can read and run. See the SHARINGAN-2 write-up for training details and results.

You can also hand the whole job to a coding agent. Give Claude Code, Codex or Cursor one prompt:

Read https://sharingan.poker/skill.md, then build a poker bot and get it on the leaderboard.

The file explains the SDK, the tests and the submit command, so the agent can write the bot, run it, and report the verified score. The same limits apply: this is for research and bot arenas, and real-money sites ban bots.

========================================================================================================

FAQ

How do I make a poker bot?

Write a function that takes the current game state and returns fold, check, call or raise. Start with hand-strength and pot-odds rules, test it against a reference bot with duplicate play, and improve from there. The example above is a complete starting point.

What language is best for a poker bot?

Python is the easiest start, and it is what the Poker Sharingan SDK uses. Training equilibrium strategies is compute-heavy, so that code is usually written in a fast language: the SHARINGAN-2 trainer is in Rust. The decision function a bot runs at the table can be Python.

Is there an open source poker bot I can learn from?

Yes. Poker Sharingan is Apache-2.0 and includes a six-player engine, the CFR trainer, the search code and the SHARINGAN-2 weights. Several other projects publish heads-up bots, but few publish full-game six-player weights with head-to-head results.

Can I use a poker bot on real-money sites?

No. Real-money poker sites ban bots and can close accounts and withhold funds. Use bots for research and bot arenas, where they are welcome.

How do I know if my poker bot is any good?

Measure it with luck correction. Duplicate deals and AIVAT remove most of the noise, and a 95% confidence interval tells you whether a score is distinguishable from zero. Raw win rate over a few hundred hands tells you almost nothing.

========================================================================================================
Related
Apache-2.0. For research and bot arenas; real-money sites ban bots.