Developer API Documentation

REST API for Indian stock market intelligence. AI-powered DVM scores, convergence signals, market regime analysis, composite ML forecasts, institutional flow, options intelligence, and 330+ endpoints across v1/v2/v3.

Authentication

All API requests (except /api/health and /api/v3/openapi-spec) require an API key sent via the X-API-Key header.

curl -H "X-API-Key: dalalai_YOUR_KEY_HERE" \
  https://dalalai.com/api/v1/stocks

Getting a Key

• Paid: Subscribe to the Developer plan (₹1,999/mo or ₹19,999/yr), then generate keys in the API Dashboard.
• Trial: Any registered user can generate a trial key (25 calls, 3 days) — no payment required.

You can have up to 3 active keys per account. Keys are SHA-256 hashed on our end — the raw key is shown only once at creation.

Free Trial No Card Required

Try the API before subscribing. Every registered user gets 25 API calls over 3 days with a trial key.

To generate a trial key, go to the API Dashboard and click “Try Free”. The trial key works on all endpoints with the same response format.

After 25 calls or 3 days, the key expires. Subscribe to the Developer plan for unlimited access.

Base URL & Versioning

https://dalalai.com/api/v1/

Current version: v1. The X-API-Version: 1 header is included in all responses. When v2 launches, v1 will remain supported for at least 6 months.

Response Format

All responses use a consistent JSON envelope:

{
  "data": { ... },       // The actual payload (null on error)
  "meta": {
    "timestamp": "2026-03-14T08:30:00Z",
    "version": 1,
    "endpoint": "/api/v1/stocks",
    "dataTimestamp": "2026-03-14 07:32:40",
    "cached": true,
    "pagination": { "page": 1, "limit": 50, "total": 799, "pages": 16 }
  },
  "error": null           // null on success
}

On error:

{
  "data": null,
  "meta": { ... },
  "error": {
    "code": 1004,
    "message": "Rate limit exceeded",
    "suggestion": "Wait and retry after the Retry-After period.",
    "docs": "https://dalalai.com/docs/api"
  }
}

Query Parameters

These query parameters work on all data endpoints. On /api/v1/stocks, they apply to the stocks array.

Field Selection — ?fields=

Return only specified fields, reducing payload size significantly.

curl -H "X-API-Key: YOUR_KEY" \
  "https://dalalai.com/api/v1/stocks?fields=Symbol,CMP,DVM_Score"

# Response: only Symbol, CMP, DVM_Score per stock (other fields omitted)

Sorting — ?sort=

Sort results server-side. Prefix with - for descending order.

# Top stocks by DVM_Score (descending)
curl -H "X-API-Key: YOUR_KEY" \
  "https://dalalai.com/api/v1/stocks?sort=-DVM_Score&limit=10"

# Alphabetical by symbol (ascending)
curl ... "https://dalalai.com/api/v1/stocks?sort=Symbol"

Filtering — ?filter=

Filter records using comparison operators. Comma-separate multiple clauses (AND logic). Max 10 clauses.

# High-conviction stocks above ₹100
curl -H "X-API-Key: YOUR_KEY" \
  "https://dalalai.com/api/v1/stocks?filter=DVM_Score>80,CMP>100&sort=-DVM_Score&fields=Symbol,CMP,DVM_Score"

Batch Requests

Fetch up to 5 endpoints in a single API call. Saves latency and rate limit quota.

curl -H "X-API-Key: YOUR_KEY" \
  "https://dalalai.com/api/v1/batch?endpoints=stocks,regime,breadth"

# Response:
{
  "data": {
    "stocks": { ... },   // full stocks response
    "regime": { ... },    // full regime response
    "breadth": { ... }    // full breadth response
  },
  "meta": { "endpoints": ["stocks", "regime", "breadth"], ... }
}

Files are deduplicated internally — if two endpoints share the same data file, it's fetched only once.

ETag & Conditional Requests

Every response includes an ETag header. On subsequent requests, send If-None-Match to get a 304 Not Modified (empty body) if data hasn't changed. Ideal for polling.

# First request — save the ETag
curl -v -H "X-API-Key: YOUR_KEY" https://dalalai.com/api/v1/regime
# Response header: ETag: "a1b2c3d4e5f6..."

# Subsequent request — include If-None-Match
curl -H "X-API-Key: YOUR_KEY" \
     -H 'If-None-Match: "a1b2c3d4e5f6..."' \
  https://dalalai.com/api/v1/regime
# → 304 Not Modified (0 bytes, no bandwidth cost)

Embeddable Widgets No Key Required

Embed live market data badges in your blog, dashboard, or social profile. Returns an SVG image. No API key needed.

# SVG badge (default)
https://dalalai.com/api/v1/widget?type=regime&format=svg

# JSON (for custom rendering)
https://dalalai.com/api/v1/widget?type=regime&format=json

Embed in HTML:

<img src="https://dalalai.com/api/v1/widget?type=regime" alt="DalalAI Market Regime" />

Available types: regime (market regime), stocks (stocks scored count), or any endpoint name.

Error Codes

Rate Limits

Rate limits are tier-based:

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1710403260
X-Request-Id: a1b2c3d4-e5f6-...
X-Data-Age-Hours: 3.2

When rate limited (HTTP 429), the Retry-After header indicates seconds to wait.

The X-Data-Age-Hours header shows how old the underlying data is. The meta.warnings array will contain a staleness warning if data is older than 26 hours.

Python SDK Guide

No library to install — just requests. Here's a production-ready wrapper:

import requests
from typing import Optional

class DalalAI:
    BASE = "https://dalalai.com/api/v1"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers["X-API-Key"] = api_key
        self._etags = {}

    def _get(self, endpoint: str, params: Optional[dict] = None):
        url = f"{self.BASE}/{endpoint}"
        headers = {}
        if url in self._etags:
            headers["If-None-Match"] = self._etags[url]
        r = self.session.get(url, params=params, headers=headers, timeout=15)
        if r.status_code == 304:
            return None  # data unchanged
        r.raise_for_status()
        if "ETag" in r.headers:
            self._etags[url] = r.headers["ETag"]
        return r.json()["data"]

    def stocks(self, sort=None, filter=None, fields=None, page=1, limit=50):
        p = {"page": page, "limit": limit}
        if sort: p["sort"] = sort
        if filter: p["filter"] = filter
        if fields: p["fields"] = fields
        return self._get("stocks", p)

    def regime(self):
        return self._get("regime")

    def batch(self, endpoints: list):
        return self._get("batch", {"endpoints": ",".join(endpoints)})

    def widget(self, type="regime", format="json"):
        return self._get("widget", {"type": type, "format": format})

# Usage:
api = DalalAI("dalalai_YOUR_KEY_HERE")
top = api.stocks(sort="-DVM_Score", filter="DVM_Score>80", fields="Symbol,CMP,DVM_Score", limit=10)
regime = api.regime()
multi = api.batch(["stocks", "regime", "breadth"])

🧪 Interactive API Playground

Try any endpoint live. Enter your API key (or use the trial endpoint) and hit Send.

// Response will appear here
// Try clicking a Quick button above ↑

Endpoints

// Response shape (paginated):
{
  "data": {
    "stocks": [{ "Symbol": "MAHABANK", "DVM_Score": 87.4, "AI_Rating": "Strong Buy", ... }],
    "total": 799, "page": 1, "limit": 50,
    "regime": { "state": "RANGING", ... }
  },
  "meta": { "pagination": { "page": 1, "limit": 50, "total": 799, "pages": 16 }, ... }
}

// Response shape (single stock):
{
  "data": { "stock": { "Symbol": "RELIANCE", "DVM_Score": 44.7, ... } }
}

{
  "data": {
    "regime": { "state": "RANGING", "confidence": 0.72, ... },
    "summary": { "stocks_scored": 799, "avg_convergence": 53.8, ... },
    "timestamp": "2026-03-14 07:32:40"
  }
}

{
  "data": {
    "top_20": [{ "symbol": "MAHABANK", "convergence_score": 87.4, "signal_strength": "very_high_convergence", ... }],
    "summary": { "stocks_scored": 799, "very_high_count": 19, "avg_convergence": 53.8 },
    "regime": "RANGING"
  }
}

Wave 9 — Advanced Analytics (20 endpoints)

Quantitative analytics, microstructure, multi-factor scoring, and institutional-grade tooling. Auto-registered data endpoints.

v2 — Composite & Developer APIs

Higher-level endpoints that compose multiple ML models and analytics into unified, actionable responses. All v2 endpoints require authentication.

Composite Data APIs

{
  "symbol": "RELIANCE",
  "lstm_forecast": { "direction": "UP", "magnitude": 2.3, ... },
  "conformal_intervals": { "5d": { "lower": 2780, "upper": 2950 }, ... },
  "ai_signal": { "ensemble_action": "BUY", "ensemble_confidence": 0.82, "models": { ... } },
  "cmp": 2856.45
}

{
  "symbol": "MAHABANK",
  "votes": { "RandomForest": { "action": "BUY", "probability": 0.87 }, ... },
  "consensus": { "action": "BUY", "agreement_pct": 83.3, "buy_votes": 5, "sell_votes": 1, "hold_votes": 0 },
  "lstm": { ... }, "gnn_peer_boost": { ... }
}

Developer APIs

{
  "symbol": "RELIANCE",
  "feature_count": 70,
  "features": { "RSI": 58.3, "MACD": 12.7, "ADX": 34.2, "ATR_pct": 1.8, ... },
  "metadata": { "Symbol": "RELIANCE", "Sector": "Energy" }
}

v3 — Premium Institutional APIs

High-value endpoints targeting FIIs, HNIs, institutional investors, and retail brokers. Each composes multiple data assets into institutional-grade intelligence. Pro Enterprise

Institutional Flow & Positioning

{
  "institutional_bias": "Bullish",
  "fii_dii": { "fii_net_cr": 1247.3, "dii_net_cr": 832.1, "combined_net_cr": 2079.4 },
  "fii_long_short_ratio": 1.42,
  "participant_oi": { ... }, "fpi_stock_holdings": { ... }, "smart_money": { ... }
}

Options & Derivatives Intelligence

{
  "symbol": "NIFTY",
  "unusual_activity": { ... },
  "oi_heatmap": { ... },
  "put_call_ratio": 0.87,
  "vix": { "level": 14.2, "label": "Normal" },
  "options_chain_summary": { "max_pain": 22500, "total_ce_oi": 1234567, "total_pe_oi": 987654 }
}

Insider, Regulatory & Compliance

{
  "symbol": "RELIANCE",
  "risk_flags": ["High promoter pledge: 22.5%", "2 SEBI takeover filing(s)"],
  "insider_transactions": [ ... ],
  "promoter_holding": { ... }, "promoter_pledge": { ... },
  "shareholding_pattern": { ... }, "sebi_takeover_filings": [ ... ]
}

Index, Macro & Risk

IPO & Primary Markets

v3 — B2B Analytics & ML Empowerment

21 new endpoints that unlock webhooks, streaming, custom factor building, historical snapshots, execution quality, and explainable AI for institutional B2B clients. Pro Enterprise

Webhooks & Real-Time Push

Custom Factor Builder

Time-Series Historical Snapshots

Portfolio Attribution & Risk

Execution Quality (TCA)

Intelligence & Signals

OpenAPI Specification

ML Intelligence APIs

High-value composite endpoints that combine 10+ ML model outputs into actionable intelligence. Cross-model consensus, accuracy-weighted predictions, and full explainability. Pro Enterprise

Pro — ML Composites (v2)

Enterprise — ML Operations (v3)

Health Check

{
  "data": {
    "status": "ok",
    "uptime": true,
    "dataSource": "ok",
    "endpoints": 409,
    "rateLimit": "tier-based"
  }
}

{
  "data": {
    "gate": "PASS",
    "summary": "Quality Gate: PASS — 21/21 passed",
    "stats": { "total": 21, "passed": 21, "warned": 0, "failed": 0 },
    "files": [
      { "file": "dvm_scores.json", "status": "PASS", "age_hours": 3.2, "record_count": 806 },
      ...
    ]
  }
}

Live API status page →

Tier Info

{
  "tier": "PRO",
  "rate_limits": { "daily_calls": 50000, "per_minute": 500 },
  "quotas": { "keys": 10, "webhooks": 25, "historical_days": 1825 },
  "all_tiers": { "free": { ... }, "starter": { ... }, "pro": { ... }, "enterprise": { ... } },
  "upgrade_url": "https://dalalai.com/b2b#pricing"
}

Account Management

These endpoints manage API keys, webhooks, and organizations. They require Firebase Authentication (Bearer token) or a valid API key depending on the endpoint.

API Key Management

POST /api/manageApiKeys — Requires Firebase Auth token in Authorization header + App Check.

// Generate a trial key
POST /api/manageApiKeys
Authorization: Bearer {firebase_id_token}
{ "action": "generate_trial" }

// Response
{
  "success": true,
  "apiKey": "dalalai_a1b2c3d4...",
  "prefix": "dalalai_a1b2c3d4",
  "trial": true,
  "limits": { "calls": 25, "expiresAt": "2026-03-26T..." }
}

Webhook Management

Manage webhook subscriptions for real-time event push notifications. Requires API key via X-API-Key header. Starter tier and above.

POST /api/webhooks
X-API-Key: dalalai_your_key
{
  "url": "https://your-server.com/webhook",
  "events": ["regime_change", "breakout_signal", "earnings_surprise"],
  "secret": "optional-signing-secret"
}

// Response: { "id": "wh_abc123", "url": "...", "events": [...], "active": true }

Organization Management Enterprise

Multi-user organizations with RBAC. Enterprise tier only. Requires API key via X-API-Key.

API Versioning Policy

DalalAI uses additive versioning. v1/v2/v3 are concurrently supported. No endpoint is removed without at least 12 months notice via:

• Deprecation: true response header when an endpoint is scheduled for removal
• Sunset: Sat, 31 Mar 2027 23:59:59 GMT header with the exact removal date
• Email notification to all subscribed API key owners
• Changelog entry at changelog

Current status: All v1, v2, and v3 endpoints are stable. No deprecations are currently scheduled. v1 is guaranteed through at least March 31, 2027.

API Availability Matrix

Every endpoint is gated to a minimum tier. Higher tiers inherit all endpoints from lower tiers. This table shows what each pricing plan unlocks.

Rate Limits & Quotas by Tier

Tier is resolved from your API key via Firestore. Use GET /api/v1/tier-info to check your current tier and quotas programmatically. Response headers include X-API-Tier, X-RateLimit-Daily, and X-RateLimit-PerMinute on every request.

Postman Collection

Import the ready-made Postman collection to test all endpoints instantly:

⬇ Download Postman Collection

After importing, set the api_key variable in your Postman environment to your API key.

Changelog

v1.6 — March 23, 2026

• 10 new ML Intelligence composite APIs — cross-model consensus, prediction confidence intervals, stock intelligence briefs, circuit breaker risk, earnings edge ML, ML health dashboard, alpha signals, accuracy trends, ensemble explainer, risk/return matrix
• 17 ML data files populated — fixed 13 stub files (DES-KNN, earnings beat, GNN, LightGBM, TabNet, TFT, online SGD, regime ensemble, quantile forecasts, circuit breaker, explainability, multi-target, reconciliation) + created 4 new files (prediction stack, model governance, accuracy report, ensemble predictions)
• Tier-based access control — 4-tier enforcement (Free/Starter/Pro/Enterprise) with 403 + upgrade CTA, per-key Firestore tier resolution, rate limit headers
• New endpoint: /api/v1/tier-info — self-service tier/quota check
• Model governance dashboard: champion/challenger tracking, drift alerts, compliance audit
• 30-day accuracy leaderboard: daily per-model scores with trend analysis
• Running total: 409 endpoints (305 v1 + 52 v2 + 52 v3)

v1.5 — March 23, 2026

• 21 new B2B Analytics & ML Empowerment APIs — webhooks, SSE streaming, custom factor builder, historical snapshots, execution quality TCA, multi-asset risk, conviction decay, explainable alerts, OpenAPI spec
• Webhooks: Register HTTPS endpoints, HMAC-SHA256 signed payloads, 10 event types (regime_change, breakout_signal, convergence_spike, earnings_surprise, insider_trade, fii_flow_reversal, portfolio_alert, price_target_hit, vix_spike, block_deal)
• SSE Streaming: Server-Sent Events for real-time signal push during market hours
• Custom Factor Builder: 30+ components, mathematical operators, walk-forward backtesting
• Time-Series Snapshots: Historical data for 13 key endpoints, up to 365-day retention
• Enriched Attribution: Brinson-Fachler + factor attribution + risk decomposition
• Multi-Asset Risk: Equities + bonds (G-Sec, yield curve) + commodities in one dashboard
• Execution Quality TCA: VPIN, Kyle's lambda, Amihud illiquidity, optimal execution planning
• 10 stress scenarios: Rate hikes, crashes, FII exits, VIX spikes, crude, rupee, SEBI, geopolitical
• Conviction Decay: Track institutional conviction trajectory + hedger capitulation signals
• Explainable Alerts: SHAP-powered "why this alert?" reasoning on every alert
• OpenAPI 3.0 spec endpoint: Auto-generate SDKs in any language
• Running total: 388+ endpoints after B2B additions

v1.4 — March 15, 2026

• 20 new Wave 9 Advanced Analytics endpoints — quant factors, microstructure, pair trades, Greeks, risk parity
• Pipeline optimization: Sunday full retrain, Wed+Fri refresh, dual scoring (pre-market + post-market)
• weekly_monthly module wired into plugin registry (stage 4.3295)
• 121 registered analytics plugins (was 98). Total v1 data endpoints: 255. Overall: 330+

v1.3 — March 15, 2026

• 13 new v3 Premium Institutional APIs — targeting FIIs, HNIs, brokers, and compliance teams
• Institutional Flow: unified FII/DII + participant OI + FPI holdings + smart money
• FII Sector Rotation: sector-level FPI aggregation + RRG + rotation playbook
• Block Deal Intelligence: enriched with delivery spikes + smart money signals
• Options Flow: unusual activity + OI heatmap + VIX + historical chain
• Insider Radar: trades + promoter + pledge + SEBI filings + risk flags
• Regulatory Radar: SEBI + BSE announcements + corporate actions
• ESG Compliance: ESG scores + shareholding + pledge + credit ratings
• Macro Dashboard: RBI + yield curve + G-Sec + VIX + cross-asset + global cues
• Stress Test: scenario analysis (rate hike, crash, FII exit, VIX spike, global selloff)
• Index Rebalance: predictions + passive flow + MF deltas
• IPO Intel: pipeline + tracker + concall sentiment
• Running total at this release: 53 (23 v1 + 17 v2 + 13 v3)

v1.2 — March 15, 2026

• 17 new v2 Composite & Developer APIs — compose 27 ML models into unified actionable endpoints
• Stock Forecast: unified LSTM + Conformal + AI Ensemble per symbol
• AI Consensus: per-model vote breakdown with weighted agreement %
• Risk Score: single 0-100 risk metric combining volatility, conformal width, and drift
• Smart Screener: multi-factor filter (signal, convergence, confidence, sentiment)
• Market Pulse: 0-100 market health score (regime + breadth + flows + sentiment + cross-asset)
• Developer APIs: batch predictions, raw features, model health dashboard, explainability, correlation graph, regime playbook, factor returns
• Total endpoints: 40 (23 v1 data + 17 v2 composite/developer)

v1.1 — March 14, 2026

• Field selection: ?fields=Symbol,CMP — reduce response payload
• Sorting: ?sort=-DVM_Score — server-side sorting
• Filtering: ?filter=DVM_Score>80 — multi-clause filtering
• Batch: /api/v1/batch?endpoints=stocks,regime — up to 5 in one call
• ETag + 304 Not Modified for bandwidth-efficient polling
• Embeddable widgets: /api/v1/widget?type=regime — SVG badges
• Usage sparkline in the API dashboard
• RSS feed for changelog

v1.0 — March 2026

• Initial release: 23 data endpoints
• API key authentication with SHA-256 hashing
• Tier-based rate limiting (Free/Starter/Pro/Enterprise)
• Standardized JSON response envelope (data, meta, error)
• Rate limit headers (X-RateLimit-*) and request tracing (X-Request-Id)
• Free trial mode: 25 calls / 3 days
• Health endpoint at /api/v1/health
• Key rotation and admin revocation

View full changelog → | RSS Feed