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

Methods

retrieveTournament

Retrieve a tournament with a given ID.

• Parameters:

  • tournamentId: ID associated with the tournament.

  • onResult: Callback with a result of type RetrieveTournamentResult

• Example usage:

LucraClient().retrieveTournament(tournamentId = "tournamentId") { result ->
    when (result) {
        is RetrieveTournamentResult.Failure -> {
            // Handle failure scenario
        }
        RetrieveTournamentResult.Success -> {
            // Handle success scenario
        }
    }
}

queryRecommendedTournaments

Retrieve a list of recommended tournaments.

• Parameters:

  • limit: The max number tournaments that will be returned.

  • offset: The starting index of the query.

  • includeCompletedTournaments: Should completed tournaments be included in the query.

  • onResult: Callback with a result of type QueryRecommendedTournamentsResult

• Example usage:

LucraClient().queryRecommendedTournaments(
  limit = 50,
  offset = 0,
  includeCompletedTournaments = true,
) { result ->
    when (result) {
        is QueryRecommendedTournamentsResult.Failure -> {
            // Handle failure scenario
        }
        QueryRecommendedTournamentsResult.Success -> {
            // Handle success scenario
        }
    }
}

submitUserScore

Submit a tournament score for a user.

• Parameters:

  • score: The score for the given attempt.

  • tournamentId: The unique ID of the tournament.

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

  • metadata: The metadata to include with the payload.

  • onResult: Callback with a result of type SubmitTournamentScoreResult;

• Example usage:

LucraClient().submitUserScore(
  score = 25,
  tournamentId = "tournamentId",
  isFinal = false,
  metadata = mapOf("key" to "value"),
) { result ->
    when (result) {
        is SubmitTournamentScoreResult.Failure -> {
            // Handle failure scenario
        }
        SubmitTournamentScoreResult.Success -> {
            // Handle success scenario
        }
    }
}

Errors:

• Throws an error if:

  • The user is not in a valid state to submit a score.

  • Request is has invalid data

  • Location services fail to provide coordinates.

  • A general network or API error occurs.

submitUserScoreByMetadata

Submit a tournament score by matching metadata criteria instead of a tournament ID.

• Parameters:

  • score: The score for the given attempt.

  • metadata: The metadata to include with the payload.

  • matchupMetadata: Optional metadata to match against existing matchups.

  • gameId: Optional game identifier.

  • locationId: Optional location identifier.

  • matchupId: Optional Lucra matchup identifier.

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

  • onResult: Callback with a result of type SubmitTournamentScoreMatchingResult.

• Example usage:

LucraClient().submitUserScoreByMetadata(
  score = 25,
  metadata = mapOf("key" to "value"),
  matchupMetadata = mapOf("key" to "value"),
  gameId = "gameId",
  locationId = "locationId",
  matchupId = "matchupId",
  isFinal = false,
) { result ->
    when (result) {
        is SubmitTournamentScoreMatchingResult.Failure -> {
            // Handle failure scenario
        }
        is SubmitTournamentScoreMatchingResult.SubmitTournamentScoreMatchingOutput -> {
            val affected = result.affectedMatchupIds
            val failed = result.failedMatchupIds
            // Handle success scenario
        }
    }
}

Errors:

• Throws an error if:

  • The user is not in a valid state to submit a score.

  • Request is has invalid data

  • Location services fail to provide coordinates.

  • A general network or API error occurs.

searchMatchupsByMetadata

Search for matchups by metadata and return Lucra matchup IDs.

• Parameters:

  • gameId: Optional game identifier.

  • locationId: Optional location identifier.

  • matchupId: Optional Lucra matchup identifier.

  • matchupMetadata: Optional metadata map to match against.

  • onResult: Callback with a result of type SearchMatchupsByMetadataResult.

• Example usage:

LucraClient().searchMatchupsByMetadata(
  gameId = "gameId",
  locationId = "locationId",
  matchupMetadata = mapOf("key" to "value"),
) { result ->
    when (result) {
        is SearchMatchupsByMetadataResult.Failure -> {
            // Handle failure scenario
        }
        is SearchMatchupsByMetadataResult.Success -> {
            val matchupIds = result.matchupIds
            // Handle success scenario
        }
    }
}

Errors:

• Throws an error if:

  • Location services fail to provide coordinates.

  • A general network or API error occurs.

joinTournament

Join a tournament with a given ID.

• Parameters:

  • tournamentId: ID associated with the tournament.

  • onResult: Callback with a result of type JoinTournamentResult

• Example usage:

LucraClient().joinTournament(tournamentId = "tournamentId") { result ->
    when (result) {
        is JoinTournamentResult.Failure -> {
            // Handle failure scenario
        }
        JoinTournamentResult.Success -> {
            // Handle success scenario
        }
    }
}

Errors:

• Throws an error if:

  • The user is not in a valid state to join.

  • Location services fail to provide coordinates.

  • Compliance validation fails.

    • If free buy in tournament, user demographic info is missing

  • Insufficient funds prevent the user from joining.

  • A general network or API error occurs.

Generic Errors:

All the Failure responses above are subtypes of FailedTournamentCall. This serves as a general way to parse errors coming from the tournament headless calls.

User State Errors (account-related issues)

• NotInitialized - User session not properly set up or account data missing

• Unverified - User hasn't completed identity verification (KYC) for real-money tournaments

• NotAllowed - User account restricted, suspended, or ineligible

• InsufficientFunds - Not enough balance for paid tournament entry

• DemographicInformationMissing - Missing email/zip code for free tournaments

Location Errors

• LocationError - Geographic restrictions (banned states, location services disabled, GeoComply failures)

API Errors

• APIError - Network issues, server errors, invalid responses, rate limits

FailedTournamentCall

These errors occur during tournament operations (retrieve, join, query, submit score) and help determine the appropriate user-facing message and recovery action.

sealed interface FailedTournamentCall {
    sealed interface UserStateError : FailedTournamentCall {
        data object NotInitialized : UserStateError
        data object Unverified : UserStateError
        data object NotAllowed : UserStateError
        data object InsufficientFunds : UserStateError
        data object DemographicInformationMissing : FailedTournamentCall
    }
    data class LocationError(val message: String) : FailedTournamentCall
    data class APIError(val message: String) : FailedTournamentCall
}

Example usage:

Headless join with handling for missing demographic info.

LucraClient().joinTournament(tournamentId = "tournament_123") { result ->
    when (result) {
        is JoinTournamentResult.Success -> {
            // Tournament joined successfully
            showMessage("Successfully joined tournament!")
        }

        is JoinTournamentResult.Failure -> {
            when (val error = result.failure) {
                // Handle free tournament demographic requirement
                is DemographicInformationMissing -> {
                    showDialog(
                        title = "Demographic Information Required",
                        message = "Please complete your demographic information to join free tournaments.",
                        positiveAction = {
                            launchFlow(LucraUiProvider.LucraFlow.DemographicForm)
                        }
                    )
                }
            }
        }
    }
}

Launching Demographic Form Independently

This feature was introduced in SDK version 5.0.0 and enhances the free buy-in tournament joining experience by ensuring users provide minimum necessary demographic information for compliance and improved user experience.

// Launch demographic collection form as a standalone flow
val demographicFlow = LucraUiProvider.LucraFlow.DemographicForm

// Using DialogFragment (recommended for full-screen experience)
val dialogFragment = LucraClient().getLucraDialogFragment(demographicFlow)
dialogFragment.show(supportFragmentManager, "DemographicForm")

3. Manual Demographic Data Validation

// Check if user has required demographic data before tournament operations
LucraClient().observeSDKUserFlow().collect { userResult ->
    when (userResult) {
        is SDKUserResult.Success -> {
            val user = userResult.sdkUser
            val hasRequiredData = !isMissingDemographicData(user)
            updateUI(hasRequiredData)
        }
        // Handle other states...
    }
}

private fun isMissingDemographicData(user: SDKUser): Boolean {
    return user.email.isNullOrEmpty() || user.zip.isNullOrEmpty()
}

Migration Guide

For Existing Integrators

If you're updating from an older SDK version:

1. Additive change - existing tournament joining code continues to work

2. New error handling - add handling for DemographicInformationMissing error

Example Migration

Before:

LucraClient().joinTournament(tournamentId) { result ->
    when (result) {
        is JoinTournamentResult.Success -> { /* handle success */ }
        is JoinTournamentResult.Failure -> {
            // Only handled KYC errors before
            if (result.failure is FailedTournamentCall.UserStateError.Unverified) {
                launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
            }
        }
    }
}

After:

LucraClient().joinTournament(tournamentId) { result ->
    when (result) {
        is JoinTournamentResult.Success -> { /* handle success */ }
        is JoinTournamentResult.Failure -> {
            when (result.failure) {
                is FailedTournamentCall.UserStateError.Unverified -> {
                    launchFlow(LucraUiProvider.LucraFlow.VerifyIdentity)
                }
                is FailedTournamentCall.DemographicInformationMissing -> {
                    launchFlow(LucraUiProvider.LucraFlow.DemographicForm)
                }
            }
        }
    }
}

Troubleshooting

Common Issues

• Demographic form not launching for free tournaments.

  • Ensure user authentication is complete before attempting to join tournaments

• Form not auto-filling previously entered data

  • The form should auto-fill based on saved user data. If not working, check user authentication state

• DemographicInformationMissing error not being handled.

  • Add the new error case to your tournament joining error handling