# MarketAI v2.0 Developer & Agent API Reference
> Institutional Financial Data & Quantitative Alpha Engine for Indian Equities (NSE & BSE)
> Base URL: https://market.acadmyai.com/v2
> Full AI Specification: https://market.acadmyai.com/llms-full.txt

## Overview
MarketAI is a low-latency, institutional-grade financial data ecosystem providing sub-millisecond equities pricing across NSE and BSE, dual Bhavcopy deliverable volume tracking, full F&O derivatives analytics (PCR, Max Pain, Open Interest regimes), 60+ pre-calculated quant ML alpha factors with Winsorized Z-scores, alternative smart money flow monitoring (FII/DII, bulk/block deals, SEBI surveillance), and Gemini 2.5 Flash Lite sentiment intelligence.

## Authentication
Include your API key as a Bearer token in the HTTP Authorization header:
```http
Authorization: Bearer sk-lvl2-your_secret_key
```

## Agent Tool Selection & Decision Matrix
Use this fast decision matrix to select the optimal endpoint:

| User / Task Objective | Recommended Endpoint | Method | Why Choose This |
| :--- | :--- | :--- | :--- |
| Single comprehensive stock card | `/v2/fintech/stock-card/{ticker}` | GET | Turnkey 1-call payload aggregating price, delivery %, Gemini 3-bullet filing summaries, F&O positioning, and SEBI surveillance. |
| Macro market health & flows | `/v2/fintech/market-pulse` | GET | Institutional FII/DII cash net flows in ₹ Cr, FII Long/Short ratio, and benchmark NIFTY derivatives mood. |
| Real-time stock quote & delivery | `/v2/stocks/{ticker}/quote` | GET | Sub-millisecond tick, day high/low, 52W high/low, deliverable volume, and institutional delivery accumulation tag. |
| Intraday / historical candles | `/v2/stocks/{ticker}/ohlcv` | GET | Continuous 15m or 1D OHLCV bars with deliverable volume, turnover, and price-action trend regime tags. |
| Benchmark & sectoral indices | `/v2/market/index/{index_name}/ohlcv` | GET | Technical indicators (EMA20, EMA50, RSI14, ATR14) for NIFTY50, BANKNIFTY, SENSEX, INDIA_VIX, etc. |
| Market volume & turnover screener | `/v2/market/volume-distribution` | GET | Volume & turnover distribution histogram across all active securities. |
| Institutional derivatives summary | `/v2/derivatives/{ticker}/summary` | GET | Put-Call Ratio (PCR by OI & volume), Max Pain strike, 4-quadrant OI Buildup regime, and ATM IV. |
| Strike-by-strike option chain | `/v2/derivatives/{ticker}/chain` | GET | Full CE & PE open interest, daily OI change, volume, turnover, and settlement prices. |
| Quant ML alpha factor snapshot | `/v2/quant/features/{ticker}` | GET | 60+ pre-calculated factors: multi-period returns, 12-1m momentum, Parkinson & Garman-Klass vol, delivery surprise Z-score, Amihud illiquidity, and sector percentiles. |
| Bulk quant dataset download | `/v2/quant/export` | GET | Streams daily cross-sectional alpha factors as an Apache Parquet binary file for direct loading into Polars, Pandas, LightGBM, or PyTorch. |
| Large institutional transactions | `/v2/alternative/bulk-deals` | GET | High-conviction bulk and block deals (>0.5% equity) with client names, deal types, and trade values. |
| Institutional cash & F&O flows | `/v2/alternative/fii-dii` | GET | Daily FII and DII cash buying/selling in ₹ Cr, FII index futures positioning, and FII Long/Short contract ratio. |
| Regulatory risk & price bands | `/v2/alternative/surveillance/{ticker}` | GET | SEBI Additional Surveillance Measures (ASM Stage 1/2), Graded Surveillance (GSM), and dynamic circuit limits (2%, 5%, 10%, 20%). |
| 5-Factor Composite Sentiment | `/v2/sentiment/{ticker}` | GET | Composite Market Sentiment Index (CMSI) in [-1.00, +1.00] across News NLP (25%), Filings (25%), Fundamentals (20%), Orderflow (20%), and Momentum (10%). |
| AI news & filing summaries | `/v2/stocks/{ticker}/news` | GET | Verified financial articles parsed by Gemini 2.5 Flash Lite with sentiment classification and credibility scores. |
| Quarterly balance sheet & P&L | `/v2/stocks/{ticker}/financials` | GET | Standardized revenue, EBITDA, net profit, EPS, and promoter/FII/DII shareholding distributions. |

## Rate Limits & SLA
- Standard Pro Tier: 120 requests/minute.
- Enterprise Tier: 1,200 requests/minute.
- Edge Latency: < 15ms via CDN edge routing.
- Uptime SLA: 99.99%.
- Rate limit headers returned on every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

For full schema definitions, field types, and tool-calling specifications, fetch https://market.acadmyai.com/llms-full.txt