Leaderboards & PnL Tracking
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/[locale]/(platform)/leaderboard/[[...filters]]/page.tsx
- src/app/[locale]/(platform)/leaderboard/_components/LeaderboardClient.tsx
- src/app/[locale]/(platform)/leaderboard/_utils/leaderboardApi.ts
- src/app/[locale]/(platform)/leaderboard/_utils/leaderboardFilters.ts
- src/app/api/og/leaderboard/route.tsx
- src/app/[locale]/(platform)/leaderboard/_components/BiggestWinsSidebar.tsx
The Leaderboards & PnL (Profit and Loss) tracking system provides a comprehensive view of trader performance and market success within the platform. It enables users to view top-performing traders ranked by profit or volume across various timeframes and categories, while also highlighting individual "Biggest Wins" to showcase high-impact trades.
This system integrates data from the platform's Data API and specialized internal endpoints to calculate performance metrics. It includes features for filtering by market category (e.g., Politics, Sports, Crypto), time periods (Today, Weekly, Monthly, All), and specific metrics (Profit/Loss vs. Volume), ensuring a dynamic and personalized experience for users monitoring market activity and trader success.
Sources: src/app/[locale]/(platform)/leaderboard/[[...filters]]/page.tsx, src/app/[locale]/(platform)/leaderboard/_components/LeaderboardClient.tsx:10-40
Architecture and Data Flow
The leaderboard system follows a client-server architecture where the frontend consumes a specialized Data API to fetch ranked lists and winning entries.
Components and Visualization
The primary entry point is the LeaderboardPage, which parses URL segments into filters and initializes the LeaderboardClient. The client manages three distinct data streams:
- Leaderboard Entries: Paginated lists of traders fetched based on category, timeframe, and metric.
- Pinned User Context: Displays the authenticated user's current rank and performance relative to the leaderboard.
- Biggest Wins: A sidebar component showcasing the most significant individual trade outcomes.
The diagram shows the interaction between the Leaderboard frontend components and the various backend API endpoints used to populate the performance views.
Sources: src/app/[locale]/(platform)/leaderboard/_components/LeaderboardClient.tsx:45-120, src/app/[locale]/(platform)/leaderboard/_utils/leaderboardApi.ts:106-125
Filtering and Parameters
The system supports granular filtering through URL segments. Filters are normalized and validated to ensure consistency between the UI and API requests.
Filter Options
| Parameter | Values | API Mapping |
|---|---|---|
| Category | overall, politics, sports, crypto, finance, culture, mentions, weather, economics, tech | mapped to category |
| Period | today, weekly, monthly, all | day, week, month, all |
| Order | profit, volume | PNL, VOL |
Sources: src/app/[locale]/(platform)/leaderboard/_utils/leaderboardFilters.ts:1-35
Implementation Detail: URL Parsing
The system uses a flexible path structure: /leaderboard/[category]/[period]/[order]. If segments are missing, it falls back to overall, monthly, and profit.
Sources: src/app/[locale]/(platform)/leaderboard/_utils/leaderboardFilters.ts:63-75, src/app/[locale]/(platform)/leaderboard/[[...filters]]/page.tsx:107-113
PnL Tracking and Hydration
A critical aspect of the leaderboard is the "Hydration" process. While the base leaderboard API provides ranks and volume, precise Profit/Loss (PnL) for specific timeframes is often fetched in batches via a proxy endpoint to ensure data accuracy.
Hydration Logic
When the category is set to "overall," the client triggers hydrateEntriesWithPortfolioPnl. This function extracts wallet addresses from the leaderboard entries and performs a POST request to /api/leaderboard/timeframe-pnl to retrieve real-time PnL data.
Sequence of events during the data hydration phase to augment base leaderboard data with specific PnL metrics.
Sources: src/app/[locale]/(platform)/leaderboard/_utils/leaderboardApi.ts:168-210, src/app/[locale]/(platform)/leaderboard/_components/LeaderboardClient.tsx:105-125
Biggest Wins Sidebar
The "Biggest Wins" feature highlights specific trade successes. Unlike the main leaderboard which tracks aggregate user performance, this sidebar focuses on individual events.
Data Resolution
The BiggestWinRow component resolves complex data structures from the API, which may contain nested user and event objects. It uses helper functions to extract:
- User Identity: Prefers
userNameorxUsername, falling back to a truncatedproxyWalletaddress. - Event Context: Displays the event title and provides a direct link to the specific market if available.
- Performance: Visualizes "Amount In" (Investment) vs. "Amount Out" (Payout) with directional arrows.
Sources: src/app/[locale]/(platform)/leaderboard/_components/BiggestWinsSidebar.tsx:50-100, src/app/[locale]/(platform)/leaderboard/_utils/leaderboardApi.ts:60-90
Social Sharing and Metadata
The platform generates dynamic Open Graph (OG) images for leaderboards to facilitate social sharing. This is handled by a specialized API route that renders a visual summary of the top traders.
OG Image Generation
The route /api/og/leaderboard fetches the top 8 rows for the requested filters and renders an image containing:
- Site Branding: Logo and Name.
- Filter Context: Visual badges for the selected category and period.
- Rankings: A table showing Rank, Avatar (or generated gradient), Username, and the primary metric (PnL or Volume).
Sources: src/app/api/og/leaderboard/route.tsx:115-180, src/app/[locale]/(platform)/leaderboard/[[...filters]]/page.tsx:35-50
Key Data Structures
LeaderboardEntry
Used for both the main list and the OG image generation.
| Field | Type | Description |
|---|---|---|
rank | string | The user's position in the leaderboard. |
userName | string | Display name of the trader. |
proxyWallet | string | The stable wallet address used as a tie-breaker in sorting. |
pnl | number | Calculated Profit and Loss. |
vol | number | Total trading volume. |
Sources: src/app/[locale]/(platform)/leaderboard/_utils/leaderboardApi.ts:15-30, src/app/api/og/leaderboard/route.tsx:15-25
Summary
The Leaderboards & PnL Tracking system provides a multi-faceted view of market participation. By combining paginated aggregate rankings with high-impact "Biggest Wins" and dynamic social metadata, the system encourages competition and transparency. The implementation relies on robust data normalization and a hydration pattern that ensures real-time PnL accuracy across diverse market categories and timeframes.