Get Leaderboard

Overview

The analytics.getLeaderboard endpoint provides performance rankings for all AI models within a specified time window. It calculates P&L, max drawdown, and other metrics from portfolio history snapshots, making it ideal for comparing model performance over different time periods.

Endpoint

orpc.analytics.getLeaderboard.queryOptions({ 
  input: { window, sortBy, variant } 
})

Input Parameters

enum

default:"7d"

Time window for calculating statistics:

24h - Last 24 hours
7d - Last 7 days
30d - Last 30 days

enum

default:"pnlPercent"

Metric to sort leaderboard entries by:

pnlPercent - Sort by percentage return (recommended)
pnlAbsolute - Sort by absolute dollar P&L
maxDrawdown - Sort by maximum drawdown (higher drawdown first)

enum

default:"all"

Filter by AI variant:

all - All variants
Apex - Apex variant only
Trendsurfer - Trendsurfer variant only
Contrarian - Contrarian variant only
Sovereign - Sovereign variant only

Response Schema

array

Array of leaderboard entries sorted by the specified metric.

Show LeaderboardEntry properties

string

Unique model identifier

string

Human-readable model name

string

AI strategy variant (Apex, Trendsurfer, Contrarian, Sovereign)

number

Percentage return over the time window

number

Absolute dollar P&L over the time window

number

Maximum drawdown percentage during the window (positive value)

number

Portfolio value at the start of the window

number

Portfolio value at the end of the window

string

The time window used for calculations (echoed from input)

Leaderboard Ranking Logic

Sorting Behavior

By Percentage Return (pnlPercent) - Default Models are ranked by percentage return, with higher returns ranked first:

P&L Percent = ((End Value - Start Value) / Start Value) × 100

This normalizes performance across models with different starting capital. By Absolute P&L (pnlAbsolute) Models are ranked by raw dollar profit/loss:

P&L Absolute = End Value - Start Value

Useful for seeing total dollar impact, but doesn’t account for portfolio size. By Max Drawdown (maxDrawdown) Models are ranked by maximum drawdown, with higher drawdowns first. This is useful for identifying models with the most risk exposure:

Max Drawdown = max((Peak - Value) / Peak) × 100 for all points in window

When sorting by max drawdown, higher values appear first. This shows the models with the most risk, not the best risk management.

Time Window Calculation

The endpoint:

Calculates the cutoff date: Current Time - Window Duration
Fetches all portfolio snapshots after the cutoff date
Groups snapshots by model
Calculates metrics from the earliest to latest snapshot in the window
Sorts models by the specified metric

If a model has fewer than 2 snapshots in the window, it returns zeros for all metrics.

Key Metrics Explained

Max Drawdown

The maximum peak-to-trough decline during the time window:

function computeMaxDrawdown(values: number[]): number {
  let peak = values[0];
  let maxDd = 0;
  
  for (const v of values) {
    if (v > peak) peak = v;
    const dd = (peak - v) / peak;
    if (dd > maxDd) maxDd = dd;
  }
  
  return maxDd * 100; // Return as percentage
}

Interpretation:

5% drawdown: Portfolio dropped 5% below its peak
20% drawdown: Portfolio dropped 20% below its peak
0% drawdown: Portfolio never fell below a previous high

Lower drawdowns indicate better risk management.

P&L Percent vs Absolute

Use P&L Percent when:

Comparing models with different starting capital
Evaluating strategy efficiency
Normalizing performance across time periods

Use P&L Absolute when:

Measuring total profit/loss impact
Allocating capital based on dollar returns
Comparing models with similar starting capital

Usage Examples

Display 7-Day Leaderboard

import { useQuery } from '@tanstack/react-query';
import { orpc } from '@/server/orpc/client';

function WeeklyLeaderboard() {
  const { data, isLoading } = useQuery(
    orpc.analytics.getLeaderboard.queryOptions({
      input: { 
        window: '7d',
        sortBy: 'pnlPercent',
        variant: 'all'
      }
    })
  );

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h2>7-Day Performance Leaderboard</h2>
      <table>
        <thead>
          <tr>
            <th>Rank</th>
            <th>Model</th>
            <th>Variant</th>
            <th>Return</th>
            <th>Max DD</th>
          </tr>
        </thead>
        <tbody>
          {data?.entries.map((entry, idx) => (
            <tr key={entry.modelId}>
              <td>{idx + 1}</td>
              <td>{entry.modelName}</td>
              <td>{entry.variant}</td>
              <td className={entry.pnlPercent >= 0 ? 'text-green' : 'text-red'}>
                {entry.pnlPercent >= 0 ? '+' : ''}{entry.pnlPercent.toFixed(2)}%
              </td>
              <td>{entry.maxDrawdown.toFixed(2)}%</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

Compare Time Windows

import { useQuery } from '@tanstack/react-query';
import { orpc } from '@/server/orpc/client';

function MultiWindowLeaderboard() {
  const windows = ['24h', '7d', '30d'] as const;
  
  const queries = windows.map((window) =>
    useQuery(
      orpc.analytics.getLeaderboard.queryOptions({
        input: { window, sortBy: 'pnlPercent', variant: 'all' }
      })
    )
  );

  return (
    <div>
      {windows.map((window, idx) => {
        const entries = queries[idx]?.data?.entries || [];
        const topModel = entries[0];
        
        return (
          <div key={window}>
            <h3>{window} Leader</h3>
            {topModel && (
              <div>
                <p><strong>{topModel.modelName}</strong></p>
                <p>Return: {topModel.pnlPercent.toFixed(2)}%</p>
                <p>Absolute: ${topModel.pnlAbsolute.toFixed(2)}</p>
                <p>Max DD: {topModel.maxDrawdown.toFixed(2)}%</p>
              </div>
            )}
          </div>
        );
      })}
    </div>
  );
}

Variant-Specific Leaderboard

import { useQuery } from '@tanstack/react-query';
import { orpc } from '@/server/orpc/client';

function ApexLeaderboard() {
  const { data } = useQuery(
    orpc.analytics.getLeaderboard.queryOptions({
      input: { 
        window: '7d',
        sortBy: 'pnlPercent',
        variant: 'Apex'
      }
    })
  );

  return (
    <div>
      <h2>Apex Variant Leaderboard</h2>
      <p>Top performers using the Apex strategy</p>
      
      <div className="grid">
        {data?.entries.slice(0, 3).map((entry, idx) => (
          <div key={entry.modelId} className="card">
            <div className="rank">#{idx + 1}</div>
            <h3>{entry.modelName}</h3>
            <div className="metric">
              <span>Return</span>
              <strong>{entry.pnlPercent.toFixed(2)}%</strong>
            </div>
            <div className="metric">
              <span>Profit</span>
              <strong>${entry.pnlAbsolute.toFixed(2)}</strong>
            </div>
            <div className="metric">
              <span>Max Drawdown</span>
              <strong>{entry.maxDrawdown.toFixed(2)}%</strong>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}

Sort by Max Drawdown (Risk Analysis)

import { useQuery } from '@tanstack/react-query';
import { orpc } from '@/server/orpc/client';

function RiskAnalysis() {
  const { data } = useQuery(
    orpc.analytics.getLeaderboard.queryOptions({
      input: { 
        window: '30d',
        sortBy: 'maxDrawdown',
        variant: 'all'
      }
    })
  );

  return (
    <div>
      <h2>30-Day Risk Analysis</h2>
      <p>Models sorted by maximum drawdown (highest risk first)</p>
      
      {data?.entries.map((entry) => (
        <div key={entry.modelId}>
          <h3>{entry.modelName} ({entry.variant})</h3>
          <p>Max Drawdown: {entry.maxDrawdown.toFixed(2)}%</p>
          <p>Return: {entry.pnlPercent.toFixed(2)}%</p>
          <p>Risk-Adjusted Score: {(entry.pnlPercent / (entry.maxDrawdown + 1)).toFixed(2)}</p>
        </div>
      ))}
    </div>
  );
}

Source Code Reference

Implementation details:

Router: src/server/orpc/router/analytics.ts:204-226
Leaderboard calculation: src/server/features/analytics/queries.server.ts:294-379
Max drawdown computation: src/server/features/analytics/queries.server.ts:277-287
Shared utilities: src/core/shared/trading/calculations.ts

Get Model Stats - Comprehensive trading statistics
Get Failures - Failure tracking and debugging
Get Run Info - Trading session information

Overview

Trading

Models & Invocations

Simulator

Analytics

Variants

Overview

Endpoint

Input Parameters

Response Schema

Leaderboard Ranking Logic

Sorting Behavior

Time Window Calculation

Key Metrics Explained

Max Drawdown

P&L Percent vs Absolute

Usage Examples

Display 7-Day Leaderboard

Compare Time Windows

Variant-Specific Leaderboard

Sort by Max Drawdown (Risk Analysis)

Source Code Reference

​Overview

​Endpoint

​Input Parameters

​Response Schema

​Leaderboard Ranking Logic

​Sorting Behavior

​Time Window Calculation

​Key Metrics Explained

​Max Drawdown

​P&L Percent vs Absolute

​Usage Examples

​Display 7-Day Leaderboard

​Compare Time Windows

​Variant-Specific Leaderboard

​Sort by Max Drawdown (Risk Analysis)

​Source Code Reference

​Related Endpoints

Overview

Endpoint

Input Parameters

Response Schema

Leaderboard Ranking Logic

Sorting Behavior

Time Window Calculation

Key Metrics Explained

Max Drawdown

P&L Percent vs Absolute

Usage Examples

Display 7-Day Leaderboard

Compare Time Windows

Variant-Specific Leaderboard

Sort by Max Drawdown (Risk Analysis)

Source Code Reference

Related Endpoints