# Tournament

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

  <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Even for percentage-based payouts, values for <code>payoutStructure</code> must be pre-calculated as absolute lovelace amounts. The contract does not perform percentage calculations; clients must convert desired percentages to exact lovelace values.</p><p>Example: For a 70%/20%/10% split of 100 ADA, you would provide <code>["70_000_000", "20_000_000", "10_000_000"]</code></p></div>
* `fixedPayouts` (\[string, string|number|bigint]\[], optional): Optional specific reward allocations to addresses
* `utxos` (string\[], min 1): Array of UTXO strings to use for the transaction
* `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**:

* The tournament ID is derived from the first UTXO in the transaction
* An NFT is minted representing the tournament
* The tournament datum contains both configuration and current state

**Example (Node.js with fetch)**:

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

* `adminAddress` (string): Tournament administrator address
* `tournamentId` (string): Tournament identifier
* `changeAddress` (string, optional): Address to receive change UTXOs (defaults to adminAddress)
* `registrations` (object\[], min 1): Array of registration objects, each containing:
  * `address` (string): Participant address
  * `outputRef` (string): Registration UTXO reference in format `txHash#index`
* `utxos` (string\[], min 1): Array of UTXO strings to use for the transaction
* `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 tournament admin can add registered participants to the tournament
* Multiple participants can be added in a single transaction
* The transaction updates the tournament datum with new participants
* Registration UTXOs are consumed in the process

**Example (Node.js with fetch)**:

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

* `limit` (number, optional): Number of tournaments to retrieve (default: 100, max: 100)
* `pageState` (string, optional): Pagination token for fetching additional results
* `cursor` (string, optional): Alias for pageState, enables TRPC infinite queries
* `contractTitle` (string, optional): Contract title for custom deployments
* `contractVersion` (string, optional): Contract version for custom deployments

**Response**:

* `results`: Array of tournament objects with their configuration and state
* `pageState`: Optional pagination token for fetching the next page of results

**Technical Notes**:

* Results are paginated with a default limit of 100 tournaments
* The response includes both tournament configuration and current state
* Tournament information is retrieved from the on-chain NFT records
* Invalid registrations may be added to a tournament, but any missing fees will be covered by the tournament administrator when confirming the registration

**Example (Node.js with fetch)**:

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

* `adminAddress` (string): Administrator address (must match tournament creator)
* `changeAddress` (string, optional): Address to receive change UTXOs (defaults to adminAddress)
* `tournamentId` (string): Tournament identifier
* `results` (string\[]): Array of participant addresses in order of their placement (1st place first, 2nd place second, etc.)

{% hint style="info" %}
This `results` list doesn't have to be exhaustive, but at least all winning participants (configured in the original `payoutStructure`) must be specified.
{% endhint %}

* `utxos` (string\[], min 1): Array of UTXO strings to use for the transaction
* `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 tournament admin can settle a tournament
* Tournament must be fully filled (all participant slots must be occupied)
* Prizes are distributed according to the tournament's payout structure
* The tournament NFT is burned during settlement
* Prize UTXOs include tournament ID as a unique tag in the datum to implement the [unique outputs pattern](https://aiken-lang.org/fundamentals/common-design-patterns#unique-outputs), preventing double-satisfaction vulnerabilities

**Example (Node.js with fetch)**:

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


---

# 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/tournament.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.