> For the complete documentation index, see [llms.txt](https://dev.ada-anvil.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.ada-anvil.io/tournament-builder/registration.md).

# Registration

{% hint style="info" %}
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
   {% endhint %}

## 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

{% hint style="info" %}
The returned transaction must be signed and submitted through the `/tournaments/submit-tx` endpoint before it takes effect on the blockchain.
{% endhint %}

**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)**:

```javascript
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

{% hint style="info" %}
The returned transaction must be signed and submitted through the `/tournaments/submit-tx` endpoint before it takes effect on the blockchain.
{% endhint %}

**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)**:

```javascript
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)**:

```javascript
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)**:

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