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

# Integration Flow

This guide outlines the step-by-step process for integrating with the Tournament Builder developed for Forge Digital Ventures. For technical details of the architecture, see the [Overview](/tournament-builder/overview.md) document.

{% hint style="info" %}
This workflow assumes you have already set up your development environment and have the necessary credentials to access the Anvil API.
{% endhint %}

## 1. Tournament Creation

{% tabs %}
{% tab title="Step-by-Step Process" %}

1. **Prepare Tournament Configuration**
   * Define bracket size, entry fees, and payout structure
   * Identify administrator address
   * Gather UTXOs for transaction fees
2. **Create Tournament Transaction**
   * Call the [`/tournaments` endpoint](/tournament-builder/tournament.md#create-tournament) with configuration
   * Receive transaction hex in response
3. **Sign and Submit Transaction**
   * Sign the transaction with appropriate keys
   * Submit the signed transaction (see [Transaction Overview](/guides/transaction.md) for details)

{% hint style="success" %}
When successful, the tournament is created and an NFT is minted to represent it on-chain. The tournament is now ready to accept registrations.
{% endhint %}
{% endtab %}

{% tab title="Example API Flow" %}

```javascript
// 1. Configure tournament parameters
const tournamentConfig = {
  name: "Tournament Name",
  adminAddress: "addr1...",
  bracketSize: 16,
  entryFee: "10000000", // 10 ADA in lovelace
  payoutStructure: ["7000000", "2000000", "1000000"],
  utxos: ["1234...#0", "5678...#1"]
};

// 2. Create tournament transaction
const response = await fetch("/tournaments", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(tournamentConfig)
});
const { transaction } = await response.json();

// 3. Sign and submit transaction
// See Transaction Overview documentation for details: ../guides/transaction/README.md
const signedTx = await signTransaction(transaction);
const submitResponse = await fetch("/tournaments/submit-tx", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ transaction: signedTx })
});
const { txHash } = await submitResponse.json();

console.log("Tournament created with transaction:", txHash);
```

{% endtab %}
{% endtabs %}

## 2. Registration Management

The Tournament Builder uses a two-phase registration process:

1. Participants self-register (creating registration UTXOs)
2. Tournament administrator collects these registrations and officially adds participants

### Phase 1: Participants Register

1. **Participant Initiates Registration**
   * Call [`POST /tournaments/{id}/register`](/tournament-builder/registration.md#register) with participant address
   * Include UTXOs covering entry fee
   * Submit resulting transaction
   * This creates a registration UTXO at the registration script address
2. **Verification**
   * Query [`GET /tournaments/{id}/registrations`](/tournament-builder/registration.md#list-registrations) to confirm registration
   * Validate status and fee payment
   * Participants must monitor their registration status
3. **Optional: Registration Cancellation**
   * If needed, participants can cancel their registration before being added to the tournament
   * Call [POST /tournaments/{id}/unregister\`](/tournament-builder/registration.md#cancel-registration)
   * The registration UTXO with the full entry fee amount is returned to the participant
   * This provides a complete refund mechanism for participants who change their mind

### Phase 2: Tournament Administrator Adds Participants

1. **Collect Registration Outputs**
   * Tournament administrator gathers valid registration output references
   * Uses [`GET /tournaments/{id}/registrations`](/tournament-builder/registration.md#list-registrations) to find valid registrations
2. **Add Participants to Tournament**
   * Administrator calls [`POST /tournaments/{id}/participants`](/tournament-builder/tournament.md#add-participants) with registration list
   * Only the tournament admin can perform this action
   * Administrator signs and submits transaction
   * This transaction consumes the registration UTXOs and updates the tournament datum
   * Participants are now officially part of the tournament

### Phase 3: Tournament Settlement

1. **Finalize Participant List**
   * Administrator reviews and confirms all participants
2. **Conduct Tournament**
   * Actual competition happens off-chain
   * Results are determined through competition
3. **Submit Results**
   * Tournament administrator submits final standings using the [`PATCH /tournaments/{id}/settle` endpoint](/tournament-builder/tournament.md#tournament-settlement)
   * Smart contract distributes rewards according to payout structure defined at tournament creation
   * Each prize recipient receives their prize as a transaction output with the tournament ID as datum
   * For details on prize distribution and fees, see the [Fee Structure](/tournament-builder/fee-structure.md) document