Tournament APIs
Creating a Rumble Tournament Settings
The first step we need to be able to create a new rumble tournament is the tournament settings. It is the base configuration to create all new tournaments.
POST /rumble-tournament-settings - open the spec 🔗
We provide an endpoint to change some parameter in the settings, but it just impact new tournaments; the previous tournaments still have the same settings when it was created.
Property
Description
prizeDistributionRules
That defines the set of rules to resolve the tournament.
Each application can have multiple ways to resolve a container. More detail below.
registrationFeeInUpx
That indicates how much players will pay to join the container.
developerFeePercentage
That indicates how much the developer of the app will get from the tournament.
Range: 0 - 10%
stakeholderFeePercentage
That can be used in case the tournament has a stakeholder involved.
Range: 0 - 10%
Example: Stock Car Tournaments can include X% for the Stock Car Account as a stakeholder.
Creating a Rumble Tournament
After settings creation, you can create a new rumble tournament calling the endpoint below:
POST /rumble-tournaments - open the spec 🔗
The endpoint requires the settings identifier and two more optional fields:
registrationFeeInUpx: An optional field that will override the registration fee on settings if used.stakeholderEosId: It is an optional field where you can specify some EOS ID that will receive some fee in the tournament resolution. To use this extra field, you must provide the attributestakeholderFeePercentageWhile creating the setting.
The endpoint will retrieve the tournament ID you will use until the resolution process. At this moment, the tournament will be on WAITING_FOR_PARTICIPANTS status.
We have some rules that need to be clear at this moment:
You can not start or close a tournament if the minimum of participants has not been reached (it is specified in tournament settings).
You can not cancel a tournament with some payment in progress on the blockchain level. After the tournament cancellation, all amount of UPX will be refunded to the original owner.
Participants Registration
At this moment, the tournament can receive new participants. The developer can call the join endpoint to register Upland users to your tournament.
POST /rumble-tournaments/:tournamentId/join - open the spec 🔗
Pay attention to the authentication method for this endpoint. Adding a Upland user to your tournament requires that he is authenticated. Because of that, this endpoint requires a Bearer token (the same one you received via webhook).
The other tournament endpoints require only the Basic Authentication (APP ID + Secret Key).
There is an optional endpoint you can use if your application needs to close the registration and block the tournament for new participants:
PATCH /rumble-tournaments/:tournamentId/close-registration - open the spec 🔗
Starting a Rumble Tournament
When the tournament reaches the min of participants, you will be able to start it using the endpoint below:
PATCH /rumble-tournaments/:tournamentId/start - open the spec 🔗
The tournament changed to IN_PROGRESS status. This status allows the developer to register the participant scores. You can send all the scores simultaneously or split them into different requests. Use the userId and the score value to register using the endpoint below:
POST /rumble-tournaments/:tournamentId/scores - open the spec 🔗
It’s essential to register all participant scores to finish the tournament, and calculating the final scoreboard is essential.
Resolving a Rumble Tournament
When you want to close and calculate the tournament result, call the resolved endpoint:
POST /rumble-tournaments/:tournamentId/resolve - open the spec 🔗
If participants have null scores, you can force the resolution using the parameter forceResolutionWithNullScore.
The resolve endpoint will retrieve the completed scoreboard, where you can check the prize pool, the winner prizes, and the developer/stakeholder fee. The tournament changes to DISTRIBUTING_PRIZES status. We will start a new transaction in the blockchain to transfer the prize and the fee to the Upland users and developers. When this transaction was finalized on the blockchain side, the tournament became CLOSED. If the transaction fails, the tournament status must be FAILED.
Prize Pool
The prize pool will comprise all fees paid by participants minus other fees.
Prize Pool = Total Amount Paid by Participants - (Developer Fee + Stakeholder Fee + Upland Fee)
When the developers define how to split the prize, the API considers the prize pool, not the total amount paid.
Resolution Rules
The resolution rules define how the tournament will be resolved when it finishes.
The resolution rule is composed of Minimum Participants and Distribution.
The Minimum Participants defines the number of participants needed to start a tournament.
The Distribution defines the number of winners and its prize distribution.
The application can have multiple resolution rules to cover different cases.
The resolution rule selected will be the one that gets closer to the number of participants in a decrescent order and also reaches the minimum number of participants.
Example:
Application Resolutions for Tournaments
First Resolution Rule:
Second Resolution Rule:
First Scenario - Two Participants:
The tournament can not start.
Second Scenario - Four Participants:
The resolution rule to be used will be the first:
The first place will take 70% of the prize pool, and the second place will take 30%.
Third Scenario - Seven Participants:
The resolution rule to be used will be the first:
The first place will take 70% of the prize pool, and the second place will take 30%.
Fourth Scenario - Eight or More Participants:
The resolution rule to be used will be the second:
The first place will take 50% of the prize pool, the second place will take 25%, the third place will take 15%, and the fourth place will take 10%.
Canceling a Rumble Tournament (Optional flow)
The developer must be able to cancel the tournament at any time before the resolution process. If any participants paid the entry fee, we will refund them. The tournament will change to REFUNDING_PARTICIPANTS status, and the refund transaction will start. When this transaction is final at the blockchain level, the tournament changes to the CANCELED status. If the total entry fee is empty, the tournament will only finalize as CANCELED status (no refund is needed).
POST /rumble-tournaments/:tournamentId/cancel - open the spec 🔗
Rumble Tournament Expiration
All the tournaments have some lifetime, and when it is reached, the tournament is closed automatically. The tournament duration is the same as the escrow container that you define for each app in the developer's portal.
Last updated