Tournament

API endpoints for creating and managing tournaments for Forge Digital Ventures

Tournament Creation

Endpoint: POST /tournaments

Creates a new tournament with the specified configuration parameters.

Request Parameters:

name (string): Tournament display name
adminAddress (string): Address with administrative control
changeAddress (string, optional): Address to receive change UTXOs (defaults to adminAddress)
bracketSize (number): Number of participants in the tournament
entryFee (string|number|bigint, optional): Fee for participants (in lovelace)
payoutStructure (string[]|number[]|bigint[]): Array defining prize distribution (in lovelace)
Even for percentage-based payouts, values for payoutStructure must be pre-calculated as absolute lovelace amounts. The contract does not perform percentage calculations; clients must convert desired percentages to exact lovelace values.
Example: For a 70%/20%/10% split of 100 ADA, you would provide ["70_000_000", "20_000_000", "10_000_000"]
fixedPayouts ([string, string|number|bigint][], optional): Optional specific reward allocations to addresses
utxos (string[], min 1): Array of UTXO strings to use for the transaction
contractTitle (string, optional): Contract title for custom deployments
contractVersion (string, optional): Contract version for custom deployments

Response:

complete: Hex-encoded transaction for signing

The returned transaction must be signed and submitted through the /tournaments/submit-tx endpoint before it takes effect on the blockchain.

Technical Notes:

The tournament ID is derived from the first UTXO in the transaction
An NFT is minted representing the tournament
The tournament datum contains both configuration and current state

Example (Node.js with fetch):

async function createTournament() {
  const apiUrl = 'https://preprod.api.ada-anvil.app/v2/services/tournaments';
  
  const requestData = {
    name: "Tournament Name",
    adminAddress: "addr_test1...",
    bracketSize: 8,
    entryFee: "5_000_000", // 5 ADA in lovelace
    payoutStructure: ["30_000_000", "15_000_000", "5_000_000"], // First, second, third place prizes
    fixedPayouts: [
      ["addr_test1...", "1_000_000"]
    ],
    utxos: ["8282...", "8282...", "8282..."] // UTXOs to consume in the transaction
  };
  
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Tournament creation transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

Adding Participants to Tournament

Endpoint: POST /tournaments/{tournamentId}/participants

Enables tournament administrators to collect valid registrations and officially add participants to the tournament.

Request Parameters:

adminAddress (string): Tournament administrator address
tournamentId (string): Tournament identifier
changeAddress (string, optional): Address to receive change UTXOs (defaults to adminAddress)
registrations (object[], min 1): Array of registration objects, each containing:
- address (string): Participant address
- outputRef (string): Registration UTXO reference in format txHash#index
utxos (string[], min 1): Array of UTXO strings to use for the transaction
contractTitle (string, optional): Contract title for custom deployments
contractVersion (string, optional): Contract version for custom deployments

Response:

complete: Hex-encoded transaction for signing

The returned transaction must be signed and submitted through the /tournaments/submit-tx endpoint before it takes effect on the blockchain.

Technical Notes:

Only the tournament admin can add registered participants to the tournament
Multiple participants can be added in a single transaction
The transaction updates the tournament datum with new participants
Registration UTXOs are consumed in the process

Example (Node.js with fetch):

async function addParticipantsToTournament(tournamentId) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/participants`;
  
  const requestData = {
    adminAddress: "addr_test1...",
    changeAddress: "addr_test1...", // Optional, defaults to adminAddress
    registrations: [
      {
        address: "addr_test12...",
        outputRef: "registrationOutputRef1"
      },
      {
        address: "addr_test13...",
        outputRef: "registrationOutputRef2"
      }
    ],
    utxos: ["8282...", "8282...", "8282..."] // UTXOs to consume in the transaction
  };
  
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Add participants transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

Retrieving Tournaments

Endpoint: GET /tournaments

Returns a list of all available tournaments.

Request Parameters:

limit (number, optional): Number of tournaments to retrieve (default: 100, max: 100)
pageState (string, optional): Pagination token for fetching additional results
cursor (string, optional): Alias for pageState, enables TRPC infinite queries
contractTitle (string, optional): Contract title for custom deployments
contractVersion (string, optional): Contract version for custom deployments

Response:

results: Array of tournament objects with their configuration and state
pageState: Optional pagination token for fetching the next page of results

Technical Notes:

Results are paginated with a default limit of 100 tournaments
The response includes both tournament configuration and current state
Tournament information is retrieved from the on-chain NFT records
Invalid registrations may be added to a tournament, but any missing fees will be covered by the tournament administrator when confirming the registration

Example (Node.js with fetch):

async function getTournaments(limit = 50, pageState = null) {
  let apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments?limit=${limit}`;
  
  if (pageState) {
    apiUrl += `&pageState=${encodeURIComponent(pageState)}`;
  }
  
  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    }
  });
  
  const data = await response.json();
  console.log(`Retrieved ${data.results.length} tournaments`);
  
  // For pagination, use the returned pageState token
  if (data.pageState) {
    console.log('More tournaments available, use pageState for pagination');
  }
  
  return data;
}

Tournament Settlement

Endpoint: PATCH /tournaments/{tournamentId}/settle

Completes a tournament by distributing prizes according to the specified results.

Request Parameters:

adminAddress (string): Administrator address (must match tournament creator)
changeAddress (string, optional): Address to receive change UTXOs (defaults to adminAddress)
tournamentId (string): Tournament identifier
results (string[]): Array of participant addresses in order of their placement (1st place first, 2nd place second, etc.)

This results list doesn't have to be exhaustive, but at least all winning participants (configured in the original payoutStructure) must be specified.

utxos (string[], min 1): Array of UTXO strings to use for the transaction
contractTitle (string, optional): Contract title for custom deployments
contractVersion (string, optional): Contract version for custom deployments

Response:

complete: Hex-encoded transaction for signing

The returned transaction must be signed and submitted through the /tournaments/submit-tx endpoint before it takes effect on the blockchain.

Technical Notes:

Only the tournament admin can settle a tournament
Tournament must be fully filled (all participant slots must be occupied)
Prizes are distributed according to the tournament's payout structure
The tournament NFT is burned during settlement
Prize UTXOs include tournament ID as a unique tag in the datum to implement the unique outputs pattern, preventing double-satisfaction vulnerabilities

Example (Node.js with fetch):

async function settleTournament(tournamentId, results) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/settle`;
  
  const requestData = {
    adminAddress: "addr_test1...",
    tournamentId: tournamentId,
    changeAddress: "addr_test1...", // Optional, defaults to adminAddress
    results: [
      "addr_test1winner...", // 1st place (gets highest prize)
      "addr_test1second...", // 2nd place
      "addr_test1third..."   // 3rd place (and so on)
    ],
    utxos: ["8282...", "8282...", "8282..."] // UTXOs to consume in the transaction
  };
  
  const response = await fetch(apiUrl, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Settlement transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

PreviousIntegration Flow NextRegistration

Last updated 8 days ago

Was this helpful?