Internet Poker Protocol (IPP)
Version 2.0
29 Oct 1999

This is a living document. A sample session and revision history follow the definitions.

Definitions

Elements of messages can be separated by spaces or tabs unless noted below.

Messages are interpreted without respect for case unless noted below.

The following definitions are used in the descriptions that follow.

• rank: One of A, 2, 3, 4, 5, 6,7, 8, 9, T, J, Q, or K. Note that the rank of ``ten'' is denoted by T.

• suit: One of S, H, D, or C.

• card: A rank and suit with no intervening whitespace, for example 7H for the seven of hearts or TC for the ten of clubs.

• name: Sequence of non-space characters, for example ``Fred'' or ``Mr_Smith''.

• amt: A number (sequence of digits) representing an amount of money.

Handshaking Messages

• IPP version info
  The server will send this message after accepting a new connection (version is the protocol version, info is simply an informational string).

• BUYIN name amt
  This should be the first message sent by a player to the server upon connection to add themselves to the game with an initial stake of amt.

• WELCOME name
  The server will respond with this when the player has been added to the game.

Information Messages

• NEWGAME type ...
  Sent by the server to start a new game. The type and parameters identifies the game being played:
  • For Texas Holdem, the type will be HOLDEM, followed by three numeric parameters indicating the low and high limits, respectively, and the maximum number of raises per round.
    Example: NEWGAME HOLDEM 10 20 3.
  • For Five-Card Draw, the type will be DRAW, followed by the same three parameters.
    Example: NEWGAME DRAW 10 20 3.
  • For Five- or Seven-Card Stud, the type will be STUD, followed by four numeric parameters. The first parameter will be the number of cards (5 or 7). The other three parameters are as above.
    Example: NEWGAME STUD 7 10 20 3.

• PLAYER name amt
  Sent by the server before play starts to identify a player and their starting stake. Players are announced in seated order clockwise from the dealer.
  Example: PLAYER Fred 1000.

• BUTTON name
  Sent by the server at the start of each hand in a game to identify the player on the button (first to bet). The button rotates clockwise from the first seated player.
  Example: BUTTON Fred.

• ANTE amt
  Sent by the server to remind a player that they have anted the indicated amt.
  Example: ANTE 5.

• DEAL card card
  Sent by the server to tell a player their hole cards. In Texas Holdem there are two hole cards, in Draw Poker there are five, in Five-Card Stud there is one, and in Seven-Card Stud there are two (initially).
  Example: DEAL AS 7H.

• FROM name msg
  Sent by the server to tell other players that the player named name has sent the given msg. Not all messages are copied, but any message that may be useful in tracking the state of the game will be copied to all other players. This includes in particular the responses to the ACTION?, SHOW?, and BEAT? messages described in the next sections.

Texas Holdem Messages

• FLOP card card card
  Sent by the server in Texas Holdem to announce the first three common cards.
  Example: FLOP 8C TS QS.

• TURN card
  Sent by the server in Texas Holdem to announce the fourth common card.
  Example: TURN 2D.

• RIVER card
  Sent by the server in Texas Holdem to announce the fifth and last common card.
  Example: RIVER KD.

Draw Poker Messages

• DRAW?
  Sent by the server to ask a player how many cards they wish to draw. Valid responses are:
  • FOLD: Folds the player for this hand.
  • DRAW num card card ...: Asks to draw num cards, and lists the cards being traded in. Note that this message is copied to other players in a FROM message with only the num indicated.

• DRAWN num card card...: Sent by the server to indicate the new cards drawn by the player.

Stud Poker Messages

• UP card
  Sent by the server to inform a player of a new up (public) card. Note that this message is copied to other players as a FROM message so that they can know what the public cards are (this is a minor overloading of the ``FROM'' notation).

• DOWN card
  Sent by the server to inform a player of a new down (private) card.

Betting Messages

• ACTION? BLIND amt
  Sent by the server to the player who is required to make the blind bet (if required). In Texas Holdem, the player on the button (or next remaining player) must bet blind in the first two rounds. The acceptable responses are:
  • BLIND amt: Makes the blind bet.
  • TAPOUT amt': Taps out for the blind bet (see the description of ACTION?, below).

• ACTION? STRADDLE amt
  Sent by the server to the player who is required to make the straddle bet (if required). In Texas Holdem, the player following the blind bettor must straddle in the first two rounds. The acceptable responses are:
  • STRADDLE amt: Makes the straddle bet.
  • FOLD: Folds the player for this hand. The next player will then be required to make the straddle bet.
  • TAPOUT amt': Taps out for the straddle bet (see the description of ACTION?, below).

• ACTION? OWING amt
  Sent by the server when it is a player's turn to bet other than the blind or the straddle. There are several possible responses:
  • CALL amt: Calls the current bet (ie., puts amt into the pot).
  • RAISE amt': Raises the current bet (ie., puts amt' == amt + limit into the pot).
  • FOLD: Folds the player for this hand.
  • OPEN amt: Opens the betting by betting amt, which must be the current limit. This response can only be sent if the betting has not yet been opened (either by a BLIND or an OPEN).
  • CHECK: Checks the bet (passes without betting). This response can only be sent if the betting has not yet been opened (either by a BLIND or an OPEN).
  • TAPOUT amt': Can only be sent if a player has less than amt cash left. This amt' is added to the pot and the player is tapped-out for the rest of the hand.

Showdown Messages

• STRAIGHTFLUSH rank
  A straight flush whose highest card is the given rank.
  Example: ``Straight flush, jack high'' = STRAIGHTFLUSH J
• FOUROFAKIND rank rank
  A four-of-a-kind of the first given rank, with a ``kicker'' card of the second given rank (both ranks are needed to handle ties in games with common cards).
  Example: ``Four sevens with ace kicker'' = FOUROFAKIND 7 A
• FULLHOUSE rank rank
  A full house whose three-of-a-kind is of the first given rank and whose pair is of the second given rank (both ranks are needed to handle ties in games with common cards).
  Example: ``Full house, queens and threes'' = FULLHOUSE Q 3
• FLUSH rank rank rank rank rank
  A flush whose five cards are of the given ranks, listed from highest to lowest.
  Example: ``Ten-high flush (ten, nine, eight, six, two of hearts)'' = FLUSH T 9 8 6 2
• STRAIGHT rank
  A straight whose highest card is the given rank.
  Example: ``King-high straight'' = STRAIGHT K
• THREEOFAKIND rank rank rank
  A three-of-a-kind of the first given rank, with ``kicker'' cards of the other two rank's, highest card first. (both ranks are needed to handle ties in games with common cards).
  Example: ``Three twos, queen, seven'' = THREEOFAKIND 2 Q 7
• TWOPAIR rank rank rank
  Two pairs of the given ranks listed from highest to lowest, and a fifth card of the third rank.
  Example: ``Two pair, jacks and eights, ace kicker'' = TWOPAIR J 8 A
• ONEPAIR rank rank rank rank
  One pair of the given rank, and third, fourth, and fifth cards of the remaining ranks, listed from highest to lowest.
  Example: ``Pair of tens, ace, five, three'' = ONEPAIR T A 5 3
• HIGHCARD rank rank rank rank rank
  A hand without even a pair whose five cards are of the given ranks, listed from highest to lowest.
  Example: ``Queen-high (QS TD 8C 7C 2D)'' = HIGHCARD Q T 8 7 2

The following messages are sent during a showdown when not playing ``cards speak.'' Possible responses are described below.

• SHOW?
  Sent by the server to the player being called to show their hand. The only acceptable response is:
  • SHOW handtype

• SHOW player card card ...
  Sent by the server to all players after a player has announced a hand, to tell the other players what that player's hole cards are. What hand the player announced will arrive in the form of a FROM message of type SHOW. No response is expected or permitted.

• BEAT? handtype
  Sent by the server to remaining players to ask if they can beat the given handtype. The two possible responses are:
  • NO
    Indicates that the player cannot beat the announced hand and must fold.
  • YES handtype
    Indicates that the player can beat the announced hand and announces the better hand.

End-of-hand Messages

• WINNER name amt handtype
  Sent by the server to indicate the winner of the hand, the amount they won, and the winning handtype. Note that in the case of ties or tap-outs, several WINNER messages may be sent by the server.

• BUSTED name
  Sent by the server to indicate a player without enough money left to stay in the game. These players can continue to receive messages but will no longer be involved in the play. That is, they will never be dealt cards nor be asked to bet or participate in a showdown.

• GAMEOVER name amt
  Sent by the server to indicate the final winner of the game. Also indicates the end of the game.

Miscellaneous Messages

• QUIT name
  Indicates that a player has unexpectedly quit the game. This should be treated like BUSTED, except that it can occur anytime if the player drops the connection to the server or is otherwise uncooperative.

Illustrative Examples

In Texas Holdem, the flow of the game is as follows (from the perspective of one player):

• DEAL card
• Betting round (low limit)
• FLOP card card card
• Betting round (low limit)
• TURN card
• Betting round (high limit)
• RIVER card
• Betting round (high limit)
• Showdown

In Draw poker, the flow of the game is as follows:

• DEAL card card card card card
• Betting round (low limit)
• DRAW?
• DRAW num card card...
• DRAWN num card card...
• Betting round (high limit)
• Showdown

In 5-Card Stud, the flow of the game is as follows:

• DEAL card
• UP card
• Betting round (low limit)
• UP card
• Betting round (low limit)
• UP card
• Betting round (high limit)
• UP card
• Betting round (high limit)
• Showdown

• DEAL card card
• UP card
• Betting round (low limit)
• UP card
• Betting round (low limit)
• UP card
• Betting round (high limit)
• UP card
• Betting round (high limit)
• DOWN card
• Betting round (high limit)
• Showdown

Sample Session

Assume that initially no players are connected, then three players (clients) named Alpha, Beta, and Gamma join.

Connection established with Alpha
From server to Alpha:	IPP 1.0 ...
From Alpha to server:	BUYIN Alpha 1000
From server to Alpha:	WELCOME Alpha
Connection established with Beta
From server to Beta:	IPP 1.0 ...
From Beta to server:	BUYIN Beta 1000
From server to Beta:	WELCOME Beta
Connection established with Gamma
From server to Gamma:	IPP 1.0 ...
From Gamma to server:	BUYIN Gamma 1000
From server to Gamma:	WELCOME Gamma
Game starts...
From server to Alpha	NEWGAME HOLDEM 10 20
From server to Beta	NEWGAME HOLDEM 10 20
From server to Gamma	NEWGAME HOLDEM 10 20
From server to Alpha	PLAYER Alpha 1000
From server to Beta	PLAYER Alpha 1000
From server to Gamma	PLAYER Alpha 1000
From server to Alpha	PLAYER Beta 1000
From server to Beta	PLAYER Beta 1000
From server to Gamma	PLAYER Beta 1000
From server to Alpha	PLAYER Gamma 1000
From server to Beta	PLAYER Gamma 1000
From server to Gamma	PLAYER Gamma 1000
Hand starts...
From server to Alpha	BUTTON Alpha
From server to Beta	BUTTON Alpha
From server to Gamma	BUTTON Alpha
From server to Alpha	ANTE 5
From server to Beta	ANTE 5
From server to Gamma	ANTE 5
From server to Alpha	DEAL 5H TC
From server to Beta	DEAL AD JD
From server to Gamma	DEAL 2C 8S
First betting round (limit 10)...
From server to Alpha	ACTION? BLIND 5
From Alpha to server	BLIND 5
From server to Alpha	OK BLIND 5
From server to Beta	FROM Alpha BLIND 5
From server to Gamma	FROM Alpha BLIND 5
From server to Beta	ACTION? STRADDLE 10
From Beta to server	STRADDLE 10
From server to Beta	OK STRADDLE 10
From server to Alpha	FROM Beta STRADDLE 10
From server to Gamma	FROM Beta STRADDLE 10
From server to Gamma	ACTION? OWING 10
From Gamma to server	CALL 10
From server to Gamma	OK CALL 10
From server to Alpha	FROM Gamma CALL 10
From server to Beta	FROM Gamma CALL 10
From server to Alpha	ACTION? OWING 5
From Alpha to server	CALL 5
From server to Alpha	OK CALL 5
From server to Beta	FROM Alpha CALL 5
From server to Gamma	FROM Alpha CALL 5
Flop...
From server to Alpha	FLOP 7S 2H QD
From server to Beta	FLOP 7S 2H QD
From server to Gamma	FLOP 7S 2H QD
Second betting round (limit 10)...
From server to Alpha	ACTION? BLIND 5
From Alpha to server	BLIND 5
From server to Alpha	OK BLIND 5
From server to Beta	FROM Alpha BLIND 5
From server to Gamma	FROM Alpha BLIND 5
From server to Beta	ACTION? STRADDLE 10
From Beta to server	STRADDLE 10
From server to Beta	OK STRADDLE 10
From server to Alpha	FROM Beta STRADDLE 10
From server to Gamma	FROM Beta STRADDLE 10
From server to Gamma	ACTION? OWING 10
From Gamma to server	RAISE 20
From server to Gamma	OK RAISE 20
From server to Alpha	FROM Gamma RAISE 20
From server to Beta	FROM Gamma RAISE 20
From server to Alpha	ACTION? OWING 15
From Alpha to server	FOLD
From server to Alpha	OK FOLD
From server to Beta	FROM Alpha FOLD
From server to Gamma	FROM Alpha FOLD
From server to Beta	ACTION? OWING 10
From Beta to server	CALL 10
From server to Beta	OK CALL 10
From server to Alpha	FROM Beta CALL 10
From server to Gamma	FROM Beta CALL 10
Turn...
From server to Alpha	TURN 4D
From server to Beta	TURN 4D
From server to Gamma	TURN 4D
Third betting round (no blind, limit 20, Alpha has folded)...
From server to Beta	ACTION? OWING 0
From Beta to server	OPEN 20
From server to Beta	OK OPEN 20
From server to Alpha	FROM Beta OPEN 20
From server to Gamma	FROM Beta OPEN 20
From server to Gamma	ACTION? OWING 20
From Gamma to server	CALL 20
From server to Gamma	OK CALL 20
From server to Alpha	FROM Gamma CALL 20
From server to Beta	FROM Gamma CALL 20
River...
From server to Alpha	RIVER TS
From server to Beta	RIVER TS
From server to Gamma	RIVER TS
Fourth betting round...
From server to Beta	ACTION? OWING 0
From Beta to server	CHECK
From server to Beta	OK CHECK
From server to Alpha	FROM Beta CHECK
From server to Gamma	FROM Beta CHECK
From server to Gamma	ACTION? OWING 0
From Gamma to server	OPEN 20
From server to Gamma	OK OPEN 20
From server to Alpha	FROM Gamma OPEN 20
From server to Beta	FROM Gamma OPEN 20
From server to Beta	ACTION? OWING 20
From Beta to server	CALL 20
From server to Beta	OK CALL 20
From server to Alpha	FROM Beta CALL 20
From server to Gamma	FROM Beta CALL 20
Showdown (Gamma is being called)...
From server to Gamma	SHOW?
From Gamma to server	ONEPAIR 2 Q 8 7
From server to Gamma	OK ONEPAIR 2 Q 8 7
From server to Alpha	FROM Gamma ONEPAIR 2 Q 8 7
From server to Beta	FROM Gamma ONEPAIR 2 Q 8 7
From server to Beta	BEAT? ONEPAIR 2 Q 8 7
From Beta to server	NO
From server to Beta	OK NO
From server to Alpha	FROM Beta NO
From server to Gamma	FROM Beta NO
End of hand...
From server to Alpha	WINNER Gamma 170 ONEPAIR 2 Q 8 7
From server to Beta	WINNER Gamma 170 ONEPAIR 2 Q 8 7
From server to Gamma	WINNER Gamma 170 ONEPAIR 2 Q 8 7
Next hand starts...
From server to Alpha	BUTTON Beta
From server to Beta	BUTTON Beta
From server to Gamma	BUTTON Beta
...

Revision History

• 29 Oct 1999:
  • Protocol extensions for draw and stud poker.
  • Version bump to 2.0 because of this.
• 12 Oct 1999:
  • Fixed a couple of minor typos.
• 16 Oct 1998:
  • Extended FOUROFAKIND, FULLHOUSE, and THREEOFAKIND messages to include additional ranks since these are needed to break ties in games with common cards.
• 13 Oct 1998:
  • Added maximum number of raises per round to NEWGAME message.
  • Added QUIT messsage for player that unexpectedly quit.
• 26 Sep 1998:
  • Added SHOW message so others can track showdown.
  • Modified OK to include message being ACK'd.
• 25 Sep 1998:
  • Added examples to handtype descriptions.
  • STRADDLE bettor can FOLD.
  • HELLO renamed BUYIN.
  • A few typos.
• 23 Sep 1998: Initial release of IPP v1.0.