Tournament Builder

Tournament Management Endpoints#

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"]

Response:

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

Technical Notes:

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:

Response:

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

Technical Notes:

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:

Response:

Technical Notes:

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:

Response:

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

Technical Notes:

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;
}