API Documentation

Discover all available factors. Returns a comprehensive catalog of all factor IDs organized by category (Market/Macro, Style, Sector, Industry, Country, Custom), with descriptions and usage examples.

Categories include:

• market_macro - Market, OilPrice, GoldPrice, InterestRate, USDollar
• style - SmallSize, Momentum, Value, Quality, LowVolatility, Growth, BetaFactor, DividendYield, Liquidity
• sector - 11 GICS sectors (Technology, Financial, Healthcare, etc.)
• industry - ~50 industries (Semiconductors, Biotechnology, Regional Banks, etc.)
• country - ~40 countries (Japan, Germany, Brazil, China, etc.)
• custom - ~80 AI-discovered thematic baskets

Response includes: factor_id, display_name, description for each factor, plus API usage examples.

Returns real-time intraday performance data with z-scores for all tracked factors. Optimized for frequent polling (every 5 seconds).

Response: { "Market": { "value": 0.00123, "zScore": 0.45 }, ... }

Returns historic multi-day returns (3d, 5d, 10d, 21d, 63d, 126d, 252d) with z-scores for all factors. Designed to be fetched once on page load.

Response: { "Market": { "3d": { "value": 0.012, "zScore": 0.8 }, "5d": {...}, "21d": {...}, ... }, ... }

Retrieves historical time-series data for a specific factor. Returns date and close values in chronological order.

Query params: ?days=N (default: 365)

Returns stocks and their beta exposures to a specific factor. The factor name must be base64 encoded to handle special characters.

Query params: ?type=all|common|etf|both

Returns daily returns for all factors over a specified period, suitable for rendering sparkline charts.

Query params: ?days=N (default: 30)

Returns the correlation matrix for all basic factors over a specified time period.

Query params: ?days=N (default: 63, options: 3, 5, 10, 21, 63, 126, 252)

Returns the component stocks/ETFs that make up a custom factor basket, including their weights.

Returns the replication equation for a specific factor, including all component weights (tickers and factors). The factor name must be base64 encoded.

Response: { "factor_name": "...", "equation": { "ticker1": weight, "Factor1": weight, ... } }

Returns a list of all available factors with calculated performance metrics (1-day, 1-week, 1-month returns).

Downloads all factor daily returns. Returns a pivoted table with dates as rows and factor names as columns. Factors are ordered by category: Basic, Sector, Industry, Country, Custom. Custom Group names are shown with their full descriptive names.

Query params: ?format=excel|json (default: excel)

Response (Excel): Excel file (.xlsx) with frozen header row, containing daily returns as decimals (e.g., 0.01 = 1%).

Response (JSON): { "meta": { "totalDates": N, "totalFactors": N, "factors": [...] }, "data": [{ "date": "YYYY-MM-DD", "Market": 0.001, ... }, ...] }

Returns spread returns (Factor1 - Factor2) and z-scores for all factor pairs across multiple timeframes (1d, 3d, 5d, 10d, 21d, 63d, 126d, 252d). Useful for identifying unusual factor divergences and pair trading opportunities.

Query params: ?mode=standard|sectors|sectors-only|industries|industries-only|all

Response: { "factors": [...], "pairs": { "Factor1|Factor2": { "1d": { "spreadReturn": 0.01, "zScore": 2.3 }, ... } } }

Returns historical rolling spread returns for a specific factor pair. The spread is calculated as Factor1 return minus Factor2 return over the specified timeframe window.

Query params: ?timeframe=1d|3d|5d|10d|21d|63d|126d|252d (default: 21d)

Response: { "factor1": "...", "factor2": "...", "timeframe": "21d", "history": [{ "date": "2024-01-15", "rollingReturn": 0.023 }, ...] }

Searches both stocks and factors by name or ticker. Supports multi-word queries where each word must match. Results are ranked by trading volume.

Query params: ?q=searchterm (required)

Returns the top 100 most popular stocks ranked by market capitalization and trading volume.

Query params: ?type=stockType (optional filter by stock type)

Returns a list of all distinct stock types available in the database (e.g., Common Stock, ETF, ADR).

Returns historical price data (date and close) for a specific stock ticker in chronological order.

Query params: ?days=N (default: 252, roughly 1 trading year)

Returns metadata for a specific stock including full name, stock type, and current price.

Fetches the most recent factor betas and exposures for a stock ticker. Returns all factor loadings sorted by beta (exposure strength), along with model quality metrics (R² and Adjusted R²).

Query params: ?model=modelName (default: "All Factors")

Available models: Base, Base + Sector, Base + Sector + Industry, All Factors

Response includes: r_squared, adjusted_r_squared, n_active_factors

Finds stocks with similar factor exposures using cosine similarity. Returns stocks ranked by how closely their factor profile matches the target.

Query params: ?limit=N (default: 10), ?model=modelName (default: "All Factors")

Returns any corporate action (dividend or stock split) for a ticker where today is the ex-date. Used to adjust previous close prices for accurate intraday return calculations.

Response: { "ticker": "AAPL", "corporate_action": { "action_type": "dividend", "amount": 0.25 } } or null if no corporate action today.

Note: For splits, the response includes split_ratio (e.g., 5 for a 5:1 split). The previous close should be divided by this ratio for accurate returns.

Returns the full performance leaderboard with Sharpe and Sortino ratios for all eligible securities across multiple timeframes (1Y, 3Y, 5Y, 10Y, 20Y). Includes annualized returns, volatility, and maximum drawdown metrics.

Response:

{
  "date": "2025-02-15",
  "data": [
    {
      "ticker": "AAPL",
      "full_name": "Apple Inc.",
      "stock_type": "Common Stock",
      "sector": "Technology",
      "y1_sharpe": 1.25,
      "y1_sortino": 1.85,
      "y1_return": 0.32,
      "y1_volatility": 0.22,
      "y1_max_drawdown": -0.15,
      "y3_sharpe": 0.95,
      "y3_sortino": 1.42,
      "y5_sharpe": 1.10,
      "y10_sharpe": 1.35,
      "lifetime_sharpe": 1.28,
      ...
    }
  ]
}

Notes:

• Returns are expressed as decimals (0.32 = 32%)
• Drawdowns are negative (−0.15 = −15%)
• lifetime_* fields contain 20-year metrics
• Response is cached for performance

Returns Sharpe and Sortino ratios for a specific ticker across all available timeframes. Useful for displaying risk-adjusted metrics on individual stock pages.

Example: GET /api/leaderboard/AAPL

Response:

{
  "data": {
    "ticker": "AAPL",
    "y1_sharpe": 1.25,
    "y1_sortino": 1.85,
    "y1_return": 0.32,
    "y1_volatility": 0.22,
    "y1_max_drawdown": -0.15,
    "y3_sharpe": 0.95,
    "y3_sortino": 1.42,
    "y5_sharpe": 1.10,
    "y10_sharpe": 1.35,
    "lifetime_sharpe": 1.28,
    ...
  }
}

Note: Returns { "data": null } if the ticker is not found in the leaderboard (e.g., doesn't meet eligibility criteria).

Returns intraday top movers: gainers, losers, and most active stocks during regular market hours. Change percentages are calculated from the previous close, adjusted for corporate actions. Includes ticker, full name, sector, market cap, last price, change %, day high/low, and total volume. Results are cached for 1 minute.

Analyzes a portfolio's factor exposures. Accepts an array of holdings with ticker and shares, calculates weighted factor exposures, identifies concentration risks, and suggests hedging strategies.

Body: { "holdings": [{ "ticker": "AAPL", "shares": 100 }, ...] }

Query params: ?model=modelName (default: "All Factors")

Returns all stocks ranked by their exposure to a specific factor. Useful for finding stocks with high or low sensitivity to particular market factors.

Query params: ?model=modelName (default: "All Factors")

Response includes: ticker, name, exposure (beta), r_squared, adjusted_r_squared

Returns all stocks with their model fit quality metrics (R² and Adjusted R²), without filtering by factor exposure. Useful for finding stocks with high or low factor model fit, or for screening based purely on model quality.

Query params: ?model=modelName (default: "All Factors")

Response includes: ticker, name, stock_type, r_squared, adjusted_r_squared

Calculates optimal hedge positions to achieve specified factor targets. Uses a greedy optimization algorithm to find the best combination of stocks and ETFs that moves portfolio exposures toward target values while respecting position size, liquidity, and sector constraints.

Body:

{
  "portfolioExposures": { "Market Beta": 1.2, "Sector: Technology": 0.35, ... },
  "portfolioTotal": 1000000,
  "portfolioHoldings": ["AAPL", "MSFT", "GOOGL"],
  "factorTargets": {
    "Market Beta": { "current": 1.2, "target": 0 },
    "Sector: Technology": { "current": 0.35, "target": 0 }
  },
  "settings": {
    "universeType": "etf_stocks",  // "etf", "stocks", "etf_stocks", or "custom"
    "customTickers": [],            // If universeType is "custom"
    "sectorFilter": [],             // Empty for all sectors
    "maxPositionSize": 0.02,        // Max 2% per stock position
    "maxEtfPositionSize": 0.10,     // Max 10% per ETF position
    "maxPositions": 200,
    "minLiquidity": 250000000,      // Min $250M daily volume
    "minR2": 0.5,                   // Min 50% R-squared
    "maxSectorExposure": 0.5,       // Max 50% in any sector
    "longOnly": false,
    "alphaFilter": true             // Prioritize alpha-aligned positions
  }
}

Response includes:

• hedgePositions - Array of recommended positions with ticker, shares, dollarValue, and factor contributions
• summary - Total hedge value, hedge efficiency, positions used
• exposureBefore / exposureAfter - Factor exposures before and after hedge