API Version 2.0 • Institutional Read-Only GET Endpoints

MarketAI Developer & Agent API Specification

Welcome to the MarketAI REST API v2.0 documentation. MarketAI provides sub-millisecond Indian equities data across 5,568+ active NSE and BSE equities, 24 benchmark and sectoral indices, dual Bhavcopy deliverable volume tracking, full F&O derivatives positioning (PCR, Max Pain, OI Regimes), 60+ pre-calculated quant ML alpha factors with Winsorized Z-scores, institutional smart money tracking (FII/DII net flows & Bulk deals), and Gemini 2.5 Flash Lite regulatory intelligence.

Strictly Read-Only & Safe for AI Agent Tool Calling

All external developer APIs in MarketAI are 100% read-only (GET). No order execution, broker credentials, or financial account mutations can ever occur via these endpoints. This makes MarketAI safe for autonomous LLM agents, algo bots, and client-side applications.

Production Base URL: https://market.acadmyai.com/v2

Building an AI Agent or Copilot?

MarketAI provides dedicated machine-readable endpoints at /llms.txt and /llms-full.txt designed for LLM context windows, along with OpenAI / Gemini JSON Schema function signatures on every endpoint.

AI Agent Decision Matrix

Agents and LLMs should use this decision matrix to route queries to the most efficient endpoint, minimizing tool roundtrips and token consumption:

User / AI Goal	Recommended Endpoint	Method	Why Choose This
Turnkey 360° stock card	/v2/fintech/stock-card/{ticker}	GET	1 call bundles Quote, Delivery %, AI Filings, F&O & SEBI surveillance
Macro market health & sentiment	/v2/fintech/market-pulse	GET	Instant macro pulse: FII/DII net flows, FII Long/Short ratio, NIFTY PCR
Real-time price & delivery %	/v2/stocks/{ticker}/quote	GET	Sub-millisecond quote with institutional delivery accumulation signals
15m & 1D historical candles	/v2/stocks/{ticker}/ohlcv	GET	Continuous 60-day 15m intraday & 1,000-day daily OHLCV with regime tags
Market indices & benchmarks	/v2/market/index/{index_name}/ohlcv	GET	24 benchmark and sectoral indices with pre-computed EMA/RSI bands
Options sentiment & strike pain	/v2/derivatives/{ticker}/summary	GET	Put-Call Ratio (OI & Vol), Max Pain strike, and 4-quadrant OI buildup
Strike-by-strike option chain	/v2/derivatives/{ticker}/chain	GET	Granular Call/Put OI, change in OI, volume, and settlement prices
Quantitative ML & Alpha factors	/v2/quant/features/{ticker}	GET	60+ pre-calculated factors with Winsorized Z-scores and sector ranks
Institutional smart money deals	/v2/alternative/bulk-deals	GET	Institutional transactions (>0.5% equity) with client names & ₹ Cr values
Risk gating & circuit limits	/v2/alternative/surveillance/{ticker}	GET	SEBI ASM/GSM stage and dynamic circuit breaker limits (2%, 5%, 10%, 20%)
5-factor multi-pillar sentiment	/v2/sentiment/{ticker}	GET	Composite Market Sentiment Index [-1.0 to +1.0] across 5 pillars

Authentication

Authenticate requests by including your secret API key as an HTTP Bearer token in the Authorization header:

HTTP Header Requirement

Authorization: Bearer sk-marketai-your_secret_key

Rate Limits & SLA

All active MarketAI Developer Pro and Enterprise accounts receive institutional-grade throughput with sub-millisecond edge routing.

Throughput120 req / min

Uptime SLA99.99%

Latency< 15ms Edge

GET/v2/fintech/stock-card/{ticker}Turnkey 1-Call Card

Bundles quote, deliverable volume %, institutional accumulation signal, 3 Gemini-distilled filing bullets, F&O derivatives positioning, and SEBI surveillance in a single API call.

AI Agent Trigger Condition:Invoke this endpoint whenever an end-user or prompt asks for a complete stock overview or analysis.

curl -X GET "https://market.acadmyai.com/v2/fintech/stock-card/RELIANCE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "name": "Reliance Industries Limited",
  "sector": "Energy",
  "market_cap_cr": 2022800.0,
  "quote": {
    "date": "2026-09-07",
    "close": 2989.75,
    "open": 2984.50,
    "high": 2995.00,
    "low": 2972.50,
    "volume": 4821900,
    "deliverable_volume": 2748483,
    "deliverable_percent": 57.0,
    "delivery_accumulation_signal": "STRONG_INSTITUTIONAL_ACCUMULATION",
    "market_regime": "BULL_EXPANSION",
    "stock_regime": "BULLISH_TREND"
  },
  "ai_intelligence": {
    "materiality": "MATERIAL_POSITIVE",
    "summary_bullets": [
      "Commissioned new 1.2 GW green energy manufacturing facility in Jamnagar.",
      "Quarterly retail footfall increased 18% YoY with sustained EBITDA margins.",
      "Jio subscriber additions accelerated with positive ARPU expansion."
    ],
    "sentiment_score": 0.76,
    "sentiment_class": "Bullish"
  },
  "derivatives": {
    "has_fo": true,
    "pcr_oi": 1.18,
    "max_pain_strike": 3000.0,
    "oi_regime": "LONG_BUILDUP"
  },
  "risk_and_surveillance": {
    "is_in_surveillance": false,
    "asm_stage": null,
    "gsm_stage": null,
    "circuit_limit_pct": 20.0
  }
}

GET/v2/fintech/market-pulseMacro Flows

Returns instantaneous macro market health: daily FII/DII cash net flows, FII Long/Short contract ratio, NIFTY Put-Call Ratio, and market regime.

curl -X GET "https://market.acadmyai.com/v2/fintech/market-pulse" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "as_of": "2026-09-07",
  "institutional_flows": {
    "fii_net_cr": 1420.50,
    "dii_net_cr": 890.25,
    "fii_long_short_ratio": 1.34
  },
  "benchmark_derivatives": {
    "index": "NIFTY",
    "pcr_oi": 1.12,
    "max_pain_strike": 24500.0,
    "oi_regime": "LONG_BUILDUP"
  },
  "market_status": "OPEN"
}

GET/v2/stocks/{ticker}/quote

Returns real-time sub-millisecond stock quotes, price change, percentage change, deliverable volume, deliverable %, delivery accumulation tag, turnover, market cap, and P/E ratio across NSE and BSE.

curl -X GET "https://market.acadmyai.com/v2/stocks/RELIANCE/quote?market=NSE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "name": "Reliance Industries Limited",
  "current_price": 2989.75,
  "change": 18.25,
  "change_percent": 0.61,
  "day_high": 2995.00,
  "day_low": 2972.50,
  "volume": 4821900,
  "deliverable_volume": 2748483,
  "deliverable_percent": 57.0,
  "delivery_accumulation_signal": "STRONG_INSTITUTIONAL_ACCUMULATION",
  "turnover_cr": 1441.20,
  "market_cap_cr": 2022800.0,
  "pe_ratio": 26.4,
  "week_52_high": 3217.90,
  "week_52_low": 2220.30
}

GET/v2/stocks/{ticker}/ohlcv

Continuous 15-minute intraday or daily historical OHLCV bars with volume, VWAP, EMA 20/50, RSI 14, and dynamic price-action regime tags.

curl -X GET "https://market.acadmyai.com/v2/stocks/RELIANCE/ohlcv?interval=15m&days=30&market=NSE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "market": "NSE",
  "interval": "15m",
  "total_candles": 750,
  "candles": [
    {
      "timestamp": "2026-09-07T09:15:00Z",
      "open": 2984.50,
      "high": 2991.00,
      "low": 2981.25,
      "close": 2988.50,
      "volume": 245000,
      "vwap": 2987.20,
      "ema_20": 2980.10,
      "rsi_14": 58.4,
      "market_regime": "BULLISH_TREND"
    }
  ]
}

GET/v2/market/index/{index_name}/ohlcv

Returns real-time technical indicator calculations (EMA 20, EMA 50, RSI 14, ATR 14) across 24 benchmark and sectoral indices: NIFTY50, SENSEX, BANKNIFTY, NIFTY_IT, INDIA_VIX, GIFT_NIFTY, GOLD, BRENT_CRUDE, US_VIX, NASDAQ.

curl -X GET "https://market.acadmyai.com/v2/market/index/NIFTY50/ohlcv?days=30" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "index_name": "NIFTY50",
  "ticker_symbol": "^NSEI",
  "category": "Domestic Benchmark",
  "current_regime": "BULLISH_EXPANSION",
  "total_candles": 30,
  "candles": [
    {
      "date": "2026-09-07",
      "open": 24850.0,
      "high": 25010.5,
      "low": 24820.0,
      "close": 24965.8,
      "volume": 312040000,
      "ema_20": 24710.2,
      "rsi_14": 63.8
    }
  ]
}

GET/v2/market/volume-distribution

Market-wide volume distribution and constituent securities filtered by turnover (₹ Cr) or share volume.

curl -X GET "https://market.acadmyai.com/v2/market/volume-distribution" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "date": "2026-09-07",
  "total_market_turnover_cr": 118420.5,
  "turnover_leaders": [
    { "ticker": "RELIANCE", "turnover_cr": 1441.2, "volume": 4821900 },
    { "ticker": "HDFCBANK", "turnover_cr": 1280.4, "volume": 7650200 },
    { "ticker": "ICICIBANK", "turnover_cr": 980.1, "volume": 5890100 }
  ]
}

GET/v2/derivatives/{symbol}/summaryF&O Intelligence

Returns official NSE derivatives positioning for F&O underlyings (NIFTY, BANKNIFTY, and active stock options): Put-Call Ratio (PCR), Max Pain strike, 4-quadrant Open Interest regime, and At-The-Money Implied Volatility (ATM IV).

curl -X GET "https://market.acadmyai.com/v2/derivatives/NIFTY/summary" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "symbol": "NIFTY",
  "date": "2026-09-07",
  "spot_close": 24965.8,
  "future_close": 24995.2,
  "pcr_oi": 1.18,
  "pcr_volume": 1.05,
  "max_pain_strike": 25000.0,
  "oi_regime": "LONG_BUILDUP",
  "oi_change_pct": 6.42,
  "price_change_pct": 0.45,
  "atm_iv": 14.8
}

GET/v2/derivatives/{symbol}/chain

Returns full strike-by-strike Call and Put open interest, change in OI, volume, and settlement prices for the selected contract expiry.

curl -X GET "https://market.acadmyai.com/v2/derivatives/NIFTY/chain" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "symbol": "NIFTY",
  "expiry_date": "2026-09-24",
  "strikes": [
    {
      "strike": 25000.0,
      "ce_oi": 842000,
      "ce_oi_change": 45000,
      "ce_ltp": 125.40,
      "pe_oi": 1120000,
      "pe_oi_change": 182000,
      "pe_ltp": 98.20
    }
  ]
}

GET/v2/quant/features/{ticker}60+ Alpha Factors

Pre-computed cross-sectional alpha factors: multi-horizon momentum (1d to 252d), Jegadeesh-Titman 12-1m momentum, Parkinson/Garman-Klass volatility, delivery surprise Z-score, Amihud illiquidity, and sector percentile ranks.

curl -X GET "https://market.acadmyai.com/v2/quant/features/RELIANCE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "date": "2026-09-07",
  "sector": "Energy",
  "momentum": {
    "return_1d": 0.0061,
    "return_5d": 0.0245,
    "return_21d": 0.0512,
    "return_63d": 0.0890,
    "return_126d": 0.1420,
    "return_252d": 0.2840,
    "momentum_12_1m": 0.2328,
    "trend_regime": "BULLISH_TREND"
  },
  "volatility": {
    "realized_vol_20d": 0.1840,
    "realized_vol_60d": 0.1980,
    "parkinson_vol_20d": 0.1650,
    "garman_klass_vol_20d": 0.1710,
    "atr_14_pct": 0.0142
  },
  "microstructure": {
    "deliverable_volume": 2748483,
    "deliverable_percent": 57.0,
    "delivery_surprise_zscore": 2.14,
    "amihud_illiquidity": 0.00042
  },
  "normalized_zscores": {
    "return_21d": 1.42,
    "delivery_surprise_zscore": 2.14,
    "parkinson_vol_20d": -0.84,
    "pcr_oi": 0.95
  },
  "sector_percentiles": {
    "return_21d": 0.88,
    "delivery_surprise_zscore": 0.94,
    "momentum_12_1m": 0.82
  }
}

GET/v2/quant/exportApache Parquet Stream

Streams cross-sectional factors for the entire universe as a compressed Apache Parquet binary file (application/octet-stream) for direct zero-copy ingestion in Polars, Pandas, LightGBM, and PyTorch.

curl -X GET "https://market.acadmyai.com/v2/quant/export" \
  -H "Authorization: Bearer sk-marketai-your_secret_key" \
  --output universe_factors.parquet

GET/v2/alternative/bulk-deals

Institutional transactions exceeding 0.5% of equity: buyer and seller client names, quantity, deal trade price, and ₹ Cr transaction value across NSE and BSE.

curl -X GET "https://market.acadmyai.com/v2/alternative/bulk-deals?ticker=RELIANCE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "total_deals": 4,
  "deals": [
    {
      "deal_date": "2026-09-04",
      "deal_type": "BUY",
      "client_name": "SOCIETE GENERALE",
      "quantity": 1250000,
      "trade_price": 2985.40,
      "value_cr": 373.18
    }
  ]
}

GET/v2/alternative/fii-dii

Daily Foreign Institutional Investor (FII) and Domestic Institutional Investor (DII) cash market and index futures net investment values.

curl -X GET "https://market.acadmyai.com/v2/alternative/fii-dii" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "date": "2026-09-07",
  "fii_buy_cr": 12840.20,
  "fii_sell_cr": 11419.70,
  "fii_net_cr": 1420.50,
  "dii_buy_cr": 9410.10,
  "dii_sell_cr": 8519.85,
  "dii_net_cr": 890.25
}

GET/v2/alternative/surveillance/{ticker}

Checks SEBI Additional Surveillance Measure (ASM) / Graded Surveillance Measure (GSM) framework stages and dynamic daily price circuit limits (2%, 5%, 10%, 20%).

curl -X GET "https://market.acadmyai.com/v2/alternative/surveillance/RELIANCE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "is_in_surveillance": false,
  "asm_stage": null,
  "gsm_stage": null,
  "circuit_limit_pct": 20.0
}

GET/v2/sentiment/{ticker}5-Pillar CMSI

Composite Market Sentiment Index [-1.0 to +1.0] synthesized across News NLP (25%), Filings (25%), Financials (20%), Institutional Footprint (20%), and Relative Momentum (10%).

curl -X GET "https://market.acadmyai.com/v2/sentiment/RELIANCE" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "cmsi_score": 0.74,
  "sentiment_label": "BULLISH",
  "pillars": {
    "news_nlp": 0.76,
    "corporate_filings": 0.82,
    "financial_trajectory": 0.70,
    "institutional_footprint": 0.78,
    "relative_momentum": 0.65
  }
}

GET/v2/news/{ticker}

Real-time deduplicated financial news and exchange corporate filings evaluated by Gemini 2.5 Flash Lite with sentiment classification, credibility scoring, and paid-promotion detection.

curl -X GET "https://market.acadmyai.com/v2/news/RELIANCE?limit=5" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "total_articles": 5,
  "articles": [
    {
      "headline": "Reliance Retail expands footprint with new fulfillment hubs across Western India",
      "source": "Economic Times",
      "published_at": "2026-09-07T08:30:00Z",
      "sentiment_score": 0.65,
      "sentiment_class": "Bullish",
      "credibility_score": 0.92,
      "article_type": "GENUINE_EVALUATION",
      "is_sponsored": false
    }
  ]
}

GET/v2/fundamentals/{ticker}/profile

Company master profile: registered corporate name, industry classification, corporate headquarters, ISIN, market capitalization, enterprise value, and valuation metrics.

curl -X GET "https://market.acadmyai.com/v2/fundamentals/RELIANCE/profile" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "name": "Reliance Industries Limited",
  "isin": "INE002A01018",
  "sector": "Energy",
  "industry": "Oil & Gas Refining & Marketing",
  "hq": "Mumbai, Maharashtra",
  "market_cap_cr": 2022800.0,
  "enterprise_value_cr": 2341500.0,
  "pe_ratio": 26.4,
  "pb_ratio": 2.85
}

GET/v2/fundamentals/{ticker}/financials

Quarterly and annual financial statements: total revenue, EBITDA, net profit, operating cash flow, and EPS history across all audited filing periods.

curl -X GET "https://market.acadmyai.com/v2/fundamentals/RELIANCE/financials?period=quarterly" \
  -H "Authorization: Bearer sk-marketai-your_secret_key"

Response Payload (200 OK)

{
  "ticker": "RELIANCE",
  "period_type": "quarterly",
  "statements": [
    {
      "period_end": "2026-06-30",
      "revenue_cr": 257824.0,
      "ebitda_cr": 42748.0,
      "net_profit_cr": 19442.0,
      "eps": 28.75
    }
  ]
}