Market Data & Analytics API Reference

Audience: Strategy-R&D engineers building and backtesting trading strategies. Authentication: All public routes under /api/graph/v1/... require a Supabase JWT (user) OR an X-Internal-Secret header (service principal). Routes under /api/internal/... require X-Internal-Secret only. Strict auth enforced in production (anon → 401).

Single-Stock Data API

Get complete stock context, scoring, technical setup, and institutional level proximity. Base path: /api/graph/v1/stocks

GET /stocks/

Fetch complete stock context with all available metrics: current price, volume, technical indicators, confluence scores (v4.5 + v5), conviction (v5), institutional levels, volume profile, patterns, earnings, and optionally computed enhancements. Parameters:

symbol (path, required): Stock symbol (e.g., NVDA)
date (query, optional): Trade date (YYYY-MM-DD); defaults to today
include (query, optional): Comma-separated list of includes to enrich response:
- levels: IntradayLevel data (pivots, IB, CPR, value area, VWAP, ORB)
- volume_profile: VolumeProfileSession (prior + developing session)
- patterns: Active technical patterns (NR7, inside day, VCP, bull flag, etc.)
- news: News event summary
- confluence_components: Structured v4.5 component breakdown (8 components with weights, scores, notes)
- level_ladder: Sorted level ladder with ATR distances and confluence zones

Response:

StockResult

Performance target: <100ms without includes, <300ms with includes. Example (with all includes):

GET /api/graph/v1/stocks/NVDA?include=levels,patterns,confluence_components,level_ladder

Returns confluence_score (0-100), conviction_v5 (meta-score with core/direction/regime), pulse_v5 (real-time momentum), entry_v2 (execution timing), momentum_health_v5, regime_v5, peer_divergence_v1, plus institutional levels, patterns, and sorted level ladder with nearest support/resistance.

GET /stocks//confluence

Get confluence scoring breakdown (v3: 6 components, v4.1+: 8 components with regime-aware weighting). Parameters:

symbol (path, required): Stock symbol
strategy (query, optional): Strategy type to check alignment for

Response:

ConfluenceResponse {
  symbol: string
  confluence_score: number            // 0–10 score
  tier: enum(EXCELLENT|GOOD|MODERATE|WEAK|POOR)
  components: {
    proximity: { score, weight, nearest_level, distance_atr }
    volatility_setup: { score, weight, patterns, bb_width_percentile }
    volume_confirmation: { score, weight, rvol, trend }
    pattern_quality: { score, weight, best_pattern, confidence }
    iv_rank: { score, weight, percentile }
    day_type_alignment: { score, weight, day_type, alignment }
  }
  recommendation: string
  weights_version?: string
}

Score tiers:

EXCELLENT (8–10): Full position size
GOOD (6–8): Normal position size
MODERATE (4–6): Reduced position size
WEAK (2–4): Avoid or minimal size
POOR (0–2): Do not trade

GET /stocks//fpt

First Passage Time (FPT) probabilistic timing analysis. Pre-computed by Go pattern-detector, reads from graph. Response:

FPTAnalysis {
  symbol: string
  current_price: number
  volatility: {
    value: number              // Garman-Klass historical vol
    source?: string
    rvol_adjustment?: number
    window_days?: integer
  }
  standard_scenarios: {
    ib_15x_up?: FPTScenario    // Initial Balance 1.5× extension
    ib_15x_down?: FPTScenario
    pivot_r1?: FPTScenario
    pivot_s1?: FPTScenario
    vwap_1sd_up?: FPTScenario  // VWAP ± 1σ
    vwap_1sd_down?: FPTScenario
  }
  timeframe_fit: enum(EXCELLENT|GOOD|MODERATE|EXTENDED|LONG)
  event_risk: {
    earnings_within_horizon?: boolean
    days_to_earnings?: integer
    event_warning?: string
  }
}

Timeframe fit classifications:

EXCELLENT: Median < 2 days (day trade)
GOOD: Median 2–5 days (swing)
MODERATE: Median 5–10 days (swing/position)
EXTENDED: Median 10–20 days (position)
LONG: Median > 20 days (investment)

POST /stocks/batch

Lightweight batch endpoint for watchlist tray. Returns price, change, pulse (real-time momentum), relative volume (rvol), and 5-minute sparkline for up to 50 symbols. Request:

BatchQuotesRequest {
  symbols: [string]           // max 50
}

Response:

BatchQuotesResponse {
  quotes: [{
    symbol: string
    last_price?: number
    change_pct?: number
    prev_close?: number
    pulse_net?: number         // ConvictionV5 momentum
    rvol?: number
    sparkline: [number]        // Last 3 days of 5-min closes
  }]
}

Performance target: <50ms.

GET /stocks//peers

Peer stocks from FMP, enriched with graph data (confluence, conviction, directional bias). Response:

PeersResponse {
  symbol: string
  peers: [{
    symbol: string
    last_price?: number
    change_pct?: number
    bullish_confluence?: number
    net_confluence?: number    // bullish - bearish
    conviction_max_v5?: number
    conflict_min_v5?: number
    directional_bias_v5?: string
  }]
}

GET /stocks//earnings/history

Historical earnings data: estimates, actuals, and surprise percentages (EPS + revenue). Parameters:

limit (query, optional): Number of quarters (1–20, default 12)

Response (shape inferred from handler):

EarningsHistoryResponse {
  symbol: string
  quarters: [{
    fiscal_period?: string
    report_date: string        // ISO date
    eps_estimate?: number
    eps_actual?: number
    eps_surprise_pct?: number
    revenue_estimate?: number
    revenue_actual?: number
    revenue_surprise_pct?: number
  }]
}

GET /stocks//price-events

Price events detected by Go pattern-detector (gaps, breakouts, MA crosses, volume spikes, compressions). Parameters:

days (query, optional): Lookback days (1–90, default 30)
event_types (query, optional): Comma-separated event types (e.g., gap_up,golden_cross)
min_severity (query, optional): Filter by severity (low, medium, high, critical)

Response:

[PriceEvent] {
  event_id: string
  event_type: string          // gap_up, breakout_52w_high, volume_spike, nr7_day, etc.
  event_date: string
  severity: string
  magnitude?: number
  reference_price?: number
  trigger_price?: number
  level_name?: string
  level_value?: number
  rel_volume?: number
  atr_ratio?: number
  details?: string
}

Chart & OHLCV Data API

Candlestick data with optional server-computed indicators. Base path: /api/graph/v1/chart

GET /chart/

Retrieve OHLCV bars for charting. Parameters:

symbol (path, required): Stock symbol
interval (query, optional): 1m, 2m, 5m, 15m, 30m, 1h, 1d (default 5m)
period (query, optional): 1d, 5d, 1m, 3m, 6m, 1y, 5y (default 1d)
session (query, optional): all or regular (RTH only; default all)
warmup (query, optional): Extra bars for indicator seeding (0–250)
indicators (query, optional): Server-computed indicators (ema9,ema20,sma50,sma200,vwap)

Response:

ChartResponse {
  symbol: string
  interval: enum(1m|2m|5m|15m|30m|1h|1d)
  period: enum(1d|5d|1m|3m|6m|1y|5y)
  candles: [{
    time: string              // ISO datetime
    open: number
    high: number
    low: number
    close: number
    volume: integer
    ema9?: number             // If requested
    ema20?: number
    sma50?: number
    sma200?: number
    vwap?: number
  }]
  warmup_count?: integer      // Bars stripped before period_start
  is_lookback?: boolean       // True if oldest bar is before requested period
  last_bar_time?: string
  staleness_seconds?: integer
  data_status?: enum(ok|stale|no_data)
}

Notes:

Long periods (3m+) fail closed if data is stale; empty candles array returned with staleness diagnostics.
Short periods (1d/5d/1m) allow lookback re-query if primary table empty.
1-minute fallback for missing aggregated data.
Split-adjusted for daily bars.

Market Context & Regime API

Market-wide conditions: day classification, VIX regime, breadth, session phases. Base path: /api/graph/v1/market

GET /market/context

Current market-wide context for informed trading decisions. Response:

MarketContextResponse {
  trade_date: string          // ISO date
  is_market_open?: boolean
  day_classification: {
    day_type: enum(trending|rotational|uncertain)
    day_type_detail?: enum(strong_trend|trending|mixed|rotational|strong_rotational)
    day_type_confidence?: integer  // 0–100
    trend_score: number        // -1 to 1 (bearish/bullish)
    rotation_score: number     // 0 to 1 (mean reversion likelihood)
    strategy_bias: string      // momentum|mean_reversion|neutral
    size_modifier?: number     // 0.5–2.0
    signals?: [string]
  }
  vix_regime: {
    level: number
    sma_50?: number
    percentile?: number
    regime: enum(low_complacent|normal|elevated|fear)
    term_structure: enum(contango|backwardation)
    can_trade?: boolean        // False if fear
    size_adjustment: string    // -25%|baseline|+15%|pause
  }
  market_conditions: [string]  // LOW_VIX, CONTANGO, BULLISH_TREND, etc.
  favored_strategies: [string] // MomentumBreakout, MeanReversion, etc.
  regime_v5?: RegimeV5        // V5 regime vector (shadow mode)
  // 2×3 regime grid fields (direction × volatility)
  regime_direction?: string    // BULL|NEUTRAL|BEAR
  regime_volatility?: string   // LOW|HIGH
  regime_label?: string        // Composite label (e.g., "Bull Rally")
  regime_episode_day?: integer // Days in current regime state
  regime_shock?: boolean
  regime_slope_pctile?: number
  regime_vol_pctile?: number
  regime_slope_raw?: number
  regime_vol_raw?: number
  regime_spy_perf?: number     // SPY return in current regime
  regime_qqq_perf?: number     // QQQ return in current regime
}

Performance target: <50ms (uses cache).

GET /market/regime

Unified market regime combining V5 vector, VIX, vol regime, and GEX. Response:

MarketRegimeResponse {
  regime_v5?: RegimeV5       // Canonical V5 state vector (MSE real-time)
  vix?: VIXContext
  day_classification?: DayClassification
  vol_regime?: VolRegimeSnapshot   // ATM IV, IV percentile, realized vol
  gex_regime?: GEXSnapshot         // Gamma exposure regime, flip strikes
  regime_computed_at?: string      // When PD last computed V5
  vol_regime_as_of?: string
  gex_as_of?: string
  regime_direction?: string        // BULL|NEUTRAL|BEAR (2×3 grid)
  regime_volatility?: string       // LOW|HIGH
  regime_label?: string
  regime_episode_day?: integer
  regime_shock?: boolean
  regime_slope_pctile?: number
  regime_vol_pctile?: number
  regime_slope_raw?: number
  regime_vol_raw?: number
  recommended_preset_trading?: string
  recommended_preset_investor?: string
  regime_stable_since?: string
  market_conditions?: [string]
  favored_strategies?: [string]
}

GET /market/intraday-bars/

Today’s 1-minute bars for real-time charting. Response:

IntradayBarsResponse {
  symbol: string
  bars: [{
    time: string              // ISO datetime
    open: number
    high: number
    low: number
    close: number
    volume: integer
  }]
  market_status: string       // overnight|pre-market|open|after-hours|closed
  current_phase: string       // Current trading phase label
}

GET /market/most-active

Top stocks by relative volume (RVOL). Parameters:

limit (query, optional): Default 50

Response:

MostActiveResponse {
  stocks: [{
    symbol: string
    rvol: number              // Relative volume multiplier
    price?: number
    change_pct?: number
    direction?: string        // up|down
    volume_today?: integer
    avg_volume_20d?: integer
  }]
  as_of: string
}

GET /market/leaderboard

Stocks by signal category (top movers, highest conviction, strongest momentum, etc.). Response:

LeaderboardResponse {
  groups: [{
    id: string                // e.g., "highest_conviction"
    label: string
    stocks?: [{
      symbol: string
      price?: number
      change_pct?: number
      volume?: integer
      signal_value?: number
    }]
  }]
  as_of: string
}

GET /market/indices

Intraday index charts and quotes (SPY, QQQ, DJI, etc.). Response:

IndicesResponse {
  indices: [{
    symbol: string
    name: string
    price?: number
    change?: number
    change_pct?: number
    bars?: [{
      t: string              // Time ISO
      o, h, l, c: number
      v: integer
    }]
  }]
  as_of: string
}

GET /market/pulse

Market pulse data for dashboard ticker cards (FMP-powered). Response (shape inferred from handler):

{
  items: [{
    symbol: string
    name: string
    category: string           // index|commodity|crypto
    price?: number
    change_pct?: number
    change_abs?: number
    prev_close?: number
    day_low?: number
    day_high?: number
    sparkline: [number]        // 5-min closes for today
  }]
  generated_at: string
}

Instruments: ^GSPC, ^IXIC, ^DJI, ^VIX, USO, GCUSD, BTCUSD.

GET /market/sector-rotation

Sector rotation scoring (average conviction, persistence, breadth, leaders/laggards). Response:

SectorRotationResponse {
  sectors: [{
    sector: string
    avg_conviction?: number
    dominant_direction: string   // bullish|bearish|neutral
    symbol_count?: integer
    prev_avg_conviction?: number
    change?: number              // Δ conviction
    relative_strength?: number
    persistence_days?: integer   // Days of same directional bias
    breadth_pct?: number         // % of sector bullish
    leaders?: [{
      symbol: string
      signal: string             // bullish|bearish
      composite_score?: number
    }]
    laggards?: [{
      symbol: string
      signal: string
      composite_score?: number
    }]
    historical_context?: [HistoricalContext]
  }]
  as_of: string
  methodology?: string
}

GET /market/rrg

Relative Rotation Graph (RRG) for sector rotation analysis. Response:

RRGResponse {
  trade_date: string
  prior_close_date: string
  phases_completed: integer
  current_phase: string
  sectors: [{
    sector: string
    etf: string                // Sector ETF ticker
    day_change_pct: number
    trail: [RRGTrailPoint]     // Phase history
    live?: RRGLivePoint
    tooltip?: RRGSectorTooltip
  }]
  breadth?: RRGBreadth
  top_movers?: object
}

GET /market/session-phases

Trading session phase analysis. Response:

SessionPhasesResponse {
  current_phase: string
  phases: [{
    id: string
    label: string
    start: string              // ISO time
    end: string
    status: string             // active|completed
    top_movers?: [{
      symbol: string
      change_pct: number
    }]
    summary?: string
  }]
  daily_breadth: {
    advancing?: integer
    declining?: integer
    unchanged?: integer
    new_highs?: integer
    new_lows?: integer
    top_advancers?: [BreadthStock]
    top_decliners?: [BreadthStock]
    top_new_highs?: [BreadthStock]
    top_new_lows?: [BreadthStock]
  }
  as_of: string
}

Symbol & Quote API

GET /symbols/index

Compact symbol index for client-side search (3K stocks, ~40KB gzipped). Response:

{
  symbols: [{
    s: string                  // Symbol
    n?: string                 // Company name
    k?: string                 // Sector
    r: integer                 // Rank by ADV30
  }]
  count: integer
  updated_at: string
}

Cache: 1 hour (Redis).

GET /quotes/

MSE live quotes (bid, ask, spread). Proxied to Market Signal Engine on localhost:8100. Parameters:

symbols (path): Comma-separated symbols (e.g., NVDA,AAPL)

Response: (varies by MSE implementation; typically quote object with bid, ask, last, time)

Performance Analytics API

GET /performance/summary

Aggregate performance metrics for closed trades. Parameters:

mode (query, optional): all, paper, or live (default all)
start_date (query, optional): ISO date (e.g., 2026-01-01)
end_date (query, optional): ISO date (e.g., 2026-12-31)

Response (shape inferred from handler):

{
  period: string              // "daily"
  mode: string
  metrics: {
    total_pnl: number
    total_trades: integer
    win_rate: number           // %
    profit_factor: number | null
    avg_win: number
    avg_loss: number
    avg_rr: number             // Average risk/reward ratio
    best_day: { date, pnl } | null
    worst_day: { date, pnl } | null
    max_drawdown: number
    current_streak: { type: "win"|"loss", count: integer }
    sharpe_ratio: number | null
    calmar_ratio: number | null
    sortino_ratio: number | null
    max_consecutive_losses: integer
  }
  daily_pnl: [{
    date: string
    pnl: number
    trade_count: integer
    wins: integer
    losses: integer
    win_rate: number
  }]
  equity_curve: [{
    date: string
    cumulative_pnl: number
  }]
  by_strategy: [{
    strategy: string
    trades: integer
    pnl: number
    win_rate: number
  }]
  by_symbol: [{
    symbol: string
    trades: integer
    pnl: number
    win_rate: number
  }]
  by_hour: [{
    hour: integer              // ET hour
    trades: integer
    avg_pnl: number
  }]
  by_signal_type: [{
    signal_type: string
    trades: integer
    pnl: number
    win_rate: number
  }]
}

Key Schemas

StockResult

Complete stock data. Fields populated based on include query parameter. Core fields:

symbol, last_price, volume, dollar_volume
technical: RSI, MACD, ADX, ATR, EMAs, SMAs, Bollinger bands, VWAP
compression: NR7, inside day, VCP contraction count, BB width percentile
levels: Pivots, IB, VWAP bands, value area, prior day/week levels, ORB levels
confluence_score, bullish_confluence, bearish_confluence, net_confluence
conviction_max_v5, conflict_min_v5, directional_bias_v5
pulse_net, pulse_bull, pulse_bear
entry_score_bull, entry_score_bear, entry_gates_passed
options: IV percentile, put/call ratio, unusual activity, theta drag, pricing edges
fundamental: Market cap, PE, EV/EBITDA, margins, dividend yield, beta
earnings: Days until, surprise %, beat rate, sentiment bias
patterns: []
price_events: Gaps, breakouts, MA crosses, volume spikes, compressions
dark_pool_pct_1d, block_trade_count, net_buy_volume

RegimeV5

V5 regime state vector (canonical regime, shadow mode).

{
  strong_trend?: number       // 0–1 probability
  mild_trend?: number
  rotation?: number
  vol_expand?: number
  compressed?: number
  transitional?: number
  dominant?: string           // Highest-probability state
  confidence?: number         // 0–1
  computed_at?: string
}

ConvictionV5

Conviction meta-score: real-time momentum composite (MSE).

{
  score?: number              // 0–100
  core?: number               // Core conviction (4-component average)
  confidence?: number         // 0–1
  direction?: string          // bullish|bearish
  regime?: string
  formula_variant?: enum(core4|enriched5|enriched6)
  options_participation?: enum(ACTIVE|STALE|INELIGIBLE)
  weight_confluence?: number
  weight_pulse?: number
  weight_entry?: number
  weight_momentum?: number
  norm_confluence?: number    // Normalized component score
  norm_pulse?: number
  norm_entry?: number
  norm_momentum?: number
  norm_options?: number
  confluence_net_at_source?: number
  pulse_net_at_source?: number
  entry_net_at_source?: number
  momentum_health_at_source?: number
  options_score_at_source?: number
  source_bar_ts?: string      // When source bar was updated
  computed_at?: string
}

ConfluenceComponentBreakdown

Structured v4.5 component breakdown (8 components).

{
  scoring_version?: string
  components: [{
    name: string
    label: string
    weight: number             // Contribution to total
    bull: number               // Raw bullish score
    bear: number               // Raw bearish score
    weighted_bull: number      // bull × weight
    weighted_bear: number
    note?: string              // Explanation
  }]
  total_bull: number           // Sum of weighted_bull
  total_bear: number
  net: number                  // total_bull - total_bear
}

Levels

Institutional price levels: pivots, IB, VWAP bands, value area, ORB, prior levels.

{
  pivot_pp, pivot_r1, pivot_r2, pivot_r3, pivot_s1, pivot_s2, pivot_s3: number
  cpr_tc, cpr_bc: number       // CPR extremes
  ib_high, ib_low, ib_range: number
  ib_1_5x_high, ib_2x_high, ib_1_5x_low, ib_2x_low: number  // IB extensions
  orb_5m_high, orb_5m_low, orb_15m_high, orb_15m_low: number
  orb_5m_status, orb_15m_status: string
  vwap, vwap_plus_1sd, vwap_minus_1sd, vwap_plus_2sd, vwap_minus_2sd: number
  vah, val, poc: number        // Volume profile
  pdh, pdl, pdc: number        // Prior day
  pwh, pwl: number             // Prior week
  onh, onl: number             // Overnight
}

LevelLadder

Sorted level ladder with ATR distances and confluence zones.

{
  current_price: number
  atr_14: number | null
  levels: [{
    type: string              // pivot_pp, ib_high, vwap, etc.
    label: string
    price: number
    side: enum(support|resistance|neutral)
    distance_atr?: number     // Price - current / ATR
    distance_pct?: number     // % distance
    freshness: enum(live|daily|structural)
    confluence_count?: integer // # of levels within 0.25 ATR
  }]
  nearest_support?: LevelLadderEntry
  nearest_resistance?: LevelLadderEntry
}

Technical

Technical indicators: RSI, MACD, ADX, ATR, MAs, Bollinger bands.

{
  rsi_14?: number
  macd?: number
  macd_signal?: number
  adx_14?: number
  atr_14?: number             // Daily ATR(14)
  atr_1m_14?: number          // Intraday ATR(14)
  daily_atr?: object          // { "14": number, ... }
  daily_atr_live?: number
  moving_averages?: {
    ema_9, ema_20, sma_50, sma_200: number | null
  }
  bollinger?: {
    upper, middle, lower: number | null
    width_percentile?: number  // 0–100
  }
  trend_stack_valid?: boolean
  range_vs_atr_14?: number
}

Compression

Volatility compression indicators.

{
  is_nr7?: boolean
  is_inside_day?: boolean
  atr_compression_ratio?: number     // ATR(3) / ATR(14)
  range_vs_atr_14?: number
  vcp_contraction_count?: integer
}

VolumeProfile

Prior and developing session volume profile (VAH, VAL, POC).

{
  prior?: {
    vah, val, poc?: number
    distribution?: string      // skewed_low|balanced|skewed_high
  }
  developing?: {
    vah, val, poc?: number
  }
}

​Market Data & Analytics API Reference

​Single-Stock Data API

​GET /stocks/

​GET /stocks//confluence

​GET /stocks//fpt

​POST /stocks/batch

​GET /stocks//peers

​GET /stocks//earnings/history

​GET /stocks//price-events

​Chart & OHLCV Data API

​GET /chart/

​Market Context & Regime API

​GET /market/context

​GET /market/regime

​GET /market/intraday-bars/

​GET /market/most-active

​GET /market/leaderboard

​GET /market/indices

​GET /market/pulse

​GET /market/sector-rotation

​GET /market/rrg

​GET /market/session-phases

​Symbol & Quote API

​GET /symbols/index

​GET /quotes/

​Performance Analytics API

​GET /performance/summary

​Key Schemas

​StockResult

​RegimeV5

​ConvictionV5

​ConfluenceComponentBreakdown

​Levels

​LevelLadder

​Technical

​Compression

​VolumeProfile

Market Data & Analytics API Reference

Single-Stock Data API

GET /stocks/

GET /stocks//confluence

GET /stocks//fpt

POST /stocks/batch

GET /stocks//peers

GET /stocks//earnings/history

GET /stocks//price-events

Chart & OHLCV Data API

GET /chart/

Market Context & Regime API

GET /market/context

GET /market/regime

GET /market/intraday-bars/

GET /market/most-active

GET /market/leaderboard

GET /market/indices

GET /market/pulse

GET /market/sector-rotation

GET /market/rrg

GET /market/session-phases

Symbol & Quote API

GET /symbols/index

GET /quotes/

Performance Analytics API

GET /performance/summary

Key Schemas

StockResult

RegimeV5

ConvictionV5

ConfluenceComponentBreakdown

Levels

LevelLadder

Technical

Compression

VolumeProfile