> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Market data

# 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/{symbol}

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/{symbol}/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/{symbol}/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/{symbol}/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/{symbol}/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/{symbol}/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/{symbol}

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/{symbol}

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/{symbols}

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`: \[{ type, confidence, detected_at }]
* `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
  }
}
```