Tournament API

The Pool Tournament feature allows end users to join pre-created tournaments and earn rewards based on their ranking at the end of the matchup. The outcome and payout structure of each pool must be provided to Lucra using these API endpoints

---

getRecommendedTournaments(includeClosed: Bool = false, limit: Int = 50) async -> Result<[TournamentsMatchup], TournamentError>

Retrieve a list of recommended tournaments.

Parameters

• includeClosed: Whether closed (completed) tournaments should be included.

• limit: Maximum number of tournaments to return.

Returns

• Result<[TournamentsMatchup], TournamentError> — An array of tournament matchups on success, or a TournamentError on failure.

Example (Swift)

let result = await lucraClient.api.getRecommendedTournaments(includeClosed: true, limit: 50)

switch result {
case .success(let tournaments):
    print("Recommended tournaments: \(tournaments.count)")
case .failure(let error):
    print("Failed to load tournaments: \(error)")
}

---

tournamentsMatchup(for matchupID: String) async -> Result<TournamentsMatchup, TournamentError>

Retrieve tournament details for a given matchup ID.

Parameters

• matchupID: The identifier of the tournament matchup.

Returns

• Result<TournamentsMatchup, TournamentError> — The tournament matchup on success, or a TournamentError on failure.

Example

let result = await lucraClient.api.tournamentsMatchup(for: "matchup_123")

switch result {
case .success(let tournament):
    print("Tournament: \(tournament.id)")
case .failure(let error):
    print("Error fetching tournament: \(error)")
}

---

joinTournament(matchupId: String, joinCode: String? = nil) async -> Result<Bool, TournamentError>

Join a tournament with the given matchup ID.

Parameters

• matchupId: Tournament matchup ID to join.

• joinCode: Optional join code for private tournaments; nil if tournament is public.

Returns

• Result<Bool, TournamentError> — true on success, or a TournamentError on failure.

Behavior

1. Fetches tournament details using tournamentsMatchup(for:).

2. Validates user state (validateUserStateForTournament).

3. If paid entry, validates that the user has available funds.

4. Requests user location.

5. Fetches a GeoComply packet based on tournament type (free or paid).

6. Attempts to join the tournament via MatchupJoinPoolTournamentsMutation.

Failure Cases

The TournamentError can contain:

User State Errors

• .user(.notInitialized)

• .user(.unverified)

• .user(.notAllowed)

• .user(.insufficientFunds)

• .user(.demographicInformationMissing)

Location Errors

• .location(.unauthorized)

• .location(.unableToDetermineLocation(error))

• .location(.clError(clError))

API Errors

• .customError(message: String)

• .unknown

Example

let result = await lucraClient.api.joinTournament(matchupId: "tournament_123", joinCode: nil)

switch result {
case .success:
    print("Successfully joined!")
case .failure(let error):
    print("Join failed: \(error)")
}

---

submitUserScore(_:tournamentID:metadata:isFinal:) async -> Result<TournamentsMatchup?, TournamentError>

Submit a user's score for a tournament matchup.

Parameters

• score: The score value being submitted.

• tournamentID: The tournament matchup identifier.

• metadata: Additional metadata to attach to the score update.

• isFinal: Whether this is the user's final attempt.

Returns

• Result<TournamentsMatchup?, TournamentError> — The updated tournament matchup on success, or a TournamentError on failure.

Behavior

1. Checks user account status; returns .user(.notAllowed) if restricted.

2. Requests location.

3. Fetches a GeoComply packet based on tournament context.

4. Submits the score via UpdateUserScoreMutation.

5. Returns the updated TournamentsMatchup if successful.

Example

let result = await lucraClient.api.submitUserScore(
    28,
    tournamentID: "tournament_123",
    metadata: ["round": "1"],
    isFinal: false
)

switch result {
case .success(let updated):
    if let updated {
        print("Updated matchup: \(updated.id)")
    } else {
        print("No matchup returned")
    }
case .failure(let error):
    print("Failed to submit score: \(error)")
}

---

Error Model

For specific error handling, please see Headless Interactions Error Handling section.

TournamentError

• .user(UserStateError) — Wraps user state errors

• .location(LocationError) — Wraps location errors

• .customError(message: String) — Custom error message

• .unknown — Unknown error

UserStateError

• .notInitialized

• .unverified

• .notAllowed

• .insufficientFunds

• .demographicInformationMissing

LocationError

• .unauthorized

• .unableToDetermineLocation(error)

• .clError(clError)

---