How do I safely run a GTO solver API solve?
Treat one real-time solve as a short lifecycle: schedule it, poll its tree until it is queryable, then read only tokens returned by that tree.
POST /v1/gto/solver, retain its solve handle, and poll POST /v1/gto/solver/tree until spot_status is queryable. Pass a returned node token to POST /v1/gto/solver/node. This page covers scheduling, polling, and reading—not solver selection or research-tree design.Quick facts
| Schedule | POST /v1/gto/solver requires board, oop_range, ip_range, pot, effective_stack, and hero. |
|---|---|
| Async signals | Schedule status can be computing, queryable, or busy; tree spot_status is the readiness signal for reads. |
| Read scope | Use the solve handle only with its tree/release calls, and use a token returned by that tree only as the node input for /v1/gto/solver/node. |
| Quota | solve_quota is present only when a new solve was triggered. Tree, node, and optional release operations are documented as free. |
| Result boundary | A readable node can contain strategy, or actions and range_strategy; a non-readable status is not strategy. |
1. Schedule and retain the handle
Use a complete, self-contained custom flop, turn, or river spot. The board length selects the street. Store the returned solve handle; it is the identifier for the later tree and release requests.
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","ip_range":"QQ,JJ","pot":6,"effective_stack":100,"hero":"OOP"}'A schedule response can be computing or queryable. If it is busy, no solve handle is available to poll; treat it as solver capacity rather than a completed solve. The public contract does not promise a wait time or availability level.
2. Poll the tree before reading strategy
Call POST /v1/gto/solver/tree with the handle. For a flop solve, turn_card is optional; river_card is also optional and pairs with turn_card when disambiguation is needed. Do not invent either field for a different solve.
curl -s https://pokerai.bet/v1/gto/solver/tree \
+ -H "Authorization: Bearer $POKERAI_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"solve":"<solve handle>"}'Continue only when spot_status is queryable. computing is not a strategy result. no_nodes is terminal for the queried round or runout, so stop polling it. expired means the handle can no longer be used and the spot must be scheduled again.
3. Read a node using its tree token
A queryable tree returns nodes with fields including node, is_hero, status, and token. Pass that token as node; it is not a substitute for the API key or a reusable solve handle. Keep handle and token data out of client logs.
curl -s https://pokerai.bet/v1/gto/solver/node \
+ -H "Authorization: Bearer $POKERAI_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"node":"<token from this solve tree>"}'A hero node can return strategy. A villain node, or a request without hole_cards, can return actions and range_strategy. If the node response reports node_status as computing, expired, or error, do not present it as strategy; error can include message.
4. Interpret only a readable node
A readable hero node can contain strategy. A villain node, or a request without hole_cards, can contain actions and range_strategy. Those fields describe the returned node; they are not a promise about a different tree, spot, or game format.
If the tree is computing, no_nodes, or expired, stop or reschedule as documented instead of presenting a result. For whether a hosted API or a desktop solver is the better research tool, see the transparent comparison.
Use only for training and review
Use this lifecycle for offline training, coaching, hand review, study, and research. It supports a submitted solve's state management, not live-table decision delivery or a claim of strategy quality, latency, or performance.
Real-time assistance at real-money tables is prohibited. Keep solver scheduling, polling, node strategy, and release flows out of live-table automation and in-hand action prompts.
Lifecycle endpoint map
These three operations are sufficient for the lifecycle described here; consume only the fields documented in the current OpenAPI contract.
| Endpoint | Lifecycle role | Documented input or signal |
|---|---|---|
POST /v1/gto/solver | Schedule | Required spot fields; save solve and inspect status and optional solve_quota. |
POST /v1/gto/solver/tree | Poll | Send solve; wait for spot_status: queryable and select a returned token. |
POST /v1/gto/solver/node | Read | Send the corresponding tree token as node; optional hole_cards narrows a hero strategy read. |
Related resources
- Developer docs — authentication, quotas, and solver workflow
- Interactive API reference — current request and response schemas
- OpenAPI snapshot — the machine-readable English contract
- GTO solver API guide — product context and API surface map
- Poker hand review API guide — place solver analysis in a post-session workflow
- llms.txt — the concise LLM entry point for Pokerai API