Registration

API endpoints for managing Tournament registrations for Forge Digital Ventures

The Tournament Builder developed for Forge Digital Ventures uses a two-phase registration process:

  1. Participants first create registration records using the /register endpoint

  2. Tournament administrators then officially add these participants to the tournament using the /participants endpoint

Creating Registration Records

Endpoint: POST /tournaments/{tournamentId}/register

Allows participants to register for a specific tournament. This only creates a registration record and does not yet add the participant to the tournament.

Request Parameters:

  • utxos (string[], min 1): Array of UTXO strings to use for the transaction

  • registererAddress (string): Address of the registering participant, used for prize payouts

  • changeAddress (string, optional): Address to receive change UTXOs (defaults to registererAddress)

  • tournamentId (string): Tournament identifier

  • contractVersion (string, optional): Contract version for custom deployments

  • contractTitle (string, optional): Contract title 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:

  • Creates an output at the parameterized registration script address

  • The output must contain the required entry fee

  • The registration datum stores the participant's address

  • This address will be used for prize payouts.

  • After registration, participants must wait for tournament admin to add them

Example (Node.js with fetch):

async function createRegistration(tournamentId) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/register`;
  
  const requestData = {
    utxos: ["8282...", "8282...", "8282..."], // UTXOs must contain enough funds to cover the entry fee
    registererAddress: "addr_test1...", // Tournament participant address
    changeAddress: "addr_test1...", // Optional, defaults to registererAddress
    tournamentId: tournamentId,
  };
  
  const response = await fetch(apiUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestData),
  });
  
  const data = await response.json();
  console.log('Registration transaction:', data.complete);
  
  // The returned transaction must be signed and submitted (see Transaction Overview: ../guides/transaction/README.md)
  return data.complete;
}

Cancelling a Registration

Endpoint: POST /tournaments/{tournamentId}/unregister

Allows participants to cancel their registration and recover their entry fee.

Request Parameters:

  • utxos (string[], min 1): Array of UTXO strings to use for the transaction

  • registererAddress (string): Address of the registered participant

  • changeAddress (string, optional): Address to receive change UTXOs (defaults to registererAddress)

  • tournamentId (string): Tournament identifier

  • outputRef (string): Reference to the registration UTXO in format txHash#index

  • 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 original registrant can cancel their registration

  • The "Cancel" redeemer is used to validate the transaction

  • The registration UTXO (including the entry fee) is returned to the participant

  • This provides a full refund of the entry fee to the canceling participant

  • Cancellation is only possible before the administrator has added the participant to the tournament

Example (Node.js with fetch):

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

Retrieving Registrations

Endpoint: GET /tournaments/{tournamentId}/registrations

Retrieves a list of all registrations for a specific tournament.

Request Parameters:

  • tournamentId (string): Tournament identifier

  • valid (boolean, optional): Filter to only valid or invalid registrations

  • limit (number, optional): Max number of results to return (1-100, default: 100)

  • page (number, optional): Page number for pagination

  • cursor (number, optional): Alias for page, enables TRPC infinite queries

  • contractTitle (string, optional): Contract title for custom deployments

  • contractVersion (string, optional): Contract version for custom deployments

Response:

  • entryFeeLovelace (string): The required entry fee amount in lovelace

  • results: Array of registration objects, each containing:

    • address (string): Registrant address

    • outputRef (string): Registration UTXO reference

    • valid (boolean): Whether the registration has sufficient funds

    • paidFeesLovelace (string): Amount of fees paid in lovelace

Technical Notes:

  • Results can be filtered by validity (sufficient funds)

  • Results are paginated with a default limit of 100 registrations

  • Output refs uniquely identify each registration UTXO on the blockchain

Example (Node.js with fetch):

async function getRegistrations(tournamentId, validOnly = true) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/registrations?valid=${validOnly}&limit=50`;
  
  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    }
  });
  
  const data = await response.json();
  console.log(`Required entry fee: ${data.entryFeeLovelace} lovelace`);
  console.log(`Found ${data.results.length} registrations`);
  
  return data;
}

Technical Notes:

  • Returns both valid and invalid registrations (can be filtered with the valid parameter)

  • Invalid registrations may not have paid the correct entry fee

Example (Node.js with fetch):

async function getRegistrations(tournamentId, validOnly = false) {
  const apiUrl = `https://preprod.api.ada-anvil.app/v2/services/tournaments/${tournamentId}/registrations${validOnly ? '?valid=true' : ''}`;
  
  const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
    },
  });
  
  const data = await response.json();
  console.log('Required entry fee (lovelace):', data.entryFeeLovelace);
  console.log('Registrations:', data.results);
  
  return data;
}
PreviousTournamentNextSubmit

Last updated

Was this helpful?