A comprehensive list of endpoints exposed by our Tournaments API
Each Endpoint has a GET and a POST operation, the GET will generate a prepared transaction for the endpoint, complete with signatures from newly created accounts and our API signer. Next, this transaction must be signed by the caller and send back in a POST body. We will validate the transaction received via HTTP POST and forward this along to the Solana network.
Transfer tokens collected by a Tournaments Entry Fee to the Reward Escrow, this enables the Entry Fee to be redistributed to tournament participants. This endpoint is only callable by a Tournament Authority.
Transfer tokens from the Tournament Authority to the Reward Escrow. It's important to specify the Reward Amount with the correct decimal precision. This endpoint is only callable by a Tournament Authority.
Example: 1 $USDC would be a reward amount of "100000", USDC has 6 decimals of precision.
Revoke all tournament points gained by a detected cheater in a tournament. This endpoint is only callable by a Tournament Authority.
Create a new round of matches within a Tournament. For each new round, increment the Round Index by 1, the API uses the Participants per Round to determine the number of matches to create for a round. This endpoint is only callable by a Tournament Authority.
Create a new Tournament, the creator mints a Tournament Authority token granting them full control over Tournament operations.
Specify a Name and a Tournament Size, optionally specify an Entry Fee and/or a Token Gate. The Name cannot be longer than 100 characters. The Size sets a limit on number of participants who can join, but this limit does not need to be reached to start the Tournament.
An Entry Fee requires a Mint and an Amount which each participant must pay to enter into your Tournament.
A Token Gate requires a Mint and an Amount which each participant must have in their Wallet to be eligible to enter into your Tournament.
Distribute the tokens stored in a Tournament Reward Escrow to a Tournament Participant
Update the state of a Match to Ended. This endpoint is only callable by a Tournament Authority.
Before a winner of a match can be determined, the Match must be in the Ended State.
Update the state of the Tournament to Ended. This endpoint is only callable by a Tournament Authority.
When a Tournament is moved to Ended, no more Matches or Rounds can be created. Cheaters can still be detected and banned at this stage, this is where rewards would be distributed to eligible participants.
Enter a Tournament Participant into a Match. This endpoint is only callable by a Tournament Authority.
The Tournament Authority is in control of which participants enter which Matches so that the Tournament Authority can control bracketing and matchmaking semantics.
A participant uses this endpoint to enter into a tournament of their choice. If the tournament has an Entry Fee or Token Gate configured, the participant must pay or have in their wallet the necessary tokens.
Finalize the results of a Tournament, all rewards have be distributed, cheaters banned and the results of the Tournament become immutable. This endpoint is only callable by a Tournament Authority.
Retrieve Match Details in JSON format
Retrieve all Matches of a particular Round in a tournament. Use the Round Index to select a particular round. Flip the finalized Boolean if you would like to selectively retrieve Matches which are finalized or not.
Retrieve all participants for a particular Match.
Retrieve all participants who are eligible for a particular Round, regardless if they have entered a Match in that Round or not.
Retrieve current Tournament Standings sorted descending from most points awarded. For each Match win a participant is awarded 1 Tournament Point.
Retrieve Tournament Details in JSON format
Determine a Winner of an Ended Match and move the Match into the Finalized State. This endpoint is only callable by a Tournament Authority.
The Winner will receive 1 Point in their points token account. Tournaments uses the points to determine which participants are eligible to play in subsequent tournament rounds and for participants and managers to keep track of Tournament state.
Currently only 1 winner can be selected but we will make this endpoint more flexible to support multiple winners in the future.
Move a Match within a Tournament into the Started State, this signifies that the Match is beginning to be played out on chain, no other participants may enter this Match. This endpoint is only callable by a Tournament Authority.
Move a Tournament into the Started State, no more participants may enter the tournament and now it's possible to begin creating Tournament Rounds. This endpoint is only callable by a Tournament Authority.
Tournaments users will interact with the Tournaments API via HTTP, this allows flexibility for a variety of user types with the service, we will proxy your requests to the blockchain for you after signing.
We support a typescript HTTP client which will always be compatible with our Tournaments API, we suggest starting here to try things out. The client is designed to be usable from web applications and scripting.
Tournaments is built on top of a generic Events Program, please refer to the Events Reference Errors & State Pages for detail. On those pages, a Tournament is an Event and a Match is a Contest.
An EntryFee can be optionally set at Tournament creation, requires all participants entering the tournament to pay a fee upon entrance. There can only be one tournament entry fee at this time
Multiple Matches can be created within a Tournament, each Match can have an unlimited number of participants, winners of matches accrue Points.
A Participant is an entity which has entered a Tournament and is eligible to play matches
Points are accrued by winners of Matches within a Tournament. These points are used to keep track of which participants are eligible to move onto the next Tournament Round. Throughout the Tournament it's possible to query the point totals of all participating. Tournament Authorities can use these point totals to determine distribution of Tournament Rewards. In addition, if it's determined that one or multiple participants have cheated, their points can be revoked.
Rewards are used to incentivize participants to enter into Tournaments. There can be unlimited number of rewards and the Tournament Authority has complete control over the distribution of these Rewards after the Tournament has been moved to the Ended State. Optionally, the Tournament Entry Fee tokens can be used as a Tournament Reward.
A Round is a grouping of matches within a Tournament, each Round has a unique Round Index. The first round in a Tournament has a Round Index of 0, this means that any participant is eligible to play in the first round of matches (provided they have entered the Tournament of course!).
The winners of each match within a Round are awarded 1 point, this corresponds to the Round Index. For example, the Second Round in this Tournament has a Round Index of 1, which means participants who have been awarded 1 Point from playing in the previous round are eligible for these new Matches.
The farther along a participant makes it within a Tournament, the more points they accrue and the Tournament Authority can query these point totals to make a decision on Reward distribution.
When a Tournament is created it's possible to add a Token Gate, a Token Gate requires that a prospective participant has a particular mint and amount of said mint in their wallet upon joining. One use case of this might be a whitelist token, only allowing participants with the token to be eligible to play in the tournament.
A Tournament is a series of Matches in which participants compete for escrowed Rewards, the Tournament results are recorded on chain and when complete, are immutable and forever public.