> For the complete documentation index, see [llms.txt](https://docs.clickoptions.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clickoptions.ai/api/public-contest.md).

# Public Contest

Public endpoints for contest information

## Join a contest

> Allows the authenticated user to join a contest. Creates a contest account, deposits the initial balance, and registers the participant.

```json
{"openapi":"3.1.0","info":{"title":"fintp-public-api","version":"0.0.1"},"tags":[{"name":"Public Contest","description":"Public endpoints for contest information"}],"servers":[{"url":"https://api.clickoptions.ai/api","description":"Generated server url"}],"paths":{"/v1/contest/{contestId}/join":{"post":{"tags":["Public Contest"],"summary":"Join a contest","description":"Allows the authenticated user to join a contest. Creates a contest account, deposits the initial balance, and registers the participant.","operationId":"joinContest","parameters":[{"name":"contestId","in":"path","description":"Contest ID","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JoinContestDto"}}},"required":true},"responses":{"200":{"description":"Successfully joined contest","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContestAccountInfoResponseDto"}}}},"400":{"description":"Invalid request - contest ended, disabled, deadline passed, nickname taken, or already registered"},"401":{"description":"Unauthorized - authentication required"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"JoinContestDto":{"type":"object","description":"Request body for joining a contest","properties":{"nickname":{"type":"string","description":"Nickname to display on the leaderboard","maxLength":255,"minLength":0}}},"ContestAccountInfoResponseDto":{"type":"object","description":"Complete contest account information with current state and historical snapshots","properties":{"id":{"type":"integer","format":"int64","description":"Contest account info ID"},"contestId":{"type":"integer","format":"int64","description":"Contest ID"},"accountId":{"type":"integer","format":"int64","description":"Account ID"},"fundedAccountId":{"type":"integer","format":"int64","description":"Funded account ID"},"userId":{"type":"integer","format":"int32","description":"User ID"},"demoContestAccountId":{"type":"integer","format":"int64","description":"Demo contest account ID"},"initialBalance":{"type":"number","description":"Initial balance for the contest account"},"joinTime":{"type":"string","format":"date-time","description":"Join time in ISO format"},"nickname":{"type":"string","description":"Participant's nickname or display name"},"contestStatus":{"type":"string","description":"Contest participation status"},"disqualificationReason":{"type":"string","description":"Reason for disqualification"},"currentRank":{"type":"integer","format":"int32","description":"Current rank in contest"},"currentNetPerformance":{"type":"number","description":"Current net performance percentage"},"currentEquity":{"type":"number","description":"Current equity"},"currentBalance":{"type":"number","description":"Current balance"},"totalTradesCount":{"type":"integer","format":"int32","description":"Total number of trades"},"tradingDaysCount":{"type":"integer","format":"int32","description":"Number of active trading days"},"currentMaxDrawdown":{"type":"number","description":"Current maximum drawdown percentage"},"currentMaxDayDrawdown":{"type":"number","description":"Current maximum daily drawdown percentage"},"lastSnapshotTime":{"type":"string","format":"date-time","description":"Latest snapshot time in ISO format"},"profitRatioViolated":{"type":"boolean","description":"Indicates if the profit ratio rule was violated"},"snapshotHistory":{"type":"array","description":"Historical snapshots for charting (ordered by time descending, max 30 entries)","items":{"$ref":"#/components/schemas/ContestAccountSnapshotHistoryDto"}}}},"ContestAccountSnapshotHistoryDto":{"type":"object","description":"Contest account snapshot data for historical charts","properties":{"snapshotTime":{"type":"string","format":"date-time","description":"Snapshot time in ISO format"},"equity":{"type":"number","description":"Current equity"},"balance":{"type":"number","description":"Current balance"},"netPerformance":{"type":"number","description":"Net performance percentage"},"maxDrawdown":{"type":"number","description":"Maximum drawdown percentage"},"maxDayDrawdown":{"type":"number","description":"Maximum daily drawdown percentage"},"totalTradesCount":{"type":"integer","format":"int32","description":"Total number of trades"},"tradingDaysCount":{"type":"integer","format":"int32","description":"Number of active trading days"},"rank":{"type":"integer","format":"int32","description":"Current rank"}}}}}}
```

## Get all contests categorized by status

> Retrieves all non-deleted contests categorized into active, upcoming, and ended lists. Includes participant count and top return for each contest.

```json
{"openapi":"3.1.0","info":{"title":"fintp-public-api","version":"0.0.1"},"tags":[{"name":"Public Contest","description":"Public endpoints for contest information"}],"servers":[{"url":"https://api.clickoptions.ai/api","description":"Generated server url"}],"paths":{"/v1/contest":{"get":{"tags":["Public Contest"],"summary":"Get all contests categorized by status","description":"Retrieves all non-deleted contests categorized into active, upcoming, and ended lists. Includes participant count and top return for each contest.","operationId":"getContests","responses":{"200":{"description":"Successfully retrieved contests","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContestsResult"}}}},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"ContestsResult":{"type":"object","description":"DTO representing categorized lists of contests for an account.","properties":{"active":{"type":"array","description":"List of active contests","items":{"$ref":"#/components/schemas/ContestInfoDto"}},"upcomming":{"type":"array","description":"List of upcoming contests","items":{"$ref":"#/components/schemas/ContestInfoDto"}},"ended":{"type":"array","description":"List of ended contests","items":{"$ref":"#/components/schemas/ContestInfoDto"}}}},"ContestInfoDto":{"type":"object","description":"DTO containing information about a contest.","properties":{"id":{"type":"integer","format":"int64","description":"Unique identifier of the contest"},"status":{"type":"string","description":"Current status of the contest (e.g., active, ended, upcoming)"},"pricePool":{"type":"string","description":"Prize pool for the contest"},"name":{"type":"string","description":"Name of the contest"},"currency":{"type":"string","description":"Currency used in the contest"},"startTime":{"type":"string","format":"date-time","description":"Start time of the contest in ISO format"},"endTime":{"type":"string","format":"date-time","description":"End time of the contest in ISO format"},"lastJoinTime":{"type":"string","format":"date-time","description":"Last allowed join time in ISO format"},"topReturn":{"type":"string","description":"Top return achieved in the contest"},"participants":{"type":"integer","format":"int32","description":"Number of participants in the contest"},"enabled":{"type":"boolean","description":"Whether the contest is enabled"},"initialDeposit":{"type":"number","description":"Initial deposit amount for participants"},"prizeDistributionBuckets":{"type":"array","description":"Prize distribution buckets (prize amounts)","items":{"type":"number"}},"minTotalTrades":{"type":"integer","format":"int32","description":"Minimum number of total trades required"},"minActiveTradingDays":{"type":"integer","format":"int32","description":"Minimum number of active trading days required"},"minNetPerformancePercent":{"type":"number","description":"Minimum net performance percentage required"},"maxTotalDrawdownPercent":{"type":"number","description":"Maximum allowed total drawdown percentage"},"maxDailyDrawdownPercent":{"type":"number","description":"Maximum allowed daily drawdown percentage"},"maxSingleTradePnlPercent":{"type":"number","description":"Maximum allowed single trade PnL percentage"},"profitRatioRuleEnabled":{"type":"boolean","description":"Whether profit ratio rule is enabled"},"minPremiumPercentPerTrade":{"type":"number","description":"Minimum premium percentage per trade"},"minTradeHoldMinutes":{"type":"integer","format":"int32","description":"Minimum time to hold a trade in minutes"},"minExpiryHoldPercent":{"type":"number","description":"Minimum expiry hold percentage"},"minExpiryHours":{"type":"integer","format":"int32","description":"Minimum number of hours until expiry"}}}}}}
```

## Get contest by ID

> Retrieves detailed information about a specific contest by its ID, including all metadata and statistics.

```json
{"openapi":"3.1.0","info":{"title":"fintp-public-api","version":"0.0.1"},"tags":[{"name":"Public Contest","description":"Public endpoints for contest information"}],"servers":[{"url":"https://api.clickoptions.ai/api","description":"Generated server url"}],"paths":{"/v1/contest/{id}":{"get":{"tags":["Public Contest"],"summary":"Get contest by ID","description":"Retrieves detailed information about a specific contest by its ID, including all metadata and statistics.","operationId":"getContestById","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successfully retrieved contest","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContestInfoDto"}}}},"404":{"description":"Contest not found"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"ContestInfoDto":{"type":"object","description":"DTO containing information about a contest.","properties":{"id":{"type":"integer","format":"int64","description":"Unique identifier of the contest"},"status":{"type":"string","description":"Current status of the contest (e.g., active, ended, upcoming)"},"pricePool":{"type":"string","description":"Prize pool for the contest"},"name":{"type":"string","description":"Name of the contest"},"currency":{"type":"string","description":"Currency used in the contest"},"startTime":{"type":"string","format":"date-time","description":"Start time of the contest in ISO format"},"endTime":{"type":"string","format":"date-time","description":"End time of the contest in ISO format"},"lastJoinTime":{"type":"string","format":"date-time","description":"Last allowed join time in ISO format"},"topReturn":{"type":"string","description":"Top return achieved in the contest"},"participants":{"type":"integer","format":"int32","description":"Number of participants in the contest"},"enabled":{"type":"boolean","description":"Whether the contest is enabled"},"initialDeposit":{"type":"number","description":"Initial deposit amount for participants"},"prizeDistributionBuckets":{"type":"array","description":"Prize distribution buckets (prize amounts)","items":{"type":"number"}},"minTotalTrades":{"type":"integer","format":"int32","description":"Minimum number of total trades required"},"minActiveTradingDays":{"type":"integer","format":"int32","description":"Minimum number of active trading days required"},"minNetPerformancePercent":{"type":"number","description":"Minimum net performance percentage required"},"maxTotalDrawdownPercent":{"type":"number","description":"Maximum allowed total drawdown percentage"},"maxDailyDrawdownPercent":{"type":"number","description":"Maximum allowed daily drawdown percentage"},"maxSingleTradePnlPercent":{"type":"number","description":"Maximum allowed single trade PnL percentage"},"profitRatioRuleEnabled":{"type":"boolean","description":"Whether profit ratio rule is enabled"},"minPremiumPercentPerTrade":{"type":"number","description":"Minimum premium percentage per trade"},"minTradeHoldMinutes":{"type":"integer","format":"int32","description":"Minimum time to hold a trade in minutes"},"minExpiryHoldPercent":{"type":"number","description":"Minimum expiry hold percentage"},"minExpiryHours":{"type":"integer","format":"int32","description":"Minimum number of hours until expiry"}}}}}}
```

## Get contest leaderboard

> Retrieves the leaderboard for a specific contest with participant rankings and performance data. Supports pagination with optional page and size parameters.

```json
{"openapi":"3.1.0","info":{"title":"fintp-public-api","version":"0.0.1"},"tags":[{"name":"Public Contest","description":"Public endpoints for contest information"}],"servers":[{"url":"https://api.clickoptions.ai/api","description":"Generated server url"}],"paths":{"/v1/contest/{contestId}/leaderboard":{"get":{"tags":["Public Contest"],"summary":"Get contest leaderboard","description":"Retrieves the leaderboard for a specific contest with participant rankings and performance data. Supports pagination with optional page and size parameters.","operationId":"getContestLeaderboard","parameters":[{"name":"contestId","in":"path","description":"Contest ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Page number (0-indexed)","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"size","in":"query","description":"Page size (number of entries per page)","required":false,"schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"Successfully retrieved leaderboard","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContestLeaderboardEntryDto"}}}},"404":{"description":"Contest not found"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"ContestLeaderboardEntryDto":{"type":"object","description":"Contest leaderboard entry with participant performance data","properties":{"id":{"type":"integer","format":"int64","description":"Contest account info ID"},"rank":{"type":"integer","format":"int32","description":"Current rank in the contest"},"nickname":{"type":"string","description":"Participant's nickname or display name"},"netPerformance":{"type":"number","description":"Net performance percentage"},"totalTradesCount":{"type":"integer","format":"int32","description":"Total number of trades"},"tradingDaysCount":{"type":"integer","format":"int32","description":"Number of active trading days"},"maxDrawdown":{"type":"number","description":"Maximum drawdown percentage"},"maxDayDrawdown":{"type":"number","description":"Maximum daily drawdown percentage"},"joinTime":{"type":"string","format":"date-time","description":"Join time in ISO format"},"contestStatus":{"type":"string","description":"Contest participation status"}}}}}}
```

## Get contest account information for authenticated user

> Retrieves the authenticated user's contest account information including current performance, latest snapshot data, and historical snapshots for charting (up to 30 most recent snapshots).

```json
{"openapi":"3.1.0","info":{"title":"fintp-public-api","version":"0.0.1"},"tags":[{"name":"Public Contest","description":"Public endpoints for contest information"}],"servers":[{"url":"https://api.clickoptions.ai/api","description":"Generated server url"}],"paths":{"/v1/contest/{contestId}/account-info":{"get":{"tags":["Public Contest"],"summary":"Get contest account information for authenticated user","description":"Retrieves the authenticated user's contest account information including current performance, latest snapshot data, and historical snapshots for charting (up to 30 most recent snapshots).","operationId":"getContestAccountInfo","parameters":[{"name":"contestId","in":"path","description":"Contest ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successfully retrieved contest account information","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ContestAccountInfoResponseDto"}}}},"401":{"description":"Unauthorized - authentication required"},"404":{"description":"Contest or account not found"},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"ContestAccountInfoResponseDto":{"type":"object","description":"Complete contest account information with current state and historical snapshots","properties":{"id":{"type":"integer","format":"int64","description":"Contest account info ID"},"contestId":{"type":"integer","format":"int64","description":"Contest ID"},"accountId":{"type":"integer","format":"int64","description":"Account ID"},"fundedAccountId":{"type":"integer","format":"int64","description":"Funded account ID"},"userId":{"type":"integer","format":"int32","description":"User ID"},"demoContestAccountId":{"type":"integer","format":"int64","description":"Demo contest account ID"},"initialBalance":{"type":"number","description":"Initial balance for the contest account"},"joinTime":{"type":"string","format":"date-time","description":"Join time in ISO format"},"nickname":{"type":"string","description":"Participant's nickname or display name"},"contestStatus":{"type":"string","description":"Contest participation status"},"disqualificationReason":{"type":"string","description":"Reason for disqualification"},"currentRank":{"type":"integer","format":"int32","description":"Current rank in contest"},"currentNetPerformance":{"type":"number","description":"Current net performance percentage"},"currentEquity":{"type":"number","description":"Current equity"},"currentBalance":{"type":"number","description":"Current balance"},"totalTradesCount":{"type":"integer","format":"int32","description":"Total number of trades"},"tradingDaysCount":{"type":"integer","format":"int32","description":"Number of active trading days"},"currentMaxDrawdown":{"type":"number","description":"Current maximum drawdown percentage"},"currentMaxDayDrawdown":{"type":"number","description":"Current maximum daily drawdown percentage"},"lastSnapshotTime":{"type":"string","format":"date-time","description":"Latest snapshot time in ISO format"},"profitRatioViolated":{"type":"boolean","description":"Indicates if the profit ratio rule was violated"},"snapshotHistory":{"type":"array","description":"Historical snapshots for charting (ordered by time descending, max 30 entries)","items":{"$ref":"#/components/schemas/ContestAccountSnapshotHistoryDto"}}}},"ContestAccountSnapshotHistoryDto":{"type":"object","description":"Contest account snapshot data for historical charts","properties":{"snapshotTime":{"type":"string","format":"date-time","description":"Snapshot time in ISO format"},"equity":{"type":"number","description":"Current equity"},"balance":{"type":"number","description":"Current balance"},"netPerformance":{"type":"number","description":"Net performance percentage"},"maxDrawdown":{"type":"number","description":"Maximum drawdown percentage"},"maxDayDrawdown":{"type":"number","description":"Maximum daily drawdown percentage"},"totalTradesCount":{"type":"integer","format":"int32","description":"Total number of trades"},"tradingDaysCount":{"type":"integer","format":"int32","description":"Number of active trading days"},"rank":{"type":"integer","format":"int32","description":"Current rank"}}}}}}
```