Rest API Manual - Texas Hold 'Em and Blackjack

Available calls:

All API calls return a string Result value as the first field in the returned data. Possible values are:

SUCCESS
CALL_ALREADY_IN_PROCESS
WAITING_FOR_GAME
GAME_ALREADY_STARTED
GAME_HAS_ENDED
INVALID_LOGIN_OR_PASSWORD
INVALID_PLAYER_KEY
BOT_IS_SUSPENDED
BOT_IS_INACTIVE
INSUFFICIENT_BALANCE
NOT_YOUR_MOVE
INVALID_MOVE

Get List Of Game Styles

Request to receive the current list of available game styles for the specified GameType as well as the bot’s current balance.

URL: http://www.aigaming.com/Api/GetListOfGameStyles

Parameters:

Name Type Notes
BotId string
BotPassword string
GameTypeId int Only supported values right now are 3 for Texas Hold ‘Em and 6 for Duplicate Blackjack

Return values:

Name Type Notes
Result string
GameStyles Array of GameStyleType
Balance int Bot balance in satoshi

GameStyleType object:

Name Type Notes
GameStyleId int Unique id referring to this game style
GameType int Game type - only supported value is 3 for Texas hold 'em
Stake int Cost to enter game in satoshi
Prize int Prize awarded to winner of game
MoveTime int Length of time client is permitted to make its move, in milliseconds
Parameter1 int GameType specific, for Texas hold 'em and blackjack this is starting stack in chips.
Parameter2 int GameType specific, for Texas hold 'em this is maximum number of deals per game; for blackjack it is number of 52 card packs of cards included in the deck
Playing int Number of players currently playing this game style
Waiting int Number of players currently waiting to play this game style (not necessarily available to play this client due to OfferGame options)

Offer Game

This allows the user to offer to play a game. Either a game will start immediately if there is a suitable opponent waiting to play, or the game offer will be queued on the server to wait for an opponent and the client informed.

URL: http://www.aigaming.com/Api/OfferGame

Parameters:

Name Type Notes
BotId string
BotPassword string
MaximumWaitTime int The server will delay returning a result from this call for up to this number of milliseconds. If an opponent is available or becomes available during this period, the server returns immediately. Valid values are 0 - 5000, default value is 500
GameStyleId int Requested game style id
DontPlayAgainstSameUser boolean If set to true, the server will not start a game against another client which is logged in using a BotId from the same user account as this one.
DontPlayAgainstSameBot boolean If set to true, the server will not start a game against another client which is logged in using the same BotId as this one. [Not currently supported]
OpponentId string If set, server will only start a game against a client logged in with the specified BotId

Return values:

Name Type Notes
Result string If an opponent is available, a game will start immediately, and Result will be SUCCESS , if no suitable opponent is available right now, Result is WAITING_FOR_GAME, and the request is queued.
GameState GameStateType GameStateType is a GameType specific set of values describing the current state of the game. Only defined if a game is starting immediately
PlayerKey string This is a unique code created by the server which should be used in all future calls related to this game offer or resulting game

GameStateType - for GameType 3: Texas Hold 'Em

Name Type Notes
BigBlind int The amount of the big blind in chips
BoardCards Array of string Cards are specified by a two character string - see below
DealCount int Maximum number of deals in this game
DealNumber int Current deal number, starting at 1
GameId int Unique id for this game
GameStatus string Text description of current status of game, e.g. RUNNING or DRAWN see below
IsDealer boolean If true, indicates that this client is in the dealer position in this deal
IsMover boolean If true, indicates that the server is waiting for this client to send a move
MandatoryResponse bool If true, indicates that the client will lose the game if they do not submit a move by the timeout deadline
OpponentHand Array of string Opponent's hole cards. These will be "XX", "XX" for most of the deal
OpponentRoundBetTotal int Total chips the opponent has bet in this betting round in chips
OpponentStack int Opponent's remaining chips
PlayerHand Array of string This client's hole cards
PlayerRoundBetTotal int Total chips this client has bet in this betting round in chips
PlayerStack int This client's remaining chips
PotAfterPreviousRound int The size of the pot in chips after the previous round of betting
ResponseDeadline datetime The deadline by which the client should send its move to the server in UTC
Round int The current betting round - 0:Preflop, 1:Flop, 2:Turn, 3:River, 4:Showdown
SmallBlind int The amount of the small blind in chips

Format of cards

Cards are identified by a two character string.
The first character is the rank and is one of: '2', '3', '4', '5', '6', '7', '8', '9', 'T', 'J', 'Q', 'K', 'A'
The second character is the suit and is one of: 'H', 'C', 'D', 'S'
So for example "JC" is the Jack of Clubs

The special value "XX" indicates a card which has been dealt but is face down, i.e. not yet visible to this client.

GameStatus values

Value Notes
STARTING_SOON Game will start shortly
RUNNING Game is in progress
WON Game is over and this client won
WON_BY_TIMEOUT This client won by the other player timing out
LOST This client lost
LOST_BY_TIMEOUT This client lost by timing out
DRAWN The game ended in a draw

GameStateType - for GameType 6: Duplicate Blackjack

Name Type Notes
AllCardsSeen Array of string A list of all the cards that have been dealt off the deck since the beginning of the game
CardsRemaining int The number of cards remaining in the deck
DealNumber int Current deal number, starting at 1
DealerCards Array of string The dealer's cards. Two cards are dealt initially of which only one is visible
GameId int Unique id for this game
GameStatus string Text description of current status of game, e.g. RUNNING or DRAWN see GameStatus
IsMover boolean If true, indicates that the server is waiting for this client to send a move
MandatoryResponse bool If true, indicates that the client will lose the game if they do not submit a move by the timeout deadline
OpponentStack int Opponent's remaining chips before this deal
PlayerCards Array of string This client's cards. Two cards are dealt initially
PlayerStack int This client's remaining chips
PreviousDealDealerCards Array of string All the dealer's cards from the previous deal
PreviousDealPlayerCards Array of string All this client's cards from the previous deal
PreviousDealResult string The result of the previous deal
ResponseDeadline datetime The deadline by which the client should send its move to the server in UTC
Round int The current deal round. Round 1 is where the client sets the bet size; in all subsequent rounds, the client specifies what action they would like to take

PreviousDealResult values

Value Notes
N/A This is the first deal
WON_BY_SHOWDOWN This player won by having a higher total or better hand than the dealer
WON_BY_BUSTING This player won because the dealer busted (had cards totaling more than 21)
LOST_BY_SHOWDOWN This player lost by having a lower total or worse hand than the dealer
LOST_BY_BUSTING This player lost because they busted
PUSH The result of the deal was a draw

Cancel Game Offer

Request to cancel a current GameOffer. This can be called before a game has started to cancel the offer from the server's queue.

URL: http://www.aigaming.com/Api/CancelGameOffer

Parameters:

Name Type Notes
BotId string
BotPassword string
PlayerKey string

Return values:

Name Type Notes
Result string If a game already started before this call was made, the Result value is GAME_ALREADY_STARTED and the GameState of the game is returned. If the game offer can be cancelled, Result is SUCCESS.
GameState GameStateType Only returned if a game has already started, otherwise null
Balance int The bot balance after the game offer is cancelled, only returned if the game offer was successfully cancelled, otherwise null

Poll For Game State

Request to receive current game state.

URL: http://www.aigaming.com/Api/PollForGameState

Parameters:

Name Type Notes
BotId string
BotPassword string
MaximumWaitTime int The server will delay returning a result from this call for up to this number of milliseconds. If the client has an out of date game state or the server is waiting for this player to move, the server will return immediately. Otherwise the server will return as soon as the game state changes. If the game state does not change for the whole of this period, the current game state is returned at the end of the period. Valid values are 0 - 5000, default value is 500
PlayerKey string

Return values:

Name Type Notes
Result string If no game has yet been started, Result is WAITING_FOR_GAME. If a game has started, Result is SUCCESS
GameState GameStateType This is only returned if a game is underway or completed

Make Move

Used to send the client's chosen game move to the server.

URL: http://www.aigaming.com/Api/MakeMove

Parameters:

Name Type Notes
BotId string
BotPassword string
PlayerKey string
Move MoveType MoveType is specific for which GameType client is playing

MoveType - for GameType 3: Texas Hold 'Em

Name Type Notes
Fold boolean Indicates that the client wishes to fold
BetSize int The bet size the client wishes to make

MoveType - for GameType 6: Duplicate Blackjack

Name Type Notes
BetSize int The bet size the client wishes to make - not required in rounds 2 and above
Action string The action the client wishes to take - not required in round 1

Action values

Value Notes
HIT Request an additional card - the server adds an additional card to the player's cards and if the player has not busted, the player is asked for their next move
STAND The player indicates they do not require any further cards and the dealer plays it's cards to complete the deal. The next GameState the player will be sent is for the first round of the next deal, and the result of this deal will be available in the "PreviousDealResult" etc. fields
DOUBLE The player requests to double their bet and receive exactly one more card. If the player has less chips remaining than required to double the bet, all their remaining chips are bet. If the additional card results in the player going bust, the deal is over and the dealer wins. If not, the dealer then plays out the remainder of the deal as in STAND

Return values:

Name Type Notes
Result string
GameState GameStateType The state of the game after the client's move has been processed

Simple Example (C#)

var httpWebRequest = (HttpWebRequest)WebRequest.Create("http://www.aigaming.com/Api/OfferGame");
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";
 
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
    // JSON value is: {"BotId":"mybotid","BotPassword":"mybotpassword","MaximumWaitTime":null,"GameStyleId":37,"DontPlayAgainstSameUser":"false","DontPlayAgainstSameBot":"false","OpponentId":null}
    // but we must escape " characters in C# literal string...
    string json = "{\"BotId\":\"mybotid\",\"BotPassword\":\"mybotpassword\",\"MaximumWaitTime\":null,\"GameStyleId\":37,\"DontPlayAgainstSameUser\":\"false\",\"DontPlayAgainstSameBot\":\"false\",\"OpponentId\":null}";
    streamWriter.Write(json);
}
 
string result;
 
using (var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse())
{
    using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
    {
        result = streamReader.ReadToEnd();
    }
}

Sample result value:

{"Result":"WAITING_FOR_GAME","GameState":null,"PlayerKey":"06bc85c1-8b06-491f-b02c-c7daf1aa60ef"}

Test the API with Postman

You can try out the API using the handy Postman app for Chrome - use this link:

https://www.getpostman.com/apps

Demo API Program

You can find a quick Visual Studio C# demo of using the API here:

https://s3.eu-west-2.amazonaws.com/aigaming/QuickPokerAPIDemo.zip

Unzip into a folder and double click QuickPokerAPIDemo.sln

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License