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