# Overview A tournament summary is an outline of all tournament information such as prize pools, players, place of finish and winnings. Much of this information is only available at the conclusion of a tournament. Without a tournament summary, tournament players are not able to accurately track their winnings. This specification is intended to be an open format that any poker site or network is free to use to ensure that they are providing complete tournament data to their players and the tournament summaries can be consumed via any tool of the customer's choice. {% hint style="info" %} **Online Poker Operators** If the specification does not meet your needs for a particular use case, please see the [Change Request Process](/contact-us/change-request-process) to learn how to submit your recommended changes for review and inclusion into the specification. The specification is versioned to allow for continual improvements. {% endhint %} {% hint style="info" %} **Third Party Developers** We strongly encourage every third party developer to support consumption of tournament summaries that follow the specification. If you believe that certain information is potentially missing or could be a benefit to be included in the tournament summary, please see the [Change Request Process](/contact-us/change-request-process) to learn how to submit your recommended changes for review and potential inclusion into the specification. The specification is versioned to allow for continual improvements. {% endhint %} # Guiding Principles Our guiding principles for making design choices. This specification was created and will be maintained by following these main principles: * **Open Standard:** * **No Intentional Secrets:** The standard does NOT withhold any detail necessary for interoperable implementation. As flaws are inevitable, the standard will fix flaws identified during implementation and interoperability testing and incorporate said changes into a revised version or superseding version of the standard to be released under terms that do not violate the open standard requirement. * **Availability:** The standard is freely and publicly available under royalty-free and patent-free terms. * **No Agreements:** There is no license agreements, NDA, grant, click-through or any other form of paper to deploy conforming implementations of the standard. * **Interoperable:** Implementation and consumption of the standard does not require any non open standard technology. * **Lossless:** * The standard should allow for no loss of data from the real-time events from the user's perspective. The user's perspective should be completely repayable via the user at any point in time after the hand has completed. * **Efficient** * The standard should be as efficient as possible without sacrificing data loss and portability. However, due to cheap storage, efficiency should always be the last guiding principle. # JSON Object Why we chose JSON. Every standardized tournament summary *MUST* contain one [standardized tournament summary JSON object](/less-than-standardized_tournament_summary-greater-than/less-than-standardized_tournament_summary-greater-than). We chose JSON due to it meeting the following needs: * It is plain text and accessible. * It is understandable by any person without requiring third party software (other than a text editor). * It is structured and the structure can be standardized and documented. * It is an efficient structured format. * JSON enjoys wide adoption and therefore has development libraries across all programming languages. # Storage Format How the JSON is stored on the user's computer. #### File and File Name Format: * All tournament summaries *MUST* be stored in plain text files. * All tournament summary files *MUST* have an .OTS file extension. * Filenames *MUST* use only ASCII characters. {% hint style="info" %} Other than the above requirements, hand history filenames can be named anything. We recommend including at least the tournament name in the filename. {% endhint %} #### Tournament Summary Groupings per File A tournament summary should be written to the tournament player's local computer as soon as the player busts from a tournament and there should be one [tournament summary JSON object](/less-than-standardized_tournament_summary-greater-than/less-than-standardized_tournament_summary-greater-than) per file. All of the information for the tournament, that is relevant to the tournament player should be available at that time. If multiple tournament summaries are requested by a user at a later date then multiple tournament summaries can be included in a single file. When multiple tournament summaries are included in a single file, each [tournament summary JSON object](/less-than-standardized_tournament_summary-greater-than/less-than-standardized_tournament_summary-greater-than) *MUST* be separated by one blank line such as: ``` {"ots":} {"ots":} {"ots":} ``` {% hint style="warning" %} If multiple tournament summaries are included in a single file, the resulting file will not be considered "valid" JSON. However, for this standard, it is considered acceptable. {% endhint %} # The Specification Standardized Tournament Summary specification. ### Standardized Tournament Summary specification **Type:** object **Format:** JSON **Version:** 1.1.5 **Structure:** ```javascript { "ots": { "spec_version": version_string, "site_name": string, "network_name": string, "internal_version": version_string, "tournament_number": string, "tournament_name": string, "start_date_utc": string, "end_date_utc": string, "currency": string, "buyin_amount": decimal, "fee_amount": decimal, "bounty_fee_amount": decimal, "bounty_value_amount": decimal, "initial_stack": integer, "type": string, "flags": array, "speed": , "prize_pool": decimal, "hero_player_name": string "player_count": integer, "tournament_finishes_and_winnings": [ , ] } } ``` **Examples:** [See examples.](/examples/sample-sit-n-go) # spec\_version Version of the tournament summary specification. #### spec\_version A string with information describing the version of the tournament summary specification. **Type:** string **Format:** [version\_string](/string-formats/version_obj) **Example:** ```javascript "spec_version": "1.2.3" ``` # site\_name The name of the site that the tournament was played on. #### site\_name The name of the site that the tournament was played on. **Type:** string **Example:** ```javascript "site_name": "MVS Poker Site" ``` # network\_name The name of the network that the tournament was played on. #### network\_name The name of the network that the tournament was played on. **Type:** string **Example:** ```javascript "network_name": "MVS Poker Network" ``` # internal\_version The site's internal version used to create the tournament summary. #### internal\_version The site's internal version used to create the tournament summary. {% hint style="danger" %} Any modification to the tournament summary format should increment the version. Even minor bug fixes! {% endhint %} **Type:** string **Format:** [version\_string](/string-formats/version_obj) **Example:** ```javascript "internal_version": "1.2.5" ``` {% hint style="info" %} It is recommended but not required to increment the major and minor versions of the internal\_version to match the spec\_version and bug fixes increment the patch number. {% endhint %} # tournament\_number The identifying tournament number. **tournament\_number** The tournament number as specified by the site.\ This should match the tournament number in the corresponding hand history file(s). **Type:** string **Example:** ```javascript "tournament_number": "1000001" ``` # tournament\_name A name describing the tournament #### tournament\_name The name of the tournament. **Type:** string **Example:** ``` "tournament_name": "MVS Super Series 6-max" ``` [
](https://hh-specs.handhistory.org/tournament-info-object/tournament_number) # start\_date\_utc The starting date and time of the tournament (in GMT/UTC). #### start\_date\_utc The starting date and time of the tournament (in GMT/UTC). {% hint style="warning" %} The time should ***always be in UTC/GMT*** regardless of the site or user's timezone. {% endhint %} **Type:** string **Format:** ISO8601 format. "yyyy-mm-ddThh:mm:ssZ" **Example:**\ See section 5.8 in the RFC: ```javascript "start_date_utc": "2017-12-31T09:45:26Z" ``` # end\_date\_utc The date and time that the tournament ended (in UTC/GMT). #### end\_date\_utc The date and time that the tournament was completed (in UTC/GMT). {% hint style="warning" %} The time should ***always be in UTC/GMT*** regardless of the site or user's timezone. {% endhint %} **Type:** string **Format:** ISO8601 format. "yyyy-mm-ddThh:mm:ssZ" **Example:**\ See section 5.8 in the RFC: ``` "end_date_utc": "2017-12-31T11:05:26Z" ``` # currency The currency of the game or tournament buy-in and fee. #### currency **Type:** string **Format:** [ISO4217 currency code​](https://www.iso.org/iso-4217-currency-codes.html) * "XPM" - Play Money; a currency with no monetary value * "XSC" - PokerStars coin * "TTS" - Tournament Tickets * "TBS" - Tournament Bucks {% hint style="info" %} If your site uses a coin specific to your site that has value and is not considered play money then please submit it to us for inclusion in the specification at which point we will include it and increase the specification's version number. Your site specific coin should be three characters and not conflict with any existing currencies. {% endhint %} Example: ```javascript "currency": "USD" ``` # buyin\_amount The buy-in amount for the tournament. #### buyin\_amount The buy-in amount for the tournament (as specified in [currency](https://ts-specs.handhistory.org/less-than-standardized_tournament_summary-greater-than/currency)). #### Type: #### Example: ```javascript "buyin_amount": 20.00 ``` # fee\_amount The fee paid to buy-in to the tournament. #### fee\_amount The fee paid to buy-in to the tournament (as specified in [currency](https://ts-specs.handhistory.org/less-than-standardized_tournament_summary-greater-than/currency)). **Type:** decimal **Example:** ```javascript "fee_amount": 2.00 ``` [
](https://hh-specs.handhistory.org/tournament-info-object/buyin_amount) # bounty\_fee\_amount The fee paid for the player's tournament bounty. #### bounty\_fee\_amount The fee paid for the player's tournament bounty. **Type:** decimal **Nullable:** true {% hint style="warning" %} For bounty tournaments only. Can be omitted or null for other tournaments. {% endhint %} **Example:** ```javascript "bounty_fee_amount": 5.00 ``` [
](https://hh-specs.handhistory.org/tournament-info-object/fee_amount) # bounty\_value\_amount The value of a single bounty winning. For progressives, it will always be the lowest amount a play can win for a single bounty that is not split. Note, this will often be the same as the bounty fee. **bounty\_value\_amount** The value of a single bounty winning. For progressives, it will always be the lowest amount a player can win for a single bounty that is not split.\ Note: this will often be the same as the bounty fee. **Type:** decimal **Nullable:** true {% hint style="warning" %} For bounty tournaments only. Can be omitted or null for other tournaments. {% endhint %} **Example:** ```javascript "bounty_value_amount": 5.00 ``` # initial\_stack The number of chips provided to the player to start the tournament. #### initial\_stack The number of chips provided to the player to start the tournament. **Type:** integer {% hint style="warning" %} The integer should ***not*** be formatted. No thousands separators, etc. {% endhint %} **Example:** ```javascript "initial_stack": 1500 ``` # type The type of the tournament. #### type The type of the tournament - single or multi-table. **Type:** string **Options:** * "STT": Single table tournament * "MTT": Multi-table tournament **Example:** A single table tournament. ```javascript "type": "STT" ``` # flags Descriptive properties of the tournament. #### flags Descriptive properties of the tournament. **Type:** array of strings **Options:** * "SNG": Sit 'N Go. * "DON": Double or nothing. Half of the players win double their buy-in and half win nothing. * "Bounty": Bounty. Players are awarded prizes for knocking out specific players. * "Shootout": A multi-table tournament played in stages where each table plays until one player remains, with the winners moving on to the next phase. * "Rebuy": Players are offered the opportunity to rebuy stacks of chips. There are various forms of this that include timed or when a player is felted, or a maximum number of rebuys. Rebuy tournaments where the only option for rebuy comes as the player is felted should be flagged as "Re-Entry" instead of rebuy tournaments. * "Matrix": One buyin is split between multiple games. Some of the prize pool is awarded for each game while another portion is awarded for the aggregate total placing between the games. * "Push\_Or\_Fold": For every hand you are required to fold or push all-in. * "Satellite": Prize includes entry into another tournament. * "Steps": Steps tournament where players incrementally gain seats to additional tournaments of greater value. * "Deep": Deep stack tournament. Starting stacks are more big blinds than a normal tournament starting stack. * "Multi-Entry": Players can have more than a single entry into the same tournament. It is not synonymous with rebuy tournaments, but rather includes tournaments where a player can have more than a single entry at the beginning of the tournament. * "Fifty50": Fifty fifty. Fifty percent of players win a prize. All winners are awarded the same base prize plus an amount based on the number of chips remaining in the player's stack when half of the players have been eliminated. * "Flipout": Players' hands are all played face up without betting rounds. * "TripleUp": A third of the players win three times their buy-in and the remaining players win nothing. * "Lottery": Fast action games with accelerated blind level timings and shorter stacks. The prize is randomly chosen before the game begins. * "Re-Entry": A player can re-enter a tournament after they are felted. * "Power\_Up": Three person game with special "powers" that are not typically possible in table games. * "Progressive-Bounty": Same as bounty tournaments except that bounty winning amounts can vary. Usually half of the bounty amount goes to the hand winner and the other half of the bounty is added to the winner's bounty. {% hint style="info" %} If your site/network offers a type of tournament that cannot be properly identified via one of the above flags then please see the [Change Request Process](https://hh-specs.handhistory.org/contact-us/change-request-process) to learn how to submit your request to include the flag in the specification at which point, once approved, it will get included and the specification version will be increased. {% endhint %} **Example:** Fifty, fifty sit 'n go. ``` "flags": [ "SNG", "Fifty50"] ``` [
](https://hh-specs.handhistory.org/tournament-info-object/type) # speed The speed the blinds increase in the tournament. #### speed The speed that the blinds increase in the tournament. **Type:** object [\](https://hh-specs.handhistory.org/speed-object/speed_obj)​ **Example:** ```javascript "speed": ``` [
](https://hh-specs.handhistory.org/tournament-info-object/flags) # prize\_pool The size of the prize pool to be distributed to the tournament winners. #### prize\_pool The size of the prize pool to be distributed to all of the tournament winners. **Type:** decimal **Example:** ```javascript "prize_pool": 123.00 ``` # hero\_player\_name The name of the hero player. **hero\_player\_name** The name of the 'hero' player that played the tournament. **Type**: string **Nullable:** true {% hint style="warning" %} If the tournament summary is not for a specific hero player then "hero\_player\_name" can either be omitted, or set to null. {% endhint %} **Example:** ``` "hero_player_name": "MVS Player" ``` # player\_count The number of players in the tournament. #### player\_count The total number of players in the tournament. **Type:** integer {% hint style="warning" %} The integer should ***not*** be formatted to include thousands separators. {% endhint %} **Example:** ```javascript "player_count": 2445 ``` # tournament\_finishes\_and\_winnings A list of all known finishes and prizes. #### tournament\_finishes\_and\_winnings An array of [\](/tournament-finish-object/tournament_finish_obj) objects listing the finishing positions and prizes of all players in the tournament, including those who have not yet been eliminated. **Type:** array of [\](/tournament-finish-object/tournament_finish_obj) objects {% hint style="info" %} One player can have several tournament finishes; for instance in re-entry or multiple-entry tournaments.\ A separate [\](/tournament-finish-object/tournament_finish_obj) should be supplied for each. {% endhint %} **Example:** ```javascript "tournament_finishes_and_winnings": [ , , ] ``` # rebuy\_cost The cost of a rebuy or re-entry **rebuy\_cost** The cost of a single rebuy or re-entry into the tournament. {% hint style="info" %} A tournament can only be a rebuy or a re-entry and this should specify the cost of a single rebuy or re-entry, including any fees charged. {% endhint %} {% hint style="warning" %} If the tournament is not a rebuy or re-entry this can be omitted, or set to null or zero. {% endhint %} Type: decimal Example: `"rebuy_cost": 10.00` # addon\_cost The cost of an add-on **addon\_cost** The cost of a single add-on in the tournament. {% hint style="warning" %} If the tournament is not a rebuy or re-entry this can be omitted, or set to null or zero. {% endhint %} **Type:** decimal **Example:** `"addon_cost": 10.00` # tournament\_rebuys Re-buys, add-ons and re-entries that occurred in the tournament. **tournament\_rebuys** A list of re-buys, add-ons and re-entries made by all players in the tournament. There should be one entry for each player who made a rebuy, re-entry or add-on. **Type:** array of \ objects **Example:** `"tournament_rebuys": [`\ `,`\ ``\ `]` # \ Speed. #### **\** Speed. **Type:** object **Structure:** ```javascript "speed": { "type": string, "round_time": integer } ``` # type Description of the speed at which the blinds increase. #### type The description at which the speed of the blinds increase. **Type:** string **Options:** * "Normal" * "Semi-Turbo" * "Turbo" * "Super-Turbo" * "Hyper-Turbo" * "Ultra-Turbo" {% hint style="info" %} Classification of the speed is at the site/network's discretion. {% endhint %} **Example:** ```javascript "type": "Semi-Turbo" ``` # round\_time The amount of time between blind increases. #### round\_time The amount of time (in seconds) between blinds increases. **Type:** integer **Format:** integer in seconds **Example:** Blinds increase every five minutes (300 seconds): ```javascript "round_time": 300 ``` # \ Object containing a tournament player's place of finish and winnings. #### tournament\_finish\_obj Object containing a tournament player's place of finish and winnings. **Type:** object **Example:** Player finished third, and won 10.00: ```javascript "tournament_finish": { "player_name": "My Player 1", "finish_position": 3, "still_playing": false, "prize": 10.00, "ticket_value": 0.00 } ``` Player has not yet been eliminated from the tournament: ```javascript "tournament_finish": { "player_name": "My Player 2", "still_playing": true, } ``` # player\_name The name of a player who played the tournament. #### player\_name The name of a player who played in the tournament. **Type:** string **Example:** ```javascript "player_name": "bot_name" ``` # finish\_position The player's place of finish. #### finish\_position The player's finishing position in the tournament. **Type:** integer **Nullable:** true {% hint style="warning" %} If the player has not yet been eliminated this can be omitted, or set to null or zero. {% endhint %} **Example:** The player finished in 155th place: ```javascript "finish_position": 155 ``` # still\_playing If the player is still playing. **still\_playing** Specifies whether or not the player is still active in the tournament.\ 'true' means that they are still playing and 'false' means that they have been eliminated. **Type:** boolean **Example:**\ The player is still playing in the tournament. ``` "still_playing": true ``` # prize The amount the player won in the the tournament as a prize. #### prize The amount the player won in the tournament as a prize, in the tournament currency. Bounties are not specified here, but are instead specified in the hand in which they are won. **Type:** decimal **Nullable:** true {% hint style="warning" %} If the player has not yet been eliminated this can be omitted, or set to null or zero. {% endhint %} **Example:**\ The player won a prize of $350 (or whatever currency the tournament is in). ```javascript "prize": 350.00 ``` # ticket\_value The value of a tournament ticket if it was awarded as part of the prize. #### ticket\_value The value of a tournament ticket if it was awarded as part of the prize, in the tournament currency. **Type:** decimal **Nullable:** true {% hint style="warning" %} If the player has not yet been eliminated this can be omitted, or set to null or zero. {% endhint %} **Example:** \ Player won a ticket worth $10 (or whatever currency the tournament is in). ```javascript "ticket_value": 10.00 ``` # \ An object defining tournament re-buys or re-entries, and add-ons. **tournament\_rebuy** An object defining the number of re-buys or re-entries, and add-ons, made by one player in the tournament. There should be one of this object for each player who made any rebuys, re-entries or add-ons in the tournament. {% hint style="info" %} A tournament can only be a rebuy or a re-entry.\ The "rebuys" field below specifies the number or rebuys or re-entries as appropriate to the type of tournament. {% endhint %} {% hint style="info" %} If a player paid a multiple of the cost to receive a multiple of the amount of chips then this should be specified as multiple rebuys/re-entries/add-ons. {% endhint %} **Type:** object **Structure:** `{`\ `"player_name": string,`\ `"rebuys": integer,`\ `"addons": integer`\ `}` **Example:** Player made 2 rebuys and 1 add-on. `{`\ `"player_name": "bot_name",`\ `"rebuys": 2,`\ `"addons": 1`\ `}`
# player\_name The name of a player who made a rebuy/re-entry or add-on. **player\_name** The name of a player who made a rebuy/re-entry or add-on in the tournament. **Type:** string **Example:** `"player_name": "bot_name"` # rebuys The number of rebuys or re-entries **rebuys** The total number or re-buys or re-entries made by a player in the tournament. {% hint style="info" %} If a player paid a multiple of the cost to receive a multiple of the amount of chips then this should be specified as multiple rebuys. {% endhint %} {% hint style="warning" %} If the player made no rebuys or re-entries this can be omitted, or set to null or zero. {% endhint %} **Type:** integer **Example:** `"rebuys": 2` # addons The number of add-ons addons The number of add-ons made by a player in the tournament. {% hint style="info" %} If a player paid a multiple of the cost to receive a multiple of the amount of chips then this should be specified as multiple add-ons. {% endhint %} {% hint style="warning" %} If the player made no add-ons this can be omitted, or set to null or zero. {% endhint %} **Type:** integer **Example:** `"addons": 1` # version\_string The version string consists of three parts. The version string consists of three integer parts each separated by a period. **Type:** string **Format:** \.\.\ * \ - (Integer) The major version number. Only increased for major changes. * \ - (Integer) The minor version number. Increased for non-major changes. * \ - (Integer) The patch version number. Increased on bug fix releases. **Example:** ```javascript "1.2.3" ``` # Sample Sit N' Go ```javascript { "ots": { "spec_version": "1.1.3", "site_name": "Anicka Poker", "network_name": "Anicka Poker", "internal_version": "1.0.3", "tournament_number": "1000001", "tournament_name": "$20 SNG", "start_date_utc": "2017-12-31T09:45:26Z", "end_date_utc": "2017-12-31T09:55:26Z", "currency": "USD", "buyin_amount": 20.00, "fee_amount": 2.00, "initial_stack": 1500, "type": "STT", "flags": [ "SNG" ], "speed": { "type": "Normal", "round_time": 600 }, "prize_pool": 120, "hero_player_name": "My Player 2", "player_count": 6, "tournament_finishes_and_winnings": [ { "player_name": "My player 1", "finish_position": 1, "still_playing": false, "prize": 60.00, "ticket_value": 0.00 }, { "player_name": "My player 2", "finish_position": 2, "still_playing": false, "prize": 35.00, "ticket_value": 0.00 }, { "player_name": "My player 3", "finish_position": 3, "still_playing": false, "prize": 25.00, "ticket_value": 0.00 }, { "player_name": "My player 4", "finish_position": 4, "still_playing": false, "prize": 0.00, "ticket_value": 0.00 }, { "player_name": "My player 5", "finish_position": 5, "still_playing": false, "prize": 0.00, "ticket_value": 0.00 }, { "player_name": "My player 6", "finish_position": 6, "still_playing": false, "prize": 0.00, "ticket_value": 0.00 } ] } } ``` # More coming soon. # Change Request Process How to contact us to request a change to the specification. The standard specification is versioned to allow for bug fixes, continued improvements and further advancements. If you have a request to change the specification, please email your requests to and provide the following information: * Your full name * Business name * Explanation of the requested change and why it is needed. * Your proposed modification to the standard specification. We will review all requests and you will be contacted regardless if your change request was approved or denied. {% hint style="success" %} Upon approval of a change request, the specification will be updated to reflect the approved change and the version number of the specification will be increased. {% endhint %} # Support How to contact us for support. Questions are welcome and will help us improve the documentation! If you have any questions regarding the standard specification, please email us at with your question and we will respond as quickly as possible. # Change Log The specification is versioned to allow for continual improvements. This page lists the changes in each version. **1.1.5 - May 9, 2024** * Changed play money currency code from PPC to XPM. **1.1.4 - August 2, 2022** * Added "**rebuy\_cost**", "**addon\_cost**", "**tournament\_rebuys**". **1.1.3 - May 19, 2021** * Specified that "**tournament\_finishes\_and\_winnings**" should list all players who entered the tournament, and made "**finish\_position"**, "**prize**", and "**ticket\_value**" optional for players who have not yet been eliminated from the tournament. **1.1.2 - May 18, 2021** * "**bounty\_fee\_amount**" and "**bounty\_value\_amount**" updated to be explicitly optional/nullable.\ Tidied up some formatting and updated the Sample Sit N' Go. **1.1.1 - March 9, 2021** * Added **"bounty\_value\_amount"** (decimal) **1.1.0 - July 24, 2020** * Added a root object to wrap each summary and identify the type of JSON object.\ **{"ots":** \**}** * Added "**still\_playing**" (boolean) in **\**. * Added "**hero\_player\_name**" (string). * Added detail page for "**tournament\_number**".\ Removed the 'T#' from the example tournament numbers to avoid confusion. * Added **"tournament\_name"** (string), * Added **"buyin\_amount"** (decimal), * Added **"fee\_amount"** (decimal), * Added **"bounty\_fee\_amount"** (decimal), * Added **"initial\_stack"** (integer), * Added **"type"** (string), * Added **"flags"** (array), * Added **"speed"** (object), * Added **"type"** (string) in **\**, * Added **"round\_time"** in **\** **1.0.0 - Early 2020** The initial version.