> 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/overview.md).

# Overview

{% hint style="warning" %}
The Tournament Builder is a premium feature developed for Forge Digital Ventures. If you would like to enable this functionality with your Anvil API access, please contact the Anvil support team.
{% endhint %}

## Overview

The Tournament Builder is a Cardano-based solution for running transparent, on-chain tournaments. It supports customizable brackets, entry fees, and payout structures, with tournament records stored as verifiable NFTs. On-chain actions like registration and prize distribution are automated by smart contracts, while gameplay and rules remain flexible and off-chain—managed by organizers. This ensures both transparency and ease of integration.

{% hint style="info" %}
For a better understanding of the Anvil API transaction flow, please refer to the [Transaction Overview](/guides/transaction.md) documentation. In particular, you need to have an understanding of the transaction submission process. Every transaction generated by the tournament builder must be signed and submitted through the Anvil API.
{% endhint %}

## Smart Contract & API Architecture

**Key Concepts:**

1. **Simple, Consistent API Endpoints**
   * All tournament actions—creating tournaments, registering participants, adding players, and submitting transactions—are exposed as clear, RESTful API endpoints.
   * Endpoints are designed for ease of use:

     [**Tournament Management**](/tournament-builder/tournament.md)

     * `POST /tournaments` — Create a new tournament
     * `GET /tournaments` — List all tournaments
     * `GET /tournaments/{id}` — Get tournament info
     * `POST /tournaments/{id}/participants` — Add participants to a tournament
     * `PATCH /tournaments/{id}/settle` — Settle tournament and distribute prizes

     [**Registration Management**](/tournament-builder/registration.md)

     * `POST /tournaments/{id}/register` — Register as a participant
     * `GET /tournaments/{id}/registrations` — List all registrations for a tournament
     * `POST /tournaments/{id}/unregister` — Cancel a registration

     **Transaction Submission**

     * `POST /tournaments/submit-tx` — Submit signed transactions for all tournament operations
2. **Dual Validator (Plutus Script) Architecture**
   * **Tournament Validator:**
     * Handles tournament creation, participant management, and payout logic.
     * Mints a unique NFT (CIP-25) for each tournament, which acts as its on-chain identity.
   * **Registration Validator:**
     * Manages individual registrations, ensuring only valid participants are added.
3. **NFT-Based Tournament Representation**
   * Each tournament is a unique NFT, minted at creation.
   * Tournament configuration and state are stored in the datum of the NFT’s UTXO.
   * NFTs use the CIP-25 metadata standard for broad wallet and ecosystem compatibility.
4. **EUTXO Transaction Model**
   * All actions are UTXO-based: tournament and registration records are UTXOs managed by validators.
   * Transactions are deterministic and can be validated off-chain before submission, reducing surprises and increasing reliability.
5. **Transparent Fee Management**
   * Entry fees, protocol fees, and per-participant fees are all handled on-chain by the smart contract.
   * Refunds and payouts are enforced by validator logic, ensuring fairness.

## Why This Approach?

* **Simplicity:**\
  The API hides blockchain complexity. Developers interact with intuitive endpoints and clear request/response formats.
* **Security & Transparency:**\
  All critical actions are enforced by on-chain logic and are fully auditable.
* **Flexibility:**\
  Organizers retain control over tournament rules and flow, while the contract guarantees fair registration and prize handling.

## Documentation Resources

{% hint style="info" %}
Before diving into the API, we recommend reviewing the integration flow and fee structure documentation to understand the complete tournament process.
{% endhint %}

### Core Documentation

{% content-ref url="/pages/9EOKO1KhoWOHeudXCXnI" %}
[Integration Flow](/tournament-builder/integration-flow.md)
{% endcontent-ref %}

{% content-ref url="/pages/2v7zlwLDyNGSBhIOS5hF" %}
[Fee Structure](/tournament-builder/fee-structure.md)
{% endcontent-ref %}

### API Reference

{% content-ref url="/pages/Ek7JPM6J95ErgSW5Datr" %}
[Tournament](/tournament-builder/tournament.md)
{% endcontent-ref %}

{% content-ref url="/pages/GGLqpYdCU7AWotZxKb0y" %}
[Registration](/tournament-builder/registration.md)
{% endcontent-ref %}