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


---

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