Documentation
API operational
Documentation/Overview
One key · four streets

Get a strategy in one request.

Use MelaSolver GPU through one self-serve API. Start with a millisecond presolved lookup, or submit a custom flop, turn, or river spot to the real-time solver pool.

Run the quickstart Open API reference POST /v1/gto/preflop · 41ms · 200 OK

Postman collection

Download the public collection, import it into Postman, and set the collection apiKey variable to your API key before sending a request. It uses Authorization: Bearer {{apiKey}} and the public https://pokerai.bet base URL; the included examples cover GTO preflop strategy and PokerKit board texture.

Postman collectionThe downloadable source contains no real key, Cookie, or private endpoint. For the complete public contract, see the API Reference and OpenAPI snapshot.

Choose your path

One API key; presolved, solve and persistent-cache counters are separate.

Presolved lookup

FAST

Preflop and 5.8M+ flop solutions. Return a strategy in milliseconds with no task polling.

Start with preflop

Real-time solve

CUSTOM

Custom flop, turn, and river trees. Submit once, poll by task ID, then retrieve the solved strategy.

Submit a solve

First 200 response

Install, authenticate, call. Nothing else to provision.

01 / InstallChoose an SDK
02 / AuthenticateExport one key
03 / RequestCall preflop
request.sh
curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"UTG"},"preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},{"position":"BB","action":"big blind","amount":1}]}'
response.json41ms · 200 OK
{
  "hole_cards": "AhKh",
  "situation": "RFI",
  "strategy": [
    { "action": "raise", "frequency": 1, "amount_bb": 3, "sizing_pot": 0.8 }
  ],
  "quota": { "used": 6, "limit": 100 }
}

Continue building

Move from first call to production without hunting through one long page.

Auth

Every request must carry an API Key. Get a Key in 60 seconds:

  1. Open the console, enter your email → receive a verification code by email (passwordless login, no signup needed).
  2. Enter the code to log in → create an API Key → copy it (shown only once, store it safely).
  3. Set it as an environment variable: export POKERAI_API_KEY=gto_xxxxxxxx, and you can run the Quickstart below.

From then on, send the same Key (the gto_xxx you just copied — this is the “Bearer token”) in a request header on every request. Pick either form below — it is one key, not two:

Authorization: Bearer gto_xxxxxxxx     # standard (recommended; matches OpenAPI scheme BearerApiKey)
# or (fully equivalent, pick one)
X-API-Key: gto_xxxxxxxx                 # equivalent (OpenAPI scheme XApiKey); handy for some gateways / SDKs / quick tests

Quota

One API key; presolved, solve and persistent-cache counters are separate. cache_quota

Two kinds of monthly quota, metered separately and reset on the 1st of each month; current usage is in the console:

  • General quota (Free default 10/month): preflop, preflop range, flop decision-tree fetch, range conversion /v1/gto/range, and projected-range calls each charge 1.
  • Solve quota (Free default 5/month): the real-time solver /v1/gto/solver charges 1 each time it triggers a new solve; reusing a cached solve and fetching the tree/node are free (the response has a solve_quota field when charged, and lacks it when not charged).

Error model

All errors return a uniform JSON: { "error": "<code>", "message": "<description>" }. A few variants: some 502s use reason instead of message; the 429 for all solvers being busy looks like { "status": "busy", "message": ... }. The endpoint-specific error values are in each endpoint's "Possible errors" table; the common status codes are below:

HTTPerror / meaningretry?
400Invalid input or missing field (see each endpoint's table for the specific error).No, fix the input
401missing_api_key / invalid_api_key: missing or invalid Key.No, check the Key
403invalid_node_token / invalid_solve: token/handle invalid or not yours.No, re-fetch the tree / reschedule first
404no_solution: no GTO data for this spot yet.No, change the spot
429quota_exceeded (general) / solve_quota_exceeded (solve): monthly quota used up.No, resets on the 1st or, on Free, choose a paid plan
429status: busy: all solvers busy (only /v1/gto/solver), not charged.Yes, back off and retry
502no_result (reason: timeout / no_worker_available) / auth_unavailable / solver_unreachable: backend transiently unavailable.Yes, back off and retry 2–3 times

Error response body examples

400 (invalid input):

{
  "error": "invalid_board",
  "message": "board must be 3 cards, e.g. \"2c2h2s\""
}

401 (missing Key) / 404 (no data) / 429 (quota used up) — single field or short message:

{ "error": "missing_api_key" }
{ "error": "no_solution", "message": "no GTO data for this spot/board" }
{ "error": "quota_exceeded" }

502 (backend transiently unavailable, retryable):

{
  "error": "no_result",
  "reason": "timeout"
}

Retry: only 429 busy and 502 are worth retrying — use exponential backoff (start ~1s, double, at most 2–3 times). The rest (400/401/403/404/quota exhausted) are terminal and retrying is useless: fix the input / change the Key / re-fetch the tree, or wait for the quota to reset on the 1st of the month. There is no per-second rate limit, so there is no Retry-After header.

Quickstart

Once you have a Key (see above), save it as POKERAI_API_KEY and copy this curl — the simplest successful call: Hero has an opening opportunity in UTG (RFI), and the preflop presolved solution returns in milliseconds. You can also copy the same quickstart snippet from the dashboard.

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"UTG"},"preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},{"position":"BB","action":"big blind","amount":1}]}'

Real response (UTG with AKs, opening opportunity → opens 100% to 3BB):

{
  "hole_cards": "AhKh",
  "situation": "RFI",
  "strategy": [
    { "action": "raise", "frequency": 1, "amount_bb": 3, "sizing_pot": 0.8 }
  ],
  "quota": { "used": 6, "limit": 100 }
}

Facing a raise? Just add the opponent's action to preflop_actions (append {"position":"UTG","action":"raise","amount":3} and change Hero to MP → it becomes a 3bet spot, and situation returns Raise). Each action's mixed frequency is returned (no recommended action; choose yourself based on frequency). The sections below are organized in three parts: Presolved solutions (preflop / flop), real-time solver computation, and range conversion.

Client SDKs Python · TypeScript · MCP

Don't want to hand-write HTTP? The official clients are auto-generated from the OpenAPI spec and fully typed, so they always track the API. Auth is just your API key.

Python pip

pip install pokerai-bet   # distribution name pokerai-bet, import as pokerai

The same Quickstart spot (Hero UTG open), typed:

from pokerai import AuthenticatedClient
from pokerai.api.lookup import preflop_strategy
from pokerai.models import (
    PreflopRequest, PreflopRequestPositions, PreflopRequestPreflopActionsItem,
)
from pokerai.models.preflop_request_preflop_actions_item_action import (
    PreflopRequestPreflopActionsItemAction as Act,
)
from pokerai.models.position import Position

client = AuthenticatedClient(base_url="https://pokerai.bet", token="gto_...")

resp = preflop_strategy.sync(client=client, body=PreflopRequest(
    hole_cards="AhKh",
    positions=PreflopRequestPositions(hero=Position.UTG),
    preflop_actions=[
        PreflopRequestPreflopActionsItem(position=Position.SB, action=Act.SMALL_BLIND, amount=0.5),
        PreflopRequestPreflopActionsItem(position=Position.BB, action=Act.BIG_BLIND, amount=1.0),
    ],
))
print(resp.to_dict())

Real output (same spot as the Quickstart):

{"hole_cards": "AhKh", "situation": "RFI",
 "strategy": [{"action": "raise", "frequency": 1, "sizing_pot": 0.8, "amount_bb": 3}],
 "quota": {"used": 2702, "limit": 100000}}

TypeScript / JavaScript npm

npm install @pokerai/client
import { createPokeraiClient } from "@pokerai/client";

const client = createPokeraiClient({ apiKey: "gto_..." });

const { data, error } = await client.POST("/v1/gto/preflop", {
  body: {
    hole_cards: "AhKh",
    positions: { hero: "UTG" },
    preflop_actions: [
      { position: "SB", action: "small blind", amount: 0.5 },
      { position: "BB", action: "big blind", amount: 1 },
    ],
  },
});
if (error) throw new Error(JSON.stringify(error));
console.log(data.situation, data.strategy);
// "RFI" [{ action: "raise", frequency: 1, amount_bb: 3, sizing_pot: 0.8 }]

Paths, request bodies, and response fields are all type-checked — your editor autocompletes the whole API. Types are generated from the spec by openapi-typescript; the runtime is openapi-fetch.

MCP (for LLM agents) npm

Let Claude / Cursor and friends call the Pokerai API as tools (@pokerai/mcp):

// mcp.json
{ "mcpServers": { "pokerai": {
  "command": "npx", "args": ["-y", "@pokerai/mcp"],
  "env": { "POKERAI_API_KEY": "gto_..." }
}}}

5 presolved-lookup tools by default; add "POKERAI_ENABLE_SOLVE": "1" to enable the real-time solver tools (consumes solve quota).

Concepts

The overall mental model — read this once and the per-endpoint sections below will go more smoothly.

Two ways to get a strategy

  • Presolved solutions: preflop / flop tap presolved GTO solutions, returned in milliseconds, suited to use cases that need a fast response.
  • Real-time solver computation: flop / turn / river are computed live by the solver (flop takes about 70 seconds; turn/river are faster), suited to any custom range/spot.
  • Range conversion: update a range along an action line into the range that enters the next street, then feed it to the solver.

No recommended action is returned

Every strategy returns each action's mixed frequency (0–1) and does not pick the action for you — you implement it yourself from frequency (take the max probability, or sample randomly by frequency).

Bet sizing: amount_bb and sizing_pot

Each bet/raise carries two sizing fields: amount_bb (the absolute amount, i.e. the BB you raise to) and sizing_pot (the value relative to the pot, the standard % of pot convention):

  • bet (first bet) = bet ÷ pot.
  • raise (facing a bet) = (raise-to − current bet) ÷ pot after the call.

Example: 3bet to 9 facing an open of 3 — pot is 4.5, after the call 4.5+3=7.5, the raise exceeds by 9−3=6, so sizing_pot = 6/7.5 = 0.8. When all-in it also carries allin: true.

tree → node (fetch tree → fetch node)

Both the flop decision tree and the real-time solver are two steps: first fetch the whole tree (each decision node carries a token), then use the Hero node's token to fetch that step's strategy.

fetch tree   /flop/tree   or   /solver (+ poll /solver/tree)
         └─→ nodes[]: each node carries is_hero + token
               └─→ pick the node with is_hero:true
fetch node   /flop/node  or   /solver/node    (body carries that node's token)
               └─→ the mixed strategy of this step
  • flop: /flop/tree (charges 1) → /flop/node (free). The root node = Hero's first decision.
  • solver: /solver scheduling returns a solve handle (charges 1) → /solver/tree polling + /solver/node (both free). The range is given only once at scheduling, not passed again.

Node path notation (two conventions, depending on the tree's source): the flop decision tree uses BET_8 (underscore, integer BB); the solver tree uses BET 8.000000 (space, 6 decimals). When passing node_id / navigating, it must match the labels in that tree (or in solver_results) character for character.

Node state machine (real-time solving)

After scheduling, poll the spot_status of /solver/tree: available (not scheduled) → computing (solving, keep polling) → queryable (can fetch nodes) → expired (cache reclaimed by TTL, must reschedule). When done querying, you may optionally call /solver/release to return the port to the pool immediately (otherwise it is reclaimed by TTL); after release, further queries on this solve handle return expired.

Presolved solutions presolved · milliseconds

preflop and flop tap presolved GTO solutions, served instantly, suited to use cases that need a fast response. The effective stack is fixed at 100BB (presolved, not an input). To compute the flop live with the real solver, see the next section.

preflop_pack

The coverage endpoint and this preflop_pack input/output revision with required coverage filters are available in production since 2026-11-13. New coverage direct-HTTP examples are a 55-event local-isolated-http capture at Relay e0b96a4c34ef56dfb5b841588ed5a0d55cfcabb1, not a production capture. Existing historical strategy captures remain unchanged; no SDK/MCP release, new URL, strategy capability or quota change is claimed. Stable <cursor:N> placeholders cannot be sent to the real API. The directory board 2c2d2h and the existing AhKhQh strategy workflow remain separate captures; no native strategy read is claimed.

Deprecated input alias; use preflop_pack. Accepted only at this original entry point. Legacy-only behavior is unchanged. optional; which 6max preflop chart set to use. Omit for the platform default (6max). Unknown value -> 400 unsupported_preflop_version.

With preflop_pack=A, the chart uses A and an enabled guarantee also uses A. Legacy-only preflop_version=A and flop_version=B remain independent (each defaults to 6max): preflop_version=A alone with the flag true gives chart A / guarantee 6max, whereas preflop_pack=A gives A / A. Mixed inputs compare only effective synonymous selectors. When the flag is off, legacy flop_version is ignored even if invalid. The guarantee response publishes preflop_pack only; manifest_version is unchanged.

Use preflop_pack inside request for type preflop or flop; the original type-specific legacy input alias remains accepted. requested_preflop_pack is the requested pack, resolved_preflop_pack is the actual hit (including fallback). Solver has no pack selector or echo. Old output names are not duplicated; old-input compatibility does not make old-output readers compatible.

Input aliases only: preflop/preflop-range accept deprecated preflop_version; Flop tree/projected-range and cache preset accept deprecated flop_version; availability uses the alias of request.type inside request. Only those original entry points accept them. Solver, custom cache roots, node requests and App-specific /v1/apps/solver/ranges gain no pack override. Pure legacy server selectors preserve null/empty omission and coercion; strict cache/coverage parsing remains strict. Canonical preflop_pack errors use 400 invalid_request; legacy unsupported_preflop_version/unsupported_flop_version errors remain unchanged. The pack catalog still returns versions/id/default, and APIs without a pack echo gain none.

Preflop

POST https://pokerai.bet/v1/gto/preflop charges 1 general

Full parameter / response schema, and try it live → interactive reference.

You don't need to judge "how many bets the pot is" — give Hero's preceding preflop actions in order, and the server derives the spot automatically (unopened / facing a raise / 3bet / 4bet…).

Call example

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Authorization: Bearer $POKERAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"MP"},"preflop_pack":"6max_RC_100bb_200NL",
       "preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},
                          {"position":"BB","action":"big blind","amount":1},
                          {"position":"UTG","action":"raise","amount":3}]}'

Omit preflop_pack for the default (6max). Available versions are listed below, or query them live with GET /v1/gto/preflop/versions.

Notes · request body

fieldtypedescription
hole_cardsstringHero's 2 hole cards, e.g. "AdKd".
positions.herostringHero's position, one of SB BB UTG MP CO BTN (placed under positions).
preflop_actionsarrayThe complete, explicit action sequence from the small blind up to the player just before Hero (Hero is not in the sequence; Hero's position is given by positions.hero, and the sequence stops at the player before Hero). Each item is { position, action, amount, allin? }, see the table below.
preflop_packstringOptional preflop pack for the chart. Omit both selectors for the platform default (6max). When explicitly present, preflop_pack must be a non-empty string from this pack catalog, without trimming or case conversion. A valid effective legacy alias may accompany it only with the same value; conflicting selectors fail with 400 before consumption. Legacy-only requests retain their original omission, null/empty, coercion, errors, defaults and fallback behavior; these rules do not relax the strict cache or coverage inputs.

Fields of each preflop_actions item

fieldtypedescription
positionstringThe position of this action, one of SB BB UTG MP CO BTN.
actionstring∈ "small blind" / "big blind" / "raise" / "call" / "fold" (note the blinds are two-word strings).
amountnumberThe incremental amount newly invested by this action (BB, not the cumulative total). Examples: small blind 0.5; big blind 1; an opening raise to 3 → amount 3 (from 0); a player who already invested 1 reraising to 9 → amount 8. fold omits it (counts as 0). Pot = sum of all amount.
allinbooleanOptional. Marks a short-stack all-in (bet/call amount below the minimum raise); when true, the minimum-raise check is skipped.

Validation (violation → 400 invalid_actions): the sequence must start with small blind (0.5), then big blind (1); each raise/call needs a positive amount; a raise's cumulative total must exceed the current bet and meet the minimum raise (= current bet + the size of the previous raise; so opening ≥ 2BB, and a 3bet over an open-to-3 must be ≥ 5BB) — unless allin:true; a call's cumulative total must exactly equal the current bet — unless allin:true.

Exact amounts only affect the pot / sizing_pot, not the frequencies: giving exact amount values only makes the pot / sizing_pot exact; GTO frequencies are determined by the spot (RFI / 3bet / 4bet + position) and do not change with bet size.

Response (200)

{"hole_cards": "AhKh", "situation": "Raise", "strategy": [{"action": "raise", "frequency": 1, "amount_bb": 9, "sizing_pot": 0.8}], "quota": {"used": 7, "limit": 100}}
fielddescription
hole_cardsThe echoed hand.
situationThe state the table faces when it's Hero's turn: RFI (no one in the pot, Hero has an opening opportunity) / Limp (someone limped, no raise) / Raise (facing one opening raise) / 3-Bet / 4-Bet / 5-Bet. Note: BB always lands on Limp (someone must have entered the pot before it acts).
strategy[]The mixed strategy of each action. raise carries amount_bb (the absolute amount raised to, in BB) and sizing_pot (see bet sizing). Preflop amount_bb is set by the number of raises before Hero, see the table below. No recommended action is returned; choose yourself based on frequency.
quotaThis month's general quota usage (used / limit).

Preflop amount_bb (derived from the presolved flop pot, raised to):

number of raises before Herospotamount_bb
0open3
13bet9
24bet25
≥35bet+all-in 100 (allin: true)

Strategy versions preflop_pack

Same 6max, different chart sets (frequencies differ for the same spot); omit for the default 6max. The authoritative list is the discovery endpoint GET /v1/gto/preflop/versions (free; returns id + label + default):

id (pass as preflop_pack)description
6max (default)6 max 100bb Deepsolver
6max_RC_100bb_200NL6 max 100bb GG 200NL 3b/f 2.2x - 2.5x
6max_RC_100bb_100NL6 max 100bb GG 100NL 3b/f
6max_RC_40bb6 max 40bb GG 100NL
curl -s https://pokerai.bet/v1/gto/preflop/versions -H "Authorization: Bearer $POKERAI_API_KEY"
// {"versions": [{"id": "6max", "label": "6 max 100bb Deepsolver", "default": true}, …], "default": "6max"}

Possible errors

HTTPerrortrigger / how to fix
400invalid_hole_cardshole_cards is not 2 cards (e.g. "AdKd").
400unsupported_table_size / invalid_positions / invalid_actionsTable type (currently only 6max), hero/positions, or preflop_actions is invalid.
400invalid_requestOptional preflop pack for the chart. Omit both selectors for the platform default (6max). When explicitly present, preflop_pack must be a non-empty string from this pack catalog, without trimming or case conversion. A valid effective legacy alias may accompany it only with the same value; conflicting selectors fail with 400 before consumption. Legacy-only requests retain their original omission, null/empty, coercion, errors, defaults and fallback behavior; these rules do not relax the strict cache or coverage inputs.
404no_solutionNo presolved solution for this preflop spot; change the spot.

Download: request.jsonresponse.json

Whole range (13×13) charges 1 general

POST https://pokerai.bet/v1/gto/preflop/range · the full 13×13 range for a spot (position + action line), returning all 169 hand types' fold/call/raise in one call. No hole_cards (the spot comes from positions + preflop_actions). Charges 1 general quota (one call, not 169). For rendering a range grid.

// Request (no hole_cards)
{"table_size": "6max", "positions": {"hero": "BTN"}, "preflop_actions": [{"position": "SB", "action": "small blind", "amount": 0.5}, {"position": "BB", "action": "big blind", "amount": 1}, {"position": "UTG", "action": "fold"}, {"position": "MP", "action": "fold"}, {"position": "CO", "action": "fold"}]}

// Response
{ "range": {"22": {"fold": 0.69, "call": 0, "raise": 0.31}, "33": {"fold": 0, "call": 0, "raise": 1}, "ATs": {"fold": 0, "call": 0, "raise": 1}, "AKs": {"fold": 0, "call": 0, "raise": 1}, "AKo": {"fold": 0, "call": 0, "raise": 1}, "KQs": {"fold": 0, "call": 0, "raise": 1}, "72o": {"fold": 1, "call": 0, "raise": 0}, "JJ": {"fold": 0, "call": 0, "raise": 1} , …169 hands total… },
  "quota": {"used": 7, "limit": 100} }

Hand notation: pair AA, suited AKs, offsuit AKo (high card first); each entry's fold+call+raise≈1. Full schema / try it live → interactive reference.

Flop decision tree

The flop strategy is a decision tree: first fetch the tree (getting all decision nodes + each node's token), your system walks the path on the tree by the actual bets, and at Hero's node fetches that step's strategy. Two steps, same as the solver (tree → node).

1) Fetch the decision tree charges 1 general

POST https://pokerai.bet/v1/gto/flop/tree · input board + pot_type + positions (no hole_cards needed, the tree is independent of the hand).

Full parameter / response schema, and try it live → interactive reference.

// Request (no hole_cards)
{"board": "2c2h2s", "pot_type": "SRP", "positions": {"hero": "UTG", "raiser": "UTG", "caller": "BTN"}}

// Response (36 nodes total; first 5 shown)
{"board": ["2c", "2h", "2s"], "pot_type": "SRP", "pot": 7.5, "effective_stack": 97, "oop_range": "AA:1,AKs:1,AQs:1,AJs:1,ATs:1,A9s:1,A8s:1,A7s:1,A6s:1,A5s:1,…", "ip_range": "AQs:0.05,AJs:0.86,ATs:0.436,A9s:0.356,A8s:0.36,A7s:0.196,…", "node_count": 36, "nodes": [{"node": "root", "is_hero": true, "token": "eyJ…"}, {"node": "root/BET_4", "is_hero": false, "token": "eyJ…"}, {"node": "root/BET_8", "is_hero": false, "token": "eyJ…"}, {"node": "root/BET_97", "is_hero": false, "token": "eyJ…"}, {"node": "root/CHECK", "is_hero": false, "token": "eyJ…"}, …], "quota": {"used": 7, "limit": 100}}
boardThe 3 flop cards, e.g. "2c2h2s".
pot_type"SRP" single-raised / "3BET" / "4BET" / "LIMP" limped.
positionsThe position of each role (SB BB UTG MP CO BTN), required per pot_type as below.
preflop_packOptional preflop pack selecting its corresponding Flop dataset; omit both selectors for 6max. Legacy Flop lookup fallback to 6max is unchanged when a selected pack lacks this spot. Node tokens retain the selected dataset; node requests have no pack override. When explicitly present, preflop_pack must be a non-empty string from this pack catalog, without trimming or case conversion. A valid effective legacy alias may accompany it only with the same value; conflicting selectors fail with 400 before consumption. Legacy-only requests retain their original omission, null/empty, coercion, errors, defaults and fallback behavior; these rules do not relax the strict cache or coverage inputs.
pot_typerequired positionsHero value
SRPhero, raiser, callerraiser or caller
3BET / 4BEThero, raiser, three_bettorraiser or three_bettor
LIMPhero, limperone of Hero or limper must be BB
fielddescription
oop_range / ip_rangeThe starting range of this spot (weighted combo string), used as the starting weights for range conversion.
nodes[]All decision nodes: node (action path, e.g. "root/CHECK/BET_8"), is_hero (whether it's a Hero decision point), token (the credential to fetch that node's strategy, passed to step 2; bound to account + spot, cannot be forged).
pot / effective_stack / node_countPot, effective stack (BB), and total number of decision nodes.
quotaThis month's general quota usage (used / limit).

2) Fetch a node's strategy free

POST https://pokerai.bet/v1/gto/flop/node · carries node (the token of some node from step 1). With hole_cards → the mixed strategy for that hand; without hole_cards → the full range strategy.

Full parameter / response schema, and try it live → interactive reference.

Every Hero decision goes through here: Hero's first action = the root node (OOP acts first, check/bet); when Hero is IP, facing a bet, or acting a second time, pick the corresponding is_hero:true node (e.g. root/CHECK/BET_8 = I checked and now face a bet → fold/call/raise). The flop tree is single-street; for cross-street (turn/river) use /v1/gto/solver/*.

// Request (Hero node, with hole_cards) -> Hero strategy
{"node": "eyJ…", "hole_cards": "AdKd"}
{"hole_cards": "AdKd", "node": "root", "is_hero": true, "strategy": [{"action": "check", "frequency": 0.7208}, {"action": "bet", "amount_bb": 4, "sizing_pot": 0.5333, "frequency": 0.0533}, {"action": "bet", "amount_bb": 8, "sizing_pot": 1.0667, "frequency": 0.2259}, {"action": "bet", "amount_bb": 97, "sizing_pot": 12.9333, "allin": true, "frequency": 0}]}

// Request (no hole_cards) -> whole-range strategy
{"node": "eyJ…"}
{"node": "root/BET_4", "is_hero": false, "actions": [{"action": "call"}, {"action": "raise", "amount_bb": 12, "sizing_pot": 0.5161}, {"action": "raise", "amount_bb": 20, "sizing_pot": 1.0323}, {"action": "raise", "amount_bb": 97, "sizing_pot": 6, "allin": true}, {"action": "fold"}], "range_strategy": {"3d3c": [0.93067, 4e-05, 0.06922, 1e-05, 7e-05], "3h3c": [0.92172, 6e-05, 0.07812, 1e-05, 0.0001], "3h3d": [0.94334, 4e-05, 0.05655, 1e-05, 7e-05], "…": "188 hands total"}, "range_hand_count": 188}
fielddescription
is_heroWhether this node is Hero's decision.
strategy[]Hero node (with hole_cards): the mixed strategy for this hand. action ∈ check / bet / call / raise / fold (bet = first bet, raise = a raise facing a bet); bet/raise carry amount_bb and sizing_pot (see bet sizing), and all-in also carries allin: true; frequency is a 0–1 probability. No recommended action is returned; choose yourself based on frequency.
actions[] + range_strategyOpponent node (or no hole_cards): the full range strategy, with each hand's frequencies aligned to actions; includes range_hand_count. Can be used to assemble solver_results for "range conversion".

The BET_8 / RAISE_20 in a node id is the absolute bet amount (BB).

Possible errors

HTTPerrortrigger / how to fix
4001) invalid_board / invalid_positions; 2) missing_node / invalid_hole_cards1) board is not 3 cards, or hero/positions invalid; 2) missing node or hole_cards is not 2 cards.
403invalid_node_token(step 2) node token invalid or not yours — call /v1/gto/flop/tree to fetch the tree first.
404no_solutionNo presolved solution for this spot/board.

Download: tree_request.jsontree_response.jsonnode_request.jsonnode_response.json

Solver (real-time) solver

POST https://pokerai.bet/v1/gto/solver family. Pure postflop solver, computed in real time, using a separate solve quota. The essence is input-to-solve: board + oop/ip ranges + pot + behind stack + who is Hero, with no history needed, so you can enter from any spot. Three steps: schedule → poll for the tree → fetch a node's strategy.

Full parameter / response schema, and try it live → interactive reference (includes /solver/tree, /solver/node).

board length sets the street: 3=flop / 4=turn / 5=river. ⚠ Real-time solving starting from the flop takes a while (measured SRP flop ~70 seconds), and is not suited to use cases that need a fast response — if you want a fast flop, use "Presolved solutions" above (served instantly in milliseconds); turn / river are faster (seconds to tens of seconds).

Call example (three steps: 1) schedule → 2) poll for the tree → 3) fetch a node)

# 1) schedule (board 3/4/5 = flop/turn/river; flop ~70 seconds)
curl -s https://pokerai.bet/v1/gto/solver -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"board":"2c2h2s","oop_range":"AA,KK,QQ,AKs","ip_range":"JJ,TT,AQs,KQs","pot":7.5,"effective_stack":97,"hero":"OOP","bet_sizes":{"flop":[33,75],"turn":[67],"river":[75]},"raise_sizes":{"flop":[50],"turn":[80],"river":[125]},"donk_sizes":{"turn":[55],"river":[90]},"raise_limit":3}'
# 2) poll for the tree until spot_status=queryable; 3) fetch the node
curl -s https://pokerai.bet/v1/gto/solver/tree -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" -d '{"solve":"eyJ..."}'

1) Schedule a solve charges 1 solve

board3=flop / 4=turn / 5=river, e.g. "2c2h2s9d" (turn).
oop_range / ip_rangeRequired. The two players' ranges entering this street, weighted combo strings, e.g. "AsKs:1,QQ:0.75,...".
pot / effective_stackRequired. The pot and behind effective stack (BB) entering this street; they determine the bet sizes and must be real.
heroRequired: "OOP" or "IP".
bet_sizesOptional: override opening bet sizes per street, e.g. {"flop":[33,75],"turn":[67],"river":[75]} (% of pot); if flop is omitted it defaults to 50%.
raise_sizesOptional: override raise sizes per street, e.g. {"flop":[50],"turn":[80],"river":[125]} (% of pot); omitted streets reuse bet_sizes or defaults.
donk_sizesOptional: override OOP donk-lead sizes, e.g. {"turn":[55],"river":[90]} (% of pot); defaults are turn 67% and river 100%.
raise_limitOptional: tree-wide raise cap, 1–4; defaults to 3 for flop/turn solves and 4 for river-only solves.
// Request (flop, with custom bet / raise / donk sizes)
{"board": "2c2h2s", "oop_range": "AA,KK,QQ,AKs", "ip_range": "JJ,TT,AQs,KQs", "pot": 7.5, "effective_stack": 97, "hero": "OOP", "bet_sizes": {"flop": [33,75], "turn": [67], "river": [75]}, "raise_sizes": {"flop": [50], "turn": [80], "river": [125]}, "donk_sizes": {"turn": [55], "river": [90]}, "raise_limit": 3}

// Response (first trigger, charges 1 solve)
{"status": "computing", "solve": "eyJ0Ijoic2x2XzJmMjk2MWU3Y2Y0ODU3OGUiLCJ1IjoiYjk4Y2Y5NzAtZTVjMS00Njk5LTg4ODQtOGQzYzcwMGIyNGJlIiwidHMiOjE3ODIxMjkxMTUyMDJ9.rtmeNcZoBNWJRhkAGkTSSR58ZafpAh35mi510bgPU6c", "solve_quota": {"used": 1, "limit": 100}}
field / casedescription
solveThe solve handle, used by the subsequent /tree and /node; the range is given only once in this step.
status = computingA new solve was triggered, charges 1 solve quota (see solve_quota).
status = queryableA cached solve already exists for this spot, not charged (no solve_quota field), poll /tree directly.
429 status = busyAll solvers are busy, not charged, retry later.

Cache hit (not charged again): re-scheduling the same spot (same board/range/pot/stack/hero/bet_sizes/raise_sizes/donk_sizes/raise_limit) no longer charges solve quota — if the response has no solve_quota field it means not charged; just use the returned solve handle to poll /tree. Examples: request / response.

2) Fetch the decision tree + node status free

POST https://pokerai.bet/v1/gto/solver/tree · carries the solve handle, poll until spot_status = queryable. To reach a later street, pass the dealt cards: turn_card (a flop solve → a specific turn) and/or river_card. A river spot from a flop solve needs BOTH turn_card + river_card (river alone isn't unique); a turn solve needs only river_card; omit both for the solve's own street.

// (2) fetch this street (flop) tree
{"solve": "eyJ…"}
{"street": "flop", "spot_status": "queryable", "pot": 7.5, "effective_stack": 97, "solve_seconds": 25.84, "node_count": 14, "nodes": [{"node": "root", "is_hero": true, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000", "is_hero": false, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000/RAISE 12.000000", "is_hero": true, "status": "queryable", "token": "eyJ…"}, …]}

// turn tree (flop solve + turn_card)
{"solve": "eyJ…", "turn_card": "9d"}
{"street": "turn", "spot_status": "queryable", "pot": 7.5, "effective_stack": 97, "solve_seconds": 25.84, "node_count": 104, "nodes": [{"node": "root/BET 4.000000/CALL/9d", "is_hero": false, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000/CALL/9d/BET 10.000000", "is_hero": true, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000/CALL/9d/BET 10.000000/RAISE 34.000000", "is_hero": false, "status": "queryable", "token": "eyJ…"}, …]}

// river tree (flop solve + turn_card + river_card)
{"solve": "eyJ…", "turn_card": "9d", "river_card": "Qh"}
{"street": "river", "spot_status": "queryable", "pot": 7.5, "effective_stack": 97, "solve_seconds": 25.84, "node_count": 308, "nodes": [{"node": "root/BET 4.000000/CALL/9d/BET 10.000000/CALL/Qh", "is_hero": true, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000/CALL/9d/BET 10.000000/CALL/Qh/BET 27.000000", "is_hero": false, "status": "queryable", "token": "eyJ…"}, {"node": "root/BET 4.000000/CALL/9d/BET 10.000000/CALL/Qh/BET 27.000000/RAISE 83.000000", "is_hero": true, "status": "queryable", "token": "eyJ…"}, …]}
fielddescription
spot_statusSolve status: available (not scheduled) / computing (solving, keep polling) / queryable (fetchable) / expired (cache reclaimed, reschedule at step 1) / no_nodes (solve converged but the queried runout/street has no decision nodes in the tree — terminal, stop polling).
nodes[]Each decision node: node (action path), is_hero, status, token (the credential to fetch that node's strategy, passed to step 3). The river runout is a chance node, navigated by river card.
street / pot / effective_stack / node_countStreet, pot, effective stack, and total number of decision nodes.
solve_secondsWall-clock time of this real-time solve, from schedule to convergence (seconds). Returned only when queryable; all runouts of the same solve share this value.

Full parameter / response schema, and try it live → interactive reference.

3) Fetch a node's strategy free

POST https://pokerai.bet/v1/gto/solver/node · carries the node token. A Hero node returns the Hero strategy; an opponent node (or no hole_cards) returns the range strategy.

{"node": "eyJ…", "hole_cards": "AhKh"}
{"hole_cards": "AhKh", "node": "root", "is_hero": true, "strategy": [{"action": "check", "frequency": 0}, {"action": "bet", "amount_bb": 4, "sizing_pot": 0.5333, "frequency": 0.2666}, {"action": "bet", "amount_bb": 97, "sizing_pot": 12.9333, "allin": true, "frequency": 0.7334}]}
fielddescription
is_heroWhether this node is Hero's decision.
strategy[]Hero node: Hero's mixed strategy for this hand (action / amount_bb / sizing_pot (see bet sizing) / frequency), with allin: true added when all-in.
actions[] + range_strategyOpponent node (or no hole_cards): in range_strategy each hand's frequencies align to the actions order; also includes range_hand_count.

Full parameter / response schema, and try it live → interactive reference.

When you are done, you may optionally call /v1/gto/solver/release to free the port immediately (otherwise the system reclaims it automatically by TTL). When the cache has been reclaimed or replaced by a newer solve, this step returns { "node_status": "expired" }; just reschedule at step 1. A per-node solve error returns { "node_status": "error", "message": … } (terminal — stop polling). Full /solver/release parameter / response schema → interactive reference.

Possible errors

HTTPerrortrigger / how to fix
400invalid_board / missing_range / invalid_pot / invalid_effective_stack / invalid_hero(scheduling) the board, oop/ip range, pot, behind stack, Hero, or other solve input is invalid.
400missing_solve / missing_node(fetch tree/node) missing the solve handle or node token.
403invalid_solve / invalid_node_tokenHandle/token invalid or not yours — reschedule / re-fetch the tree.
429status: busyAll solvers are busy, not charged, back off and retry.
502solve_failedTriggering the solve failed; retry later.
503upstream_unavailable(tree/node) the solver is unreachable after the service's own retries (transport error / 5xx) — retryable.

Download (turn, board=4): schedule_reqschedule_restree_reqtree_resnode_reqnode_res

Download (flop, board=3): schedule_reqschedule_restree_reqtree_resnode_reqnode_res

Download (river, board=5): schedule_reqschedule_restree_reqtree_resnode_reqnode_res

End-to-end polling example (Python)

import requests, time
H = {"Authorization": "Bearer $POKERAI_API_KEY"}
BASE = "https://pokerai.bet/v1/gto"

# 1) schedule (charges 1 solve quota; free on cache hit)
solve = requests.post(f"{BASE}/solver", headers=H, json={
    "board": "2c2h2s9d", "oop_range": "AA,KK,QQ,AKs", "ip_range": "JJ,TT,AQs,KQs",
    "pot": 20, "effective_stack": 90, "hero": "OOP",
    "bet_sizes": {"turn": [67], "river": [75]},
    "raise_sizes": {"turn": [80], "river": [125]},
    "donk_sizes": {"turn": [55], "river": [90]},
    "raise_limit": 3}).json()["solve"]

# 2) poll for the tree until queryable
while True:
    tree = requests.post(f"{BASE}/solver/tree", headers=H, json={"solve": solve}).json()
    if tree["spot_status"] == "queryable": break
    time.sleep(2)                       # computing -> back off and retry

# 3) fetch Hero's root node strategy
root = next(n for n in tree["nodes"] if n["node"] == "root")
strat = requests.post(f"{BASE}/solver/node", headers=H,
                      json={"node": root["token"], "hole_cards": "AhKh"}).json()
print(strat["strategy"])

Range conversion range

POST https://pokerai.bet/v1/gto/range charges 1 general

Full parameter / response schema, and try it live → interactive reference.

Update the OOP/IP ranges along an action line. Mainly used to get the range that enters the next street (flop→turn / turn→river), then feed it to /v1/gto/solver. All of the range-update computation (including normalize and bluff discount) is done by the solver, and is consistent with the solver's results.

This is a pass-through proxy: you assemble all of the input yourself, including solver_results (the decision tree). The decision tree can be one of your own solves, or assembled from this platform's flop decision tree: call /v1/gto/flop/tree for the starting range, then for each node call /v1/gto/flop/node without hole_cards to fetch the full range_strategy, nested as {node_type,player,strategy,childrens}. See the script at the end.

Request body

{
  "range_oop": "AQs:1,AJs:0.48,...",            // required, starting OOP range
  "range_ip":  "AA:1,AKs:1,...",                 // required, starting IP range
  "solver_results": { /* required: the decision tree */ },
  "node_id": "root/CHECK",          // required, the action line
  "board": "2c2h2s",                             // optional, unseparated string (same as other endpoints)
  "normalize": true,                             // optional, default true
  "explain": false,                              // optional, per-hand change explanation
  "track_hands": ["AA"],                         // optional, track only these hands
  "bluff_discount_ratio": 0.8,                   // optional, bluff discount
  "hero_position": "oop",                        // optional, "oop" / "ip" — which player is Hero (for card blocking)
  "hero_hand": "AsKs"                            // optional, remove combos that contain Hero's cards (blockers); echoed back
}

Card blocking (optional): set hero_position ("oop"/"ip") + hero_hand to remove every combo that contains one of Hero's cards from the ranges — useful for range-vs-hand analysis. Both are echoed back in the response. (This pair is also honored by the projected-range wrappers; /v1/gto/flop/projected-range additionally supports partner_hands.)

Call example

# solver_results is large, put it in a file and use -d @
curl -s https://pokerai.bet/v1/gto/range -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" -d @range_request.json

Response (200, real response, long strings truncated)

{"bluff_combos_ratio": 0.33, "bluff_discount_ratio": 1, "board": ["2c", "2h", "2s"], "hand_bottom_ranks_ip": "KsQh:2413,KsQd:2413,KsQc:2413,KhQs:2413,…", "hand_bottom_ranks_oop": "KcJh:2414,KcTs:2415,KsTs:2415,KsTh:2415,…", "hand_ranks_ip": "QcQh:313,QdQh:313,QdQs:313,QhQs:313,QcQs:313,…", "hand_ranks_oop": "Ad2d:155,AdAc:311,AhAc:311,AhAd:311,AsAc:311,…", "node_id": "root/CHECK", "path_length": 1, "range_ip_new": "33:0.193023,44:0.216279,54s:0.65814,…", "range_ip_new_raw": "3c3d:0.193023,3c3h:0.193023,3c3s:0.193023,…", "range_ip_new_raw_before_normalization": "3c3d:0.166,3c3h:0.166,3c3s:0.166,3d3h:0.166,…", "range_oop_new": "33:0.245724,44:0.272975,54s:0.420008,…", "range_oop_new_raw": "3d3c:0.245857,3h3c:0.245847,3h3d:0.24586,…", "range_oop_new_raw_before_normalization": "3d3c:0.245843,3h3c:0.245833,3h3d:0.245845,…", "quota": {"used": 7, "limit": 100}}
fielddescription
range_oop_new / range_ip_newThe normalized updated range (class notation), used directly as the next street's oop_range / ip_range fed to the solver.
range_oop_new_raw / range_ip_new_rawThe intermediate value after bluff discount, not normalized (combo notation); use as needed.
range_oop_new_raw_before_normalization / range_ip_new_raw_before_normalizationThe raw value narrowed only along the action line, without bluff discount or normalization.
hand_ranks_oop / hand_ranks_ipHand strength ranking (combo:rank, smaller value is stronger).
hand_bottom_ranks_oop / hand_bottom_ranks_ipBottom-of-range ranking.
node_id / board / path_lengthThe echoed action line, board, and number of action-line steps.
bluff_discount_ratio / bluff_combos_ratioThe bluff discount parameters actually used this time.
quotaThis month's general quota usage (used / limit).

Possible errors

HTTPerrortrigger / how to fix
400missing_fieldMissing one of range_oop / range_ip / solver_results / node_id.
400bad_requestThe solver side rejected it (e.g. the node_id does not lead anywhere in the decision tree you supplied).

Download: request.json (~1MB, includes the decision tree)response.jsonassemble_solver_results.py (end-to-end script)

Flop projected range projected-range

POST https://pokerai.bet/v1/gto/flop/projected-range charges 1 general

Full parameter / response schema, and try it live → interactive reference.

Narrow the OOP/IP ranges along a flop action line to directly get the starting range that enters the turn. Supply the full spot (board/pot_type/positions) and one action line (node_id), and the platform assembles the decision tree on the server automatically and completes the range update, returning the same fields as range conversion, plus an echoed pot_type.

This is a convenience wrapper over /v1/gto/range: it spares you the manual steps of calling /v1/gto/flop/tree + per-node /v1/gto/flop/node to assemble solver_results. It only applies to flop action lines (the decision tree is assembled from this platform's presolved flop results); for turn→river etc. where you must bring your own decision tree, still use /v1/gto/range.

Request body

{
  "board": "2c2h2s",
  "pot_type": "SRP",
  "positions": { "hero": "UTG", "raiser": "UTG", "caller": "BTN" },
  "node_id": "root/BET_4",
  "normalize": true,
  "bluff_discount_ratio": 0.8,
  "bluff_combos_ratio": 0.5,
  "hero_position": "oop",
  "hero_hand": "AsKs",
  "partner_hands": ["Ac9c"]
}
fielddescription
boardRequired. The flop (unseparated string, same as other endpoints), e.g. "2c2h2s".
pot_typeRequired. The pot type, e.g. "SRP".
positionsRequired. { hero, raiser, caller } (same as flop); 3bet/limp spots may carry three_bettor / limper.
node_idOptional, default "root". The flop action line, using the api notation returned by /v1/gto/flop/tree (absolute bet amount in BB), e.g. "root/BET_4", "root/CHECK/BET_8/CALL".
normalizeOptional, default true. Whether to normalize the updated range.
bluff_discount_ratio / bluff_combos_ratioOptional, each in [0,1] (out of range → 400). bluff_discount_ratio weights the bottom-of-range bluff combos; bluff_combos_ratio is the fraction of the range treated as bluffs. Omit to use the server's turn/river defaults. Both echoed back.
hero_position / hero_handOptional card blocking. Set hero_position ("oop"/"ip") + hero_hand (e.g. "AsKs"): removes every combo containing one of Hero's cards from the villain's updated range (range_*_new_raw), and ensures Hero's own hand is present in Hero's own range. Both echoed back. Only range_*_new_raw is affected — hand_ranks / hand_bottom_ranks are board-filtered only.
partner_handsOptional array of 4-char combos (e.g. ["Ac9c"]), requires hero_position. Removes every combo containing one of those cards from the villain's range_*_new_raw — model known dead cards (folded hands, exposed cards). Input only (not echoed). Also supported on /v1/gto/turn/projected-range.
preflop_packOptional preflop pack selecting its corresponding Flop dataset; omit both selectors for 6max. Legacy Flop lookup fallback to 6max is unchanged when a selected pack lacks this spot. Node tokens retain the selected dataset; node requests have no pack override. When explicitly present, preflop_pack must be a non-empty string from this pack catalog, without trimming or case conversion. A valid effective legacy alias may accompany it only with the same value; conflicting selectors fail with 400 before consumption. Legacy-only requests retain their original omission, null/empty, coercion, errors, defaults and fallback behavior; these rules do not relax the strict cache or coverage inputs.

Call example

curl -s https://pokerai.bet/v1/gto/flop/projected-range -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" -d @projected_range_request.json

Response (200, all fields listed, long strings truncated)

{"board": ["2c", "2h", "2s"], "pot_type": "SRP", "node_id": "root/BET_4", "bluff_combos_ratio": 0.5, "bluff_discount_ratio": 0.8, "hero_position": "oop", "hero_hand": "AsKs", "hand_bottom_ranks_ip": "AhTh:2405,AsTs:2405,Ac9c:2406,Ad9d:2406,…", "hand_bottom_ranks_oop": "AhJs:2404,AsJc:2404,AsJd:2404,AsJh:2404,…", "hand_ranks_ip": "QcQd:313,QcQh:313,QcQs:313,QdQh:313,…", "hand_ranks_oop": "Ad2d:155,AdAc:311,AdAh:311,AdAs:311,…", "path_length": 1, "range_ip_new": "33:0.193023,44:0.216279,54s:0.65814,55:0.344186,…", "range_ip_new_raw": "3c3d:0.193023,3c3h:0.193023,3c3s:0.193023,3d3h:0.193023,…", "range_ip_new_raw_before_normalization": "3c3d:0.166,3c3h:0.166,3c3s:0.166,3d3h:0.166,…", "range_oop_new": "44:0.0120032,55:0.0422217,66:0.181192,77:0.327323,…", "range_oop_new_raw": "4s4c:0.0666554,4s4h:0.0666554,5d5c:0.005,5d5h:0.005,…", "range_oop_new_raw_before_normalization": "4s4c:0.011816,4s4h:0.011816,5s5c:0.0392591,5s5h:0.0392591,…", "quota": {"used": 7, "limit": 100}}
fielddescription
range_oop_new / range_ip_newThe normalized updated range (class notation), used directly as the next street's oop_range / ip_range fed to the solver.
range_oop_new_raw / range_ip_new_rawThe intermediate value after bluff discount, not normalized (combo notation); use as needed.
range_oop_new_raw_before_normalization / range_ip_new_raw_before_normalizationThe raw value narrowed only along the action line, without bluff discount or normalization.
hand_ranks_oop / hand_ranks_ipHand strength ranking (combo:rank, smaller value is stronger).
hand_bottom_ranks_oop / hand_bottom_ranks_ipBottom-of-range ranking.
node_id / board / pot_type / path_lengthThe echoed action line, board, pot type, and number of action-line steps.
bluff_discount_ratio / bluff_combos_ratioThe bluff discount parameters actually used this time.
quotaThis month's general quota usage (used / limit).

Possible errors

HTTPerrortrigger / how to fix
400invalid_board / invalid_positionsboard is not 3 cards, or positions.hero is invalid.
404no_solution (and a server errorType such as no_ranges / no_root_node)No presolved flop tree for this spot, or the node_id action line does not lead anywhere.

Download: request.jsonresponse.json

Turn projected range (turn→river) projected-range

POST https://pokerai.bet/v1/gto/turn/projected-range free

Full parameter / response schema, and try it live → interactive reference.

The turn→river version of the flop projected range, for a real-time turn solve. Narrow the ranges along a turn action line (including the street-closing CALL/CHECK) to directly get the starting range that enters the river. The entering-turn OOP/IP ranges are read from the solve's own config (the ranges it was scheduled with via /v1/gto/solver), so you only pass the solve handle solve + one node_id. Free (the solve was already charged via /v1/gto/solver), like /v1/gto/solver/tree; returns the same fields as range conversion.

Poll /v1/gto/solver/tree until spot_status = queryable first. For turn→river you don't assemble solver_results manually (the platform reads it from the solve and assembles it).

Request body

{
  "solve": "eyJ…",
  "node_id": "root/CHECK/BET 6.000000/CALL",
  "normalize": true,
  "bluff_discount_ratio": 0.8,
  "hero_position": "oop",
  "hero_hand": "AsKs"
}
fielddescription
solveRequired. The solve handle returned by /v1/gto/solver (a turn solve).
node_idRequired. A turn action line, may end in the street-closing CALL/CHECK. Solver node notation (with spaces), e.g. "root/CHECK/BET 6.000000/CALL" (from /v1/gto/solver/tree nodes).
normalizeOptional, default true. Whether to normalize the updated range.
bluff_discount_ratioOptional. Bluff discount (0..1).
hero_position / hero_handOptional card blocking: hero_position ("oop"/"ip") + hero_hand (e.g. "AsKs") removes every combo containing one of Hero's cards from the villain's updated range.
partner_handsOptional array of 4-char combos (e.g. ["Ac9c"]), requires hero_position. Removes every combo containing one of those cards from the villain's range_*_new_raw. Input only.

Call example

curl -s https://pokerai.bet/v1/gto/turn/projected-range -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" -d @turn_projected_range_request.json

Response (200, all fields listed, long strings truncated)

{"bluff_combos_ratio": 0.33, "bluff_discount_ratio": 1, "board": ["8d", "4h", "8s", "Qc"], "hand_bottom_ranks_ip": "TcTs:2943,TdTh:2943,TdTs:2943,9h9s:3020,…", "hand_bottom_ranks_oop": "AhKd:4646,AhKc:4646,AcKh:4646,JsTs:4746,…", "hand_ranks_ip": "Ac8c:2007,Ah8h:2007,KcKs:2645,KhKs:2645,…", "hand_ranks_oop": "8c8h:85,Ah8h:2007,Ac8c:2007,9c8c:2029,…", "node_id": "root/CHECK/BET 6.000000/CALL", "path_length": 3, "range_ip_new": "99:0.603064,A8s:0.5,AKs:0.70197,AQs:0.453337,…", "range_ip_new_raw": "9c9d:0.71487,9c9h:0.394271,9c9s:0.71487,…", "range_ip_new_raw_before_normalization": "9c9d:0.714699,9c9h:0.394176,9c9s:0.714699,…", "range_oop_new": "88:0.131148,98s:0.0902494,A8s:0.0344418,…", "range_oop_new_raw": "8c8h:0.777777,9c8c:0.185048,9h8h:0.17177,…", "range_oop_new_raw_before_normalization": "8c8h:0.418968,9c8c:0.0996806,9h8h:0.0925282,…"}
fielddescription
range_oop_new / range_ip_newThe normalized entering-river range (class notation), used directly as the river solve's oop_range / ip_range.
range_*_raw / range_*_raw_before_normalizationThe un-normalized / pre-discount intermediate values (combo notation).
hand_ranks_* / hand_bottom_ranks_*Hand strength ranking / bottom-of-range ranking (combo:rank, smaller is stronger).
node_id / board / path_lengthThe echoed action line, board (4 cards), and number of action-line steps.
bluff_discount_ratio / bluff_combos_ratioThe bluff discount parameters actually used this time.

Note: free, so the response has no quota field; and no pot_type (that is flop-only).

Possible errors / states

HTTPerror / statetrigger / how to fix
200{ "spot_status": "computing" }The solve has not converged yet — keep polling /v1/gto/solver/tree until queryable.
400missing_solve / missing_node_idMissing the solve handle or node_id.
410expiredThe solve expired (TTL) — reschedule via /v1/gto/solver.
502no_solution etc.Upstream solve error.

Download: request.jsonresponse.json

Node EVs solver

POST https://pokerai.bet/v1/gto/evs free

Full parameter / response schema, try it live → interactive reference.

Per-hand, per-action expected values at one node of a completed solve. Give the solve handle solve (from /v1/gto/solver) + a node_id (from /v1/gto/solver/tree); optional hand filters to one hand. Free (the solve was already charged). Poll /v1/gto/solver/tree until spot_status = queryable first.

Request body

{
  "solve": "eyJ0Ijoic2x2X3h4eXoi...(handle from /v1/gto/solver)",
  "node_id": "root",
  "hand": "2c2d"
}
fielddescription
solveRequired. The solve handle from /v1/gto/solver.
node_idRequired. A node from /v1/gto/solver/tree (solver notation, e.g. "root", "root/CHECK/BET 6.000000").
handOptional. Filter to one hand's EVs (e.g. "2c2d"); omit for all hands.

Response (200, each hand's EV array aligned with actions)

{"node_id": "root", "task_id": "slv_srp_…", "player": 1, "round": "FLOP", "actions": ["CHECK", "BET 4.000000", "BET 97.000000"], "evs": {"2c2d": [-0.826359, -0.792223, -1.643411], "2c2h": […], …}}
fielddescription
actionsThe node's actions in order; each hand's EV array aligns with this.
evsPer hand → array of each action's EV (bb). With hand given, evs is a single array for that hand.
player / round / node_id / task_idWhich player acts, the street, and the echoed node / solve id.

Note: free, so no quota field. Returns { "spot_status": "computing" } if the solve has not converged (poll /v1/gto/solver/tree).

Play a hand (full flow)

Stringing the endpoints together: one SRP hand (UTG opens, BTN calls), Hero = UTG. The curls below omit the auth header (same as Quickstart).

1) Preflop — should we open

POST /v1/gto/preflop
{ "hole_cards": "AdKd", "positions": { "hero": "UTG" },
  "preflop_actions": [ { "position": "SB", "action": "small blind", "amount": 0.5 }, { "position": "BB", "action": "big blind", "amount": 1 } ] }

Just the SB + BB posts (no raises) = Hero is the first to act (an opening spot). Returns the opening frequency and sizing.

2) Flop — flop strategy

Flop 2c2h2s. The flop is a decision tree, two steps: first fetch the tree, then use Hero's node token to fetch the strategy.

// 1) fetch the tree (no hole_cards needed)
POST /v1/gto/flop/tree
{ "board": "2c2h2s", "pot_type": "SRP",
  "positions": { "hero": "UTG", "raiser": "UTG", "caller": "BTN" } }
// → in nodes[], root (is_hero:true) carries a token

// 2) use root's token to fetch Hero strategy
POST /v1/gto/flop/node
{ "node": "<token of root>", "hole_cards": "AdKd" }

Hero's first decision = root; facing a bet / acting a second time → pick the corresponding is_hero:true node. See Flop decision tree.

3) Turn — real-time solve, range derived from the flop

The turn (e.g. 9d) needs a real-time solve, which requires both players' ranges entering the turn. Get them with the flop decision tree + range conversion:

  1. /v1/gto/flop/tree for the starting oop_range / ip_range and decision nodes.
  2. Along a flop action line (e.g. root/CHECK/BET_8/CALL), call /v1/gto/flop/node per node (without hole_cards) to fetch range_strategy and assemble solver_results — see the assemble_solver_results.py script in the range conversion section.
  3. /v1/gto/range updates along that line → range_oop_new / range_ip_new are the ranges entering the turn.
  4. Feed them to the solver (board with 4 cards), poll for the tree until queryable, then fetch the node:
    POST /v1/gto/solver
    { "board": "2c2h2s9d", "oop_range": "<OOP range entering turn>", "ip_range": "<IP range entering turn>",
      "pot": <turn pot>, "effective_stack": <turn effective stack>, "hero": "OOP" }

Already have your own range/spot? At step 3 give oop_range / ip_range directly and skip the derivation.

4) River — real-time solve

The river (board with 5 cards) is the same as the turn: you can solve it standalone (give the range entering the river directly), or use range conversion to update the turn action line once more to get the range entering the river and then feed it to the solver.

Poker engine / semantics API

Wraps pokerkit-plus (a superset of pokerkit 0.7.3): board/hand semantics, ranges & equity, eval/equity/ICM/notation, and game simulation. Reuses the same API key & quota — cheap endpoints charge the general bucket, Monte-Carlo endpoints the solve bucket. Base path /v1/pokerkit/*; card inputs are unseparated strings (AsKsQs), enums return {name,value}. Full per-endpoint params/schema & try-it-live → interactive reference; machine-readable spec → /openapi.en.json (combined GTO + pokerkit snapshot).

Board / hand semantics charges 1 general

Board (Hero-independent): /texture (wetness/connectivity/draws available), /nuts (nuts + tying combos), /category-combos, /board-report (texture+nuts). Hero: /hand-tier (made-hand tier), /draws, /outs, /blockers, /hand-report (texture+tier+draws+outs in one call).

Request fields (shared in this group)

fielddescription
boardRequired. 3/4/5 community cards, unseparated, e.g. "AsKsQs".
holeRequired for Hero endpoints (hand-tier / draws / outs / blockers / hand-report). 2 hole cards, e.g. "JhTh"; board endpoints (texture / nuts / category-combos / board-report) omit it.
hand_typeOptional, default StandardHighHand (v1 only; other types return 400).
deadOptional. Dead / removed cards (accepted by all endpoints in this group).

Texture charges 1 general

POST https://pokerai.bet/v1/pokerkit/texture — Board structure: wetness/connectivity/rank band/draw availability/suit shape. Full params / try it live →

{"board": "AsKsQs"}

{"result": {"cards": ["As", "Ks", "Qs"], "wetness": {"name": "WET", "value": "Wet"}, "connectivity": {"name": "HIGH", "value": "High"}, "rank_band": {"name": "HIGH", "value": "High"}, "straight_draw": {"name": "OPEN_ENDED", "value": "Open-ended"}, "flush_draw": {"name": "LIVE", "value": "Live"}, "are_two_tone": false, "are_monotone": true, "are_rainbow": false}}

Nuts charges 1 general

POST https://pokerai.bet/v1/pokerkit/nuts — Strongest makeable hand + all tying two-card combos (with is_royal / board_is_nuts). Full params / try it live →

{"board": "AsKsQs"}

{"result": {"hand": "TsJsKsQsAs", "combos": [{"cards": ["Ts", "Js"], "hand": "TsJsKsQsAs", "as_frozenset": ["Js", "Ts"]}], "candidate_count": 1176, "board_is_nuts": false, "is_royal": true, "label": {"name": "STRAIGHT_FLUSH", "value": "Straight flush"}}}

Category combos charges 1 general

POST https://pokerai.bet/v1/pokerkit/category-combos — Every live two-card combo grouped by made category. Full params / try it live →

{"board": "AsKsQs"}

{"result": {"by_category": {"HIGH_CARD": [{"cards": ["2c", "3c"], "hand": "2c3cKsQsAs", "as_frozenset": ["2c", "3c"]}, {"cards": ["2c", "3d"], "hand": "2c3dKsQsAs", "as_frozenset": ["2c", "3d"]}], …}}}

Board report charges 1 general

POST https://pokerai.bet/v1/pokerkit/board-report — texture + nuts in one call (board overview). Full params / try it live →

{"board": "AsKsQs"}

{"result": {"texture": {"cards": ["As", "Ks", "Qs"], "wetness": {"name": "WET", "value": "Wet"}, "connectivity": {"name": "HIGH", "value": "High"}, "rank_band": {"name": "HIGH", "value": "High"}, "straight_draw": {"name": "OPEN_ENDED", "value": "Open-ended"}, "flush_draw": {"name": "LIVE", "value": "Live"}, "are_two_tone": false, "are_monotone": true, "are_rainbow": false}, "nuts": {"hand": "TsJsKsQsAs", "combos": [{"cards": ["Ts", "Js"], "hand": "TsJsKsQsAs", "as_frozenset": ["Js", "Ts"]}], "candidate_count": 1176, "board_is_nuts": false, "is_royal": true, "label": {"name": "STRAIGHT_FLUSH", "value": "Straight flush"}}}}

Hand tier charges 1 general

POST https://pokerai.bet/v1/pokerkit/hand-tier — Hero made-hand tier (pair / two-pair / trips / kicker tiers, is_nut). Full params / try it live →

{"hole": "JhTh", "board": "AsKsQs"}

{"result": {"category": {"name": "STRAIGHT", "value": "Straight"}, "is_nut": false, "pair_tier": null, "two_pair_tier": null, "three_of_a_kind_tier": null, "kicker_tier": null, "nut_rank": {"name": "NON_NUT", "value": "Non-nut"}}}

Draws charges 1 general

POST https://pokerai.bet/v1/pokerkit/draws — Hero draws (straight / flush draw, nut rank). Full params / try it live →

{"hole": "Ah5h", "board": "Kh7h2c"}

{"result": {"straight_draw": null, "flush_draw": {"name": "LIVE", "value": "Live"}, "nut_rank": {"name": "NUT", "value": "Nut"}}}

Outs charges 1 general

POST https://pokerai.bet/v1/pokerkit/outs — Hero outs that upgrade the made category, grouped + count. Full params / try it live →

{"hole": "Ah5h", "board": "Kh7h2c"}

{"result": {"by_category": {"ONE_PAIR": ["2d", "2s", "5c", "5d", "5s", "7c", "7d", "7s", "Kc", "Kd", "Ks", "Ac", "Ad", "As"], "FLUSH": ["2h", "3h", "4h", "6h", "8h", "9h", "Th", "Jh", "Qh"]}, "count": 23}}

Blockers charges 1 general

POST https://pokerai.bet/v1/pokerkit/blockers — how many nut combos Hero blocks (blocker cards / fraction). Full params / try it live →

{"hole": "AhAd", "board": "AsKsQs"}

{"result": {"nut_combos_total": 1, "nut_combos_blocked": 0, "blocker_cards": [], "block_fraction": 0.0, "blocks_nuts": false}}

Hand report charges 1 general

POST https://pokerai.bet/v1/pokerkit/hand-report — texture + tier + draws + outs in one call (Hero overview, flagship). Full params / try it live →

{"hole": "JhTh", "board": "AsKsQs"}

{"result": {"texture": {"cards": ["As", "Ks", "Qs"], "wetness": {"name": "WET", "value": "Wet"}, "connectivity": {"name": "HIGH", "value": "High"}, "rank_band": {"name": "HIGH", "value": "High"}, "straight_draw": {"name": "OPEN_ENDED", "value": "Open-ended"}, "flush_draw": {"name": "LIVE", "value": "Live"}, "are_two_tone": false, "are_monotone": true, "are_rainbow": false}, "tier": {"category": {"name": "STRAIGHT", "value": "Straight"}, "is_nut": false, "pair_tier": null, "two_pair_tier": null, "three_of_a_kind_tier": null, "kicker_tier": null, "nut_rank": {"name": "NON_NUT", "value": "Non-nut"}}, "draws": {"straight_draw": null, "flush_draw": null, "nut_rank": null}, "outs": {"by_category": {}, "count": 0}}}

Ranges / equity charges 1 general

/range/expand (notation → concrete combos), /range/value (value range by made-category floor; aggression ∈ NO_BET/SINGLE_BET/RAISED), /range/nut-advantage (exact nut share, no sampling).

Request fields (shared in this group)

fielddescription
notation(expand) range-notation array, e.g. ["AA","KQs","QQ+"].
hero / villain(nut-advantage) one range-notation array each.
boardCommunity cards (required for value / nut-advantage; expand omits it).
aggression(value) NO_BET / SINGLE_BET / RAISED sets the category floor; or floor to set it explicitly.

Range expand charges 1 general

POST https://pokerai.bet/v1/pokerkit/range/expand — Expand range notation into concrete two-card combos. Full params / try it live →

{"notation": ["AA", "KQs"]}

{"result": [["Ac", "Ad"], ["Ac", "Ah"], ["Ac", "As"], ["Ad", "Ah"], ["Ad", "As"], ["Ah", "As"], ["Kc", "Qc"], ["Kd", "Qd"], ["Kh", "Qh"], ["Ks", "Qs"]]}

Range value charges 1 general

POST https://pokerai.bet/v1/pokerkit/range/value — Build a value range by made-category floor (aggression). Full params / try it live →

{"board": "AsKsQs", "aggression": "SINGLE_BET"}

{"result": [["2s", "3s"], ["2s", "4s"], ["2s", "5s"], ["2s", "6s"], ["2s", "7s"], ["2s", "8s"], …]}

Range nut-advantage charges 1 general

POST https://pokerai.bet/v1/pokerkit/range/nut-advantage — Exact nut-share split by combo count (no sampling, deterministic). Full params / try it live →

{"hero": ["AA", "KK"], "villain": ["QQ", "JJ"], "board": "AsKsQs"}

{"result": {"hero_share": 0.5, "villain_share": 0.5, "basis": {"name": "NUT_SHARE", "value": "Nut share"}}}

Eval · equity · ICM · notation

charges 1 general /eval/hand, /eval/compare (rank + ties), /icm (deterministic), /notation/parse (.phh → structured). charges 1 solve Monte-Carlo: /equity, /hand-strength, /range/equity-advantage — with sample_count (capped) and seed (reproducible, ~2s@10k).

Request fields (shared in this group)

Monte-Carlo endpoints (equity / hand-strength / range/equity-advantage) charge the solve bucket; the rest charge general.

fielddescription
hole / holdings / boardEval inputs: single hole + board (eval/hand), or multi-hand holdings (2+) + board (eval/compare).
ranges / hole_range / hero / villainRange notation (equity / hand-strength / range/equity-advantage).
sample_count / seedMonte-Carlo: sample count (capped; over the cap clamps) / RNG seed (reproducible).
payouts / chips(icm) payout structure / per-player chips.
text(notation/parse) a .phh hand-history string.

Eval hand charges 1 general

POST https://pokerai.bet/v1/pokerkit/eval/hand — Evaluate hole + board into a made hand (5 cards + category label). Full params / try it live →

{"hole": "JhTh", "board": "AsKsQs"}

{"result": {"hand": "JhThAsKsQs", "label": {"name": "STRAIGHT", "value": "Straight"}}}

Eval compare charges 1 general

POST https://pokerai.bet/v1/pokerkit/eval/compare — Rank 2+ holdings on a board (with ties). Full params / try it live →

{"holdings": ["AcAd", "KsKh", "JhTh"], "board": "AsKsQs"}

{"result": [{"index": 2, "hole": "JhTh", "hand": "JhThAsKsQs", "rank": 1, "label": {"name": "STRAIGHT", "value": "Straight"}}, {"index": 0, "hole": "AcAd", "hand": "AcAdAsKsQs", "rank": 2, "label": {"name": "THREE_OF_A_KIND", "value": "Three of a kind"}}, {"index": 1, "hole": "KsKh", "hand": "KsKhAsKsQs", "rank": 3, "label": {"name": "THREE_OF_A_KIND", "value": "Three of a kind"}}]}

Equity charges 1 solve

POST https://pokerai.bet/v1/pokerkit/equity — Equity of multiple ranges on a board (Monte-Carlo). Full params / try it live →

{"ranges": [["AA"], ["KK"]], "board": "", "sample_count": 2000, "seed": 7}

{"result": {"equities": [0.8235, 0.1765], "sample_count": 2000}}

Hand strength charges 1 solve

POST https://pokerai.bet/v1/pokerkit/hand-strength — Hero win fraction vs N players (Monte-Carlo). Full params / try it live →

{"hole_range": ["AhKh"], "board": "Qh7c2d", "player_count": 3, "sample_count": 2000, "seed": 7}

{"result": {"hand_strength": 0.3945, "player_count": 3, "sample_count": 2000}}

ICM charges 1 general

POST https://pokerai.bet/v1/pokerkit/icm — ICM equity split from chips / payouts (deterministic). Full params / try it live →

{"payouts": [50, 30, 20], "chips": [5000, 3000, 2000]}

{"result": {"icm": [38.392857142857146, 32.75, 28.857142857142854]}}

Range equity-advantage charges 1 solve

POST https://pokerai.bet/v1/pokerkit/range/equity-advantage — Equity-share split between two ranges (Monte-Carlo). Full params / try it live →

{"hero": ["AA", "KK"], "villain": ["QQ", "JJ"], "board": "AsKsQs", "sample_count": 2000, "seed": 7}

{"result": {"hero_share": 0.80325, "villain_share": 0.19675, "basis": {"name": "EQUITY", "value": "Equity"}, "sample_count": 2000}}

Notation parse charges 1 general

POST https://pokerai.bet/v1/pokerkit/notation/parse — Parse a .phh hand history into structured config (variant / blinds / stacks / actions…). Full params / try it live →

{"text": "variant = \"NT\"\nante_trimming_status = true\nantes = [0, 0]\nblinds_or_straddles = [1, 2]\nmin_bet = 2\nstarting_stacks = [200, 200]\nactions = [\"d dh p1 AhKh\", \"d dh p2 QsQd\", \"p1 cbr 6\", \"p2 cc\", \"d db Qh7c2d\"]\n"}

{"result": {"variant": "NT", "ante_trimming_status": true, "antes": [0, 0], "blinds_or_straddles": [1, 2], "bring_in": null, "small_bet": null, "big_bet": null, "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p1 cbr 6", "p2 cc", "d db Qh7c2d"], "automations": [{"name": "ANTE_POSTING", "value": "Ante posting"}, …], "author": null, "event": null, "day": null, "month": null, "year": null, "hand": null, "currency": null}}

Game simulation charges 1 general

Full-information, stateless replay: the client carries the action list, the server rebuilds the state with pokerkit (zero server state). /games/state (current-spot snapshot), /games/step (apply next_action; expected_action_count is an optimistic-concurrency token, mismatch → 409), /notation/replay (config or .phh text → per-step snapshots), /cards/normalize (validate/normalize a card string).

Request fields (shared in this group)

fielddescription
variantRequired. Variant code, e.g. "NT" (no-limit hold'em); full list at /v1/pokerkit/meta.
antes / starting_stacksRequired. Per-player antes / starting stacks (integer arrays).
blinds_or_straddles / min_betBlinds / straddles; min_bet required for no-limit / pot-limit (fixed-limit / stud use small_bet / big_bet / bring_in).
actionsAction list so far (pokerkit notation: d dh p1 AhKh deal hole, p2 cbr 6 raise to 6, p1 cc check/call, p1 f fold).
next_action / expected_action_count(step) action to apply / concurrency token (= length of the list you extend; mismatch → 409).
text / index(replay) a .phh text instead; index returns just that step. cards/normalize takes only cards (a card string).

Games state charges 1 general

POST https://pokerai.bet/v1/pokerkit/games/state — Action list → current-spot snapshot (all hole cards shown). Full params / try it live →

{"variant": "NT", "antes": [0, 0], "blinds_or_straddles": [1, 2], "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6"]}

{"result": {"snapshot": {"terminal": false, "street_index": 0, "actor_index": 0, "pot": 8, "bets": [2, 6], "stacks": [198, 194], "board": [], "hole_cards": [{"player": 0, "cards": ["Ah", "Kh"]}, {"player": 1, "cards": ["Qs", "Qd"]}], "legal_actions": [{"action": "fold"}, {"action": "check_or_call", "amount": 4}, {"action": "complete_bet_or_raise_to", "min": 10, "max": 200}]}, "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6"]}}

Games step charges 1 general

POST https://pokerai.bet/v1/pokerkit/games/step — Apply next_action → new snapshot (concurrency token; 409 on mismatch). Full params / try it live →

{"variant": "NT", "antes": [0, 0], "blinds_or_straddles": [1, 2], "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6"], "next_action": "p1 cc", "expected_action_count": 3}

{"result": {"snapshot": {"terminal": false, "street_index": 1, "actor_index": null, "pot": 12, "bets": [0, 0], "stacks": [194, 194], "board": [], "hole_cards": [{"player": 0, "cards": ["Ah", "Kh"]}, {"player": 1, "cards": ["Qs", "Qd"]}], "legal_actions": [{"action": "deal_board"}]}, "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6", "p1 cc"]}}

Notation replay charges 1 general

POST https://pokerai.bet/v1/pokerkit/notation/replay — config or .phh → per-step snapshots (optional index for a single step). Full params / try it live →

{"variant": "NT", "antes": [0, 0], "blinds_or_straddles": [1, 2], "min_bet": 2, "starting_stacks": [200, 200], "actions": ["d dh p1 AhKh", "d dh p2 QsQd", "p2 cbr 6", "p1 f"], "index": 2}

{"result": {"snapshot": {"terminal": false, "street_index": 0, "actor_index": 1, "pot": 3, "bets": [2, 1], "stacks": [198, 199], "board": [], "hole_cards": [{"player": 0, "cards": ["Ah", "Kh"]}, {"player": 1, "cards": ["Qs", "Qd"]}], "legal_actions": [{"action": "fold"}, {"action": "check_or_call", "amount": 1}, {"action": "complete_bet_or_raise_to", "min": 4, "max": 200}]}, "step_count": 5}}

Cards normalize charges 1 general

POST https://pokerai.bet/v1/pokerkit/cards/normalize — Validate / normalize a card string to standard 2-char cards. Full params / try it live →

{"cards": "Ah Ks Qs"}

{"result": ["Ah", "Ks", "Qs"]}

Also GET /v1/pokerkit/meta (versions / variant codes / hand types / enum vocabularies). Full parameter schema and try-it-live for every endpoint → interactive reference (browse both APIs from the top).

All example downloads

A summary of each endpoint's complete request/response (real data, no fields omitted) is in the "Download" of each section above, or: preflop · flop tree · flop node · solver · range · projected range · projected range response · assemble script.

Versioning & changelog

Versioning policy

  • The /v1 in the path is the major version. Breaking changes (removing/changing fields, changing semantics) go to a new major version /v2, and /v1 stays available.
  • Backward-compatible additions (new endpoints, new optional fields, new response fields) are added directly to /v1 without separate notice — please parse by "ignoring unknown fields" and do not strictly allowlist-validate response fields.
  • Field deprecation will be flagged in the changelog below ahead of time, and removed only after a transition period.

Changelog

datechange
2026-11-18

Cache metric endpoints — available in production since 2026-11-18. Cache EV/EQ endpoints are available in production since 2026-11-18. POST /v1/gto/postflop/cache/ev and /eq accept only a returned action token and concrete hole_cards. On /query, include_ev:true or include_eq:true returns 400 invalid_request before Auth validation, consumption or Native dispatch; omission/false remains ordinary query behavior. Each admitted independent EV/EQ request consumes 1 existing cache unit, including hit/join, and every admitted success carries that caller's cache_quota. Pre-admission inapplicable/unsupported missing consumes 0; after confirmation, failure, timeout or cancellation can still be charged. 503 cache_charge_unknown carries no quota and is not automatically retried; exhaustion returns 402 cache_quota_exceeded. The retained local-isolated capture is deployed:false, not a production three-street success or real-billing capture.

2026-11-17

Cache EV/EQ endpoint migration is source-verified and pending deployment. Current production still uses the historical include_ev/include_eq query flags. In the future Relay release, true flags will return 400 invalid_request before validation, consumption or Native dispatch; omission/false remains an ordinary query. Use POST /v1/gto/postflop/cache/ev or /eq with only a returned action token and concrete hole_cards. Each admitted independent EV/EQ request consumes 1 existing cache unit, including hit/join; every admitted successful response carries that caller’s cache_quota. Pre-admission inapplicable or unsupported missing consumes 0; 503 cache_charge_unknown carries no quota and is not automatically retried. EV is raw_net_bb; EQ is root_range_joint, not a posterior. The verified 16-request, single-UID, 200NL 3BET replay is local-isolated/Auth-stub evidence, not production or customer charging.

Optional postflop cache EQ is live. Optional cache EQ is available in production since 2026-11-17. Display strategy first, then send include_eq=true with a returned action token and concrete hole_cards; it is mutually exclusive with EV. The ratio uses the effective cached Flop root opponent range, not a range conditioned on later actions. Node EQ reads are free; root and each Turn/River selection retain their existing charges. The original complete three-street examples remain local-isolated, not production captures.

Builder production success requests, responses and timings are now published; this is documentation of the existing release, not a new SDK or API release. Production examples: Docs · JSON · Python · JavaScript

Postflop cache EV/EQ budget is 15 seconds. Native single EV/EQ calculations have a 15-second hard cap and a 14,900ms soft budget. Service reads remain capped at 15 seconds and Relay requests at 20 seconds. Actual work can end sooner for the remaining deadline and cleanup reserve; these are implementation budgets, not a universal SLA. Linux processes remain limited to 2 GiB. Existing root/deal charges, free metric-node reads, fixed token TTL, mutually exclusive flags, and EV/EQ semantics are unchanged.

2026-11-16

Optional postflop cache EV is live. Optional cache EV is available in production since 2026-11-16. Query and display strategy first, then request include_ev=true with a returned action token and concrete hole_cards. The EV request waits within its budget. Existing root and card selection charges apply; token continuation does not consume cache quota. The examples remain local-isolated, not production captures.

2026-11-14

Persistent postflop cache query is live. Available in production since 2026-11-12. POST /v1/gto/postflop/cache/query queries preset or complete custom persistent caches. Follow returned token values through actions and use turn_card / river_card to cross streets. Only active API Builder/Pro subscriptions are eligible. An independent subscription-period quota applies: a root, each Turn, and each River selection each cost 1; ordinary reads with a valid token are free. Cache coverage may be incomplete.

Free preset-cache coverage is live. Available in production since 2026-11-13: GET /v1/gto/postflop/cache/coverage discovers published preset roots. Any valid API key, including Starter and exhausted accounts, can browse for free: no presolved, solve or cache quota is consumed. Strategy query still requires API Builder/Pro and follows the existing charges. No SDK or MCP package release is claimed. Every page requires board and a pack selection: preflop_pack, or its original flop_version input alias. Preserve the original board spelling and pack filters. Continue through empty items until next_cursor=null; limit defaults to 50 (1–200). The opaque cursor is not a strategy token; as_of is a page observation time, not a cross-page snapshot. Coverage does not guarantee that every listed cache can be read.

preflop_pack field migration is live. The public standard input is preflop_pack; an invalid explicit value never falls back to a legacy selector or default. Field migration available in production since 2026-11-13. Optional preflop pack for the chart. Omit both selectors for the platform default (6max). When explicitly present, preflop_pack must be a non-empty string from this pack catalog, without trimming or case conversion. A valid effective legacy alias may accompany it only with the same value; conflicting selectors fail with 400 before consumption. Legacy-only requests retain their original omission, null/empty, coercion, errors, defaults and fallback behavior; these rules do not relax the strict cache or coverage inputs. With preflop_pack=A, the chart uses A and an enabled guarantee also uses A. Legacy-only preflop_version=A and flop_version=B remain independent (each defaults to 6max): preflop_version=A alone with the flag true gives chart A / guarantee 6max, whereas preflop_pack=A gives A / A. Mixed inputs compare only effective synonymous selectors. When the flag is off, legacy flop_version is ignored even if invalid. The guarantee response publishes preflop_pack only; manifest_version is unchanged. Use preflop_pack inside request for type preflop or flop; the original type-specific legacy input alias remains accepted. requested_preflop_pack is the requested pack, resolved_preflop_pack is the actual hit (including fallback). Solver has no pack selector or echo. Old output names are not duplicated; old-input compatibility does not make old-output readers compatible. Input aliases only: preflop/preflop-range accept deprecated preflop_version; Flop tree/projected-range and cache preset accept deprecated flop_version; availability uses the alias of request.type inside request. Only those original entry points accept them. Solver, custom cache roots, node requests and App-specific /v1/apps/solver/ranges gain no pack override. Pure legacy server selectors preserve null/empty omission and coercion; strict cache/coverage parsing remains strict. Canonical preflop_pack errors use 400 invalid_request; legacy unsupported_preflop_version/unsupported_flop_version errors remain unchanged. The pack catalog still returns versions/id/default, and APIs without a pack echo gain none. Canonical output uses preflop_pack only; availability uses requested_preflop_pack and resolved_preflop_pack. Old input compatibility does not guarantee compatibility for readers of old output fields. URLs are unchanged.

Optional EV source has passed source acceptance but is not deployed. To show strategy first, query normally, then request include_ev=true with an action token and hole_cards; this request waits for calculation within its budget. Use response token, not the display node path. EV is raw_net_bb in bb from the quantized cached fixed strategy, not solver live EV or EQ times pot. First release supports proven preset non-ARP configurations; custom and unsupported configurations return missing. Values follow strategy order; zero and negative values are valid, missing is never zero-filled, and any missing action makes combo missing. status is ok, partial, or missing. Non-Hero action returns the existing view and empty action_values with missing/not_applicable. EV uses one slot per owner, busy returns 200 strategy plus missing without queue; normal reader busy is 429, request timeout 504, identity drift 409. The 10-second and 2-GiB implementation budgets are not a universal SLA. Omission or false retains old wire, billing and fixed token TTL.

2026-11-13Available in production since 2026-11-13: GET /v1/gto/postflop/cache/coverage discovers published preset roots. Any valid API key, including Starter and exhausted accounts, can browse for free: no presolved, solve or cache quota is consumed. Strategy query still requires API Builder/Pro and follows the existing charges. No SDK or MCP package release is claimed. The response contains only source, as_of, items and next_cursor; no cache_quota. items are complete preset root request bodies. The default hero is a legal OOP live seat and may be changed to the other live seat. Only next_cursor=null ends pagination: continue through an empty items page when its cursor is non-null. as_of is a page observation time, not a cross-page snapshot or TTL. Responses use Cache-Control: no-store.
2026-11-13The coverage endpoint and this preflop_pack input/output revision with required coverage filters are available in production since 2026-11-13. New coverage direct-HTTP examples are a 55-event local-isolated-http capture at Relay e0b96a4c34ef56dfb5b841588ed5a0d55cfcabb1, not a production capture. Existing historical strategy captures remain unchanged; no SDK/MCP release, new URL, strategy capability or quota change is claimed. Stable placeholders cannot be sent to the real API. The directory board 2c2d2h and the existing AhKhQh strategy workflow remain separate captures; no native strategy read is claimed. With preflop_pack=A, the chart uses A and an enabled guarantee also uses A. Legacy-only preflop_version=A and flop_version=B remain independent (each defaults to 6max): preflop_version=A alone with the flag true gives chart A / guarantee 6max, whereas preflop_pack=A gives A / A. Mixed inputs compare only effective synonymous selectors. When the flag is off, legacy flop_version is ignored even if invalid. The guarantee response publishes preflop_pack only; manifest_version is unchanged. Use preflop_pack inside request for type preflop or flop; the original type-specific legacy input alias remains accepted. requested_preflop_pack is the requested pack, resolved_preflop_pack is the actual hit (including fallback). Solver has no pack selector or echo. Old output names are not duplicated; old-input compatibility does not make old-output readers compatible. Every page requires board and a pack selection: use preflop_pack (recommended), or the deprecated flop_version alias instead. Neither pack parameter is individually mandatory, but at least one is required; if both occur once they must contain the same valid value. No all-pack or boardless browsing is available. board is exactly three distinct legal cards in six characters. Empty/invalid values, duplicate occurrences of the same key, unknown parameters and conflicting aliases return 400. Canonical and legacy pack spellings normalize to the same cursor filter. Only preflop_pack, flop_version, board, limit and cursor are accepted. limit defaults to 50, maximum 200, and must be a decimal integer 1–200 without leading zeroes, signs, fractions or exponents. Explicit packs never fall back. Input aliases only: preflop/preflop-range accept deprecated preflop_version; Flop tree/projected-range and cache preset accept deprecated flop_version; availability uses the alias of request.type inside request. Only those original entry points accept them. Solver, custom cache roots, node requests and App-specific /v1/apps/solver/ranges gain no pack override. Pure legacy server selectors preserve null/empty omission and coercion; strict cache/coverage parsing remains strict. Canonical preflop_pack errors use 400 invalid_request; legacy unsupported_preflop_version/unsupported_flop_version errors remain unchanged. The pack catalog still returns versions/id/default, and APIs without a pack echo gain none.
2026-11-12Source preparation, not deployed: GET /v1/gto/postflop/cache/coverage discovers published preset roots. Any valid API key, including Starter and exhausted accounts, can browse for free: no presolved, solve or cache quota is consumed. Strategy query still requires API Builder/Pro and follows the existing charges. No SDK or MCP package release is claimed. The response contains only source, as_of, items and next_cursor; no cache_quota. items are complete preset root request bodies. The default hero is a legal OOP live seat and may be changed to the other live seat. Only next_cursor=null ends pagination: continue through an empty items page when its cursor is non-null. as_of is a page observation time, not a cross-page snapshot or TTL. Responses use Cache-Control: no-store. Subsequently available in production since 2026-11-13.
2026-11-11Release preparation: POST /v1/gto/postflop/cache/query queries preset or complete custom persistent caches. Follow returned token values through actions and use turn_card / river_card to cross streets. Only active API Builder/Pro subscriptions are eligible. An independent subscription-period quota applies: a root, each Turn, and each River selection each cost 1; ordinary reads with a valid token are free. Cache coverage may be incomplete. Online availability depends on deployment. Subsequently available in production since 2026-11-12.
2026-09-14POST /v1/gto/availability is an authenticated, free preflight for a matching preflop, flop, or solver request. It returns a point-in-time availability snapshot without consuming quota; it does not reserve capacity or guarantee a later cache load or result request, which continues under its existing billing rules.
2026-08-27POST /v1/gto/flop/tree now returns ranges.requested, ranges.effective, ranges.adjusted, adjustment_summary, range_provenance, and optional hero_hand_coverage. Top-level ranges are the effective aliases used by the tree; requested ranges are audit-only. A removed hand must not continue to /flop/node, which returns typed HTTP 422 hand_not_in_effective_range. POST /v1/gto/preflop/range can return an optional offline immutable pruning guarantee; missing or incomplete coverage fails closed.
2026-07-22/v1/gto/solver now accepts independent raise_sizes, donk_sizes, and raise_limit fields in addition to bet_sizes.
2026-07-12Added POST /v1/gto/solver/release — release a solve's pool port early so it returns to the pool immediately instead of waiting out the cache TTL (optional, free; call after your last /solver/tree / /solver/node for that solve).
2026-07-04Added /v1/gto/evs (per-hand, per-action node EVs of a completed solve); /v1/gto/turn/projected-range now also supports partner_hands.
2026-07-04/v1/gto/flop/projected-range now honors bluff_discount_ratio / bluff_combos_ratio from the request, injects Hero's own hand into Hero's range, and adds partner_hands (block partner dead cards from the villain range).
2026-06-22Added the Poker engine / semantics API /v1/pokerkit/* (board/hand semantics, ranges/equity, eval/equity/ICM/notation, game simulation; same key & quota). See below.
2026-06-22Added /v1/gto/preflop/range (the whole 13×13 preflop range, 169 hands in one call).
2026-06-18Split flop: removed the single-query /v1/gto/flop, replaced by /v1/gto/flop/tree (fetch tree) + /v1/gto/flop/node (fetch node, free), aligned with the solver's tree/node.
2026-06-17Added /v1/gto/flop/projected-range (a convenience wrapper over /v1/gto/range: supply the full flop spot + action line, the server assembles the decision tree automatically and returns the turn range directly).
2026-06-17Unified board / hand format: input is an unseparated string, response board is always returned as an array.
2026-06-17Added the OpenAPI 3.0 spec; added range-notation / concepts / full-flow tutorial docs.
2026-06-17/v1/gto/solver now supports real-time flop solving (board=3); bet_sizes.flop can customize the flop bet sizes.
2026-06-17Fix: flop-query raise amount_bb was wrongly 0 (now returns the correct absolute BB).
2026-06-17Added range conversion /v1/gto/range; /flop/tree exposes the starting oop_range / ip_range; /flop and /solver/node return the full range strategy when hole_cards is not passed.
2026-06-16Added the turn / river real-time solver /v1/gto/solver family (separate solve quota); added the flop decision tree /v1/gto/flop/tree.
2026-06-15Removed the recommendation field from all responses — please choose actions yourself based on frequency.

pokerai.bet · GTO API v1

Cache API

The strategy endpoint has been available in production since 2026-11-12, Coverage since 2026-11-13, and the independent EV and EQ endpoints since 2026-11-18. Use Coverage to find a published preset, Strategy to read and navigate it, and EV or EQ to evaluate a specific hand at a returned action node.

Coverage

GET https://pokerai.bet/v1/gto/postflop/cache/coverage

Interactive reference

0 Cache quota

Call example

curl -sS --get https://pokerai.bet/v1/gto/postflop/cache/coverage \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  --data-urlencode "preflop_pack=6max" \
  --data-urlencode "board=2c2d2h"

Available in production since 2026-11-13: GET /v1/gto/postflop/cache/coverage discovers published preset roots. Any valid API key, including Starter and exhausted accounts, can browse for free: no presolved, solve or cache quota is consumed. Strategy query still requires API Builder/Pro and follows the existing charges. No SDK or MCP package release is claimed.

Parameters

Every page requires board and a pack selection: use preflop_pack (recommended), or the deprecated flop_version alias instead. Neither pack parameter is individually mandatory, but at least one is required; if both occur once they must contain the same valid value. No all-pack or boardless browsing is available. board is exactly three distinct legal cards in six characters. Empty/invalid values, duplicate occurrences of the same key, unknown parameters and conflicting aliases return 400. Canonical and legacy pack spellings normalize to the same cursor filter. Only preflop_pack, flop_version, board, limit and cursor are accepted. limit defaults to 50, maximum 200, and must be a decimal integer 1–200 without leading zeroes, signs, fractions or exponents. Explicit packs never fall back. Service returns a canonical board representative, not every suit-isomorphic spelling; query applies the existing suit mapping. Preserve the original request board spelling on every page even when items return a canonical board.

cursor is private, bound to the account, purpose and filters, at most 4 KiB, with a fixed one-hour lifetime that does not renew. It is not a strategy node token. Keep the original board spelling and every explicit filter on later pages; reordering cards or changing an isomorphic spelling requires a new first page. limit may change. Old cursors with a null pack or board filter cannot be filled in; restart the first page.

Response and errors

The response contains only source, as_of, items and next_cursor; no cache_quota. items[].preflop_pack is canonical; no flop_version output is duplicated. items are complete preset root request bodies. The default hero is a legal OOP live seat and may be changed to the other live seat. Only next_cursor=null ends pagination: continue through an empty items page when its cursor is non-null. as_of is a page observation time, not a cross-page snapshot or TTL. Responses use Cache-Control: no-store.

HTTP errors: 400 invalid_request; 401 missing_api_key/invalid_api_key; 403 ip_blocked; 429 normal platform rate limiting; 502 auth_unavailable; 503 cache_unavailable; 504 cache_timeout. An unavailable dependency is an error, never a successful empty directory. No response exposes internal IDs, internal continuation keys/after or credentials. The public next_cursor remains an opaque continuation token; published captures replace it with a stable placeholder. Responses omit cache_quota.

Full response (local-isolated)

The coverage endpoint and this preflop_pack input/output revision with required coverage filters are available in production since 2026-11-13. New coverage direct-HTTP examples are a 55-event local-isolated-http capture at Relay e0b96a4c34ef56dfb5b841588ed5a0d55cfcabb1, not a production capture. Existing historical strategy captures remain unchanged; no SDK/MCP release, new URL, strategy capability or quota change is claimed. Stable <cursor:N> placeholders cannot be sent to the real API. The directory board 2c2d2h and the existing AhKhQh strategy workflow remain separate captures; no native strategy read is claimed.

{
  "source": "persistent_cache",
  "as_of": "2026-11-13T12:00:06.563Z",
  "items": [
    {
      "preflop_pack": "6max",
      "board": "2c2d2h",
      "pot_type": "4BET",
      "positions": {
        "raiser": "UTG",
        "three_bettor": "MP",
        "hero": "UTG"
      }
    }
  ],
  "next_cursor": "<cursor:1>"
}

The directory lists published roots locatable by preset metadata. It does not probe each native reader or guarantee a total, percentage, immediate readability or complete Turn/River coverage. A later query may miss or change and still follows its original billing rules. Choose one item explicitly after free discovery, then send that original body once to POST /v1/gto/postflop/cache/query. Do not query every item inside the pagination loop or automatically retry paid requests.

Find a preset and query it
curl -sS --get https://pokerai.bet/v1/gto/postflop/cache/coverage \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  --data-urlencode "preflop_pack=6max" \
  --data-urlencode "board=2c2d2h" \
  --data-urlencode "limit=50"
# Follow every next_cursor with the same explicit filters; only null ends paging.
# Then explicitly choose one item as selected-item.json (Builder/Pro, paid once):
curl -sS https://pokerai.bet/v1/gto/postflop/cache/query \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" --data-binary @selected-item.json
Python · HTTP
#!/usr/bin/env python3
"""Direct HTTP. Free discovery first; optionally query one explicitly selected item.
Run: POKERAI_API_KEY=... python3 postflop_cache_coverage_discover.py [item-index]
Without an index, only the free directory is read. No paid retries or SDK methods.
Optional POKERAI_BASE_URL selects a controlled loopback replay host.
Example source: local-isolated-http, not a production capture. Board 2c2d2h is
separate from the existing AhKhQh Flop -> Turn -> River strategy capture.
"""
import json
import os
import sys
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = os.environ.get("POKERAI_BASE_URL", "https://pokerai.bet").rstrip("/")
KEY = os.environ["POKERAI_API_KEY"]


def discover(filters=None):
    # Preserve original board spelling and explicit filters on every page.
    params = dict({"preflop_pack": "6max", "board": "2c2d2h"} if filters is None else filters)
    params.setdefault("limit", 50)
    items = []
    while True:
        request = Request(BASE + "/v1/gto/postflop/cache/coverage?" + urlencode(params),
                          headers={"Authorization": "Bearer " + KEY})
        with urlopen(request, timeout=25) as response:
            page = json.load(response)
        items.extend(page["items"])
        if page["next_cursor"] is None:
            return items
        # An empty items page with a cursor is not the end.
        params["cursor"] = page["next_cursor"]


def query_selected(item):
    # One paid root request, outside discovery. Builder/Pro and normal charges apply.
    request = Request(BASE + "/v1/gto/postflop/cache/query",
                      data=json.dumps(item).encode(),
                      headers={"Authorization": "Bearer " + KEY,
                               "Content-Type": "application/json"}, method="POST")
    with urlopen(request, timeout=25) as response:
        return json.load(response)


if __name__ == "__main__":
    items = discover()
    print(json.dumps({"items": items}))
    if len(sys.argv) > 1:
        print(json.dumps(query_selected(items[int(sys.argv[1])])) )
    # For returned-node navigation, use the existing postflop_cache_workflow.py
    # and /docs#postflop-cache; its AhKhQh capture is a separate example.
JavaScript · HTTP
#!/usr/bin/env node
// Direct HTTP: free discovery, then optionally one explicitly selected paid root.
// POKERAI_API_KEY=... node postflop_cache_coverage_discover.js [item-index]
// No index means free discovery only. No SDK assumptions or automatic paid retries.
// Example source: local-isolated-http, not a production capture. The 2c2d2h directory and
// existing AhKhQh Flop -> Turn -> River capture are separate evidence.
import { pathToFileURL } from 'node:url';
import { realpathSync } from 'node:fs';
const base = (process.env.POKERAI_BASE_URL || 'https://pokerai.bet').replace(/\/$/, '');
const key = process.env.POKERAI_API_KEY;

async function request(path, body) {
  const response = await fetch(base + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: `Bearer ${key}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    signal: AbortSignal.timeout(25000),
  });
  const value = await response.json();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${JSON.stringify(value)}`);
  return value;
}

export async function discover(filters = { preflop_pack: '6max', board: '2c2d2h' }) {
  // Retain original board spelling and every explicit filter across pages.
  const params = new URLSearchParams({ limit: '50', ...filters });
  const items = [];
  while (true) {
    const page = await request('/v1/gto/postflop/cache/coverage?' + params);
    items.push(...page.items);
    if (page.next_cursor === null) return items;
    // An empty intermediate page must still continue.
    params.set('cursor', page.next_cursor);
  }
}

export async function querySelected(item) {
  // One paid root, outside pagination; Builder/Pro and existing charges apply.
  return request('/v1/gto/postflop/cache/query', item);
}

if (import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
  const items = await discover();
  console.log(JSON.stringify({ items }));
  if (process.argv[2] !== undefined) console.log(JSON.stringify(await querySelected(items[Number(process.argv[2])])));
  // Reuse postflop_cache_workflow.js and /docs#postflop-cache for node navigation.
  // That AhKhQh source capture must not be presented as this directory's response.
}

JSON · Python · JavaScript · Postman · Flop → Turn → River

Strategy

POST https://pokerai.bet/v1/gto/postflop/cache/query

Interactive reference

Each admitted root or Turn/River card selection uses 1 Cache quota. Ordinary valid token reads use 0, including action continuation.

Call example

curl -sS "$POKERAI_BASE_URL/v1/gto/postflop/cache/query" \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"board":"AhKhQh","pot_type":"4BET","positions":{"hero":"UTG","raiser":"UTG","three_bettor":"MP"}}'

Parameters

Available in production since 2026-11-12. POST /v1/gto/postflop/cache/query reads exact persistent caches, without solving, approximation, downgrade or fallback. Cache coverage is not guaranteed. API Builder/Pro only (not App/Direct plans). Preset and complete custom roots both start from exactly three distinct Flop cards; four/five-card standalone roots, unknown fields, mixed roots/tokens and mode/type inputs are rejected. Preset fields reuse board, pot_type, positions, preflop_pack; version defaults to 6max, explicit versions never downgrade. SRP needs raiser/caller; 3BET/4BET need raiser/three_bettor; LIMP needs caller/checker, plus hero. Custom hero is OOP/IP; preset hero is a seat.

Input node is an opaque account-bound token, while output node is a display path: never parse, concatenate or construct a token. Select a cached action by its action/amount fields and use its returned child.token for a free node read. Finish Flop actions before sending the parent chance token with turn_card; finish Turn actions before sending its chance token with river_card. One immediately following card per request; no early/wrong-street/double selection. Chance previews are optional. Card children have no free token. Unlike /solver/tree, this token is one specific boundary, not a solve handle accepting an arbitrary runout. Tokens expire 60 minutes after root issuance (30-second clock tolerance); reads and selections never renew them.

Custom root parameters

Custom roots must include cache_config with schema_version=1, allin_threshold (0,10], complete solver_params (accuracy>0, max_iteration/print_interval integers≥1, use_isomorphism=0/1, skip_ratio=0..0.999999), and memory.trainable_precision=fp32/cum_fp16. Optional solver_backend=cpu/metal: omission is a distinct historical key, not the current backend or cpu. Optional pruning defaults to enabled:false with empty turn_cards/river_cards; explicit pruning supplies all three fields. Optional approx.adaptive_range_pruning is complete already-applied provenance, not a request to prune: applied:true, policy_version, policy=weight_then_hand_class, trigger=metal_cap_exceeded, original/effective_range_hash_oop/ip, removed_combo_pct_oop/ip, removed_weight_pct_oop/ip, max_removed_combo_pct/max_removed_weight_pct, preserve_suit_symmetry, protect_exact_combos, target_headroom and cap_gb, reason. Ratios are 0..1, target_headroom is (0,1], cap_gb>0; booleans and nonempty hashes/text are required. Ranges are the effective ranges; missing history cannot be guessed.

Common sizing uses a required bet_sizes object with optional streets; values are positive integer pot percentages. Flop default [50]; SPR≤10 gives Turn [33,67,120], River [33,75,150], otherwise [67,120] / [75,150]. Raises default to each street’s bets; OOP donks Turn [67], River [100]; both players receive allin rows. Empty bet lists are invalid; empty raise/donk lists disable them. raise_limit defaults to 3, allowed 1..4. Alternatively bet_sizes is complete per-player rows: player=oop/ip, round=flop/turn/river, type=bet/raise/donk with positive finite sizes, or type=allin without sizes. Unspecified rows are not added; explicit positive integer raise_limit is required, and raise_sizes/donk_sizes cannot be mixed. Range strings reuse class/exact-combo syntax with weights 0..1 (default 1). See the complete custom request and OpenAPI for the closed objects.

{
  "board": "AhKhQh",
  "oop_range": "JJ:0.75,TT:0.25",
  "ip_range": "AA:0.6,KK:0.4",
  "pot": 10.0,
  "effective_stack": 8.0,
  "hero": "OOP",
  "bet_sizes": [
    {
      "player": "oop",
      "round": "flop",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "oop",
      "round": "flop",
      "type": "raise",
      "sizes": [
        100
      ]
    },
    {
      "player": "oop",
      "round": "turn",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "oop",
      "round": "turn",
      "type": "raise",
      "sizes": [
        100
      ]
    },
    {
      "player": "oop",
      "round": "river",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "oop",
      "round": "river",
      "type": "raise",
      "sizes": [
        100
      ]
    },
    {
      "player": "ip",
      "round": "flop",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "ip",
      "round": "flop",
      "type": "raise",
      "sizes": [
        100
      ]
    },
    {
      "player": "ip",
      "round": "turn",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "ip",
      "round": "turn",
      "type": "raise",
      "sizes": [
        100
      ]
    },
    {
      "player": "ip",
      "round": "river",
      "type": "bet",
      "sizes": [
        33
      ]
    },
    {
      "player": "ip",
      "round": "river",
      "type": "raise",
      "sizes": [
        100
      ]
    }
  ],
  "cache_config": {
    "schema_version": 1,
    "allin_threshold": 0.67,
    "solver_params": {
      "accuracy": 0.001,
      "max_iteration": 2,
      "print_interval": 1,
      "use_isomorphism": 1,
      "skip_ratio": 0
    },
    "memory": {
      "trainable_precision": "fp32"
    },
    "solver_backend": "cpu"
  },
  "raise_limit": 2
}

Response and errors

HTTP 200 returns the strategy, range strategy, card choices or terminal context for the current node. A 404 indicates a cache miss, 409 a changed cache, and 410 an expired token. Paid misses or failures after a confirmed charge can still consume quota.

hole_cards applies only to the current request, with no inherited hand. A hero action plus hand returns strategy[] using StrategyItem mixed frequencies. Otherwise return the acting player’s actions[] + range_strategy + range_hand_count; actions have no frequency, matrix columns follow actions, count equals combos. Chance has cards without strategy; terminal/showdown/truncated have empty children. The dedicated EV and EQ endpoints return their respective metrics. amount_bb is BB, sizing_pot is pot-relative. Root pot/effective_stack come from frozen configuration; continuation responses commonly omit both. Never fill them with zero or treat root values as current remaining values.

Independent cache_quota, shared by an account’s keys, follows the subscription service period, not calendar month; it is separate from quota/solve_quota. Base Builder 2000 / Pro 20000; current-period multiplier 1/1.5/2 yields the limits below. Root, each Turn and each River consume 1; repeating the same selection consumes again. Admission rejections do not debit; a read miss or failure after consume still debits. Valid ordinary node/hand/chance reads are free even when exhausted or used exceeds limit, and successful free reads omit cache_quota. A balance, period or bonus snapshot cannot guarantee the next paid request. Use the current consume receipt; missing receipt/unknown commitment does not mean no debit. Do not automatically retry paid requests, solve or refund.

API1×1.5×2×
Builder200030004000
Pro200003000040000

cache_quota · HTTP errors and receipts · Flop → Turn → River · OpenAPI

Complete requests and corresponding responses

Controlled source: local-isolated-http, fixed Relay 938d04e708dc8bb5e47c38f330e3397d0851c102. This is not a production capture, deployment promise, or proof of all cache/ARP combinations. Every displayed response preserves the original frequencies, amounts, board and children; only opaque tokens use stable <TOKEN_NNN> placeholders. These placeholders cannot be sent to a real API. The downloadable JSON includes all 20 public responses and evidence metadata outside the responses. Python/JavaScript use environment API keys and dynamic returned tokens, with no SDK assumptions or automatic paid retries. The fixture path bets 3 BB, calls, checks twice, then selects 2d→2s; live data may differ and the example stops if its expected cached action is absent.

root · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "board": "AhKhQh",
  "pot_type": "4BET",
  "positions": {
    "hero": "UTG",
    "raiser": "UTG",
    "three_bettor": "MP"
  }
}

{
  "source": "persistent_cache",
  "node": "root",
  "token": "<TOKEN_001>",
  "node_type": "action",
  "street": "flop",
  "board": [
    "Ah",
    "Kh",
    "Qh"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/CHECK",
      "cached": true,
      "token": "<TOKEN_002>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000",
      "cached": true,
      "amount_bb": 3,
      "sizing_pot": 0.3,
      "allin": false,
      "token": "<TOKEN_003>"
    },
    {
      "action": "bet",
      "node": "root/BET 8.000000",
      "cached": true,
      "amount_bb": 8,
      "sizing_pot": 0.8,
      "allin": true,
      "token": "<TOKEN_004>"
    }
  ],
  "pot": 10,
  "effective_stack": 8,
  "is_hero": true,
  "actions": [
    {
      "action": "check"
    },
    {
      "action": "bet",
      "amount_bb": 3,
      "sizing_pot": 0.3,
      "allin": false
    },
    {
      "action": "bet",
      "amount_bb": 8,
      "sizing_pot": 0.8,
      "allin": true
    }
  ],
  "range_strategy": {
    "JcJd": [
      1,
      0,
      0
    ],
    "JcJh": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ],
    "JdJh": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ],
    "JcJs": [
      1,
      0,
      0
    ],
    "JdJs": [
      1,
      0,
      0
    ],
    "JhJs": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ],
    "TcTd": [
      1,
      0,
      0
    ],
    "TcTh": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ],
    "TdTh": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ],
    "TcTs": [
      1,
      0,
      0
    ],
    "TdTs": [
      1,
      0,
      0
    ],
    "ThTs": [
      0.05098039284348488,
      0,
      0.9490196108818054
    ]
  },
  "range_hand_count": 12,
  "cache_quota": {
    "used": 1,
    "limit": 2000
  }
}
flop-hand · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_001>",
  "hole_cards": "JdJc"
}

{
  "source": "persistent_cache",
  "node": "root",
  "token": "<TOKEN_005>",
  "node_type": "action",
  "street": "flop",
  "board": [
    "Ah",
    "Kh",
    "Qh"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/CHECK",
      "cached": true,
      "token": "<TOKEN_006>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000",
      "cached": true,
      "amount_bb": 3,
      "sizing_pot": 0.3,
      "allin": false,
      "token": "<TOKEN_007>"
    },
    {
      "action": "bet",
      "node": "root/BET 8.000000",
      "cached": true,
      "amount_bb": 8,
      "sizing_pot": 0.8,
      "allin": true,
      "token": "<TOKEN_008>"
    }
  ],
  "is_hero": true,
  "hole_cards": "JdJc",
  "strategy": [
    {
      "action": "check",
      "frequency": 1
    },
    {
      "action": "bet",
      "amount_bb": 3,
      "sizing_pot": 0.3,
      "allin": false,
      "frequency": 0
    },
    {
      "action": "bet",
      "amount_bb": 8,
      "sizing_pot": 0.8,
      "allin": true,
      "frequency": 0
    }
  ]
}
flop-opponent · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_003>"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000",
  "token": "<TOKEN_009>",
  "node_type": "action",
  "street": "flop",
  "board": [
    "Ah",
    "Kh",
    "Qh"
  ],
  "children": [
    {
      "action": "call",
      "node": "root/BET 3.000000/CALL",
      "cached": true,
      "token": "<TOKEN_010>"
    },
    {
      "action": "raise",
      "node": "root/BET 3.000000/RAISE 8.000000",
      "cached": true,
      "amount_bb": 8,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_011>"
    },
    {
      "action": "fold",
      "node": "root/BET 3.000000/FOLD",
      "cached": true,
      "token": "<TOKEN_012>"
    }
  ],
  "is_hero": false,
  "actions": [
    {
      "action": "call"
    },
    {
      "action": "raise",
      "amount_bb": 8,
      "sizing_pot": 0.3125,
      "allin": true
    },
    {
      "action": "fold"
    }
  ],
  "range_strategy": {
    "AcAd": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ],
    "AcAs": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ],
    "AdAs": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ],
    "KcKd": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ],
    "KcKs": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ],
    "KdKs": [
      0.08627451211214066,
      0.9137254953384399,
      0
    ]
  },
  "range_hand_count": 6
}
flop-chance · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_010>"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL",
  "token": "<TOKEN_013>",
  "node_type": "chance",
  "street": "flop",
  "board": [
    "Ah",
    "Kh",
    "Qh"
  ],
  "children": [
    {
      "card": "2c",
      "node": "root/BET 3.000000/CALL/2c",
      "cached": true
    },
    {
      "card": "2d",
      "node": "root/BET 3.000000/CALL/2d",
      "cached": true
    },
    {
      "card": "2h",
      "node": "root/BET 3.000000/CALL/2h",
      "cached": true
    },
    {
      "card": "2s",
      "node": "root/BET 3.000000/CALL/2s",
      "cached": true
    },
    {
      "card": "3c",
      "node": "root/BET 3.000000/CALL/3c",
      "cached": true
    },
    {
      "card": "3d",
      "node": "root/BET 3.000000/CALL/3d",
      "cached": true
    },
    {
      "card": "3h",
      "node": "root/BET 3.000000/CALL/3h",
      "cached": true
    },
    {
      "card": "3s",
      "node": "root/BET 3.000000/CALL/3s",
      "cached": true
    },
    {
      "card": "4c",
      "node": "root/BET 3.000000/CALL/4c",
      "cached": true
    },
    {
      "card": "4d",
      "node": "root/BET 3.000000/CALL/4d",
      "cached": true
    },
    {
      "card": "4h",
      "node": "root/BET 3.000000/CALL/4h",
      "cached": true
    },
    {
      "card": "4s",
      "node": "root/BET 3.000000/CALL/4s",
      "cached": true
    },
    {
      "card": "5c",
      "node": "root/BET 3.000000/CALL/5c",
      "cached": true
    },
    {
      "card": "5d",
      "node": "root/BET 3.000000/CALL/5d",
      "cached": true
    },
    {
      "card": "5h",
      "node": "root/BET 3.000000/CALL/5h",
      "cached": true
    },
    {
      "card": "5s",
      "node": "root/BET 3.000000/CALL/5s",
      "cached": true
    },
    {
      "card": "6c",
      "node": "root/BET 3.000000/CALL/6c",
      "cached": true
    },
    {
      "card": "6d",
      "node": "root/BET 3.000000/CALL/6d",
      "cached": true
    },
    {
      "card": "6h",
      "node": "root/BET 3.000000/CALL/6h",
      "cached": true
    },
    {
      "card": "6s",
      "node": "root/BET 3.000000/CALL/6s",
      "cached": true
    },
    {
      "card": "7c",
      "node": "root/BET 3.000000/CALL/7c",
      "cached": true
    },
    {
      "card": "7d",
      "node": "root/BET 3.000000/CALL/7d",
      "cached": true
    },
    {
      "card": "7h",
      "node": "root/BET 3.000000/CALL/7h",
      "cached": true
    },
    {
      "card": "7s",
      "node": "root/BET 3.000000/CALL/7s",
      "cached": true
    },
    {
      "card": "8c",
      "node": "root/BET 3.000000/CALL/8c",
      "cached": true
    },
    {
      "card": "8d",
      "node": "root/BET 3.000000/CALL/8d",
      "cached": true
    },
    {
      "card": "8h",
      "node": "root/BET 3.000000/CALL/8h",
      "cached": true
    },
    {
      "card": "8s",
      "node": "root/BET 3.000000/CALL/8s",
      "cached": true
    },
    {
      "card": "9c",
      "node": "root/BET 3.000000/CALL/9c",
      "cached": true
    },
    {
      "card": "9d",
      "node": "root/BET 3.000000/CALL/9d",
      "cached": true
    },
    {
      "card": "9h",
      "node": "root/BET 3.000000/CALL/9h",
      "cached": true
    },
    {
      "card": "9s",
      "node": "root/BET 3.000000/CALL/9s",
      "cached": true
    },
    {
      "card": "Ac",
      "node": "root/BET 3.000000/CALL/Ac",
      "cached": true
    },
    {
      "card": "Ad",
      "node": "root/BET 3.000000/CALL/Ad",
      "cached": true
    },
    {
      "card": "As",
      "node": "root/BET 3.000000/CALL/As",
      "cached": true
    },
    {
      "card": "Jc",
      "node": "root/BET 3.000000/CALL/Jc",
      "cached": true
    },
    {
      "card": "Jd",
      "node": "root/BET 3.000000/CALL/Jd",
      "cached": true
    },
    {
      "card": "Jh",
      "node": "root/BET 3.000000/CALL/Jh",
      "cached": true
    },
    {
      "card": "Js",
      "node": "root/BET 3.000000/CALL/Js",
      "cached": true
    },
    {
      "card": "Kc",
      "node": "root/BET 3.000000/CALL/Kc",
      "cached": true
    },
    {
      "card": "Kd",
      "node": "root/BET 3.000000/CALL/Kd",
      "cached": true
    },
    {
      "card": "Ks",
      "node": "root/BET 3.000000/CALL/Ks",
      "cached": true
    },
    {
      "card": "Qc",
      "node": "root/BET 3.000000/CALL/Qc",
      "cached": true
    },
    {
      "card": "Qd",
      "node": "root/BET 3.000000/CALL/Qd",
      "cached": true
    },
    {
      "card": "Qs",
      "node": "root/BET 3.000000/CALL/Qs",
      "cached": true
    },
    {
      "card": "Tc",
      "node": "root/BET 3.000000/CALL/Tc",
      "cached": true
    },
    {
      "card": "Td",
      "node": "root/BET 3.000000/CALL/Td",
      "cached": true
    },
    {
      "card": "Th",
      "node": "root/BET 3.000000/CALL/Th",
      "cached": true
    },
    {
      "card": "Ts",
      "node": "root/BET 3.000000/CALL/Ts",
      "cached": true
    }
  ]
}
turn · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_013>",
  "turn_card": "2d"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d",
  "token": "<TOKEN_014>",
  "node_type": "action",
  "street": "turn",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/BET 3.000000/CALL/2d/CHECK",
      "cached": true,
      "token": "<TOKEN_015>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000/CALL/2d/BET 5.000000",
      "cached": true,
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_016>"
    }
  ],
  "is_hero": true,
  "actions": [
    {
      "action": "check"
    },
    {
      "action": "bet",
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true
    }
  ],
  "range_strategy": {
    "JcJd": [
      1,
      0
    ],
    "JcJh": [
      0,
      1
    ],
    "JdJh": [
      0,
      1
    ],
    "JcJs": [
      1,
      0
    ],
    "JdJs": [
      1,
      0
    ],
    "JhJs": [
      0,
      1
    ],
    "TcTd": [
      1,
      0
    ],
    "TcTh": [
      0,
      1
    ],
    "TdTh": [
      0,
      1
    ],
    "TcTs": [
      1,
      0
    ],
    "TdTs": [
      1,
      0
    ],
    "ThTs": [
      0,
      1
    ]
  },
  "range_hand_count": 12,
  "cache_quota": {
    "used": 2,
    "limit": 2000
  }
}
turn-hand · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_014>",
  "hole_cards": "JdJc"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d",
  "token": "<TOKEN_017>",
  "node_type": "action",
  "street": "turn",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/BET 3.000000/CALL/2d/CHECK",
      "cached": true,
      "token": "<TOKEN_018>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000/CALL/2d/BET 5.000000",
      "cached": true,
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_019>"
    }
  ],
  "is_hero": true,
  "hole_cards": "JdJc",
  "strategy": [
    {
      "action": "check",
      "frequency": 1
    },
    {
      "action": "bet",
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "frequency": 0
    }
  ]
}
turn-opponent · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_015>"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d/CHECK",
  "token": "<TOKEN_020>",
  "node_type": "action",
  "street": "turn",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK",
      "cached": true,
      "token": "<TOKEN_021>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000/CALL/2d/CHECK/BET 5.000000",
      "cached": true,
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_022>"
    }
  ],
  "is_hero": false,
  "actions": [
    {
      "action": "check"
    },
    {
      "action": "bet",
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true
    }
  ],
  "range_strategy": {
    "AcAd": [
      0,
      1
    ],
    "AcAs": [
      0,
      1
    ],
    "AdAs": [
      0,
      1
    ],
    "KcKd": [
      0,
      1
    ],
    "KcKs": [
      0,
      1
    ],
    "KdKs": [
      0,
      1
    ]
  },
  "range_hand_count": 6
}
turn-chance · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_021>"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK",
  "token": "<TOKEN_023>",
  "node_type": "chance",
  "street": "turn",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d"
  ],
  "children": [
    {
      "card": "2c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2c",
      "cached": true
    },
    {
      "card": "2h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2h",
      "cached": true
    },
    {
      "card": "2s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s",
      "cached": true
    },
    {
      "card": "3c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/3c",
      "cached": true
    },
    {
      "card": "3d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/3d",
      "cached": true
    },
    {
      "card": "3h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/3h",
      "cached": true
    },
    {
      "card": "3s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/3s",
      "cached": true
    },
    {
      "card": "4c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/4c",
      "cached": true
    },
    {
      "card": "4d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/4d",
      "cached": true
    },
    {
      "card": "4h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/4h",
      "cached": true
    },
    {
      "card": "4s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/4s",
      "cached": true
    },
    {
      "card": "5c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/5c",
      "cached": true
    },
    {
      "card": "5d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/5d",
      "cached": true
    },
    {
      "card": "5h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/5h",
      "cached": true
    },
    {
      "card": "5s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/5s",
      "cached": true
    },
    {
      "card": "6c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/6c",
      "cached": true
    },
    {
      "card": "6d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/6d",
      "cached": true
    },
    {
      "card": "6h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/6h",
      "cached": true
    },
    {
      "card": "6s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/6s",
      "cached": true
    },
    {
      "card": "7c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/7c",
      "cached": true
    },
    {
      "card": "7d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/7d",
      "cached": true
    },
    {
      "card": "7h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/7h",
      "cached": true
    },
    {
      "card": "7s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/7s",
      "cached": true
    },
    {
      "card": "8c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/8c",
      "cached": true
    },
    {
      "card": "8d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/8d",
      "cached": true
    },
    {
      "card": "8h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/8h",
      "cached": true
    },
    {
      "card": "8s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/8s",
      "cached": true
    },
    {
      "card": "9c",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/9c",
      "cached": true
    },
    {
      "card": "9d",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/9d",
      "cached": true
    },
    {
      "card": "9h",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/9h",
      "cached": true
    },
    {
      "card": "9s",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/9s",
      "cached": true
    },
    {
      "card": "Ac",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Ac",
      "cached": true
    },
    {
      "card": "Ad",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Ad",
      "cached": true
    },
    {
      "card": "As",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/As",
      "cached": true
    },
    {
      "card": "Jc",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Jc",
      "cached": true
    },
    {
      "card": "Jd",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Jd",
      "cached": true
    },
    {
      "card": "Jh",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Jh",
      "cached": true
    },
    {
      "card": "Js",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Js",
      "cached": true
    },
    {
      "card": "Kc",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Kc",
      "cached": true
    },
    {
      "card": "Kd",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Kd",
      "cached": true
    },
    {
      "card": "Ks",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Ks",
      "cached": true
    },
    {
      "card": "Qc",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Qc",
      "cached": true
    },
    {
      "card": "Qd",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Qd",
      "cached": true
    },
    {
      "card": "Qs",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Qs",
      "cached": true
    },
    {
      "card": "Tc",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Tc",
      "cached": true
    },
    {
      "card": "Td",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Td",
      "cached": true
    },
    {
      "card": "Th",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Th",
      "cached": true
    },
    {
      "card": "Ts",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/Ts",
      "cached": true
    }
  ]
}
river · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_023>",
  "river_card": "2s"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s",
  "token": "<TOKEN_024>",
  "node_type": "action",
  "street": "river",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d",
    "2s"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s/CHECK",
      "cached": true,
      "token": "<TOKEN_025>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s/BET 5.000000",
      "cached": true,
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_026>"
    }
  ],
  "is_hero": true,
  "actions": [
    {
      "action": "check"
    },
    {
      "action": "bet",
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true
    }
  ],
  "range_strategy": {
    "JcJd": [
      0.501960813999176,
      0.501960813999176
    ],
    "JcJh": [
      0.501960813999176,
      0.501960813999176
    ],
    "JdJh": [
      0.501960813999176,
      0.501960813999176
    ],
    "JcJs": [
      0.501960813999176,
      0.501960813999176
    ],
    "JdJs": [
      0.501960813999176,
      0.501960813999176
    ],
    "JhJs": [
      0.501960813999176,
      0.501960813999176
    ],
    "TcTd": [
      0.501960813999176,
      0.501960813999176
    ],
    "TcTh": [
      0.501960813999176,
      0.501960813999176
    ],
    "TdTh": [
      0.501960813999176,
      0.501960813999176
    ],
    "TcTs": [
      0.501960813999176,
      0.501960813999176
    ],
    "TdTs": [
      0.501960813999176,
      0.501960813999176
    ],
    "ThTs": [
      0.501960813999176,
      0.501960813999176
    ]
  },
  "range_hand_count": 12,
  "cache_quota": {
    "used": 3,
    "limit": 2000
  }
}
river-hand · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_024>",
  "hole_cards": "JdJc"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s",
  "token": "<TOKEN_027>",
  "node_type": "action",
  "street": "river",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d",
    "2s"
  ],
  "children": [
    {
      "action": "check",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s/CHECK",
      "cached": true,
      "token": "<TOKEN_028>"
    },
    {
      "action": "bet",
      "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s/BET 5.000000",
      "cached": true,
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "token": "<TOKEN_029>"
    }
  ],
  "is_hero": true,
  "hole_cards": "JdJc",
  "strategy": [
    {
      "action": "check",
      "frequency": 0.501960813999176
    },
    {
      "action": "bet",
      "amount_bb": 5,
      "sizing_pot": 0.3125,
      "allin": true,
      "frequency": 0.501960813999176
    }
  ]
}
showdown · HTTP 200
POST /v1/gto/postflop/cache/query
{
  "node": "<TOKEN_031>"
}

{
  "source": "persistent_cache",
  "node": "root/BET 3.000000/CALL/2d/CHECK/CHECK/2s/CHECK/CHECK",
  "token": "<TOKEN_033>",
  "node_type": "showdown",
  "street": "river",
  "board": [
    "Ah",
    "Kh",
    "Qh",
    "2d",
    "2s"
  ],
  "children": []
}
paid-hand-miss · HTTP 422
POST /v1/gto/postflop/cache/query
{
  "board": "AhKhQh",
  "pot_type": "4BET",
  "positions": {
    "hero": "UTG",
    "raiser": "UTG",
    "three_bettor": "MP"
  },
  "hole_cards": "9c9d"
}

{
  "error": "hand_not_in_effective_range",
  "cache_quota": {
    "used": 5,
    "limit": 2000
  }
}

Direct HTTP programs

Python · HTTP
#!/usr/bin/env python3
"""Direct HTTP, no SDK or automatic retries. Token placeholders are never used.
Run: POKERAI_API_KEY=... python3 postflop_cache_workflow.py [custom_request.json]
Optional POKERAI_BASE_URL selects a controlled local HTTP host for replay.
Fixture source: local-isolated-http, Relay 938d04e708dc8bb5e47c38f330e3397d0851c102.
This example does not establish production deployment or cache coverage.
"""
import json
import os
import sys
from urllib.error import HTTPError
from urllib.request import Request, urlopen

base = os.environ.get("POKERAI_BASE_URL", "https://pokerai.bet").rstrip("/")
key = os.environ["POKERAI_API_KEY"]
root_request = {"board": "AhKhQh", "pot_type": "4BET",
                "positions": {"hero": "UTG", "raiser": "UTG", "three_bettor": "MP"}}
if len(sys.argv) > 1:
    with open(sys.argv[1], encoding="utf-8") as source:
        root_request = json.load(source)


def query(body):
    request = Request(base + "/v1/gto/postflop/cache/query",
                      data=json.dumps(body).encode(), method="POST",
                      headers={"Authorization": "Bearer " + key,
                               "Content-Type": "application/json"})
    try:
        with urlopen(request, timeout=25) as response:
            result = json.load(response)
    except HTTPError as error:
        # A missing receipt does not prove no debit. Never automatically retry.
        raise RuntimeError(f"HTTP {error.code}: {error.read().decode()}") from error
    print(json.dumps(result))
    return result


def child_token(node, action, amount=None):
    matches = [child for child in node["children"]
               if child.get("action") == action and child.get("cached")
               and "token" in child
               and (amount is None or child.get("amount_bb") == amount)]
    if len(matches) != 1:
        raise RuntimeError("Expected exactly one cached action; stop, do not guess a path")
    return matches[0]["token"]


def read_hand(node):
    hand = query({"node": node["token"], "hole_cards": "JdJc"})
    assert "cache_quota" not in hand
    assert hand["is_hero"] and hand["hole_cards"] == "JdJc"
    # StrategyItem.frequency is a mixed frequency; unknown EV/EQ is absent.
    return hand["strategy"]


flop = query(root_request)                         # paid root
read_hand(flop)                                   # free hand
opponent = query({"node": child_token(flop, "bet", 3)})
flop_chance = query({"node": child_token(opponent, "call")})  # optional free preview
assert flop_chance["node_type"] == "chance"
turn = query({"node": flop_chance["token"], "turn_card": "2d"})  # paid Turn
read_hand(turn)
opponent = query({"node": child_token(turn, "check")})
turn_chance = query({"node": child_token(opponent, "check")})   # optional free preview
assert turn_chance["node_type"] == "chance"
river = query({"node": turn_chance["token"], "river_card": "2s"})  # paid River
read_hand(river)
# This isolated fixture uses one unchanged service period/limit. Live bonuses or
# period changes can change the next receipt: always use that request's receipt.
print(json.dumps({"cache_receipts": [node["cache_quota"] for node in [flop, turn, river]]}))
JavaScript · HTTP
// Direct HTTP, no SDK or automatic retries; Node.js 18+.
// POKERAI_API_KEY=... node postflop_cache_workflow.js [custom_request.json]
// Optional POKERAI_BASE_URL selects a controlled local HTTP host for replay.
// Fixture source: local-isolated-http, Relay 938d04e708dc8bb5e47c38f330e3397d0851c102.
// This example does not establish production deployment or cache coverage.
(async () => {
  const base = (process.env.POKERAI_BASE_URL || 'https://pokerai.bet').replace(/\/$/, '');
  const key = process.env.POKERAI_API_KEY;
  if (!key) throw new Error('Set POKERAI_API_KEY');
  let rootRequest = { board: 'AhKhQh', pot_type: '4BET',
    positions: { hero: 'UTG', raiser: 'UTG', three_bettor: 'MP' } };
  if (process.argv[2]) {
    const { readFile } = await import('node:fs/promises');
    rootRequest = JSON.parse(await readFile(process.argv[2], 'utf8'));
  }
  async function query(body) {
    const response = await fetch(base + '/v1/gto/postflop/cache/query', {
      method: 'POST', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(body), signal: AbortSignal.timeout(25000),
    });
    const result = await response.json();
    // A missing receipt does not prove no debit. Never automatically retry.
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
    console.log(JSON.stringify(result));
    return result;
  }
  function childToken(node, action, amount) {
    const matches = node.children.filter(child => child.action === action && child.cached && child.token
      && (amount === undefined || child.amount_bb === amount));
    if (matches.length !== 1) throw new Error('Expected exactly one cached action; stop, do not guess a path');
    return matches[0].token;
  }
  async function readHand(node) {
    const hand = await query({ node: node.token, hole_cards: 'JdJc' });
    if ('cache_quota' in hand || !hand.is_hero || hand.hole_cards !== 'JdJc') throw new Error('Unexpected hand response');
    // StrategyItem.frequency is a mixed frequency; unknown EV/EQ is absent.
    return hand.strategy;
  }
  const flop = await query(rootRequest);                         // paid root
  await readHand(flop);                                          // free hand
  let opponent = await query({ node: childToken(flop, 'bet', 3) });
  const flopChance = await query({ node: childToken(opponent, 'call') }); // optional free preview
  if (flopChance.node_type !== 'chance') throw new Error('Expected Flop chance');
  const turn = await query({ node: flopChance.token, turn_card: '2d' });  // paid Turn
  await readHand(turn);
  opponent = await query({ node: childToken(turn, 'check') });
  const turnChance = await query({ node: childToken(opponent, 'check') }); // optional free preview
  if (turnChance.node_type !== 'chance') throw new Error('Expected Turn chance');
  const river = await query({ node: turnChance.token, river_card: '2s' }); // paid River
  await readHand(river);
  // Period/bonus changes can alter limits: use each consume receipt, not a prior snapshot.
  console.log(JSON.stringify({ cache_receipts: [flop, turn, river].map(node => node.cache_quota) }));
})().catch(error => { console.error(error.message); process.exitCode = 1; });

Downloads

JSON · custom JSON · Python · JavaScript · Postman

EV

POST https://pokerai.bet/v1/gto/postflop/cache/ev

Interactive reference

1 Cache quota per admitted request · includes hits and joins

Call example

curl -sS -X POST https://pokerai.bet/v1/gto/postflop/cache/ev \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"node":"<returned action token>","hole_cards":"AhKh"}'

Parameters

Send only a returned action token in node and two concrete cards in hole_cards. Replace the token placeholder before running the example.

Response and errors

HTTP 200 returns ev in net BB (raw_net_bb), with action_values aligned to the returned strategy and combo_value for the hand.

Admitted successes include the caller’s cache_quota. An inapplicable or unsupported result can return missing before admission without a charge. HTTP 400 means invalid input, 402 exhausted Cache quota and 410 an expired token. Do not automatically retry 503 cache_charge_unknown.

Current HTTP workflows

4BET · AsAh · Python · JavaScript

EQ

POST https://pokerai.bet/v1/gto/postflop/cache/eq

Interactive reference

1 Cache quota per admitted request · includes hits and joins

Call example

curl -sS -X POST https://pokerai.bet/v1/gto/postflop/cache/eq \
  -H "Authorization: Bearer $POKERAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"node":"<returned action token>","hole_cards":"AhKh"}'

Parameters

Send only a returned action token in node and two concrete cards in hole_cards. Replace the token placeholder before running the example.

Response and errors

HTTP 200 returns eq as a ratio against the effective cached Flop-root range (root_range_joint), with a value from 0 to 1 when available.

Admitted successes include the caller’s cache_quota. An inapplicable or unsupported result can return missing before admission without a charge. HTTP 400 means invalid input, 402 exhausted Cache quota and 410 an expired token. Do not automatically retry 503 cache_charge_unknown.

Current HTTP workflows

The current EQ replay can use up to 6 Cache units when run against production: 3 for root/deal queries and 3 for independent EQ requests. It stops if the target is absent or the expected EQ is missing, and never retries paid requests automatically.

6max · 4BET · AsAh · Python · JavaScript

4BET · AsAh · Python · JavaScript

Current HTTP workflows

Cache EV/EQ endpoints are available in production since 2026-11-18. POST /v1/gto/postflop/cache/ev and /eq accept only a returned action token and concrete hole_cards. On /query, include_ev:true or include_eq:true returns 400 invalid_request before Auth validation, consumption or Native dispatch; omission/false remains ordinary query behavior. Each admitted independent EV/EQ request consumes 1 existing cache unit, including hit/join, and every admitted success carries that caller's cache_quota. Pre-admission inapplicable/unsupported missing consumes 0; after confirmation, failure, timeout or cancellation can still be charged. 503 cache_charge_unknown carries no quota and is not automatically retried; exhaustion returns 402 cache_quota_exceeded. The retained local-isolated capture is deployed:false, not a production three-street success or real-billing capture.

JSON (local-isolated)

Python · HTTP
#!/usr/bin/env python3
import json, os, urllib.request
BASE=os.environ.get('POKERAI_BASE_URL','https://pokerai.bet').rstrip('/')
KEY=os.environ.get('POKERAI_API_KEY')
def post(path, body):
 r=urllib.request.Request(BASE+path,data=json.dumps(body).encode(),headers={'Authorization':'Bearer '+KEY,'Content-Type':'application/json'},method='POST')
 with urllib.request.urlopen(r) as x: return json.load(x)
def check(node):
 return next(c['token'] for c in node['children'] if c.get('action')=='check' and c.get('token'))
def metrics(node):
 plain=post('/v1/gto/postflop/cache/query',{'node':node['token'],'hole_cards':'AhKh'})
 ev=post('/v1/gto/postflop/cache/ev',{'node':node['token'],'hole_cards':'AhKh'})
 eq=post('/v1/gto/postflop/cache/eq',{'node':node['token'],'hole_cards':'AhKh'})
 assert 'strategy' in plain and 'ev' in ev and 'eq' in eq and 'token' not in ev and 'token' not in eq
 print(json.dumps({'plain':plain,'ev':ev,'eq':eq}))
root=post('/v1/gto/postflop/cache/query',{'board':'4c8d9h','pot_type':'3BET','positions':{'hero':'SB','raiser':'MP','three_bettor':'SB'},'preflop_pack':'6max_RC_100bb_200NL','hole_cards':'AhKh'})
metrics(root)
flop_chance=post('/v1/gto/postflop/cache/query',{'node':check(post('/v1/gto/postflop/cache/query',{'node':check(root)}))})
turn=post('/v1/gto/postflop/cache/query',{'node':flop_chance['token'],'turn_card':'As','hole_cards':'AhKh'})
metrics(turn)
turn_chance=post('/v1/gto/postflop/cache/query',{'node':check(post('/v1/gto/postflop/cache/query',{'node':check(turn)}))})
river=post('/v1/gto/postflop/cache/query',{'node':turn_chance['token'],'river_card':'7d','hole_cards':'AhKh'})
metrics(river)
JavaScript · HTTP
const BASE=(process.env.POKERAI_BASE_URL||'https://pokerai.bet').replace(/\/$/,''); const KEY=process.env.POKERAI_API_KEY;
async function post(path,body){const r=await fetch(BASE+path,{method:'POST',headers:{Authorization:'Bearer '+KEY,'Content-Type':'application/json'},body:JSON.stringify(body)});if(!r.ok)throw new Error(await r.text());return r.json()}
const check=n=>n.children.find(c=>c.action==='check'&&c.token).token;
async function metrics(node){const plain=await post('/v1/gto/postflop/cache/query',{node:node.token,hole_cards:'AhKh'});const ev=await post('/v1/gto/postflop/cache/ev',{node:node.token,hole_cards:'AhKh'});const eq=await post('/v1/gto/postflop/cache/eq',{node:node.token,hole_cards:'AhKh'});if(!plain.strategy||!ev.ev||!eq.eq||ev.token||eq.token)throw new Error('unexpected metric response');console.log(JSON.stringify({plain,ev,eq}))}
const root=await post('/v1/gto/postflop/cache/query',{board:'4c8d9h',pot_type:'3BET',positions:{hero:'SB',raiser:'MP',three_bettor:'SB'},preflop_pack:'6max_RC_100bb_200NL',hole_cards:'AhKh'});await metrics(root);const flopChance=await post('/v1/gto/postflop/cache/query',{node:check(await post('/v1/gto/postflop/cache/query',{node:check(root)}))});const turn=await post('/v1/gto/postflop/cache/query',{node:flopChance.token,turn_card:'As',hole_cards:'AhKh'});await metrics(turn);const turnChance=await post('/v1/gto/postflop/cache/query',{node:check(await post('/v1/gto/postflop/cache/query',{node:check(turn)}))});const river=await post('/v1/gto/postflop/cache/query',{node:turnChance.token,river_card:'7d',hole_cards:'AhKh'});await metrics(river);

Historical production EQ (2026-11-17)

Historical production EQ capture

The production capture records 11 HTTPS calls from a Builder test account, including EQ on the Flop, Turn and River. Under the former query-flags protocol, the root and two deals used 3 Cache units total (20 → 23 / 2,000). The EQ node reads, action navigation and Coverage used 0. The recorded response bodies and timings remain available in the original JSON capture.

Historical local-isolated EQ · 4BET / AsAh

JSON (local-isolated)

Historical 2026-11-16/17 old query-flags records (not current endpoint-call examples): Optional EV: local-isolated 4BET / AsAh

JSON

Preflop-to-flop range contract

Start with POST /v1/gto/preflop/range; optionally request include_flop_pruning_guarantees: true and an optional preflop_pack. There is no flop_context. The optional guarantee is an offline immutable manifest lookup for a completed Flop batch, never a live Flop or database query.

The guarantee status is complete, incomplete_coverage, or awaiting_terminal_preflop_action. Only complete supplies a terminal continuation and per-seat always_removed; it means every compatible canonical board in that one terminal scenario proved the hand weight zero. It is conservative, must not be inferred when data is absent, and never replaces a board-specific POST /v1/gto/flop/tree. An incomplete result may have continuation.ranges: null; awaiting has continuation: null.

Pass an optional two-card hole_cards value to POST /v1/gto/flop/tree. The response keeps top-level oop_range/ip_range as the effective aliases used by the strategy tree, and also exposes ranges.requested, ranges.effective, ranges.adjusted, range_provenance.effective_source, and policy_audit_status. mismatch reports historical effective-versus-current-policy disagreement, not an artifact/range mismatch. Missing configuration fails closed. Feed ranges.effective, not requested ranges, into range conversion.

With requested hole_cards, inspect hero_hand_coverage: unchanged, reweighted, removed, or not_in_requested_range. A removed hand ends the workflow: do not retry POST /v1/gto/flop/node. It returns typed HTTP 422 hand_not_in_effective_range, not a 404. A reweighted hand may continue with a node token.

With preflop_pack=A, the chart uses A and an enabled guarantee also uses A. Legacy-only preflop_version=A and flop_version=B remain independent (each defaults to 6max): preflop_version=A alone with the flag true gives chart A / guarantee 6max, whereas preflop_pack=A gives A / A. Mixed inputs compare only effective synonymous selectors. When the flag is off, legacy flop_version is ignored even if invalid. The guarantee response publishes preflop_pack only; manifest_version is unchanged.

The three guarantee JSON files are illustrative public-field projections; range, manifest and strategy data are unchanged, not a new native capture.