# Pokerai API

> The first self-serve, solver-grade GTO (game-theory-optimal) strategy API for 6-max No-Limit
> Texas Hold'em. It returns mixed-frequency strategy for every street: preflop and flop come from
> millions of presolved solutions (5.8M+ strategy nodes across 66K isomorphic-board spots, served
> in milliseconds); turn and river are solved on demand on a real-time solver pool. Every request
> is stateless and self-contained — you send the spot, the API returns the strategy. It does NOT
> store your hands, and it does NOT return a single "recommended" action — it returns the GTO
> frequency of each action so you choose per your own randomization.

Base URL: https://pokerai.bet
Auth: `Authorization: Bearer <API_KEY>` (get a free key at https://pokerai.bet/login)
Format: JSON request + JSON response, `Content-Type: application/json`.
Quota: monthly, metered per key. Two independent counters — a **presolved** counter (preflop/flop
lookups) and a **solve** counter (real-time turn/river solves). HTTP 402 `quota_exceeded` when a
counter is exhausted. Free tier available. Tree-poll and node reads do not charge.
Scope: 6-max NLHE, multiple stack depths (e.g. 100bb, 40bb). Action vocab: check, call, bet, raise,
fold (bet = first bet into a pot, raise = raising a bet). Sizes are % of pot; all-in has no size.
Acceptable use: training, coaching, hand review, study, and research. Real-time assistance (RTA) at
real-money tables is prohibited.

## Canonical example — preflop strategy

`preflop_actions` must be the full sequence starting with the small-blind and big-blind posts, then every raise/call up to (not including) hero. The API returns the frequency of each action — often a mix, not a single move.

Request `POST https://pokerai.bet/v1/gto/preflop`:
```json
{ "hole_cards": "9h9s", "positions": { "hero": "MP" },
  "preflop_actions": [ { "position": "SB", "action": "small blind", "amount": 0.5 },
                       { "position": "BB", "action": "big blind", "amount": 1 },
                       { "position": "UTG", "action": "raise", "amount": 2.5 } ] }
```
Response `200` (a genuinely mixed spot — 99 in MP facing a UTG open):
```json
{ "hole_cards": "9h9s", "situation": "Raise",
  "strategy": [ { "action": "fold", "frequency": 0.254 },
                { "action": "call", "frequency": 0.106 },
                { "action": "raise", "frequency": 0.64, "amount_bb": 9, "sizing_pot": 1 } ] }
```
(Hero MP holding AhKh facing a UTG open: raise 100% of the time, to 9bb.)

## Endpoints (presolved — charge 1 presolved quota each)

- `POST /v1/gto/preflop` — preflop strategy for one hole-cards + action sequence. Situation
  (RFI/Limp/Raise/3-Bet/4-Bet/5-Bet) is derived from the actions.
- `POST /v1/gto/preflop/range` — the whole 13x13 preflop range for a spot (one call, not 169).
- `GET  /v1/gto/preflop/versions` — available preflop chart versions (stack depths / formats).
- `POST /v1/gto/flop/tree` — presolved flop decision tree: starting ranges + all decision nodes
  (each node carries a token for /v1/gto/flop/node).
- `POST /v1/gto/flop/node` — strategy at one node of a presolved flop tree.
- `POST /v1/gto/range` — strategy/range for a supplied flop action line (assemble solver_results).
- `POST /v1/gto/flop/projected-range` — updated range after an action line on the flop.
- `POST /v1/gto/turn/projected-range` — updated range after an action line into the turn.

## Endpoints (real-time solver — charge solve quota)

- `POST /v1/gto/solver` — submit a turn/river spot for on-demand solving; returns a task state
  (available → computing → queryable). Poll, then read.
- `POST /v1/gto/solver/tree` — decision tree of a solved spot (poll; does not charge).
- `POST /v1/gto/solver/node` — strategy at one node of a solved spot (does not charge).
- `POST /v1/gto/evs` — per-hand, per-action expected values (EVs) at one node of a solved spot
  (does not charge). Solve handle + node_id; optional hand filters to one hand.

## Docs

- Docs (English): https://pokerai.bet/docs.en
- Docs (中文): https://pokerai.bet/docs
- Interactive API reference: https://pokerai.bet/reference
- OpenAPI spec: https://pokerai.bet/openapi.yaml
- Full LLM context (every endpoint with a real request/response): https://pokerai.bet/llms-full.txt

## A real product built on this API

Counterplay (过招) is a real-time GTO trainer for iOS built entirely on Pokerai API (zero cache):
each hand is played against pure-GTO opponents and every decision is graded against the GTO
frequency returned by these endpoints.