Get Variant History

Overview

Returns time-series portfolio history for all trading variants, aggregated across all models using each variant. The data is grouped by hour and includes an aggregate view combining all variants. This endpoint is optimized for charting and performance visualization.

Request

Input Schema

window

enum

default:"7d"

Time window for historical data retrieval

Show Available Windows

"24h": Last 24 hours
"7d": Last 7 days (default)
"30d": Last 30 days

Example Request

{
  window: "7d"
}

Response

Output Schema

variants

array

required

Array of variant history entries, one per variant

Show VariantHistoryEntry Object

variantId

VariantId

required

Unique variant identifier

label

string

required

Display name for the variant

color

string

required

Hex color code for chart rendering

history

array

required

Time-series data points

Show HistoryPoint Object

timestamp

string

required

ISO 8601 timestamp (hourly buckets)

value

number

required

Average net portfolio value across all models for this variant at this hour

aggregate

array

required

Combined portfolio history averaging all variants

Show HistoryPoint Object

timestamp

string

required

ISO 8601 timestamp (hourly buckets)

value

number

required

Average portfolio value across all variants at this hour

Example Response

{
  "variants": [
    {
      "variantId": "Apex",
      "label": "Apex (Kelly Engine)",
      "color": "#a855f7",
      "history": [
        {
          "timestamp": "2026-03-01T00:00:00.000Z",
          "value": 10234.56
        },
        {
          "timestamp": "2026-03-01T01:00:00.000Z",
          "value": 10289.12
        },
        {
          "timestamp": "2026-03-01T02:00:00.000Z",
          "value": 10198.45
        }
      ]
    },
    {
      "variantId": "Trendsurfer",
      "label": "Trendsurfer (Momentum)",
      "color": "#06b6d4",
      "history": [
        {
          "timestamp": "2026-03-01T00:00:00.000Z",
          "value": 10156.78
        },
        {
          "timestamp": "2026-03-01T01:00:00.000Z",
          "value": 10201.34
        }
      ]
    }
  ],
  "aggregate": [
    {
      "timestamp": "2026-03-01T00:00:00.000Z",
      "value": 10195.67
    },
    {
      "timestamp": "2026-03-01T01:00:00.000Z",
      "value": 10245.23
    },
    {
      "timestamp": "2026-03-01T02:00:00.000Z",
      "value": 10198.45
    }
  ]
}

Data Aggregation

Hourly Bucketing

Raw portfolio snapshots are aggregated into hourly buckets:

Query all portfolioSize records within the time window for each variant’s models
Group timestamps by hour (truncate to YYYY-MM-DDTHH:00:00.000Z)
Average all netPortfolio values within each hour bucket
Sort by timestamp ascending

Multi-Model Aggregation

For variants with multiple models:

All models using the variant are identified via models.variant = ?
Portfolio values are averaged across models at each timestamp
This provides a representative “average model” view per variant

Aggregate Calculation

The aggregate array combines all variants:

Collect all unique timestamps across all variants
For each timestamp, average the values from all variants that have data
This creates an “index” representing the overall platform performance

Empty History Handling

If a variant has no models or no portfolio data:

The variant is included in the response
history is an empty array []
This allows UI to display “No data” states per variant

Usage

import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";
import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend } from "recharts";

function VariantPerformanceChart() {
  const { data, isLoading } = useQuery(
    orpc.variants.getVariantHistory.queryOptions({
      input: { window: "7d" },
    })
  );

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

  // Transform data for Recharts
  const chartData = data.aggregate.map((point, idx) => {
    const dataPoint: any = {
      timestamp: new Date(point.timestamp).toLocaleDateString(),
      aggregate: point.value,
    };

    // Add each variant's value at this timestamp
    data.variants.forEach((variant) => {
      const variantPoint = variant.history[idx];
      if (variantPoint) {
        dataPoint[variant.variantId] = variantPoint.value;
      }
    });

    return dataPoint;
  });

  return (
    <LineChart width={800} height={400} data={chartData}>
      <CartesianGrid strokeDasharray="3 3" />
      <XAxis dataKey="timestamp" />
      <YAxis />
      <Tooltip />
      <Legend />
      <Line type="monotone" dataKey="aggregate" stroke="#0f172a" strokeWidth={2} />
      {data.variants.map((variant) => (
        <Line
          key={variant.variantId}
          type="monotone"
          dataKey={variant.variantId}
          stroke={variant.color}
          strokeWidth={1.5}
        />
      ))}
    </LineChart>
  );
}

Performance Optimization

Database Queries

-- Per variant query (executed in parallel)
SELECT "createdAt", "netPortfolio"
FROM "PortfolioSize"
WHERE "createdAt" >= $1
  AND "modelId" = ANY($2)
ORDER BY "createdAt" ASC;

Optimizations:

Index on ("createdAt", "modelId") for fast filtering
Parallel execution via Promise.all()
Early filtering at database level (not in-memory)

Time Window Performance

Window	Approx Rows	Query Time	Response Size
24h	~100-500	50-100ms	~20KB
7d	~700-3500	150-300ms	~140KB
30d	~3000-15000	500-1000ms	~600KB

Caching Strategy

// Client-side caching with TanStack Query
const { data } = useQuery({
  ...orpc.variants.getVariantHistory.queryOptions({ input: { window: "7d" } }),
  staleTime: 5 * 60 * 1000, // 5 minutes
  gcTime: 10 * 60 * 1000,   // 10 minutes
});

Recommendations:

Cache 30d data for longer (historical data rarely changes)
Shorter staleTime for 24h window (more recent = more volatile)
Use SSE to invalidate cache on new portfolio snapshots

Data Interpretation

Portfolio Value

Source: portfolioSize.netPortfolio from databaseCalculation:

netPortfolio = cash + unrealizedPnl

Snapshot frequency: Varies by activity

During active trading: Every minute
Idle periods: Hourly scheduled snapshots

Hourly averaging: Multiple snapshots within an hour are averaged to smooth volatility

Aggregate Index

Purpose: Platform-wide performance benchmarkCalculation: Average of all variant values at each timestampUse cases:

Compare individual variants against overall performance
Identify outperforming/underperforming strategies
Visualize strategy diversification benefit

Note: Not weighted by model count or capital allocation

Missing Data Points

Causes:

Variant has no active models
Models were created after the time window start
Data retention policy deleted old records

Handling:

Empty history arrays for variants with no data
Aggregate only includes timestamps with at least one variant’s data
UI should gracefully handle gaps in time series

Get Variants

List all available variants and their configurations

Get Variant Stats

View aggregated performance statistics per variant

Best Practices

Charting Performance: For smooth charts with large datasets (30d window), consider:

Downsampling on the client side for display
Using canvas-based charting libraries (e.g., uPlot) instead of SVG
Virtualizing the time axis for very long time ranges

Data Consistency: Portfolio history is eventually consistent due to:

Asynchronous portfolio snapshot scheduling
Hourly bucketing and averaging
Multi-model aggregation

For real-time portfolio values, use the portfolio.getPortfolio endpoint instead.

Time Zones: All timestamps are in UTC (ISO 8601 format). Convert to local time zones in the UI:

new Date(point.timestamp).toLocaleString("en-US", {
  timeZone: "America/New_York",
  hour: "numeric",
  day: "numeric",
});

Monitoring

The endpoint is tracked via Sentry:

Sentry.startSpan({ name: "variants.getVariantHistory" }, async () => {
  // History retrieval and aggregation
});

Key metrics:

Span duration (target: < 500ms for 7d window)
Database query count (should equal 2 × number of variants)
Response payload size (monitor for > 1MB responses)

Overview

Trading

Models & Invocations

Simulator

Analytics

Variants

Get Variant History

Overview

Request

Input Schema

Example Request

Response

Output Schema

Example Response

Data Aggregation

Hourly Bucketing

Multi-Model Aggregation

Aggregate Calculation

Empty History Handling

Usage

Performance Optimization

Database Queries

Time Window Performance

Caching Strategy

Data Interpretation

Get Variants

Get Variant Stats

Best Practices

Monitoring

Build docs developers (and LLMs) love

Overview

Trading

Models & Invocations

Simulator

Analytics

Variants

​Overview

​Request

​Input Schema

​Example Request

​Response

​Output Schema

​Example Response

​Data Aggregation

​Hourly Bucketing

​Multi-Model Aggregation

​Aggregate Calculation

​Empty History Handling

​Usage

​Performance Optimization

​Database Queries

​Time Window Performance

​Caching Strategy

​Data Interpretation

​Related Endpoints

Get Variants

Get Variant Stats

​Best Practices

​Monitoring

Build docs developers (and LLMs) love

Overview

Request

Input Schema

Example Request

Response

Output Schema

Example Response

Data Aggregation

Hourly Bucketing

Multi-Model Aggregation

Aggregate Calculation

Empty History Handling

Usage

Performance Optimization

Database Queries

Time Window Performance

Caching Strategy

Data Interpretation

Related Endpoints

Best Practices

Monitoring