The Hacker School Poker Engine (HSPE) is a persistently running game server that coordinates and executes games of poker. Remote users can connect to HSPE and participate in games of poker against other remotely-connected users. The HSPE API provides a Restful interface with lightweight JSON-formatted responses to interact with the HSPE.

This documentation provides an overview of how the Hacker School Poker Engine (HSPE) operates and how you can use the API to build AI bots to play games of poker.

Games of poker in HSPE are played using the rules of No Limit Texas Holdem. We also enforce the following rules:

• Each game has a maximum of 10 players allowed.

• Each game has a minimum of 2 players required to play the game. If you are the only player in a game the game will not start until another player joins.

• All players start with $10,000

• Big blinds are $20, Small blinds are $10

Betting is allowed in increments no smaller than $1 (no floating point bets). All bets sent to HSPE must be valid. Invalid bets will lead to you immediately folding your hand. Invalid bets are:

• Bets with negative values

• Bets greater than your current wealth

• Bets less than the minimum required to call and less than your current wealth (you are allowed to bet less than the amount required to call if this bet would put you “all in”)

• Bets that raise on the previous bet, but do so less than the minimum raise amount as defined by the general rules of poker (you must raise at least as much as the last raise amount)

It is the responsibility of a player to query HSPE at regular intervals and get the state of the game they are playing. There is currently no rate limiting enforced but we suggest players to query HSPE no more than once every 50ms

A player can join a game at any time. If a hand is in progress, the player will start playing at the beginning of the next hand. If the game is full, the player will be put in queue and will start playing once there is a seat open at the table.

A player can fold and leave a game at any time.

HSPE will only accept bet/fold orders from a player when it is that player's turn. Orders sent when it is not that player's turn will be ignored. When it is a player's turn, they will have a 15 second window to send a bet/fold instruction before HSPE times out and removes the player from the game.

Fork the github repo, run go build, then run pokerserver. This will start up a server running on your machine on port 8080.

HSPE will be hosted on port 8080. Say you spin up a instance of the server running on 127.0.0.1. A request to retrieve all active games would look like:

GET https://127.0.0.1:8080/games/

Some requests to HSPE need to be authenticated. HSPE uses HTTP basic authentication for this purpose.

The bodies of successful responses will be sent in JSON format. Unsuccessful responses, those with error codes, maybe be sent as plain text not formatted as JSON.

The following documentation assume the server is running on 127.0.0.1:8080. Replace this address with the appropriate location of the server.

Fields

Fields

Notes
Each round will have at least one Pot. Some rounds might have multiple pots if side pots are needed. Pots are ordered chronologically earliest to latest

Fields

Fields

Fields

Notes
flop, turn, and river are populated when the appropriate round is reached, and are otherwise null values. Cards are represented as strings of two characters. For example, the ace of spades is “AS”, the two of hearts is “2H”, and the ten of clubs is “TC”.

Fields

Request:

GET http://127.0.0.1:8080/games/fbbbbb44-bc4f-c3f6-6519-d81bd1a66d8a

Response:

[
   {
      "gameID":"fbbbbb44-bc4f-c3f6-6519-d81bd1a66d8a",
      "table":[
         {
            "playerID":"2fd318e4-0947-64b9-8b63-14f5a5824b8b",
            "handle":"",
            "state":"active",
            "wealth":15002,
            "bet_so_far":0,
            "small blind":true
         },
         {
            "playerID":"0dd7d693-06f9-b5ba-694d-f8779579fa8a",
            "handle":"",
            "state":"active",
            "wealth":4006,
            "bet_so_far":0,
            "small blind":false
         }
      ],
      "turn":{
         "playerID":"2fd318e4-0947-64b9-8b63-14f5a5824b8b",
         "bet_so_far":0,
         "bet_to_player":0,
         "minimum_raise":0,
         "expiry":"2014-09-24 15:14:53.021303798 -0400 EDT"
      },
      "cards":{
         "hole":[
            "AC",
            "TD"
         ],
         "flop":[
            "2S",
            "3S",
            "JS"
         ],
         "turn":[
            "4D"
         ],
         "river":[
            "AH"
         ]
      },
      "pots":[
         {
            "size":60,
            "players":[
               "8c479795-adcb-a3c1-bebd-4bdf54016f4a",
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         },
         {
            "size":0,
            "players":[
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         },
         {
            "size":0,
            "players":[
               "2fd318e4-0947-64b9-8b63-14f5a5824b8b",
               "0dd7d693-06f9-b5ba-694d-f8779579fa8a"
            ]
         }
      ]
   }
]