No limit texas hold'em Game API Reference

API documentation for request and response for hold'em games.

Game Formats Support

Blinds and Straddle

Our API supports both two-blind and three-blind poker formats.

Blinds are the forced bets that initiate action in every hand.
In two-blind games, only the Small Blind (SB) and Big Blind (BB) are used.

In three-blind games, a third forced bet, the Straddle, is added.

You only need to define the Big Blind value in the request, since the API automatically infers:

• Small Blind = half the Big Blind
• Straddle = twice the Big Blind

How to specify the format in your request:

• For two-blind games, set:
  straddle_seat = -1
• For three-blind games, set:
  straddle_seat to a valid seat number

You will find detailed documentation for straddle_seat in the request section below.

Players and Ante

The API supports up to 9 players in a game. The minimum number of players depends on the number of blinds:

• 2-blind games support 2 to 9 players.
• 3-blind games support 4 to 9 players. This requirement exists to support the standard game rule: "the button is not allowed to post a straddle". 3-blind games with fewer than 4 players will fail the request.

The API supports games with antes. You can set the ante value using the ante field in the request object, which specifies the ante amount in chips.

Antes are forced bets posted by all players before the blinds. They increase the initial pot size and affect preflop strategy.

To request a hand without antes, set:
"ante": 0

Chips and Stack Depth

All amount values in the request and response are represented in chips, not in big blinds.

The API supports deep-stack scenarios, with a maximum depth of 2,000 BB.
For example, if the Big Blind is 100 chips, the maximum stack allowed is: 200,000 chips (two hundred thousand).

Although deeper stack depths are supported, the model is optimized for effective stack depths between 80 BB and 400 BB. The model is expected to perform most consistently and reliably within this range.

Post Seats

The API also supports post seats. A post seat refers to a player who joins the table out of turn or changes seats and must post a forced bet to enter the action fairly, ensuring they contribute to the pot just like the other players.

Post-seat players are required to pay the highest blind:

• In two-blind games, this is the Big Blind.
• In three-blind games, this is the Straddle. You will find the corresponding field in the Request Format section below.

Game representation

Card Notation

The API uses a two character notation to represent playing cards. The first character indicates the rank and the second character indicates the suit. Valid ranks are: 2, 3, 4, 5, 6, 7, 8, 9, T, J, Q, K, A. Valid suits are: s, h, d, c.

For example, As represents the ace of spades and Kh represents the king of hearts.

For player cards in the field hole_cards, we concatenate two cards into a single string. Using the example above, the player hand would be AsKh.

For the flop street, which contains three cards, the API uses the same two character format but concatenates all three cards without separators. For example, AsKhTd represents the ace of spades, the king of hearts, and the ten of diamonds.

Action Notation

The API uses a string to represent the action taken by a player. The valid actions are: fold, call, check, raise, bet, and allin. These are the values you will use when sending a request.

In the response object, you may also see single character action codes. These codes are: f, c, x, r, b, and allin.

For example, the action fold appears as f, call appears as c, and check appears as x.

Money actions in single character format can also include the percentage of the pot associated with that action. For example, a raise of fifty percent (50%) of the pot is represented as r50.

Request Format

{
  "request_id": "unique-request-id",
  "hand": {
    "gameuuid": "<hand-unique-identifier>",
    "game_mode_code": "<game-mode-identifier>",
    "players": [<Player-object>],
    "actions": {
      "entries": [<Action-object>],
    },
    "big_blind": <big-blind-size>,
    "ante": <ante-size>,
    "dealer_seat": <dealer-player-seat>,
    "sb_seat": <small-blind-player-seat>,
    "bb_seat": <big-blind-player-seat>,
    "straddle_seat": <straddle-seat-for-3blind-games>,
    "post_seats": [<seat-number-of-post-seat-players>]
  }
}

Request Fields

Top Level

Hand Object

Player Object

"players": [
    {
        "seat_no": <player-seat-number>,
        "stack": <chip-amount>,
        "hole_cards": "<two-cards-notation-in-case-of-hero-player-or-must-be-removed>"
    },
    ...
]

Action Object

When building the request, you must set the action fields in the exact order they occur in the game. The field request.hand.actions.entries.action should contain either the player action or the board cards, following the sequence in which they are revealed.

Important:

• The actions in the request must always appear in the precise order they happened during the hand.
• The API will not process games that have already finished.
• If no actions have taken place yet, you can set an empty list in entries.

Please refer to the example in the section Simple game example at the bottom of the page for guidance on how to correctly populate the actions field.

"actions": {
  "entries": [
    {
      "action": "<action-label>",
      "amount": "<amount-in-chips-in-case-of-money-action>,
      "seat_no": "<player-seat-number-who-took-the-action>"
    },
    ...
  ]
}

Response Format

Success Response

{
  "request": {
    "request_id": <request-unique-identifier>,
    "hand": { ... }
  },
  "solution_information": <Solution-information-object>,
  "strategy": <Strategy-object>
}

Response Fields

Top Level

Strategy Solution Object

"strategy": {
    "actions": [<Action-distribution-object>],
    "suggested_action": <single-sampled-action-object>
}

Top level fields

Actions Object

"strategy": {
  "actions": [
    {
      "action": <Action-object>,
      "action_name": <action-code-string>,
      "hand_strategy": <action-probability-according-to-strategy-solution>,
      "hand_ev": <action-expected-value>
    },
    ...
  ],
  ...
}

Suggested Action Object For every request, the API will sample a single action from the action probability distribution in the strategy solution. This is the action that is returned in the suggested_action field.

"suggested_action": {
  "action": "<action-label>",
  "amount": "<amount-in-chips-in-case-of-money-action>,
  "seat_no": "<player-seat-number-who-took-the-action>"
}

Simple game example:

Step 1: Define the game details

First, we define the general game parameters.
In this example, we are playing a two-blind No-Limit Hold’em game with a Big Blind of 100 chips and an ante of 100 chips. Also, we are the dealer in seat 0. The small blind is in seat 1 and the big blind is in seat 2.

    "big_blind": 100,                          // the big blind is 100 chips
    "ante": 100,                               // the ante is 100 chips
    "dealer_seat": 0,                          // the dealer player seat is 0
    "sb_seat": 1,                              // the small blind player seat is 1
    "bb_seat": 2,                              // the big blind player seat is 2
    "straddle_seat": -1,                       // for two-blind games, set to -1

Step 2: Populate the players details

Next, we define the players involved in the hand.
We have three players:

1. The Small Blind, seated in seat 1 with a 2,000-chip stack.
2. The Big Blind, seated in seat 2 with a 2,000-chip stack.
3. Ourselves (the hero), seated in seat 0 as the dealer, also with a 2,000-chip stack.

Because we are the hero, we must also provide our hole cards.

"players": [
        {
            "seat_no": 1,
            "stack": 2000
        },
        {
            "seat_no": 2,
            "stack": 2000
        },
        {
            "seat_no": 0,
            "stack": 2000,
            "hole_cards": "AsKs"
        }
    ]

Step 3: Fill in the action history

Now we will complete the action details up to the current decision point.

So far, the hand has progressed as follows:

1. Preflop, we raised to 225 chips (50 percent of the pot).
2. The Small Blind player folded.
3. The Big Blind player called.
4. The flop was dealt: 3hKd8h.
5. The Big Blind was first to act on the flop and checked.
6. We acted next and bet 900 chips (100 percent of the pot).
7. The Big Blind player called.
8. The turn card was dealt: 4h.
9. The Big Blind checked again on the turn.

At this point we are on the turn, we are next to act, and we want to send this request to the API to obtain a suggestion for our next action.

  "actions": {
    "entries": [
        {
            "action": "raise",
            "amount": 225
        },
        {
            "action": "fold"
        },
        {
            "action": "call"
        },
        {
            "action": "3hKd8h"
        },
        {
            "action": "check"
        },
        {
            "action": "bet",
            "amount": 900
        },
        {
            "action": "call"
        },
        {
            "action": "4h"
        },
        {
            "action": "check"
        }
    ]

4. Ready to send the request to the API

curl --location '<your-base-url>/lookup' \
--header 'Content-Type: application/json' \
--header 'Authorization: <your-api-key>' \
--data '{
    "request_id": "step-by-step-turn-first-action-0003",
    "hand": {
        "gameuuid": "hand-number-0002",
        "game_mode_code": "normal",
        "players": [
            {
                "seat_no": 1,
                "stack": 2000
            },
            {
                "seat_no": 2,
                "stack": 2000
            },
            {
                "seat_no": 0,
                "stack": 2000,
                "hole_cards": "AsKs"
            }
        ],
        "actions": {
            "entries": [
                {
                    "action": "raise",
                    "amount": 225
                },
                {
                    "action": "fold"
                },
                {
                    "action": "call"
                },
                {
                    "action": "3hKd8h"
                },
                {
                    "action": "check"
                },
                {
                    "action": "bet",
                    "amount": 900
                },
                {
                    "action": "call"
                },
                {
                    "action": "4h"
                },
                {
                    "action": "check"
                }
            ]
        },
        "big_blind": 100,
        "ante": 100,
        "dealer_seat": 0,
        "sb_seat": 1,
        "bb_seat": 2,
        "straddle_seat": -1
    }
}'

5. Getting the response from the API

With the response, we can either take the suggested action, at the very bottom, and as you can see it suggests to go allin. It provides the action, the amount to be taken in chips and also the pot percentage associated with it.

Or we can analyze the actions array, which contains the possible actions, with their probability distribution and ev. For example, we can see that the allin action suggestion has a probability of 81.59% within the distribution of actions. The player could also consider checking, with a probability of 12.11%. But a low bet, with 300 chips (12% of the pot) has a probability of 0.74%, and with a lower ev of 10.35, which is a less recommended action within the API strategy solution.

{
  "request": {...},
  "solution_information": {...},
  "strategy": {
    "actions": [
      {
        "action": {
          "action": "fold",
          "amount": null,
          "pot_size": null,
          "seat_no": 0
        },
        "action_name": "f",
        "hand_strategy": 0.0,
        "hand_ev": 0.0
      },
      {
        "action": {
          "action": "check",
          "amount": null,
          "pot_size": null,
          "seat_no": 0
        },
        "action_name": "x",
        "hand_strategy": 0.12108314607591483,
        "hand_ev": 20.27873992919922
      },
      {
        "action": {
          "action": "allin",
          "amount": 775,
          "pot_size": 0.2980769230769231,
          "seat_no": 0
        },
        "action_name": "allin30",
        "hand_strategy": 0.8159218908783148,
        "hand_ev": 20.27873992919922
      },
      {
        "action": {
          "action": "bet",
          "amount": 300,
          "pot_size": 0.11538461595773697,
          "seat_no": 0
        },
        "action_name": "b12",
        "hand_strategy": 0.007434605979140483,
        "hand_ev": 10.354211807250977
      },
      {
        "action": {
          "action": "bet",
          "amount": 700,
          "pot_size": 0.26923078298568726,
          "seat_no": 0
        },
        "action_name": "b27",
        "hand_strategy": 0.05556035706662989,
        "hand_ev": 20.27873992919922
      }
    ],
    "suggested_action": {
          "action": "allin",
          "amount": 775,
          "pot_size": 0.2980769230769231,
          "seat_no": 0
    }
  }
}