# MarketAI v2.0 Complete Developer & Agent Technical Specification
> Institutional Indian Equities Data, Derivatives Engine, and Quant ML Feature Store
> Production Base URL: https://market.acadmyai.com/v2
> OpenAPI Specification: https://market.acadmyai.com/v2/openapi.json
> Header Requirement: Authorization: Bearer <API_KEY>

---

## Table of Contents
1. Authentication & Security
2. Turnkey FinTech B2B Suite
   - GET /v2/fintech/stock-card/{ticker}
   - GET /v2/fintech/market-pulse
3. Market Microstructure & Equities Data
   - GET /v2/stocks/{ticker}/quote
   - GET /v2/stocks/{ticker}/ohlcv
   - GET /v2/market/index/{index_name}/ohlcv
   - GET /v2/market/volume-distribution
4. Institutional Derivatives & Options Engine
   - GET /v2/derivatives/{ticker}/summary
   - GET /v2/derivatives/{ticker}/chain
5. Quant ML Alpha Factor Store
   - GET /v2/quant/features/{ticker}
   - GET /v2/quant/export
6. Smart Money & Alternative Data
   - GET /v2/alternative/bulk-deals
   - GET /v2/alternative/fii-dii
   - GET /v2/alternative/surveillance/{ticker}
7. AI Market Intelligence & Sentiment
   - GET /v2/sentiment/{ticker}
   - GET /v2/stocks/{ticker}/news
   - GET /v2/stocks/{ticker}/financials
8. OpenAI & Gemini Tool-Calling Function Schemas

---

## 1. Authentication & Security

All requests to the `/v2` API must pass an API key in the `Authorization` header as an HTTP Bearer token:
```http
Authorization: Bearer sk-lvl2-your_secret_key
```

### HTTP Response Codes
- `200 OK`: Request succeeded.
- `400 Bad Request`: Invalid parameter format (e.g. invalid date or unknown interval).
- `401 Unauthorized`: Missing or invalid API key.
- `404 Not Found`: Ticker or requested resource not found in registry.
- `429 Too Many Requests`: Rate limit exceeded (Default: 120 req/min). Check `Retry-After` header.
- `500 Internal Server Error`: Server-side processing error.

---

## 2. Turnkey FinTech B2B Suite

### GET /v2/fintech/stock-card/{ticker}
**Agent Trigger Condition:** Use this endpoint whenever an AI assistant or fintech user requests a complete, high-density stock summary. It bundles EOD price, delivery accumulation, Gemini AI regulatory filing bullets, F&O positioning, and SEBI surveillance into a single low-latency call, eliminating the need to trigger 4 separate tools.

#### Path Parameters
| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `ticker` | `string` | Yes | National Stock Exchange (NSE) ticker symbol | `RELIANCE`, `TCS`, `HDFCBANK` |

#### Response Schema (JSON)
```json
{
  "ticker": "RELIANCE",
  "name": "Reliance Industries Limited",
  "sector": "Energy",
  "market_cap_cr": 2022800.0,
  "quote": {
    "date": "2026-09-04",
    "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 addition 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
  }
}
```

#### Field Dictionary
- `delivery_accumulation_signal`:
  - `STRONG_INSTITUTIONAL_ACCUMULATION`: Deliverable volume >= 55%.
  - `MODERATE_DELIVERY_SUPPORT`: Deliverable volume between 40% and 55%.
  - `SPECULATIVE_INTRADAY_CHURN`: Deliverable volume < 20%.
  - `NEUTRAL`: Standard delivery between 20% and 40%.
- `materiality`: `MATERIAL_POSITIVE` | `NEUTRAL` | `MATERIAL_NEGATIVE`.
- `oi_regime`: `LONG_BUILDUP` | `SHORT_BUILDUP` | `SHORT_COVERING` | `LONG_UNWINDING`.
- `circuit_limit_pct`: Max allowed daily price swing percentage set by exchange (e.g., 2.0, 5.0, 10.0, 20.0).

---

### GET /v2/fintech/market-pulse
**Agent Trigger Condition:** Use this endpoint when a user asks about the overall health, institutional mood, or sentiment of the Indian market. It provides macro FII/DII cash flows, FII futures long/short ratio, and NIFTY F&O sentiment.

#### Response Schema (JSON)
```json
{
  "as_of": "2026-09-04",
  "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"
}
```

---

## 3. Market Microstructure & Equities Data

### GET /v2/stocks/{ticker}/quote
**Agent Trigger Condition:** Fetch sub-millisecond price, day range, 52W range, valuation multiples, and delivery volume accumulation.

#### Path Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `ticker` | `string` | Yes | Equity symbol (e.g. `INFY`, `TCS`) |

#### Response Schema (JSON)
```json
{
  "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
**Agent Trigger Condition:** Fetch historical candle series for technical charting, algorithmic backtests, or price action analysis.

#### Query Parameters
| Parameter | Type | Required | Default | Allowed Enums / Range | Description |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `interval` | `string` | No | `15m` | `15m`, `1d` | Candle timeframe (15-minute intraday or 1-day) |
| `days` | `integer`| No | `30` | `1` to `730` | Historical lookback window in calendar days |
| `market` | `string` | No | `NSE` | `NSE`, `BSE` | Primary exchange feed |

#### Response Schema (JSON)
```json
{
  "ticker": "RELIANCE",
  "market": "NSE",
  "interval": "15m",
  "total_candles": 2,
  "data": [
    {
      "date": "2026-09-04 15:15:00+05:30",
      "open": 2984.50,
      "high": 2991.00,
      "low": 2982.10,
      "close": 2989.75,
      "volume": 342100,
      "deliverable_volume": 194997,
      "deliverable_percent": 57.0,
      "stock_regime": "BULLISH_TREND"
    }
  ]
}
```

---

### GET /v2/market/index/{index_name}/ohlcv
**Agent Trigger Condition:** Fetch indicator-enriched candles ($EMA_{20}$, $EMA_{50}$, $RSI_{14}$, $ATR_{14}$) for market benchmarks and sectoral indices.

#### Path Parameters
| Parameter | Type | Required | Allowed Enums |
| :--- | :--- | :--- | :--- |
| `index_name` | `string` | Yes | `NIFTY50`, `SENSEX`, `BANKNIFTY`, `NIFTY_IT`, `NIFTY_AUTO`, `NIFTY_PHARMA`, `NIFTY_FMCG`, `INDIA_VIX`, `GIFT_NIFTY`, `NASDAQ`, `US_VIX` |

#### Query Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `days_back` | `integer` | No | `30` | Lookback period in days (1 to 400) |
| `interval` | `string` | No | `15m` | `15m`, `1d`, `1w` |

---

### GET /v2/market/volume-distribution
**Agent Trigger Condition:** Screen market-wide liquidity to isolate securities experiencing unusual volume expansion or high turnover.

#### Query Parameters
| Parameter | Type | Required | Default | Allowed Enums | Description |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `metric` | `string` | No | `turnover_cr` | `turnover_cr`, `volume` | Histogram metric |
| `market` | `string` | No | `NSE` | `NSE`, `BSE` | Target exchange |

---

## 4. Institutional Derivatives & Options Engine

### GET /v2/derivatives/{ticker}/summary
**Agent Trigger Condition:** Evaluate institutional positioning in F&O securities. Returns Put-Call Ratio (PCR), theoretical Max Pain strike, 4-quadrant OI Buildup regime, and ATM Implied Volatility.

#### Path Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `ticker` | `string` | Yes | F&O underlying symbol (e.g. `NIFTY`, `BANKNIFTY`, `RELIANCE`, `TCS`) |

#### Query Parameters
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `as_of` | `string` | No | Latest date | Date filter in `YYYY-MM-DD` format |

#### Response Schema (JSON)
```json
{
  "symbol": "RELIANCE",
  "date": "2026-09-04",
  "spot_close": 2989.75,
  "future_close": 2998.40,
  "pcr_oi": 1.18,
  "pcr_volume": 1.05,
  "max_pain_strike": 3000.0,
  "oi_regime": "LONG_BUILDUP",
  "oi_change_pct": 6.42,
  "price_change_pct": 1.25,
  "total_ce_oi": 14280500,
  "total_pe_oi": 16851000,
  "total_ce_volume": 421090,
  "total_pe_volume": 442140,
  "atm_iv": 18.4
}
```

#### OI Regime Classification Logic
- `LONG_BUILDUP`: Price >= 0 and OI >= 0 (Institutional Buying)
- `SHORT_BUILDUP`: Price < 0 and OI >= 0 (Institutional Shorting)
- `SHORT_COVERING`: Price >= 0 and OI < 0 (Shorts Squeezed)
- `LONG_UNWINDING`: Price < 0 and OI < 0 (Bulls Liquidating)

---

### GET /v2/derivatives/{ticker}/chain
**Agent Trigger Condition:** Fetch granular strike-by-strike Call/Put open interest, daily OI delta, traded contracts, and turnover for option strategy execution.

#### Query Parameters
| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `expiry` | `string` | No | Expiry date filter (`YYYY-MM-DD`) | `2026-09-24` |

#### Response Schema (JSON)
```json
{
  "symbol": "RELIANCE",
  "trade_date": "2026-09-04",
  "total_strikes": 42,
  "chain": [
    {
      "strike": 3000.0,
      "expiry": "2026-09-24",
      "ce": {
        "close": 42.50,
        "settle": 43.10,
        "oi": 1250000,
        "change_in_oi": 84200,
        "volume": 15400,
        "turnover_lakhs": 462.5
      },
      "pe": {
        "close": 38.20,
        "settle": 37.90,
        "oi": 1480000,
        "change_in_oi": 120500,
        "volume": 18900,
        "turnover_lakhs": 567.0
      }
    }
  ]
}
```

---

## 5. Quant ML Alpha Factor Store

### GET /v2/quant/features/{ticker}
**Agent Trigger Condition:** Retrieve 60+ pre-calculated normalized alpha factors for quantitative scoring, machine learning features, or stock factor screening.

#### Response Schema (JSON)
```json
{
  "ticker": "RELIANCE",
  "date": "2026-09-04",
  "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
  },
  "derivatives": {
    "pcr_oi": 1.18,
    "oi_regime": "LONG_BUILDUP"
  },
  "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/export
**Agent Trigger Condition:** Stream cross-sectional market factors as an Apache Parquet binary file for quantitative researchers training PyTorch/LightGBM models or conducting high-speed vector backtests in Polars/Pandas.

#### Query Parameters
| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `target_date` | `string` | No | Target date in `YYYY-MM-DD` (defaults to latest) | `2026-09-04` |

#### Headers Returned
- `Content-Type: application/octet-stream`
- `Content-Disposition: attachment; filename=marketai_factors_2026-09-04.parquet`

---

## 6. Smart Money & Alternative Data

### GET /v2/alternative/bulk-deals
**Agent Trigger Condition:** Screen high-conviction institutional and promoter transactions (>0.5% equity stake or ₹5+ Cr turnover) on NSE and BSE.

#### Query Parameters
| Parameter | Type | Required | Default | Constraints | Description |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `ticker` | `string` | No | None | Valid symbol | Filter by stock |
| `limit` | `integer`| No | `50` | `1` to `200` | Number of transactions |

#### Response Schema (JSON)
```json
{
  "count": 1,
  "deals": [
    {
      "ticker": "ZOMATO",
      "date": "2026-09-04",
      "exchange": "NSE",
      "deal_type": "BULK",
      "client_name": "GOLDMAN SACHS SINGAPORE PTE",
      "buy_sell": "BUY",
      "quantity": 12500000,
      "trade_price": 248.50,
      "deal_value_cr": 310.63
    }
  ]
}
```

---

### GET /v2/alternative/fii-dii
**Agent Trigger Condition:** Monitor institutional capital flows across cash equity and derivatives markets.

#### Query Parameters
| Parameter | Type | Required | Default | Range | Description |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `days` | `integer` | No | `30` | `1` to `180` | Lookback window in days |

#### Response Schema (JSON)
```json
{
  "total_days": 1,
  "flows": [
    {
      "date": "2026-09-04",
      "fii_net_cr": 1420.50,
      "dii_net_cr": 890.25,
      "fii_long_short_ratio": 1.34
    }
  ]
}
```

---

### GET /v2/alternative/surveillance/{ticker}
**Agent Trigger Condition:** Risk-gate automated trading algorithms before order placement. Check if a security is under SEBI Additional Surveillance Measures (ASM), Graded Surveillance Measures (GSM), or reduced price circuit bands.

#### Response Schema (JSON)
```json
{
  "ticker": "RELIANCE",
  "date": "2026-09-04",
  "is_in_surveillance": false,
  "asm_stage": null,
  "gsm_stage": null,
  "circuit_limit_pct": 20.0,
  "remarks": "Clean (No SEBI Surveillance Active)"
}
```

---

## 7. AI Market Intelligence & Sentiment

### GET /v2/sentiment/{ticker}
**Agent Trigger Condition:** Obtain an institutional 5-factor Composite Market Sentiment Index (CMSI) rating (-1.00 to +1.00) based on news NLP, regulatory filings, financial momentum, institutional orderflow, and market structure.

#### Response Schema (JSON)
```json
{
  "ticker": "RELIANCE",
  "cmsi_score": 0.72,
  "sentiment_classification": "BULLISH",
  "weights": {
    "news_nlp_sentiment": 0.25,
    "corporate_governance_and_filings": 0.25,
    "earnings_and_fundamental_momentum": 0.20,
    "institutional_orderflow_and_footprint": 0.20,
    "market_structure_and_momentum": 0.10
  },
  "pillar_scores": {
    "news_nlp": 0.68,
    "filings_materiality": 0.85,
    "fundamental_momentum": 0.70,
    "institutional_orderflow": 0.75,
    "relative_strength": 0.60
  }
}
```

---

### GET /v2/stocks/{ticker}/news
**Agent Trigger Condition:** Fetch verified financial news headlines and articles scored by Gemini 2.5 Flash Lite with sentiment classes and credibility ratings.

---

### GET /v2/stocks/{ticker}/financials
**Agent Trigger Condition:** Fetch quarterly audited income statements, EBITDA margins, and promoter/FII/DII shareholding distributions.

---

## 8. OpenAI & Gemini Tool-Calling Function Schemas

For AI agents integrating MarketAI into automated function-calling tool registries (e.g. OpenAI Assistants, LangChain, Autogen, Gemini Tools), below are the standard JSON Schema function signatures:

### Function 1: `get_fintech_stock_card`
```json
{
  "name": "get_fintech_stock_card",
  "description": "Fetch a high-density 1-call summary of an Indian stock including price, delivery volume %, Gemini AI filing summary, F&O positioning (PCR, Max Pain), and SEBI surveillance flags.",
  "parameters": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "NSE equity ticker symbol (e.g. RELIANCE, TCS, INFY)"
      }
    },
    "required": ["ticker"]
  }
}
```

### Function 2: `get_market_pulse`
```json
{
  "name": "get_market_pulse",
  "description": "Fetch daily macro pulse of the Indian market including FII/DII net flows in Cr, FII Long/Short ratio, and benchmark NIFTY PCR and Max Pain.",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

### Function 3: `get_derivatives_summary`
```json
{
  "name": "get_derivatives_summary",
  "description": "Retrieve institutional derivatives positioning, Put-Call Ratio (PCR), Max Pain strike, and 4-quadrant Open Interest Buildup regime for an F&O underlying.",
  "parameters": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Underlying symbol (e.g. NIFTY, BANKNIFTY, RELIANCE)"
      },
      "as_of": {
        "type": "string",
        "description": "Optional date filter in YYYY-MM-DD format"
      }
    },
    "required": ["ticker"]
  }
}
```

### Function 4: `get_quant_features`
```json
{
  "name": "get_quant_features",
  "description": "Fetch 60+ pre-calculated quant alpha factors, volatility estimators (Parkinson, Garman-Klass), delivery surprise Z-scores, and cross-sectional sector percentile ranks.",
  "parameters": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "NSE ticker symbol"
      },
      "as_of": {
        "type": "string",
        "description": "Optional date filter in YYYY-MM-DD format"
      }
    },
    "required": ["ticker"]
  }
}
```

### Function 5: `get_surveillance_status`
```json
{
  "name": "get_surveillance_status",
  "description": "Risk-gate orders by checking SEBI Additional Surveillance Measures (ASM), Graded Surveillance (GSM), and active circuit breaker percentage limits for an equity.",
  "parameters": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "NSE ticker symbol"
      }
    },
    "required": ["ticker"]
  }
}
```