Guides

Perpetual Tournaments

Suggest Edits

Perpetual match tournaments proceed through these lifecycle states:

  • Creation - Setting up the tournament
  • Run Tournament - In your game, players compete in a continual spawn-and-eliminate style competition
  • Eliminate Player - Players who are eliminated forfeit their earnings to other players
  • Distribute Winnings - Eligible players can withdraw from the tournament and claim their earnings
  • Distribute Commissions
  • Cancel Tournament - Stop accepting entries, eliminations and withdrawals, and allow all players to claim their earnings

Perpetual tournaments do not support supplemental prize pools.

Creation

/nx/tournaments/perpetual

In order to create a perpetual tournament, you will need to specify:

  • Entry fee (in USDC) amount

You may also optionally provide:

  • Maximum active entries - Defaults to 128
  • One commission recipient and percentage commission

These values are not modifiable after the tournament has been created.

Enroll Players

/nx/tournaments/perpetual/{id}/enrolledUsers

When you want a player to enter the tournament, call the Enroll Player endpoint. This will generate a transaction consent URL to which you will redirect the player to complete their entry. The transaction will transfer the necessary game currency from the player’s wallet to the tournament program on-chain.

Run Tournament

/nx/tournaments/perpetual/{id}/eliminations

You can begin running the tournament in your game at any time. You should not allow a player to enter the game until you have confirmed that the player has successfully paid their entry fee. Once the player has paid their fee, you will make calls to our endpoints in order to update the player’s earnings.

Throughout the game, you will call our Eliminate endpoint to reallocate prizes between players. The endpoint supports multiple game models, such as allocating 100% of the prizes held by one player to another, or allowing losing players to retain some of their prize money.

This endpoint consumes:

  • targetReferenceId - The ID of the player who has been eliminated
  • initiatorReferenceId - The ID of the player who has eliminated the target
  • basisPoints - Number of basis points to deduct from the target player. Optional, defaults to 10,000 bps or 100%. The amount deducted from the funding player does not have to be 100%.
  • escrowElimination - When true, the target funds are sent to program-level escrow rather than to the initiator player.

Using the Tournament Escrow

/nx/tournaments/perpetual/{id}/escrowAllocations

/nx/tournaments/perpetual/{id}/escrow

The tournament escrow is used for situations where eliminated players forfeit their prizes, but not directly to the initiating player. The most common example is gameplay modes where upon being attacked, a player drops their loot on the map, and any other player may retrieve the loot later.

Every tournament has an escrow account.

The escrow account is funded by the /eliminations endpoint, called with escrowElimination: true. The target player’s prize value is transferred to the escrow, increasing its balance. The escrow account does not track individual additions or subtractions.

Once during the life of the tournament, you can make a call to delete the escrow, in which case funds are distributed to the GameShift developer wallet. After this point, the escrow may not be used.

Distributing Winnings to Players

/nx/tournaments/perpetual/{id}/enrolledUsers/{userId}/distribute

When a player becomes eligible to receive their prizes, you will call our Distribute endpoint. Once you call this endpoint, you will no longer be able to allocate prizes to this player and the player will be marked dis-enrolled.

The Distribute endpoint will push the rewards to the player’s wallet. By default, it will distribute the entirety of the player’s winnings (minus fees and commissions), but you can also specify a partial distribution.

Cancel Tournament

/nx/tournaments/perpetual/{id}/cancel

Closing a tournament will automatically stop any new entries and immediately withdraw all active players. This action is irreversible. At this point, you can distribute their earnings through the Distribute endpoint.

NOTE: You may only cancel a tournament if there are no eliminations.

Get Tournament Statistics

We offer multiple data reporting endpoints:

/nx/tournaments/perpetual and /nx/tournaments/perpetual/{id}
Returns tournament level details, including details such as the prize pool associated with the tournament (and what address to fund), the commission recipient, and the status of the tournament.

/nx/tournaments/perpetual/{id}/enrolledUsers
Returns the full list of all players enrolled in the tournament and their current standings. The current standings are calculated after all eliminations have been accounted for.

/nx/tournaments/perpetual/{id}/commissions
Reports current commission balances and historical disbursements

Updated 1 day ago