API Guide

📡 BullsEye API Guide — Core Component Modules

This document provides a detailed breakdown of the 5 main modular components in the api/components/ directory. Each component is a self-contained microservice that returns structured financial or analytical data.

---

1. 🟢 Market Data Component

Path: /api/components/market-data/
Method: GET

Query Parameters

• symbol (string) — e.g., "RELIANCE"
• exchange (string) — e.g., "NSE"
• segment (string) — "cash" | "futures" | "options"
• fields[] (array of string) — subset of:
  • ltp, percent_change, net_change
  • bid_ask_spread, top_bids, top_asks
  • depth_imbalance_ratio, volume
  • ohlc, vwap, 52w_high_low
  • iv, option_greeks, put_call_ratio
  • oi_change, oi_concentration_zscore
  • sector_perf_change, fii_dii_activity
  • market_sentiment_score, beta, volatility_percentile

Example:

GET /api/components/market-data/?symbol=RELIANCE&fields[]=ltp&fields[]=iv

---

2. 🟡 Portfolio Component

Path: /api/components/portfolio/
Method: GET

Query Parameters

• segment (string) — "equity" | "futures" | "options"
• details (boolean) — Whether to include full breakdown

Returned Metrics

• holding_quantity, avg_buy_price, current_market_value
• unrealized_pnl, realized_pnl, pnl_percent
• asset_allocation_percent, portfolio_turnover
• margin_utilized, margin_breakdown (span, exposure)
• order_history, time_in_market
• liquidity_score, holding_period_avg_days
• execution_quality_rating, slippage_percent

---

3. 🔵 Stock Screener Component

Path: /api/components/stock-screener/
Method: POST

Payload Structure

{
  "filters": {
    "pe_ratio": {"max": 20},
    "debt_to_equity": {"lt": 0.5},
    "dividend_yield": {"gte": 2},
    "rsi": {"lt": 30},
    "volume": {"gte": 1000000}
  }
}

Available Filter Keys

• Valuation: pe_ratio, pb_ratio, peg_ratio, ev_ebitda
• Growth: revenue_cagr_5y, eps_growth_5y, fcf_yield
• Quality: roe, roce, altman_z_score, piotroski_score
• Technical: rsi, macd_signal, bollinger_band_position
• Sentiment: delivery_percent, short_interest_ratio, fii_dii_holding_trend
• Risk: beta, volatility, moat_score
• Tags: sector, industry, market_cap

---

4. 🟣 Technical Analysis Component

Path: /api/components/technical-analysis/
Method: GET

Query Parameters

• symbol (string) — e.g., "INFY"
• interval (string) — "1m", "5m", "1d", etc.
• study[] (array of string) — "macd", "rsi", "supertrend", etc.
• chart_type (optional) — "candlestick" | "heikin_ashi" | "renko"
• brick_size (number) — Required if chart_type = renko

Output Tags

• ohlc_series, volume_series
• indicator_series: keyed by study[]
• event_annotations: earnings, dividends, splits
• correlation_matrix (if compare_with[] passed)

---

5. 🔴 Fundamental Analysis Component

Path: /api/components/fundamental-analysis/
Method: GET

Query Parameters

• symbol (string) — Stock name or ticker
• data_type (string) — "ratios" | "financials" | "ownership"

Returned Data Fields

• pe_ratio, pb_ratio, dividend_yield, dividend_payout_ratio
• roe, roce, debt_to_equity, interest_coverage_ratio
• cash_conversion_cycle, net_profit_margin, ebitda_margin
• revenue_cagr_5y, eps_cagr_3y
• altman_z_score, moat_score, comparative_sector_score
• shareholding_pattern, pledged_percent, insider_trades

---

✅ Note: Each of these components plugs into the orchestrator (/api/assemble) and query analyzer (/api/query) to create seamless user responses in real-time chat or dashboard formats.