Authentication
Every endpoint (other than key creation and checkout) requires an X-API-Key header. There is no OAuth flow, no session token — treat your key like a password.
A missing or invalid key returns 401 Unauthorized.
Python SDK
Prefer typed calls over raw HTTP? Install the official Python client from PyPI. It handles the X-API-Key header, JSON parsing into typed objects, pagination, and automatic retry with back-off when you hit a 429 rate limit.
Then set your key (either pass it directly or via the BHARATSTOCK_API_KEY environment variable) and call any endpoint:
The client mirrors this reference: client.stocks, client.deals, client.screener, client.indices, client.market, plus client.search(), client.movers(), client.price_shockers(), and client.status(). Source and full docs on PyPI →
JS/TS SDK
Building in Node.js or TypeScript? Install the official JS/TS client from npm. It handles the X-API-Key header, camelCased typed responses, pagination, and automatic retry with back-off when you hit a 429 rate limit. Works in Node 18+ and modern browsers/edge runtimes (native fetch, zero runtime dependencies).
Then set your key (either pass it directly or, in Node, via the BHARATSTOCK_API_KEY environment variable) and call any endpoint:
The client mirrors this reference and the Python SDK's structure: client.stocks, client.deals, client.screener, client.indices, client.market, plus client.search(), client.movers(), client.priceShockers(), and client.status(). Source and full docs on npm →
Rate limits
Enforced per calendar day (UTC), per API key. Limits depend on your plan: 60/day on Free, 1,000/day on Starter, 5,000/day on Growth, 10,000/day on Developer, 40,000/day on Pro. Every plan has access to every endpoint — the plan governs your daily request quota and how far back you can read (see Historical data depth).
Returned with HTTP status 429. The counter resets at UTC midnight.
Usage & redistribution
Your subscription grants a limited, internal-use right: you may consume the data inside your own application or workflow and display it (or analysis derived from it) to your own end-users. You may not resell, re-serve, relicense, syndicate, or bulk-redistribute the raw data to third parties as a feed, dataset, file, or API, or use it to build a competing data-distribution product.
This is strictest for exchange-sourced data (EOD prices/OHLCV, index names and values, and bulk/block deals), which is owned by the exchanges (NSE/BSE). Redistributing that data generally requires your own direct redistribution licence from the exchange — we do not grant, and cannot pass through, any such right. If you have a redistribution or white-label use case, contact us before building on it. Full terms are in the Terms of Use.
Historical data depth
Paid plans return the full archive — over a decade of daily prices, financials, corporate actions, shareholding, and more. On the Free plan the time-series endpoints return only the most recent 1 year of history (annual financials get 2 years so you can still compare year-over-year). This applies to prices, technical indicators, index prices, financials, corporate actions, shareholding, bulk/block/insider deals, and FII/DII activity.
The window is silently clamped — a Free key requesting an older from date just receives rows from within the allowed window (no error). Upgrade to any paid plan for the complete history.
MCP server
Use BharatStock as native tools inside AI assistants (Claude Desktop, Cursor, and other MCP hosts) via our official Model Context Protocol server, published on npm as bharatstock-mcp. It wraps the same data endpoints as this API, using your API key — so your plan's limits and history depth apply exactly as they do here.
MCP is a Developer/Pro feature. The server verifies your plan on startup; Free and Starter keys are declined with an upgrade prompt.
Add it to your MCP host's config (no install needed — npx fetches it on demand):
Once connected, your assistant gets 31 tools covering the full consumer API — quotes, historical prices, financials, fundamentals, technicals, shareholding, corporate actions, bulk/block/insider deals, sector peer comparison, search, market movers, the screener, indices, FII/DII activity, and mutual-fund schemes/NAVs/returns/holdings (incl. scheme portfolios — what a scheme holds).
Optional fields: only BHARATSTOCK_API_KEY is required. You may also set BHARATSTOCK_BASE_URL in env to point at a self-hosted/staging API (defaults to the public API). Some hosts (e.g. Kiro) also accept an autoApprove array listing tool names to run without a per-call prompt — a host-specific convenience, not part of the config the key needs.
Prefer a hosted URL (for hosts that connect to a remote MCP endpoint instead of spawning a process)? Point them at https://bharatstockapi.com/v1/mcp with an Authorization: Bearer <your key> header — same Developer/Pro requirement.
Pagination
List endpoints share one envelope shape across the whole API: a data array plus a pagination object. Use the page and page_size query parameters to page through results.
Errors
Validation errors return 422 with a structured detail array. Not-found resources return 404. Everything else follows standard HTTP status codes.
NSE vs BSE data coverage
Every stock has an exchange field: "NSE" for stocks listed on NSE (including ones cross-listed on BSE too), or "BSE" for stocks listed only on BSE. The two data pipelines are now equivalent in coverage — quarterly and annual financials, sector/industry, daily prices and corporate actions are all populated for BSE-exclusive stocks as well. Quarterly financials come from BSE's integrated filing feed and are current to the latest reported quarter, same freshness as NSE. Sector/industry, which BSE's own security master doesn't expose, is backfilled by inference and populated for the large majority of BSE-exclusive stocks (it may be null where no reliable classification exists — best-effort, not guaranteed, same as NSE's own feed). Every stock response includes a data_coverage object stating this, so you can branch on it programmatically instead of inferring it from exchange:
data_coverage is a structural statement of what the pipeline can populate for that exchange, not a live check of the database — e.g. sector_industry: true means "populated where available," not "guaranteed non-null." For NSE it comes from NSE's classification feed (which covers roughly 750 of the more liquid names); for BSE-exclusive stocks it's backfilled by inference and populated for the large majority, but may still be null where no reliable classification exists.
Public data-integrity status — no API key required. Reports whether our daily automated checks are currently passing: freshness (each feed current to its real publication cadence) and correctness (every derived value recomputed from its inputs and required to agree, e.g. P/E = price ÷ TTM EPS, adjusted close = close × factor). This is the same data behind the human-friendly status page.
Values: status is operational, degraded, or unknown (not yet verified). Each check reports a plain-English label, a category (Freshness / Completeness / Correctness), and a status. Unauthenticated and safe to poll.
List all stocks, paginated and optionally filtered by search text or sector.
| Param | Type | Description |
|---|---|---|
| page | int | Page number. Default 1. |
| page_size | int | Rows per page, max 200. Default 50. |
| q optional | string | Search by symbol or company name. |
| sector optional | string | Filter by exact sector name, e.g. "Financial Services". |
| active_only | bool | Exclude delisted stocks. Default true. |
Company info plus the latest available EOD price for a ticker.
| Param | Type | Description |
|---|---|---|
| exchange optional | string | NSE or BSE. Only needed to disambiguate a ticker shared by two different companies across exchanges (see note below). Defaults to the NSE listing. |
Unknown ticker returns 404.
Historical daily prices, optionally bounded by date range. Includes a bonus/split-adjusted close so charts don't show a fake jump on an ex-date.
| Param | Type | Description |
|---|---|---|
| from optional | date | Start date, e.g. 2026-01-01. |
| to optional | date | End date. |
| page, page_size | int | Standard pagination, most recent first. |
Adjusted vs raw: volume, close, and turnover are raw as-traded values — not adjusted for splits or bonuses. The only adjusted field is adjusted_close (= close × adjustment_factor), which restates the close across bonus and split actions so a long series is comparable; rights issues and dividends are not reflected. If you need split/bonus-consistent volume, adjust it yourself using the corporate-actions endpoint.
Latest price snapshot for multiple tickers in one call — built for watchlists and dashboards. Unknown symbols come back with found: false instead of failing the whole request.
| Param | Type | Description |
|---|---|---|
| symbols | string | Comma-separated tickers, e.g. RELIANCE,TCS,INFY. Max 50. |
Quarterly or annual P&L, balance sheet, and cash flow, normalized from official company financial disclosures — including bank/NBFC statement formats and consolidated-vs-standalone reporting. Annual rows also expose other_equity (Ind-AS reserves + retained earnings, for the Altman Z-score) and capex (purchase of PPE + intangibles, so Free Cash Flow = cash_flow_operating − capex).
| Param | Type | Description |
|---|---|---|
| period_type | string | quarterly or annual. Default quarterly. |
| page, page_size | int | Standard pagination, most recent period first. |
The example above is trimmed for brevity. Each period row carries the full set of statement fields below (any line a company did not disclose in that filing comes back null, never a fabricated 0).
| Field group | Fields |
|---|---|
| P&L | revenue, other_income, total_income, cost_of_materials_consumed, purchases_of_stock_in_trade, employee_benefit_expense, finance_costs, depreciation_and_amortisation, other_expenses, total_expenses, operating_profit, ebitda, exceptional_items, profit_before_tax, tax_expense, net_profit, net_profit_attributable_to_owners, net_profit_attributable_to_minority_interest, eps, diluted_eps (both as filed for that period), eps_adjusted, diluted_eps_adjusted (restated onto today's share count: eps ÷ eps_adjustment_factor, where eps_adjustment_factor is the cumulative share multiplier of every bonus/split after the period, e.g. 5.0 for a 4:1 bonus; 1.0 = no later bonus/split), pe_ratio (historical, period-end price ÷ TTM EPS), face_value_per_share, debt_equity_ratio, changes_in_inventories (change in FG/WIP/stock-in-trade), debt_service_coverage_ratio, interest_service_coverage_ratio (coverage ratios as-filed). |
| Balance sheet see note | total_assets, non_current_assets, current_assets, property_plant_equipment, inventories, trade_receivables_current, cash_and_cash_equivalents, total_equity, equity_attributable_to_owners, minority_interest_balance, other_equity, total_liabilities, non_current_liabilities, current_liabilities, borrowings_non_current, borrowings_current, trade_payables_current, goodwill, other_intangible_assets, capital_work_in_progress, investment_property, current_investments, noncurrent_investments, provisions_current, provisions_noncurrent, deferred_tax_assets_net, deferred_tax_liabilities_net. |
| Cash flow annual only | cash_flow_operating, cash_flow_investing, cash_flow_financing, net_change_in_cash, capex (Free Cash Flow = cash_flow_operating − capex), lease_payments_financing (lease-liability principal repaid). |
| Segments | segment_revenue, segment_results (arrays of per-segment rows, when the company reports segment-wise), plus segment_results_total — the filing's own segment total, the reconciliation anchor the per-segment results roll up toward profit before interest and tax (a separate scalar, so summing segment_results never double-counts). As-filed. |
| Notes see note | segment_notes, results_notes — the as-filed narrative note blocks from the filing (verbatim). The segment note is where the unallocated / elimination / exceptional reconciliation detail is published in prose. Populated mainly for recent filings that include these notes; null where the filing has none, including most older periods. |
Coverage note. Annual P&L starts at FY2014-15 (FY2017-18 annual rows are largely missing), and covers essentially all listed companies from FY2022-23. Annual balance-sheet fields are populated from FY2022-23 for essentially all companies, and for some companies from FY2018-19; earlier years are null. Annual cash flow is populated from FY2021-22. On quarterly rows the balance sheet appears on the half-year rows (30 Sep and 31 Mar), and cash flow is null: pass period_type=annual for cash flow. Coverage varies by company, so check the company you need.
Bank / NBFC fields. For banks and NBFCs, each period row also carries the sector-specific line items from the banking filing (all in rupees except the percentages/ratios). A value is null when the company did not disclose it in that filing — some banks (e.g. HDFC Bank, SBI) report NPA and capital-adequacy through a separate regulatory return and file them as absent here, so those fields come back null rather than a misleading 0.
| Field | Description |
|---|---|
deposits, advances | Total deposits and advances (₹). |
gross_npa, net_npa | Gross and net non-performing assets (₹). |
gross_npa_pct, net_npa_pct | Gross and net NPA as a percentage. |
interest_earned, interest_expended | Interest income and interest expense (₹). |
cet1_ratio | Basel III Common Equity Tier 1 (CET1) capital-adequacy ratio (%). |
additional_tier1_ratio | Additional Tier 1 (AT1) capital-adequacy ratio — the add-on above CET1 (%). |
tier1_ratio | Total Tier 1 capital-adequacy ratio = CET1 + AT1 (%). |
return_on_assets | Return on assets (%). |
provisions_and_contingencies | Provisions other than tax & contingencies (₹). |
operating_profit_pre_provision | Operating profit before provisions & contingencies (₹). |
operating_expenses | Operating expenses (₹). |
net_interest_income | Derived: interest earned − interest expended (₹). |
net_interest_margin_pct | Derived: net interest income ÷ advances (%). |
credit_cost_pct | Derived: provisions ÷ advances (%). |
cost_to_income_pct | Derived: operating expenses ÷ (net interest income + other income) (%). |
deposit_growth_yoy_pct, advances_growth_yoy_pct | Derived: year-on-year growth vs the same period one year earlier (%). |
Insurer fields. For insurers, each period row also carries gross_premium_income, net_premium_income, investment_income, claims_incurred, underwriting_profit, premium_earned, gross_premium_written, net_premium_written, policyholder_surplus, net_commission, operating_expenses_related_to_insurance and premium_deficiency (₹; premium_deficiency is the general-insurer reserve movement that completes the underwriting bridge: premium_earned − claims_incurred − net_commission − operating_expenses_related_to_insurance − premium_deficiency = underwriting_profit). investment_income is the insurance revenue-account net investment-income line (for a life insurer, the large line between net premium (revenue) + other_income and the grand total_income). claims_incurred is incurred claims for a general insurer and benefits paid for a life insurer; underwriting_profit, premium_earned, premium written, net_commission and operating_expenses_related_to_insurance are general-insurer lines (the last two bridge premium_earned − claims_incurred to underwriting_profit), while policyholder_surplus is a life-insurer line — a field is null on the taxonomy that doesn't file it. (VNB margin, combined ratio and solvency are disclosed only in investor presentations, not the regulatory filing, so they are not available.)
General-insurer balance sheet. A general insurer files its balance sheet under the IRDAI "Sources / Application of Funds" form, which is not comparable to an Ind-AS balance sheet. For that reason total_assets, total_equity, current_assets and current_liabilities are returned as null for general insurers (serving them as Ind-AS fields would be misleading); the as-filed premium, claims, underwriting and expense lines above are served normally. Life insurers' balance-sheet fields are unaffected.
NBFC fields. For NBFCs, each period row also carries fees_and_commission_income, dividend_income and impairment_on_financial_instruments (₹) — the last is the Ind-AS credit-cost / provision line. (NPA, advances and capital-adequacy ratios are filed only under the banking schedule, so they are not available for NBFCs that file under Ind-AS.)
Statement format. Each period row carries statement_format — one of bank, nbfc, insurer or commercial — identifying the as-filed accounting schedule the row follows, so you can tell which sector-specific line block to expect without inferring it from which fields are populated. It is always set (commercial for an ordinary non-financial company).
Reported date. Each period row carries filed_date (YYYY-MM-DD) — the date the period's results were first filed with the exchange, i.e. the original release date for point-in-time and event-study work. A later revised or re-filed copy of the same results does not move it. It is null when the exchange feeds do not give a reliable date for that period (for example some yfinance-sourced periods).
Non-March (e.g. December) year-end companies. For a company whose fiscal year does not end in March (several India arms of global MNCs end 31 December), the quarter and fiscal_year labels follow that company's own fiscal calendar — its October–December quarter is Q4 and its fiscal year is labelled by the calendar year (e.g. 2025). Its audited full-year row is served as an annual period ending on its own year-end date.
NSE SME (EMERGE) stocks. SME-platform companies are covered for end-of-day prices and identity on the standard endpoints, but their financials are filed half-yearly and are not published in the machine-readable regulatory feed — so financials (and the ratios derived from them) are typically empty for SME tickers.
Valuation and profitability ratios, computed on read from the latest price and the latest annual filing (falling back to quarterly if no annual filing exists yet).
SMA, EMA, RSI, and MACD, computed server-side from daily closes. Values are null wherever there isn't enough price history yet to compute them.
| Param | Type | Description |
|---|---|---|
| sma_period | int | Default 20. |
| ema_period | int | Default 20. |
| rsi_period | int | Default 14 (Wilder's smoothing). |
| from, to optional | date | Bound the returned window. |
Dividends, bonus issues, splits, and rights issues for a ticker, most recent ex-date first.
| Param | Type | Description |
|---|---|---|
| action_type optional | string | dividend, bonus, split, rights, buyback, or other. |
Monthly mutual fund holdings — which MF schemes hold this stock, their position size in crores, percentage of AUM, and month-over-month quantity change. Paginated, sorted by market value descending.
Source: compiled from the fund houses' own official monthly portfolio disclosures — pulled directly from 44+ AMCs' sites (first-party) for the houses we cover, with an aggregator filling any remaining houses. First-party AMC data is authoritative where available.
| Param | Type | Description |
|---|---|---|
| page | int | Page number (default 1). |
| page_size | int | Items per page, 1-100 (default 20). |
| month | string | Optional. Filter by month in YYYY-MM format (e.g. 2026-06). Defaults to latest available. |
Compare valuation and profitability ratios across every active stock in a sector — computed in bulk rather than looping the single-ticker ratios endpoint.
| Param | Type | Description |
|---|---|---|
| sector | string | Exact sector name, e.g. "Financial Services". |
| sort | string | market_cap, pe_ratio, pb_ratio, roe, or roce. Default market_cap. |
| limit | int | Max 100. Default 20. |
Bulk deals for a ticker — single-day trades where one client traded more than 0.5% of the company's listed equity. Most recent first.
| Param | Type | Description |
|---|---|---|
| buy_sell | string | Optional. Filter by BUY or SELL only. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
| exchange | string | Optional. NSE or BSE to disambiguate shared tickers. |
Block deals for a ticker — large trades executed in the exchange's dedicated block-deal window (minimum ticket size ~₹10 Cr). Same parameters and shape as bulk deals.
| Param | Type | Description |
|---|---|---|
| buy_sell | string | Optional. BUY or SELL. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
| exchange | string | Optional. NSE or BSE. |
Insider / promoter (SEBI PIT) disclosures for a ticker — filed when promoters, directors, or KMPs buy or sell above the regulatory threshold. Strong "smart money" signal.
| Param | Type | Description |
|---|---|---|
| transaction_type | string | Optional. acquisition or disposal. |
| promoters_only | bool | Optional. true to see only promoter/promoter-group disclosures. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
| exchange | string | Optional. NSE or BSE. |
Recent bulk deals across all stocks, most recent first. Includes symbol and company_name in each row. Cached.
| Param | Type | Description |
|---|---|---|
| buy_sell | string | Optional. BUY or SELL. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
Recent block deals across all stocks, most recent first. Same response shape as /v1/deals/bulk.
| Param | Type | Description |
|---|---|---|
| buy_sell | string | Optional. BUY or SELL. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
Recent insider/promoter disclosures across all stocks. Includes symbol, company_name, and all fields from the per-ticker endpoint. Useful for scanning "who's been buying" market-wide.
| Param | Type | Description |
|---|---|---|
| transaction_type | string | Optional. acquisition or disposal. |
| promoters_only | bool | Optional. true for promoter-only. |
| page | int | Default 1. |
| page_size | int | Max 200. Default 50. |
Top gainers, losers, or most-active-by-volume stocks for the most recent trading day with price data. Uses the latest date present in the data, not today's calendar date, so it stays correct on weekends and holidays.
| Param | Type | Description |
|---|---|---|
| category | string | gainers, losers, or active. Default gainers. |
| limit | int | Max 100. Default 20. |
Stocks whose price moved by at least a given percent versus the previous close. Unlike /movers (always a top-N ranking), this is a threshold filter — it can return zero rows on a quiet day, or more than limit on a volatile one.
| Param | Type | Description |
|---|---|---|
| min_change_pct | float | Minimum absolute % move. Default 5.0. |
| direction | string | up, down, or both. Default both. |
| limit | int | Max 200. Default 50. |
Fuzzy search across ticker symbol and company name. Ranks exact/prefix symbol matches above substring/company-name matches, active stocks first.
| Param | Type | Description |
|---|---|---|
| q | string | Search text, e.g. "reliance". |
| limit | int | Max 50. Default 10. |
Filter and screen stocks by 72 pre-computed metrics (refreshed daily) using a generic filter syntax. Combine as many filters as needed. Returns paginated results sorted by any metric.
Pagination & sorting
| Param | Type | Description |
|---|---|---|
| page optional | int | Page number. Default 1. |
| page_size optional | int | Results per page, 1-200. Default 50. |
| sort_by optional | string | Any metric name (e.g. market_cap, pe_ratio, roe, return_1y, free_cash_flow). Default: market_cap. |
| sort_order optional | string | desc or asc. Default: desc. |
Filtering (generic syntax)
| Param | Type | Description |
|---|---|---|
| filter repeatable | string | Format: metric.operator.value. Pass multiple filter params to combine conditions (AND logic). |
| sector optional | string | Sector name (exact match), e.g. "Information Technology". |
| exchange optional | string | NSE or BSE. |
Operators
| Operator | Meaning | Example |
|---|---|---|
gt | Greater than (>) | filter=roe.gt.15 |
lt | Less than (<) | filter=pe_ratio.lt.20 |
gte | Greater than or equal (≥) | filter=promoter_holding.gte.50 |
lte | Less than or equal (≤) | filter=debt_to_equity.lte.1 |
eq | Equals (=) | filter=current_ratio.eq.2 |
Note: Response includes 72 metrics per stock. market_cap in the response is in Crores; filter=market_cap.gt.10000 also expects Crores. Metrics are refreshed daily at 9pm IST. Stocks with NULL for a filtered metric are excluded from that filter.
All 72 filterable & sortable metrics
| Category | Metrics |
|---|---|
| Price | price, high_52w, low_52w, distance_from_52w_high_pct, distance_from_52w_low_pct, avg_volume_30d, avg_delivery_pct_30d, avg_turnover_30d, price_vs_200dma_pct, price_vs_50dma_pct |
| Returns | return_1w, return_1m, return_3m, return_6m, return_1y, return_2y, return_3y, return_5y |
| Volatility | volatility_30d, volatility_365d |
| Valuation | market_cap, pe_ratio, pb_ratio, book_value_per_share, roe, roce, dividend_yield, earnings_yield, peg_ratio, ev_to_ebitda, enterprise_value, price_to_sales, shares_outstanding |
| Per-share | eps, diluted_eps, cash_per_share, revenue_per_share |
| Margins | operating_margin, net_margin, ebitda_margin |
| Absolute financials | ebitda, revenue_ttm, net_profit_ttm |
| Growth | revenue_growth_yoy, profit_growth_yoy, eps_growth_yoy, revenue_growth_qoq, net_profit_margin_qoq_change |
| Balance sheet | debt_to_equity, current_ratio, interest_coverage, total_debt, working_capital, asset_turnover, inventory_turnover, receivables_days, payables_days |
| Cash flow | cash_flow_operating, free_cash_flow, cfo_to_net_profit |
| Tax & depreciation | tax_rate, depreciation_to_revenue |
| Shareholding | promoter_holding, promoter_holding_change_qoq, fii_holding, dii_holding, mutual_funds_holding, public_holding, individuals_holding, fii_holding_change_qoq, dii_holding_change_qoq, mutual_funds_holding_change_qoq, total_shares |
Every metric above supports _gt and _lt filter suffixes. For example: pe_ratio_lt=15, fii_holding_gt=10, debt_to_equity_lt=1, return_5y_gt=100. Combine as many as needed.
Units & windows: avg_turnover_30d is the mean daily traded turnover in INR lakhs (the same per-day value exposed on /prices). avg_volume_30d and avg_delivery_pct_30d are the mean daily raw volume and delivery %. All three average a 30-calendar-day trailing window (≈ 20–22 sessions, not a fixed 30-session count), including the latest session, as an equal-weighted mean. Each metrics row carries a computed_at date (last recomputed day).
Daily aggregate FII/DII cash market activity — buy, sell, and net values in ₹ Crores. Market-wide aggregate (not per-stock). Sorted by date descending.
| Param | Type | Description |
|---|---|---|
| from optional | date | Start date (YYYY-MM-DD). Default: 30 days ago. |
| to optional | date | End date (YYYY-MM-DD). Default: today. |
| limit optional | int | Max rows (1-365). Default: 30. |
| latest optional | bool | If true, return only the single most recent day (ignores from/to/limit). |
Note: Values are in ₹ Crores. Positive fii_net/dii_net = net buying. Published after market close each trading day.
List / search mutual-fund schemes across every AMC (the industry-wide AMFI NAV universe). Each row is one AMFI scheme_code — a (scheme, plan, option) variant with its own NAV. Distinct from /v1/stocks/{ticker}/mf-holdings (which schemes hold a given stock).
Source: the scheme universe and daily NAVs come from AMFI's official industry-wide NAV feed, updated every evening — with NAV history back to 2006 (~20 years).
| Param | Type | Description |
|---|---|---|
| q optional | string | Case-insensitive substring match on scheme name. |
| amc optional | string | Filter by AMC name (substring). |
| category optional | string | Filter by AMFI category (substring), e.g. Flexi Cap. |
| plan optional | string | Direct or Regular (substring). |
| option optional | string | Growth or IDCW (substring). |
| isin optional | string | Exact match on either ISIN (growth or div-reinvest). |
| limit optional | int | Max rows (1-500). Default: 50. |
| offset optional | int | Rows to skip (pagination). Default: 0. |
One scheme's identity plus its latest NAV (with the as-of date). The path value is the AMFI scheme_code from the list endpoint.
Trailing returns computed from the scheme's NAV series (sourced from AMFI's daily feed). Sub-1-year horizons are point-to-point; 1Y and longer are annualized (CAGR). Always derived from the raw NAV — never precomputed — so they can't drift from the underlying series. Horizons without enough history are null.
Note: Percentages. For 1Y and longer the value is annualized (CAGR); for shorter horizons it's the simple point-to-point change.
List / search the mutual-fund schemes we hold monthly portfolio data for — use it to populate a scheme picker. Each row is keyed by the holdings scheme-name string, not the AMFI scheme_code. This is the inverse of /v1/stocks/{ticker}/mf-holdings (which schemes hold a given stock). Note the seam: AMFI publishes monthly portfolios at the scheme level, so holdings carry no AMFI scheme_code and no Direct/Regular distinction — they're looked up by name, distinct from the scheme_code used by /v1/mf/schemes.
Auth: requires X-API-Key.
| Param | Type | Description |
|---|---|---|
| q optional | string | Case-insensitive substring match on scheme name. |
| fund_house optional | string | Filter by fund house (substring). |
| limit optional | int | Max rows (1-200). Default: 50. |
| offset optional | int | Rows to skip (pagination). Default: 0. |
One scheme's equity portfolio for a month — the stocks it holds — with month-over-month quantity change. The path value is the holdings scheme_name string exactly as returned by /v1/mf/portfolios (not the AMFI scheme_code). This is the inverse of /v1/stocks/{ticker}/mf-holdings. An unknown scheme name returns 200 with portfolio_date: null and an empty data array (not a 404).
Auth: requires X-API-Key.
| Param | Type | Description |
|---|---|---|
| month optional | string | Portfolio month as YYYY-MM. Default: the latest available month. An invalid format returns 400. |
| page optional | int | Page number (>=1). Default: 1. |
| page_size optional | int | Rows per page (1-100). Default: 50. |
Instrument types: each row carries instrument_type so you can tell the asset classes apart — EQUITY (Indian listed share), FOREIGN_EQUITY (a non-Indian equity, e.g. a US stock, with its as-filed ISIN), DEBT (bonds / g-secs / SDLs / T-bills), MONEY_MARKET (CPs / CDs / TREPS / repo), CASH (cash & net current assets), MUTUAL_FUND_UNIT (units of another fund / ETF), DERIVATIVE (futures / options / arbitrage), COMMODITY (physical gold / silver bars held by a gold or silver ETF), OTHER. Non-equity & foreign rows have symbol: null (they aren't in our Indian-equity universe) and are identified by company_name + isin; some cash / NCA / derivative lines carry no ISIN.
Sector & industry: every stock-matched EQUITY row carries sector and industry — BharatStock's own classification of the stock, identical for every fund house. They are null for rows that are not a stock in our universe (foreign equity, debt, cash, derivatives, fund units).
Coverage: coverage_pct is the total % of AUM captured for this scheme/month, summed across the whole month (not just the current page). Holdings now span every instrument class (equity, foreign equity, debt, money market, cash, derivatives, fund units), so for a recent month of a covered scheme this sums to ~100. A value materially below 100 flags a genuinely uncaptured line that month. null when there are no holdings.
Restatements: restated_on is the date this month's holdings block was re-ingested after its initial load (null if never restated). It lets you tell a restated month from a stable one — if you compare a month fetched earlier against the same month fetched later and the figures differ, a non-null restated_on confirms the change is a restatement, not real portfolio movement.
Free tier: history is limited to a recent window; a month older than the floor clamps to an empty data array. Paid plans return the full archive.
MF data scope — what's covered and what isn't: our mutual-fund data is built on AMFI's two public feeds (the daily NAV file and the monthly portfolio disclosures). Per scheme we provide: identity (name, AMC, plan, option, ISINs), category, daily NAV + full NAV history, trailing returns computed from NAV, and the monthly stock-level holdings above (quantity, market value, % of AUM, month-over-month change). We do not currently provide fund manager, expense ratio, benchmark (or benchmark history), riskometer, exit load, scheme-level AUM in rupees, or net flows — those come from scheme SID/SAI documents, factsheets or a licensed vendor we don't ingest, and are not on the near-term roadmap. (We don't store a scheme's total AUM, but each holding row carries its pct_of_aum.)
List all tracked NSE indices, paginated and optionally filtered by category (e.g. broad-market vs. sectoral).
| Param | Type | Description |
|---|---|---|
| category optional | string | e.g. "BROAD MARKET INDICES", "SECTORAL INDICES". |
Historical daily EOD levels for an index, optionally bounded by date range.
Changelog
Notable changes to the REST API, the MCP server and the official SDKs (Python bharatstock on PyPI, JavaScript/TypeScript bharatstock on npm). The REST API is additive and backward compatible: new fields are added, existing fields keep their meaning. SDK 0.1.11 and later pass new response fields through automatically (.raw in Python, camelCased in JS), so an API-only addition does not need an SDK release.
REST API
- 2026-11-17 — Data corrections:
paid_up_equity_capitalwas stored as a share count instead of rupees for about 27 small caps (so market cap, rank, book value per share and P/B read about 10x too low); single reporting periods filed on the wrong scale (for example IRCTC Sep-2022 and NAVNETEDUL Mar-2026 quarterly figures) were restored; and mutual fund overnight, liquid and money-market funds (Axis, Baroda BNP Paribas, Choice, Canara Robeco, Groww, HSBC, Edelweiss, Bajaj Finserv, Mahindra Manulife, Bank of India, 360 ONE) now carry every repo/TREPS line so their weights sum to about 100%. - 2026-11-16 —
/v1/stocks/{ticker}/financials: HDFC Bank consolidated rows for Mar-2024, Sep-2024, Sep-2025, Mar-2026 and Sep-2026 (and the FY2023-24 and FY2025-26 annual rows) now carry the minority-interest share of profit stated in the filing, withnet_profit,profit_before_tax,operating_profitandebitdaon the same pre-minority basis as the other quarters. These values previously read 0 and were understated by the minority share. - 2026-11-16 —
/v1/stocks/{ticker}/financials: corrected the coverage note. Annual balance sheets are available from FY2022-23 (some companies from FY2018-19) and annual cash flow from FY2021-22, earlier than the FY2024-25 previously stated. Annual P&L starts at FY2014-15. No data changed. - 2026-11-15 —
/v1/stocks/{ticker}/financials:results_notesandsegment_notesare now returned as single-line text, with<br />tags, line breaks and padding whitespace removed. The wording and numbers are unchanged. - 2026-11-14 —
/v1/stocks/{ticker}/financials: newfiled_dateon every period, the date the period's results were first filed with the exchange. A later revised copy does not move it. null where the feeds give no reliable date. - 2026-11-13 —
/v1/stocks/{ticker}/financials: neweps_adjusted,diluted_eps_adjustedandeps_adjustment_factor, restating EPS onto today's share count for every later bonus/split. As-filedepsanddiluted_epsare unchanged. Also, a bonus or split reported by both NSE and BSE is now counted once in price and EPS adjustment, and a daily job re-checks stocks with an unexplained price cliff for a missed bonus/split. - 2026-11-13 — Mutual fund holdings: physical gold/silver bar lines now carry instrument type
COMMODITY(previously dropped or mistyped), and renamed schemes (HSBC, Baroda BNP Paribas, ELSS, Gold FoF) are folded onto one scheme name. - 2026-11-04 — Adjusted prices: split/bonus adjustment now classifies each pre-event row's scale individually, fixing unadjusted bonus events (for example LICI 1:1) and isolated spikes in 52-week highs.
- 2026-11-03 — Financials (banks):
tier1_rationow means total Tier 1 (CET1 + Additional Tier 1). Newadditional_tier1_ratio. Rows where diluted EPS exceeded basic EPS (impossible under Ind AS 33) were corrected, and stray wrongface_value_per_sharevalues were repaired. - 2026-11-02 — Financials: new as-filed
segment_results_total,segment_notesandresults_notesper period (SDK 0.1.12). - 2026-10-28 — Financials: Dec/Jun/Sep year-end companies now get their audited annual row, and
quarter/fiscal_yearlabels follow each company's own fiscal year-end. Newstatement_format(bank/nbfc/insurer/commercial) and general-insurerpremium_deficiency. - 2026-10-26 —
/v1/mf/portfolios/{scheme}/holdings: newrestated_on(set when a month was re-ingested after its first load). Cash lines for UTI, Franklin and PPFAS are now captured so scheme weights sum to about 100%, and fund units/ETFs are typedMUTUAL_FUND_UNIT. - 2026-10-15 — Financials: insurer lines (
investment_income,claims_incurred,underwriting_profit,premium_earned, gross/net premium written,policyholder_surplus) and NBFC lines (fees_and_commission_income,dividend_income,impairment_on_financial_instruments). Insurer paid-up capital, cash and annual EPS are no longer null. - 2026-10-11 — Financials: 14 Ind-AS statement lines (goodwill, intangibles, capital work in progress, investment property, current/non-current investments, provisions, net deferred tax,
changes_in_inventories, lease payments, debt and interest service coverage ratios). - 2026-10-07 —
GET /v1/mf/portfoliosis served from a precomputed summary, removing multi-second responses. - 2026-11-14 — Mutual fund holdings: margin-for-derivatives lines are typed as cash, UTI debt/money-market rows and negative net-current-assets weights are parsed, Sundaram's second monthly workbook is read, and more renamed schemes are folded onto their current name.
- 2026-11-13 — Financials: when a filer copies the continuing-operations EPS into the discontinued field (doubling the combined figure) or mis-files basic vs diluted, the stored
eps/diluted_epsnow use the figure that reconciles with profit and share count. Re-ingesting an old filing no longer undoes a corrected value. - 2026-11-11 — Stock profile
face_valueis no longer overwritten by a stale exchange list value that the company's own filings contradict. - 2026-11-08 — Financials:
net_profit_attributable_to_ownersis restored tonet_profit − minority interestwhere a filer mis-filed it (a zero or a wrong figure). Missingpaid_up_equity_capitalis filled from a same-face neighbouring period where provable. Annual rows pick the full-yearis_auditedcontext. - 2026-11-07 — Financials: six-month cumulative figures mislabelled as a standalone quarter were removed (COALINDIA, ONESOURCE 2026-09-30). Face-value splits written in NSE's abbreviated "Fv Spl" form are now recognised, so price adjustment and pre-split face values are correct.
- 2026-11-06 — Financials: bank
cet1_ratiovalues filed about 100× too small were corrected. Mutual fund holdings: stock futures that quant now files under the underlying ISIN are stored as derivatives, so scheme weights return to 100%, and ICICI subtotal double-counts and fragmented scheme names (Wealth Company) were fixed. - 2026-11-04 — Financials: EPS-anchored ×10/×100 scale slips (for example MARKSANS FY25 revenue) are corrected at ingest and in stored rows.
- 2026-11-02 — Financials: ×100 source scale slips are now prevented at ingest, and an EPS sign that contradicted net profit was corrected. Stock metrics: a return window the price series does not span (a newly listed stock) is now null. Face-value splits written "To Re N" are parsed, fixing price adjustment. Reissued-ISIN duplicate stocks were merged.
- 2026-11-01 — Mutual fund holdings: Franklin legacy coverage inflated by NAV-footer rows and defaulted-bond placeholders was fixed (for example Franklin Short Term Income 284.9% → 100%), four correctness checks were added, and the aggregator fallback source was repointed.
- 2026-11-01 — Financials: collapsed or zero
paid_up_equity_capitalis reconstructed daily from the SEBI share count × face value, and a falseface_value_per_shareof 0 is nulled. - 2026-10-31 — Financials:
paid_up_equity_capitalscale slips are corrected without being applied to genuine historical share-count changes (YESBANK regression fixed). - 2026-10-25 — Rate limits: each paid key's daily limit is fixed at the plan limit in force when it was issued. Later plan-limit changes apply to new keys only.
- 2026-10-10 — Free plan daily limit set to 60 requests.
Security
- 2026-11-15 — Added dependency and container image vulnerability scanning and automated monthly dependency updates. The service container now runs as a non-root user. Upgraded runtime dependencies to clear known advisories. MCP server 0.2.2 updated its dependencies (
npm audit: 0 vulnerabilities). - 2026-11-14 — Published the /security page and an RFC 9116
/.well-known/security.txt. Code and dependency scans now fail on findings instead of only reporting, and affected dependencies were updated. - 2026-11-07 — Free-tier abuse detection ignores shared cloud addresses and flags signup bursts and repeated names.
- 2026-10-31 — Admin-secret comparison is constant-time. Hardened parsing of exchange filings. Added web-security code scanning. Build workflows hardened against shell injection.
- 2026-10-11 — Ingestion from the exchanges now aborts early and reports failure when an upstream throttles, instead of silently recording empty data.
- 2026-10-07 — Resolved static-analysis and dependency-audit findings.
Plans, dashboard & website
- 2026-11-16 — /learn reorganised into tabs (API tutorials, mutual fund data, concepts, glossary). Added 13 code-first guides with Python, curl and Node.js examples.
- 2026-11-15 — Landing page security section describes the scans we run.
- 2026-11-14 — New /security page. Landing navigation spacing reworked.
- 2026-11-11 — /data-sources now lists NSE and BSE end-of-day prices and indices.
- 2026-11-10 — Dashboard: cancelling a subscription asks for a reason. Checkout is blocked, with a clear message, while a previous subscription is still being linked.
- 2026-11-09 —
/llms.txtadded for AI-agent discovery. - 2026-11-08 — Diwali pricing: Growth ₹700/month and Developer ₹1,000/month for new sign-ups. Existing subscribers keep the price and daily limit they signed up at.
- 2026-11-06 — Dashboard: dark mode toggle, including mobile.
- 2026-11-04 — Stocks directory search shows matches across all pages.
- 2026-11-03 — Product brochure page and PDF.
/learnexpanded to 100 guides. The MCP server is listed in the official MCP Registry. - 2026-11-02 — /status shows Mutual Funds in its own section (freshness and correctness checks).
- 2026-10-27 — Dashboard: Transactions tab, GST billing address, and update payment method.
- 2026-10-26 — New Growth plan between Starter and Developer for new sign-ups (Starter 1,000/day, Developer ₹1,500 at the time, Pro 40,000/day).
- 2026-10-24 — Terms updated: personal, internal model evaluation and backtesting is included on Developer and Pro with no approval step. Training or fine-tuning a model still needs a separate licence.
- 2026-10-20 — Mid-cycle plan upgrades are prorated, and the higher plan starts only after payment is confirmed.
- 2026-10-18 —
/learnguides section added. - 2026-10-17 — Dashboard Usage panel: requests by endpoint category.
MCP server (bharatstock-mcp)
- 0.2.2 (2026-11-15) — Security maintenance: updated dependencies.
npm auditreports 0 vulnerabilities. No change to the tools. - 0.2.1 (2026-11-06) — Maintenance release. No change to the tools.
- 0.1.5 (2026-11-03) — Broader listing metadata and keywords for discoverability. No tool change.
- 0.1.4 (2026-11-03) — Published to the official MCP Registry as
com.bharatstockapi/bharatstock-mcp. - 0.1.3 (2026-11-02) — Financials tool output carries the segment reconciliation fields (JS SDK 0.1.12).
- 0.1.2 (2026-10-05) — Every API field, including later additions, flows through to tool output (JS SDK 0.1.11).
- 0.1.1 (2026-09-20) — Added
list_mutual_fund_portfoliosandget_mutual_fund_portfolio_holdings. - 0.1.0 (2026-09-22) — Initial release: local stdio server and remote Streamable HTTP server, with tools for stocks, discovery, indices, market-wide data and mutual funds.
Python SDK
- 0.1.12 — Financials: three new as-filed fields per period —
segment_results_total(the filing's own segment total, the reconciliation anchor the per-segmentsegment_resultsroll up toward PBIT, as a separate scalar so summing the array never double-counts), andsegment_notes/results_notes(the narrative note blocks; the segment note carries the unallocated/elimination/exceptional reconciliation in prose). null/absent for legacy filings. - 0.1.11 — Forward-compatibility: every response keeps its full raw JSON on
.raw, so any field the API adds later is reachable (obj.raw["new_field"]/page.raw["new_field"]) with no SDK upgrade. Known fields stay typed. - 0.1.10 —
get_portfolio_holdingsnow exposescoverage_pcton the returned page: the total % of AUM captured by the scheme/month's holdings (Indian listed equities only, so it typically sums to under 100). - 0.1.9 — Added MF portfolio methods to the
MutualFundsresource:list_portfolios(scheme discovery by holdings name) andget_portfolio_holdings(a scheme's equity portfolio for a month). The inverse of per-stockmf_holdings. - 0.1.7 (2026-09-15) — Added a
Changelogproject link and this changelog page. Metadata only; no code change. - 0.1.6 (2026-09-15) — Packaging metadata:
CHANGELOG.mdshipped in the sdist. No code change. - 0.1.5 (2026-09-15) — Documentation refresh for the Mutual Funds resource (fully documented, runnable examples). No code change.
- 0.1.4 — Added the
MutualFundsresource: list/search schemes, scheme detail + latest NAV, daily NAV history (~20 years), and trailing returns (1m/3m/6m/1y/3y/5y/since-inception).
JavaScript / TypeScript SDK
- 0.1.12 — Financials: three new as-filed fields per period —
segmentResultsTotal(the filing's own segment total, the reconciliation anchor the per-segmentsegmentResultsroll up toward PBIT, as a separate scalar so summing the array never double-counts), andsegmentNotes/resultsNotes(the narrative note blocks; the segment note carries the unallocated/elimination/exceptional reconciliation in prose). null/absent for legacy filings. - 0.1.11 — Forward-compatibility: paginated responses pass through every top-level envelope field (camelCased) and every row field, so a field the API adds later appears with no SDK upgrade. Known fields stay typed.
- 0.1.10 —
getPortfolioHoldingsnow exposescoveragePcton the returned page: the total % of AUM captured by the scheme/month's holdings (Indian listed equities only, so it typically sums to under 100). - 0.1.9 — Added MF portfolio methods to the
mutualFundsresource:listPortfoliosandgetPortfolioHoldings, mirroring the Python SDK. The inverse of per-stockmfHoldings. - 0.1.8 (2026-09-15) — Added a "Jump to Changelog" link and this changelog page. Metadata only; no code change.
- 0.1.7 (2026-09-15) — Shipped a standalone
CHANGELOG.md. No code change. - 0.1.6 (2026-09-15) — Documentation refresh for the
mutualFundsresource. No code change. - 0.1.5 — Added the
mutualFundsresource:listSchemes,getScheme,nav,returns, mirroring the Python SDK.
Full per-release notes also ship inside each package (README changelog + CHANGELOG.md).