Raise Size Notation
While building the request, setting the correct amounts for money actions or even calculating calls and all ins can be tricky. This document explains the different ways to express raise sizes in the request.
Theory Behind the Raise Size Notation
Before we start, let us review the theory behind the raise size notation.
The GameHand request and response is constructed using a "per-street-raise-to" approach, following the guidelines below:
-
Preflop Money Actions: These take blinds and straddle values into account but exclude antes. Antes are handled separately before any preflop actions.
-
Street-wise Accumulation: Money actions accumulate within each street independently. When a new street starts, the accumulation resets to zero.
Min Raise Rules (NLHE)
The API follows the NLHE minimum bet/raise rules. The following summary of the rules:
- A raise must at least match the size of the previous raise, unless the player is all-in.
- Preflop open raise depends on higher blind pay (big-blind in 2-blind game and straddle in 3-blind game)
- Example in a game with Big-blind = 100 chips
- 2-blind game minimun preflop open raise: 200 chips
- 3-blind game minimun preflop open raise: 400 chips
- Example in a game with Big-blind = 100 chips
- Minimum bet and raise rules reset per street. What happened on a previous street does not affect the minimum bet on the next one.
- Post-flop streets minimun open bet is 1 big blind (or 1 straddle if 3-blind game)
- Antes does not affect minimun raise.
Understanding Pot Percentages
The action_name and pot-size fields use percentages based on a "pot-after-call" rule. This section explains what that means in plain terms and how to interpret it.
Quick glossary (for readers new to poker):
- Pot — The pile of chips in the middle that players are competing for. It grows whenever someone puts chips in (e.g. by calling or raising).
Why "pot after call"?
The percentage is not based on the chips already in the pot. It is based on the pot as it would be after you call. That way, the number describes how big your extra chips (the raise) are relative to the total pot that the next player would face if they call. So when you see something like "50% pot", it means: the raise size is 50% of (current pot + the amount you would have to put in to call).
Example: heads-up game, no antes
- Setup: Two players ("heads-up"). Ante = 0, big blind = 100 chips, small blind = 50 chips. The pot before any action, just the blinds, is 150 (50 + 100).
- Your action: You are first to act and you raise to 200 chips (the minimum raise is 200, see Min Raise Rules section).
- Why the API calls a "50% pot" raise:
- raise increment: The extra chips you put in over a minimum "call" are: 200 − 100 = 100 chips (your "raise increment").
*(To just call the big blind you would put 100; you put 200, so the increment is 100.)_ - pot after call: The "pot after call" is: current pot + your call amount = 150 + 50 = 200 chips.
*(You are in the small blind position, so you have already put in 50. To just call the big blind you would add 50 more. So "call amount" = 50, and pot after call = 150 + 50 = 200.)_ - Pot percentage = (raise increment) ÷ (pot after call) = 100 ÷ 200 = 50%.
- raise increment: The extra chips you put in over a minimum "call" are: 200 − 100 = 100 chips (your "raise increment").
So even though the pot on the table is 150 chips, the API uses 200 (the pot after your call) to compute the percentage. That’s why this raise is reported as a 50% pot raise.
Same scenario in request form before the raise:
{
"request_id": "simple-game-setup-0001",
"hand": {
"players": [
{"seat_no": 0, "stack": 10000},
{"seat_no": 1, "stack": 10000, "hole_cards": "Tc5h"}
],
"actions": {"entries": []},
"big_blind": 100,
"ante": 0,
"dealer_seat": 1,
"sb_seat": 1,
"bb_seat": 0,
"game_type_code": "nlhe",
"post_seats": [],
"straddle_seat": -1
}
}Determining Raise, Bet, and All-in Values in Request Construction
Now that we defined the theory we can build a simple example to illustrate the process. Firs we will setup the game, and for each action we will calculate the stack sizes of each player and the chip amount associated with it.
Now that we have defined the theory, we can walk through a simple example to illustrate the process. First, we will set up the game, and for each action we will calculate the amounts in chips and current pot size associated with it.
Setup a simple game:
1. Game configuration:
This example uses a three blind game with a big blind of 100 chips and an ante of 100 chips. We will start with a basic seat mapping and match the players to their seats in the next step.
{
"request_id": "simple-game-setup-0001",
"hand": {
"big_blind": 100,
"ante": 100,
"dealer_seat": 0,
"sb_seat": 1,
"bb_seat": 2,
"straddle_seat": 3,
(...)
}
}2. Add the players to the game:
We use seven players at the table and identify them using position notation. Each player has the following stack sizes:
- Small Blind (SB): 10000 chips
- Big Blind (BB): 20000 chips
- Straddle (STD): 15000 chips
- Under the Gund (UTG): 17000 chips
- High Jack (HJ): 3500 chips
- Cutoff (CO): 13500 chips
- Button/Dealer (BTN): 21000 chips
So let us build the players object, making sure to match each player to the seat defined in the previous step. In this example, the Small Blind will be the hero, so we will add hole cards for that player.
{
"players": [
{
"seat_no": 0,
"stack_size": 21000 // BTN
},
{
"seat_no": 1,
"stack_size": 10000, // SB - Hero
"hole_cards": "TsJs"
},
{
"seat_no": 2,
"stack_size": 20000 // BB
},
{
"seat_no": 3,
"stack_size": 15000 // STD
},
{
"seat_no": 4,
"stack_size": 17000 // UTG
},
{
"seat_no": 5,
"stack_size": 3500 // HJ
},
{
"seat_no": 6,
"stack_size": 13500 // CO
}
]
}3. Action history:
First lets create a action history for us to follow in the example:
- Preflop:
- UTG folds
- HJ raises to 300
- CO calls
- BTN raises to 600
- SB calls
- BB folds
- STD calls
- HJ calls
- CO folds
- flop:
- SB checks
- STD checks
- HJ bets 200
- BTN raises to 3000
- SB calls
- STD folds
- HJ calls / goes all in
- Turn:
- SB checks
- BTN goes all in
- A request is made to the API to retrieve the strategy for the Small Blind player.
Action analysis:
Next, we will go step by step to calculate the chip amount associated with each action and track the pot size for reference.
- Before Preflop:
- Total of 7 players, each adding 100 chips to the pot as the ante.
- Pot size: 700 chips
- Preflop:
- Pot size start calculation: Starts with 700 chips from the ante, plus the small blind of 50 chips (half the bb), the big blind of 100 chips and the straddle of 200 chips (twice the bb).
- Therefore, pot size before any action is added to the request is: 1050 chips.
- UTG folds: no chips added to the pot
- HJ raises 400 chips:
- The raise amount already includes the blinds.
- That means the HJ player paid the incoming raise amount of 200 from straddle and added 200 more chips on top of that.
- Current pot size is initial_preflop_pot_size + raise_value = 1050 + 400 = 1450 chips.
- For reference to calculate the player current stack in the game, even though it is not necessary for the request, you can simply do: initial-stack-size - ante - raise = 17000 - 100 - 400 = 16500 chips.
- Amount field in the request will be 400.
- Also notice this raise is the minimum legal raise, since blinds are considered raises and this game is a 3-blind game, Straddle is considered the highest blind and incoming bet. Any value smaller than 400 will raise an error.
- CO calls:
- That means the CO player paid the 400 chips from the raise, that also includes the blinds.
- Current pot size is 1450 + 400 = 1850 chips.
- BTN raises 600 chips:
- The 600 raise contains the incoming raise amount, which means this 600 chips consists of the 400 incoming raise plus 200 more chips.
- 600 is also the minimum legal raise, since the highest blind is the straddle at 200 chips.
- Current pot size is 1850 + 600 = 2450 chips.
- Let's calculate the player current stack:
- BTN = initial stack size - ante - raise = 21000 - 100 - 600 = 20300 chips
- Amount field in the request will be 600.
- SB calls
- There is an attached request example at the bottom of the page, called Appendix A, that shows the request for this action, up to this point.
- Here is an important detail, the straddle player has already paid the small blind (50 chips), so by calling the 600 chips raise, he needs to cover the remaining amount of the raise which is 600 - 50 = 550 chips.
- Current pot size is 2450 + 550 = 3000 chips.
- BB folds:
- No chips added to the pot, since the big blind was already paid implicitly at the start of the Preflop.
- STD calls
- Same as SB player above, the straddle player has already paid the blinds up to the straddle value, so by calling the 600 chips raise, he is only adding 400 chips to the pot.
- Current pot size is 3000 + 400 = 3400 chips.
- HJ calls
- The HJ player calls, since he is the last player that first raised, he has already added to the pot the initial raise of 400 chips. In order to call, he needs to add only 200 more chips.
- Current pot size is 3400 + 200 = 3600 chips.
- CO folds:
- No chips added to the pot, since the CO player has already paid the blinds and the initial raise of 400 chips by calling in his last action.
- Pot size start calculation: Starts with 700 chips from the ante, plus the small blind of 50 chips (half the bb), the big blind of 100 chips and the straddle of 200 chips (twice the bb).
- Flop:
- Board cards:
- Before any action is taken the request must contain the board cards.
- If a request is made to this point in the game without board cards, the request will be rejected.
- SB checks:
- The second attached request example as appendix B, shows the request for this action, up to this point.
- A new street starts and players are allowed to check.
- No chips added to the pot, the pot remains at 3600 chips.
- STD checks:
- No chips added to the pot, the pot remains at 3600 chips.
- HJ bets 200 chips:
- With the new street all raise amounts are reset to 0, so the HJ player can do the minimum legal raise of 200 chips.
- Current pot size is 3600 + 200 = 3800 chips.
- BTN raises to 3000 chips:
- The BTN player raises 3000 chips, which are 200 from the incoming raise plus 2800 more chips.
- Current pot size is 3800 + 3000 = 6800 chips.
- SB calls:
- By calling, SB also adds 3000 chips to the pot.
- Current pot size is 6800 + 3000 = 9800 chips.
- STD folds:
- No chips added to the pot.
- HJ calls / goes all in:
- HJ player wants to call the BTN raise, so he needs to add 2800 more chips to the pot. However, he has less than that amount in his stack.
- In order to calculate the amount of chips the HJ player has, lets start by listing all the chips HJ player has spent throughout all the actions:
- Ante: -100 chips
- Preflop: -600 chips
- Initial raise in flop: -200 chips
- Now we can deduce from the initial stack amount: 3500 - 100 - 600 - 200 = 2600 chips left in the stack.
- Since the HJ player has less than 2800 chips in his stack, he needs to go all in to call the BTN raise.
- The API will accept an action "call" and internally it will handle the "allin call" correctly.
- Current pot size is 9800 + 2600 = 12400 chips.
- Board cards:
- Turn:
- Board cards:
- Now for the next street another action must be added containing the turn card.
- SB checks:
- No chips added to the pot, the pot remains at 12400 chips.
- BTN goes all in:
- First, note that HJ is not making any action since he is already all in. We can skip his action entirely.
- BTN player goes allin, and allin actions require an amount associated with it.
- The allin amount to send to the API is just the remaining chips from BTN player stack size.
- BTN player stack size is 21000 - 100 - 600 - 3000 = 17300 chips.
- The amount of the allin will be 17300 chips.
- SB final action as hero:
- Now we will place a request to the API to suggest a strategy for the SB player.
- The request is shown in the Appendix C.
- Board cards:
Appendix
Appendix A: Request for first SB action in action analysis example
{
"request_id": "action-analyses-0001",
"hand": {
"gameuuid": "hand-number-0005",
"game_mode_code": "normal",
"big_blind": 100,
"ante": 100,
"dealer_seat": 0,
"sb_seat": 1,
"bb_seat": 2,
"straddle_seat": 3,
"players": [
{
"seat_no": 0,
"stack": 11000
},
{
"seat_no": 1,
"stack": 10000,
"hole_cards": "TsJs"
},
{
"seat_no": 2,
"stack": 20000
},
{
"seat_no": 3,
"stack": 15000
},
{
"seat_no": 4,
"stack": 17000
},
{
"seat_no": 5,
"stack": 3500
},
{
"seat_no": 6,
"stack": 13500
}
],
"actions": {
"entries": [
{
"action": "fold" // UTG in seat 4
},
{
"action": "raise", // HJ in seat 5
"amount": 400
},
{
"action": "call" // CO in seat 6
},
{
"action": "raise", // BTN in seat 0
"amount": 600
}
]
}
}
}Appendix B: Request for second SB action, first flop action in action analysis example
{
"request_id": "action-analyses-0002",
"hand": {
"gameuuid": "hand-number-0005",
"game_mode_code": "normal",
"big_blind": 100,
"ante": 100,
"dealer_seat": 0,
"sb_seat": 1,
"bb_seat": 2,
"straddle_seat": 3,
"players": [
{
"seat_no": 0,
"stack": 11000
},
{
"seat_no": 1,
"stack": 10000,
"hole_cards": "TsJs"
},
{
"seat_no": 2,
"stack": 20000
},
{
"seat_no": 3,
"stack": 15000
},
{
"seat_no": 4,
"stack": 17000
},
{
"seat_no": 5,
"stack": 3500
},
{
"seat_no": 6,
"stack": 13500
}
],
"actions": {
"entries": [
{
"action": "fold" // UTG in seat 4
},
{
"action": "raise", // HJ in seat 5
"amount": 400
},
{
"action": "call" // CO in seat 6
},
{
"action": "raise", // BTN in seat 0
"amount": 600
},
{
"action": "call" // SB in seat 1
},
{
"action": "fold" // BB in seat 2
},
{
"action": "call" // STD in seat 3
},
{
"action": "call" // HJ in seat 5
},
{
"action": "fold" // CO in seat 6
},
{
"action": "8dAsAc"
}
]
}
}
}Appendix C: Request for last SB action, last action in the game during turn
{
"request_id": "action-analyses-0003",
"hand": {
"gameuuid": "hand-number-0005",
"game_mode_code": "normal",
"big_blind": 100,
"ante": 100,
"dealer_seat": 0,
"sb_seat": 1,
"bb_seat": 2,
"straddle_seat": 3,
"players": [
{
"seat_no": 0,
"stack": 21000
},
{
"seat_no": 1,
"stack": 10000,
"hole_cards": "TdJd"
},
{
"seat_no": 2,
"stack": 20000
},
{
"seat_no": 3,
"stack": 15000
},
{
"seat_no": 4,
"stack": 17000
},
{
"seat_no": 5,
"stack": 3500
},
{
"seat_no": 6,
"stack": 13500
}
],
"actions": {
"entries": [
{
"action": "fold" // UTG in seat 4
},
{
"action": "raise", // HJ in seat 5
"amount": 400
},
{
"action": "call" // CO in seat 6
},
{
"action": "raise", // BTN in seat 0
"amount": 600
},
{
"action": "call" // SB in seat 1
},
{
"action": "fold" // BB in seat 2
},
{
"action": "call" // STD in seat 3
},
{
"action": "call" // HJ in seat 5
},
{
"action": "fold" // CO in seat 6
},
{
"action": "8dAsAc"
},
{
"action": "check" // SB in seat 1
},
{
"action": "check" // STD in seat 3
},
{
"action": "bet", // HJ in seat 5
"amount": 200
},
{
"action": "raise", // BTN in seat 0
"amount": 3000
},
{
"action": "call" // SB in seat 1
},
{
"action": "fold" // STD in seat 3
},
{
"action": "call" // HJ in seat 5
},
{
"action": "Jh"
},
{
"action": "check" // SB in seat 1
},
{
"action": "allin", // BTN in seat 0
"amount": 17300
}
]
}
}
}