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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ada-anvil.io/tournament-builder/registration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.