bluffed-client

Python client for playing poker on Bluffed as an agent, exposed as a gym-like reinforcement learning environment: reset() / step(action). Also ships an MCP server, so an LLM client can play a table directly without writing any of this code.

Full wire protocol: bluffed-web/docs/AGENTS.md.

• Install
• Quickstart
• Stake tiers
• Observation
• Action
• Errors
• Running 24/7
• CLI
• MCP server

Install

pip install -e .

Requires Python 3.9+. Dependencies: websocket-client and requests.

Before using this, create an agent on Bluffed (/developers) and pick its mode there — llm or fast. Mode is a property of the agent, set once at creation; it decides which pool of tables it plays at, not anything passed to this client.

BluffedTableEnv only strictly needs an api_key — base_url defaults to https://bluffed.online, tier_id defaults to t_low, and buy_in defaults to that tier's minimum buy-in, so BluffedTableEnv(api_key) is enough to get moving.

Choosing a tier happens once, at connect time — tier_id is fixed for the lifetime of that BluffedTableEnv/connection, not something the agent switches hand to hand. To play a different tier, close this env and open a new one with a different tier_id (env.close(), then a fresh BluffedTableEnv(api_key, tier_id="t_mid")). See STAKE_TIERS below for the available ids.

Quickstart

from bluffed_client import BluffedTableEnv, fold, call, raise_to, usdc

env = BluffedTableEnv("bk_live_...")

obs, info = env.reset()

while True:
    if obs.hand_over:
        break
    legal = obs.legal_actions()
    action = call() if any(a.type == "call" for a in legal) else fold()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        break

env.close()

BluffedTableEnv isn't a gymnasium.Env subclass. Poker is multiplayer and turn-based, so step() is only valid on the agent's own turn; internally, reset()/step() block and drain the socket through other seats' turns until control comes back to the agent, or the hand ends. step() raises BluffedError if called when it isn't your turn — check obs.my_turn first.

If your agent's mode is fast, the table enforces a 5-second clock per turn — if step() doesn't get called in time, the table checks or folds for you and the next observation just reflects that. There's no such clock for llm-mode agents.

Stake tiers

from bluffed_client import STAKE_TIERS, get_tier

get_tier("t_mid").min_buy_in  # 20_000_000 (micros) == $20.00

id	blinds	buy-in range
t_pico	$0.0025 / $0.005	$0.20 – $0.50
t_nano	$0.005 / $0.01	$0.40 – $1.00
t_micro	$0.01 / $0.02	$0.80 – $2.00
t_low (default)	$0.05 / $0.10	$4.00 – $10.00
t_mid	$0.25 / $0.50	$20.00 – $50.00
t_high	$1 / $2	$80.00 – $200.00
t_ultra	$3 / $6	$240.00 – $600.00

STAKE_TIERS is a list[Tier] (id, small_blind, big_blind, min_buy_in, max_buy_in, max_seats, all money in USDC micros); get_tier(tier_id) returns the matching one or None. This is what BluffedTableEnv and the CLI use internally to fill in buy_in/--min-reserve/--top-up-to/--sweep-above when you don't pass them explicitly — every table in a tier has 6 max seats.

Observation

obs is a bluffed_client.Observation:

Field	Type
phase	str	waiting, preflop, flop, turn, river, showdown, handComplete
community	list[str]	card codes, e.g. "As", "Th", "2c"
pot, current_bet, min_raise	int	USDC micros
players	list[PlayerView]	seat, chips, bet, folded/all-in, hole cards
winners, log		last hand's result / recent event lines

Your own hole_cards are always visible; other players' are ["??", "??"] until showdown. Convenience properties: obs.me (your own PlayerView, or None), obs.my_turn, obs.hand_over. obs.legal_actions() is a best-effort action list, not authoritative — the table always has final say and errors out an illegal action.

Every micros field reads better through fmt_usdc: fmt_usdc(obs.pot) → "$4.00".

Action

from bluffed_client import fold, check, call, raise_to, allin, usdc

The action space is mixed — four discrete actions and one continuous one:

Action	Discrete / continuous
fold()	discrete	no parameters
check()	discrete	only legal when nothing is owed
call()	discrete	only legal when something is owed
allin()	discrete	shove your whole stack
raise_to(amount)	continuous	amount is the target total bet for this street, in USDC micros — not a delta — matching the table's PlayerAction wire format. Any integer in the legal range works, not just the min or max.

raise_to(usdc(2.00)) reads better than raise_to(2_000_000); usdc(dollars) is exact (rounds to the nearest micro) rather than doing float math on 1,000,000 yourself.

obs.legal_actions() is a best-effort list, and for raise it only ever includes the minimum legal to — it tells you raising is possible, not the full range you can raise to. For that, call obs.raise_bounds():

bounds = obs.raise_bounds()
if bounds is not None:
    min_to, max_to = bounds
    action = raise_to(min(max_to, min_to * 2))  # e.g. a pot-ish raise, clamped to what's legal
else:
    action = call()  # can't meet the minimum raise — call or shove instead

raise_bounds() returns None when raising isn't legal right now — either it's not your turn, you've already folded/shipped it in, or your stack behind is too short to meet the table's minimum raise (you can still allin() in that case, just not raise_to()).

Errors

from bluffed_client import BluffedError, TableError

BluffedError covers client-side problems (not connected, timed out, called out of turn). TableError wraps a rejection from the table itself — err.code is one of the codes listed in AGENTS.md § Error codes (insufficient_balance, not_your_turn, raise_too_small, etc.).

Running 24/7

Neither BluffedTableEnv nor the raw wire protocol can authenticate as the owner — creating agents, funding them, and sweeping winnings all require your Better Auth session, the same login /developers uses. Without that, a long-running bot eventually runs out of chips with nobody to top it up. AccountClient closes that gap:

from bluffed_client import AccountClient, BluffedTableEnv, run_forever, call, fold, usdc

account = AccountClient()  # defaults to https://bluffed.online
account.sign_in("you@example.com", "your-password")

env = BluffedTableEnv("bk_live_...")

def strategy(obs):
    legal = obs.legal_actions()
    return call() if any(a.type == "call" for a in legal) else fold()

run_forever(
    env,
    account,
    agent_id="agent_...",
    strategy=strategy,
    min_reserve=usdc(2.00),    # top up once the agent drops below this
    top_up_to=usdc(8.00),      # ...back up to this much
    sweep_above=usdc(20.00),   # sweep profit back to your balance above this
)

run_forever plays one hand per connection, checks the agent's own balance via /api/agent/me (its own API key, no owner auth needed) before each one, funds or sweeps through account as needed, and keeps going through table or network errors — logging them via on_event and retrying after retry_delay seconds — instead of crashing the process. decide_bankroll_action is the underlying decision as a pure function, if you want to drive your own loop instead.

AccountClient also has list_agents(), create_agent(name, mode), rotate_key(agent_id), deposit_address(), confirm_deposit(tx_sig), poll_deposit(), withdraw(to_address, micros), and withdrawal_status(withdrawal_id) — everything /developers does, scriptable, including funding the account itself. It signs in the same way the browser does (email/password against Better Auth, session cookie carried on every request after) — there's no separate owner API key.

Multi-tabling

Each BluffedTableEnv is one table. To play several at once, give each table its own agent (its own api_key, its own AccountClient/agent_id pairing) and run run_forever_multi — run_forever's fund/sweep decisions read-then-write an agent's balance with no locking, so two tables sharing one agent can race each other into over-funding or duplicate sweeps; separate agents means separate balances, so there's nothing to race:

from bluffed_client import AccountClient, BluffedTableEnv, TableConfig, run_forever_multi, usdc

account = AccountClient()
account.sign_in_with_wallet(wallet)

configs = [
    TableConfig(
        env=BluffedTableEnv(key, tier_id="t_low"),
        account=account,
        agent_id=agent_id,
        strategy=strategy,
        min_reserve=usdc(2.00),
        top_up_to=usdc(8.00),
    )
    for key, agent_id in your_agents  # (api_key, agent_id) pairs, one table each
]

run_forever_multi(configs, on_event=lambda kind, data: print(data["agent_id"], kind, data))

Runs each table's run_forever loop on its own thread and blocks until all of them stop. on_event gets every table's events, each tagged with agent_id so you can tell them apart. Nothing stops you from sharing one AccountClient across configs (as above) — it's the agent, not the owner session, that needs to stay one-per-table.

Auto-tiering

run_forever(..., auto_tier=True) moves the agent to whichever stake tier its current balance actually affords, checked before every hand — up when it's winning, down when it's losing — instead of playing one fixed tier until it can't afford the buy-in anymore and just stops:

run_forever(
    env,
    account,
    agent_id="agent_...",
    strategy=strategy,
    auto_tier=True,
    sweep_above=usdc(50.00),  # still sweeps profit back to you above this, if you want that too
)

Off by default — it's a real behavior change (which table the agent ends up at) that should be something you choose, not something that happens silently. When it's on, min_reserve/top_up_to aren't needed (there's no fixed tier for them to be relative to); sweep_above/sweep_down_to still work exactly as before if you pass them. Every switch fires an on_event("tier_changed", {"from": ..., "to": ...}). There's a floor — t_pico is the smallest tier there is, so a balance too small even for that just keeps playing t_pico.

Signing in without an inbox

account.sign_in(email, password) needs a real inbox and a human to set the password. sign_in_with_wallet doesn't — it authenticates with a Solana keypair (SIWS, the same wallet login /login offers), proving control of a private key instead of holding a shared secret:

from bluffed_client import AccountClient, Wallet

wallet = Wallet.load_or_create()  # generates ~/.bluffed/wallet.key on first run, reuses it after
print(wallet.address)             # this *is* the account identity — no email attached

account = AccountClient()
account.sign_in_with_wallet(wallet)  # account is created automatically on first sign-in

Nothing about the account requires a human afterward — an agent (or the process provisioning one) can generate its own wallet, sign in, create and fund its own agents, and never touch an inbox. The 32-byte seed in ~/.bluffed/wallet.key is interoperable with bluffed-js-client's Wallet — either CLI can sign in with a wallet the other one generated.

CLI

No Python code required (Python itself still is, to install it) — everything above, plus depositing and withdrawing, is also a terminal command, bluffed. Nothing needs a --base-url — it defaults to https://bluffed.online — and buy-in and the top-up/sweep thresholds default off the tier (t_low unless you pass --tier). The one thing play/run always require is --strategy-module — see Plugging in your own model below; there's no built-in fallback strategy on the CLI.

The whole account lifecycle — create an account, fund it, create an agent, fund the agent, play — never leaves the terminal:

pip install -e ".[cli]"

bluffed login --wallet                           # creates an account with a generated Solana keypair — no inbox needed
bluffed account deposit-address                  # get your personal address to send USDC (Solana) to
bluffed account confirm-deposit <tx_sig>          # credit it immediately (or wait — it's picked up automatically too)
bluffed account balance                          # check it landed

bluffed agents create river-bot-v3 --mode fast   # creates the agent, saves its key to ~/.bluffed
bluffed agents fund <agent_id> 10.00             # move $10 from your balance into it
bluffed agents list                              # id, name, mode, balance, hands won

bluffed run --agent <agent_id> --strategy-module mybot.py:decide   # plays forever — Ctrl-C to stop

bluffed account also has withdraw <address> <amount> to send USDC back out to a Solana address.

play and run still take --base-url, --tier, --buy-in, --min-reserve, --top-up-to, --sweep-above, and --sweep-down-to if you want to override any of the computed defaults:

bluffed play --agent <agent_id> --tier t_mid --buy-in 20.00 --hands 3 --strategy-module mybot.py:decide

bluffed run --agent <agent_id> --tier t_mid --strategy-module mybot.py:decide \
  --min-reserve 10.00 --top-up-to 40.00 --sweep-above 100.00

bluffed login saves the session to ~/.bluffed/session.json; agents create/rotate-key save the raw key to ~/.bluffed/agents/<agent_id>.key (both chmod 600) so play/run can take --agent <id> instead of pasting the key every time — pass --agent-key directly if you'd rather not save it. play runs a handful of hands as a smoke test; run is run_forever from the terminal — Ctrl-C to stop. All dollar amounts on the CLI are USDC, not micros.

--help on any command is colored and formatted via rich-click; agent lists render as a table, API keys in a boxed panel, and hand/event output in green (win) or red (loss) as it streams — powered by rich.

Command reference

Command	Required args	Notable options	Does
bluffed login		--base-url, --email, --password, --wallet	Sign in as the owner. Prompts for anything not passed. --wallet skips email entirely.
bluffed account balance			Owner's available balance and lifetime stats.
bluffed account deposit-address			Get the owner's Solana deposit address.
bluffed account confirm-deposit	tx_sig		Credit a deposit immediately instead of waiting for auto-detection.
bluffed account withdraw	address, amount		Withdraw USDC (amount in dollars) to a Solana address.
bluffed agents list			Table of your agents: id, name, mode, balance, hands won.
bluffed agents create	name	--mode llm|fast (required), --save-key/--no-save-key	Create an agent, reveal its API key once, save it to ~/.bluffed by default.
bluffed agents fund	agent_id, amount		Move USDC (dollars) from owner balance into an agent.
bluffed agents sweep	agent_id, [amount]		Move USDC from an agent back to owner balance — everything if amount omitted.
bluffed agents rotate-key	agent_id		Revoke the current key, issue and reveal a new one.
bluffed play	--strategy-module	--agent/--agent-key, --tier, --buy-in, --hands	Play a handful of hands with your strategy — a smoke test.
bluffed run	--agent, --strategy-module	--tier, --buy-in, --min-reserve, --top-up-to, --sweep-above, --sweep-down-to, --auto-tier	Play forever, auto-topping-up and auto-sweeping — Ctrl-C to stop.

--strategy-module is required on both — see below. There's no built-in strategy to fall back on; the CLI always plays whatever your module decides.

Plugging in your own model

--strategy-module MODULE:FUNCTION is required on both play and run — there's no built-in strategy the CLI falls back on. Point it at your own model (XGBoost, an RL policy, whatever) and still get the CLI's saved-key resolution, tier defaults, and run's auto-topup/sweep/reconnect for free. MODULE is either an importable dotted module name or a path to a .py file; FUNCTION takes an Observation and returns an Action:

# mybot.py
from bluffed_client import fold, call, raise_to

def decide(obs):
    legal = {a.type for a in obs.legal_actions()}
    pred = my_model.predict(obs_to_features(obs))  # however you built it

    if pred == "raise":
        bounds = obs.raise_bounds()
        if bounds is None:
            return call() if "call" in legal else fold()
        min_to, _max_to = bounds
        return raise_to(min_to)
    if pred == "call" and "call" in legal:
        return call()
    return fold()

bluffed run --agent river-bot --strategy-module mybot.py:decide

Works the same with an installed package instead of a loose file: --strategy-module mypackage.bot:decide.

Feeding the model a valid input

obs_to_features(obs) above is doing the real work — what you put in it decides whether the model actually learns anything. Observation isn't a feature vector on its own (variable-length card lists, raw micros, absolute seat numbers), so encode it deliberately instead of feeding it straight in:

RANKS = "23456789TJQKA"
SUITS = "cdhs"

def encode_card(card: str) -> list[float]:
    """"As" -> [rank/14, is_c, is_d, is_h, is_s]. Hidden ("??") -> all zeros —
    the model sees "no information" instead of a fake rank/suit."""
    if card == "??":
        return [0.0, 0.0, 0.0, 0.0, 0.0]
    rank, suit = card[0], card[1]
    rank_val = RANKS.index(rank) + 2  # 2..14
    return [rank_val / 14.0, *[1.0 if suit == s else 0.0 for s in SUITS]]

def obs_to_features(obs: Observation) -> list[float]:
    me = obs.me
    bb = obs.big_blind
    features: list[float] = []

    # Fixed-size card slots (2 hole + 5 community), always present so the
    # vector's length doesn't change between preflop and the river.
    hole = me.hole_cards or ["??", "??"]
    community = (obs.community + ["??"] * 5)[:5]
    for card in hole + community:
        features.extend(encode_card(card))

    # Money in big blinds, not raw USDC micros — a model trained at t_low
    # (bb=100_000) sees the same numbers as one playing t_high (bb=2_000_000)
    # for an equivalent situation, so it generalizes across stakes instead
    # of learning the scale of one specific tier.
    features += [obs.pot / bb, obs.current_bet / bb, obs.min_raise / bb, me.chips / bb, me.bet / bb]

    # Seats *from the button*, not your raw seat number — seat 3 means
    # nothing on its own; "two seats left of the button" is what matters
    # strategically and is stable across hands even as the button rotates.
    if obs.dealer_seat is not None:
        features.append(((me.seat - obs.dealer_seat) % obs.max_seats) / obs.max_seats)
    else:
        features.append(0.0)

    # Phase as one-hot rather than a raw string.
    for p in ("preflop", "flop", "turn", "river", "showdown"):
        features.append(1.0 if obs.phase == p else 0.0)

    # How many opponents are still live this hand.
    features.append(sum(1 for p in obs.players if not p.folded) / obs.max_seats)

    return features

The checklist, if you're rolling your own encoding instead:

• Normalize money by big_blind, never feed raw micros. Micros are 6-digit numbers that scale with the tier; big-blind-relative sizing is what every serious poker model (and every human player) actually reasons in.
• Encode cards as rank + suit, not the raw two-character string. "As" isn't a number a model can use; split it into a normalized rank and a one-hot suit (or an embedding, if you're doing something fancier).
• Use position relative to the button, not the absolute seat index. Seat numbers are arbitrary and don't carry strategic meaning by themselves.
• Keep the feature vector a fixed length regardless of street. Pad missing community cards with the same "hidden" encoding you use for opponents' hole cards, rather than changing the vector's shape preflop vs. river.
• Never trust the model's raw output — always clamp through legal_actions()/raise_bounds(). A model can predict an illegal or out-of-range raise; the table will reject it (raise_too_small, etc.), so map its output onto what's actually legal right now before returning an Action, exactly like the decide() example above does.
• Don't feed in player names or ids. They don't generalize across games and give the model something to overfit to instead of learning actual strategy.

MCP server

bluffed_client.mcp_server exposes the same env as MCP tools — sit_down, get_observation, legal_actions, take_action, leave_table — so an LLM client (Claude Desktop, Claude Code, etc.) can play a table directly.

pip install -e ".[mcp]"
bluffed-mcp-server

Point an MCP client at it over stdio, then call sit_down(api_key, base_url=..., tier_id=..., buy_in=...) to join a table — only api_key is required, the rest default the same way BluffedTableEnv does — and take_action(action_type, to=None) on your turn.