API & MCP Documentation

41 REST endpoints · 41 MCP tools · NSE/BSE data · AI agents, quant devs, algo traders.

Overview

The Finmagine API is the only programmatic gateway to Indian equity intelligence for AI agents. The real moat is not raw data — it is ECS (Earnings Catalyst Score), PEAD (post-earnings drift signals), RRG (Relative Rotation Graph sector trajectories), management tone (NLP-scored concall sentiment), conviction ranking, and concall decoder — all pre-computed and queryable in a single round-trip. Fundamentals, financials, momentum, and market breadth cover 5,000+ NSE/BSE companies and are delivered via Model Context Protocol (MCP) so AI agents can run end-to-end research workflows without writing code.

Base URL	`https://finmagine.com/api/v1`
MCP endpoint	`https://finmagine.com/api/mcp`
Format	JSON (all responses)
Auth	API key — header or query param
Versioning	URL-based (`/v1/`)

Authentication

All endpoints (except GET /status) require an API key. Three ways to pass it:

Method	Header / Parameter	Example
Header (recommended)	`X-Api-Key`	`X-Api-Key: fmk_abc123…`
Bearer token	`Authorization`	`Authorization: Bearer fmk_abc123…`
Query parameter	`?apiKey=`	`?symbol=RELIANCE&apiKey=fmk_abc123…`

Keys follow the format fmk_ + 32 hex characters. Generate a key in the portal →

Rate limits

Limits are enforced per API key, with both daily and hourly counters. Counters reset automatically — no action needed.

Tier	Requests / day	Requests / hour	Company universe
Free	50	10	25 Nifty 50 blue chips
Premium Web	500	100	Full universe
Professional Web	2,000	400	Full universe
API Pro	1,000	200	Full universe
API Max	5,000	1,000	Full universe + Screener

Rate limit status is returned in every response header:

X-RateLimit-Limit-Daily:  1000
X-RateLimit-Limit-Hourly: 200
X-RateLimit-Remaining-Daily:  847
X-RateLimit-Remaining-Hourly: 193

Response format

Every successful response is wrapped in a consistent envelope:

{
  "data": { /* endpoint payload */ },
  "meta": {
    "tier":                      "api_pro",
    "requests_remaining_today":  847,
    "requests_remaining_hour":   193,
    "timestamp":                 1748598000
  }
}

Use meta.requests_remaining_today and meta.requests_remaining_hour to implement graceful back-off in scripts before hitting HTTP 429. Both counters reset automatically — daily at midnight IST, hourly on the hour.

Error handling

All errors return a consistent JSON envelope with no data key:

{
  "error":   true,
  "status":  401,
  "message": "Invalid or missing API key."
}

Status	Meaning	What to do
400	Missing or invalid parameter	Check required params and value ranges in the endpoint reference
401	Invalid or revoked API key	Verify the `fmk_` key is correct and active in the portal
403	Tier does not have access to this endpoint	Upgrade at pricing.php — the error message names the required tier
404	Symbol or resource not found	Use `search_companies` / `GET /companies` to verify the correct NSE symbol
429	Rate limit exceeded (hourly or daily)	Read `meta.requests_remaining_hour` in responses to catch this before it happens; back off and retry after the next hour boundary
503	Database unavailable	Transient — retry with exponential back-off

Free tier symbols

Free-tier keys can only query these 25 large-cap NSE symbols. Upgrade to any paid plan for the full universe.

RELIANCE  TCS       HDFCBANK  INFY      ICICIBANK
HINDUNILVR BAJFINANCE SBILIFE  KOTAKBANK AXISBANK
ASIANPAINT LT        NESTLEIND MARUTI    TATAMOTORS
SUNPHARMA WIPRO      ONGC      NTPC      POWERGRID
COALINDIA  DIVISLAB  CIPLA     DRREDDY   TITAN

GET /status

GET /api/v1/status No auth required

Health check. Returns API version and service name.

curl https://finmagine.com/api/v1/status

GET /companies

GET /api/v1/companies All tiers

Search and filter companies. Free tier restricted to 25 symbols.

Parameter	Type	Description
q	string	Name or symbol search
sector	string	NSE sector filter
min_mcap	float	Min market cap (₹ Cr)
max_mcap	float	Max market cap (₹ Cr)
min_rs	int	Min RS rating (1–99)
limit	int	Results (default 20, max 50)
page	int	Page number (default 1)

GET /company/profile

GET /api/v1/company/profile?symbol=RELIANCE All tiers

Full fundamental profile: PE, PB, ROCE, ROE, D/E, margins, market cap, 52-week range, RS rating, EMA levels.

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/company/profile?symbol=HDFCBANK"

Response fields

symbol, company_name, sector, industry	Identity
market_cap_cr, price_cmp	Market data (₹)
pe, pb, roce, roe, de, opm_pct	Core ratios
revenue_cagr_5y, pat_cagr_5y	5-year growth CAGRs
fcf_yield, pledge_pct	Quality signals
rs_rating, rs_rank	IBD-style RS (1–99)
wk52_high, wk52_low, ema_10, ema_21	Technical levels
altman_z_score, profitable_years_10y	Risk metrics

GET /company/financials

GET /api/v1/company/financials?symbol=RELIANCE All tiers

Quarterly or annual P&L statements. Free tier: max 4 periods.

Parameter	Type	Description
symbol	string	Required. NSE ticker.
period	string	`quarterly` (default) or `annual`
limit	int	Periods to return (max 12; free tier max 4)

Response fields per period

period, sales_cr, ebitda_cr, pat_cr, opm_pct

GET /company/ratios

GET /api/v1/company/ratios?symbol=RELIANCE All tiers

Extended ratio set including FCF yield, Altman Z-score, OCF/PAT, pledge %, CAGRs.

GET /company/momentum

GET /api/v1/company/momentum?symbol=RELIANCE All tiers

RS rating, EMA crossover signals, 52-week high proximity, 30-day RS history.

Derived boolean signals

near_52wh	Price ≥ 95% of 52-week high
above_ema10	Price above 10-day EMA
above_ema21	Price above 21-day EMA
ema10_above_ema21	Short-term uptrend signal
rs_history	Array of {rating_date, rs_rating} — last 30 days

GET /market/breadth

GET /api/v1/market/breadth All tiers

Indian market breadth: last 30 trading days of advances/declines, % stocks above 10/20/40-day MA, Nifty close and daily change.

GET /market/momentum

GET /api/v1/market/momentum All tiers

Top NSE stocks ranked by RS rating. Optional sector filter. Tier-capped result count (api_max/api_pro: 50, professional_web: 30, free: 10).

Parameter	Type	Description
sector	string	Optional sector filter
limit	int	Results (tier-capped)

GET /market/sectors

GET /api/v1/market/sectors All tiers

Per-sector summary: stock count, average RS rating, top RS stock, total and average market cap.

GET /screener

GET /api/v1/screener api_max only

Multi-criteria stock screener. Returns up to 50 matches — no pagination by design (anti-scraping measure).

Parameter	Type	Description
min_roce	float	Min ROCE %
max_pe	float	Max PE (positive PE only)
min_mcap	float	Min market cap (₹ Cr)
max_mcap	float	Max market cap (₹ Cr)
min_rs	int	Min RS rating
min_roe	float	Min ROE %
max_de	float	Max debt/equity
sector	string	Sector filter
industry	string	Industry filter
sort_by	string	`market_cap_cr` \| `rs_rating` \| `roce` \| `roe` \| `opm_pct`
sort_dir	string	`desc` (default) \| `asc`

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/screener?min_roce=20&max_pe=30&min_rs=70&sort_by=rs_rating"

GET /company/ecs

GET /api/v1/company/ecs?symbol=TCS api_pro+

Earnings Catalyst Score for the latest quarter: composite post-earnings score + rank within the Nifty 500 universe + PEAD signal.

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/company/ecs?symbol=HDFCBANK"

Response fields

ecs_score	Composite score (higher = stronger post-earnings momentum)
ecs_rank	Rank within the universe for that quarter (1 = highest)
pead_signal	Boolean — true if PEAD drift detected
quarter	Quarter label e.g. "Mar 2026"

GET /company/guidance-tone

GET /api/v1/company/guidance-tone?symbol=TCS api_pro+

Management guidance tone extracted from earnings concalls: overall sentiment score, beat/miss/inline counts, and derived tone label.

⚠ Coverage: ~400 companies that publish investor presentations or concall transcripts. Returns null fields for others.

overall_tone_score	Float — positive/negative sentiment (-1 to +1)
tone_label	positive \| neutral \| negative
guidance_beat, guidance_miss, guidance_inline	Count of guidance items per outcome
positive_count, negative_count	Sentence-level sentiment counts

GET /company/order-wins

GET /api/v1/company/order-wins?symbol=LT&limit=10 api_pro+

AI-extracted order win announcements: deal value, client name, segment, and confidence level. High and medium confidence only.

⚠ Coverage: ~300 companies that regularly file order-win announcements with NSE. Returns an empty array for others — not an error.

Parameter	Type	Description
symbol	string	Required. NSE ticker.
limit	int	Results (default 10, max 25)

GET /company/insider-trades

GET /api/v1/company/insider-trades?symbol=RELIANCE&days=90&type=buy api_pro+

Promoter and director buy/sell transactions with trade value, shares, and % holding change.

⚠ Filing lag: NSE Form D disclosures typically arrive 1–10 business days after the trade. Very recent trades may not appear yet.

Parameter	Type	Description
symbol	string	Required. NSE ticker.
days	int	Look-back days (default 90, max 365)
type	string	buy \| sell \| all (default: all)

GET /company/banking-kpis

GET /api/v1/company/banking-kpis?symbol=HDFCBANK api_pro+

Banking sector KPIs from investor presentations: NIM, GNPA%, NNPA%, CASA ratio, credit growth. Returns an empty array for non-banking companies (no error). Multiple periods returned as a reverse-chronological array — newest quarter first.

nim_pct	Net Interest Margin %
gnpa_pct, nnpa_pct	Gross / Net NPA %
casa_ratio	CASA deposit ratio %
credit_growth_pct	Loan book growth YoY %

GET /company/pead

GET /api/v1/company/pead?symbol=RELIANCE api_pro+

Post-Earnings Announcement Drift events for a single company: volume surge ratio, price change on event day, and drift at 5/10/20 days.

⚠ Signal note: Thinly traded small-caps may show elevated false-positive rates due to low volume baseline. Signal window is 45 days post-earnings.

GET /company/conglomerate

GET /api/v1/company/conglomerate?symbol=TCS api_pro+

Returns the Indian business group this company belongs to (Tata, Adani, Reliance, Bajaj, etc.) with live fundamentals for all group members. Returns 404 if not in a tracked group.

group_id, group_name	Business group identifier and display name
members	Array of group companies with price, RS, market cap

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/company/conglomerate?symbol=TITAN"

GET /company/pledge-history

GET /api/v1/company/pledge-history?symbol=ADANIENT api_pro+

Promoter pledging history: last 12 quarters of pledge % as a share of promoter holding and total shares outstanding. Returned as a reverse-chronological array — newest quarter first.

promoter_holding_pct	Promoter % of total shares
pledged_pct_of_promoter	Pledged shares as % of promoter holding
pledged_pct_of_total	Pledged shares as % of total equity

GET /market/ecs

GET /api/v1/market/ecs?limit=25 api_pro+

ECS leaderboard: top NSE stocks by Earnings Catalyst Score for the latest (or specified) earnings quarter.

Parameter	Type	Description
quarter	string	e.g. "Mar 2026" (default: auto-detect latest)
limit	int	Results (default 25, max 50)

GET /market/conviction

GET /api/v1/market/conviction?min_matches=3&limit=25 api_pro+

High-conviction stocks appearing across multiple screener presets simultaneously. More appearances = stronger multi-factor confluence.

Parameter	Type	Description
min_matches	int	Minimum preset count (default 3, max 5)
sector	string	Optional sector filter
limit	int	Results (default 25, max 50)

match_count	Number of presets this stock appears in
matched_presets	Array of preset names (e.g. stage2, vcp, near52wh)

GET /market/pead

GET /api/v1/market/pead?limit=25 api_pro+

Current PEAD candidates: stocks with confirmed volume surges and price drift signals in the last 45 days.

⚠ Signal note: Thinly traded small-caps may produce false positives. Best used on Nifty 500 universe stocks.

Parameter	Type	Description
limit	int	Results (default 25, max 50)

GET /market/rrg

GET /api/v1/market/rrg?as_of=1m api_pro+

Relative Rotation Graph data for all 18 NSE sectors: RS-Ratio and RS-Momentum relative to Nifty 500, with quadrant classification.

Parameter	Type	Description
as_of	string	`1m` for 1-month snapshot, `YYYY-MM-DD` for specific date, omit for latest

rs_ratio	Relative strength vs benchmark (>100 = outperforming)
rs_momentum	Rate of change of RS-Ratio (>100 = accelerating)
quadrant	leading \| weakening \| lagging \| improving

GET /market/industry-stages

GET /api/v1/market/industry-stages api_pro+

Stage 1–4 (Weinstein) classification for all NSE industries as of the latest computation. Stage 2 = accumulation/uptrend — the highest-probability entry environment.

stage	1 (base) \| 2 (advancing) \| 3 (top) \| 4 (declining)
score	Composite score driving stage classification
avg_rs, avg_ret_1m, avg_pct_from_52wh	Industry aggregate signals
stock_count	Number of stocks in this industry

GET /market/rs-changes

GET /api/v1/market/rs-changes?days=10&min_delta=15&direction=gainers api_pro+

RS velocity — stocks whose Relative Strength rating changed most over the look-back window. Useful for detecting early momentum acceleration before price breaks out.

Parameter	Type	Description
days	int	Look-back window (default 10, max 30)
direction	string	gainers \| losers \| all (default: gainers)
min_delta	int	Minimum RS points moved (default 15)
sector	string	Optional sector filter
limit	int	Results (default 25, max 50)

rs_current, rs_previous	RS rating at latest and N-days-ago dates
rs_delta	Change (positive = gaining momentum)

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/market/rs-changes?days=7&min_delta=20&direction=gainers&limit=20"

GET /feeds/order-wins

GET /api/v1/feeds/order-wins?days=30&confidence=high api_pro+

Cross-company order win announcements feed: AI-extracted deal value, client, segment. Hard cap 50 results — no pagination by design (anti-scraping measure).

⚠ Coverage: ~300 companies that file order-win announcements with NSE. Infrastructure, defence, and capital goods sectors have the best coverage.

Parameter	Type	Description
days	int	Look-back days (default 30, max 90)
confidence	string	high \| medium \| all (default: all high+medium)
sector	string	Optional sector filter
limit	int	Results (default 25, max 50)

GET /feeds/insider

GET /api/v1/feeds/insider?days=30&type=buy&min_value_cr=1 api_pro+

Cross-company insider trading activity feed. Hard cap 50 results — no pagination by design (anti-scraping measure).

⚠ Filing lag: NSE Form D disclosures typically arrive 1–10 business days after the trade. Recent trades may be incomplete.

Parameter	Type	Description
days	int	Look-back days (default 30, max 90)
type	string	buy \| sell \| all (default: all)
min_value_cr	float	Minimum deal value in ₹ Crores (default 0)
sector	string	Optional sector filter
limit	int	Results (default 25, max 50)

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/feeds/insider?type=buy&min_value_cr=5&days=14"

GET /feeds/bulk-block-deals

GET /api/v1/feeds/bulk-block-deals?days=14&deal_type=block api_pro+

Bulk and block deal transactions on NSE: institutional buy/sell activity with client names and deal values. Hard cap 50 results — no pagination by design (anti-scraping measure).

Parameter	Type	Description
days	int	Look-back days (default 14, max 90)
deal_type	string	bulk \| block \| all (default: all)
sector	string	Optional sector filter
limit	int	Results (default 25, max 50)

GET /feeds/circuit

GET /api/v1/feeds/circuit?direction=upper&date=2026-05-30 Free tier

Stocks that hit upper or lower circuit limits on a given date, ordered by RS rating. Hard cap 200 results.

Parameter	Type	Description
direction	string	upper \| lower \| all (default: all)
date	string	YYYY-MM-DD (default: today)

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/feeds/circuit?direction=upper"

GET /company/daily-prices

GET /api/v1/company/daily-prices?symbol=RELIANCE&limit=60 api_pro+

Daily OHLCV price history from nse_delivery: open, high, low, close, volume, delivery quantity and delivery %. Hard cap 365 rows.

Parameter	Type	Description
symbol	string	NSE ticker (required)
from	string	Start date YYYY-MM-DD (optional)
to	string	End date YYYY-MM-DD (default: today)
limit	int	Max rows 1-365 (default: 60)

GET /company/shareholding

GET /api/v1/company/shareholding?symbol=RELIANCE&periods=8 api_pro+

Quarterly promoter/FII/DII/public shareholding pattern history including pledged %. Max 16 periods, sorted newest-first.

Parameter	Type	Description
symbol	string	NSE ticker (required)
periods	int	Quarters to return 1-16 (default: 8)

GET /company/corporate-actions

GET /api/v1/company/corporate-actions?symbol=RELIANCE&action_type=split api_pro+

Historical corporate actions for a stock: stock splits, bonuses, rights issues, buybacks. Returns ex-date, record date, and ratio.

Parameter	Type	Description
symbol	string	NSE ticker (required)
action_type	string	split \| bonus \| rights \| buyback \| merger \| other \| all (default: all)
limit	int	Max rows 1-20 (default: 10)

GET /market/index-constituents

GET /api/v1/market/index-constituents?index=NIFTY+50 Free tier

All stocks in a named NSE index with company name, sector, market cap, RS rating, and price. Omit index to list all available indices.

Parameter	Type	Description
index	string	Index name e.g. "NIFTY 50", "NIFTY 500", "NIFTY MIDCAP 150" (omit to list all)

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/market/index-constituents?index=NIFTY+50"

GET /market/top-movers

GET /api/v1/market/top-movers?direction=gainers&limit=20 Free tier

Daily top gainers or losers by day-over-day % change (prev close → today close). Returns symbol, company, sector, RS rating, close, prev_close, pct_change, and volume.

Parameter	Type	Description
direction	string	gainers \| losers \| all (default: gainers)
date	string	Trading date YYYY-MM-DD (default: latest in DB)
min_mcap	float	Min market cap in Cr (optional)
limit	int	Max results 1-25 (default: 20)

curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/market/top-movers?direction=gainers&limit=10"

GET /feeds/corporate-actions

GET /api/v1/feeds/corporate-actions?action_type=split&days=30 api_pro+

Recent corporate actions across all NSE companies within a look-back window. Useful for screening upcoming split and bonus ex-dates.

⚠ Timing: Updated from NSE bhavcopy after market close. Same-day announcements may not appear until the following morning.

Parameter	Type	Description
action_type	string	split \| bonus \| rights \| buyback \| merger \| other \| all (default: all)
days	int	Look-back window in days (default: 30, max: 90)
limit	int	Results (default: 25, max: 50)

GET /company/ai-summary

GET /api/v1/company/ai-summary?symbol=RELIANCE&period=Mar+2026 api_max

AI-generated quarterly earnings summary (DeepSeek, 703 companies). Returns structured JSON with headline, verdict, and key insights. Omit ?period for the latest available quarter.

⚠ Coverage: 703 companies for Mar 2026. Earlier quarters have lower coverage (~400 companies). Returns 404 if no summary exists for the requested period.

Parameter	Type	Description
symbol	string	NSE symbol (required)
period	string	Quarter label e.g. "Mar 2026" (optional, default: latest)

GET /company/management-tone

GET /api/v1/company/management-tone?symbol=HDFCBANK api_pro+

Full AI management tone analysis: guidance_score (0–100), tone_trajectory across quarters, phrase_drift (language shift signals), investor_lens (analyst perception), and quarters analysed. More detailed than /company/guidance-tone which returns score only.

⚠ Coverage: ~400 companies that publish concall transcripts with NSE. Returns empty data object for others — not an error.

Parameter	Type	Description
symbol	string	NSE symbol (required)

GET /company/sector-kpis

GET /api/v1/company/sector-kpis?symbol=ULTRACEMCO api_pro+

Sector-specific operational KPIs extracted from investor presentations (e.g. Cement: capacity, volume, realization, EBITDA/tonne; Banks: NIM, GNPA, PCR). Omit ?period to get all quarters as a trend.

⚠ Coverage: ~150 companies across ~25 sectors that publish investor presentations. Returns empty array for companies that don't file presentations.

Parameter	Type	Description
symbol	string	NSE symbol (required)
period	string	Quarter label e.g. "Mar 2026" (optional, default: all quarters)

GET /company/ai-profile

GET /api/v1/company/ai-profile?symbol=RELIANCE api_max

AI-generated 10-section company profile from investor concall analysis: business model, competitive moat, management quality, growth drivers, risk factors, financial health, industry dynamics, recent developments, investment thesis, bull/bear case.

⚠ Coverage: ~400 companies. Returns 404 if no AI profile has been generated for the requested company yet.

Parameter	Type	Description
symbol	string	NSE symbol (required)
period	string	Quarter label e.g. "Mar 2026" (optional, default: latest)

GET /company/concall-decoder

GET /api/v1/company/concall-decoder?symbol=RELIANCE api_max

Structured concall decoder: multi-quarter analysis of management language, commitment tracking, guidance vs actual, and tone signals extracted from earnings call transcripts.

⚠ Coverage: ~400 companies that publish concall transcripts with NSE. Returns an error if no transcript data is available for the requested company.

Parameter	Type	Description
symbol	string	NSE symbol (required)
period	string	Quarter label e.g. "Mar 2026" (optional, default: latest)

GET /company/scorecard

GET /api/v1/company/scorecard?symbol=RELIANCE api_pro+

Pre-computed Momentum+Fundamental scorecard. Returns overall score, category, and 5 sub-scores (financial health, growth prospects, competitive position, management quality, valuation). Omit ?symbol to get top-N companies ranked by overall score.

Parameter	Type	Description
symbol	string	NSE symbol. Omit to return ranked list.
limit	int	Max companies for ranked list (default: 50, max: 100)

GET /market/breakout-conditions

GET /api/v1/market/breakout-conditions FREE

Nifty 50 EMA breakout readiness signal. Are conditions favourable for breakout trades today? Returns Nifty close vs EMA-21 and EMA-50, verdict (ABOVE_BOTH / ABOVE_21_ONLY / BELOW_BOTH), and action guidance. Add ?days=N for historical data.

Parameter	Type	Description
days	int	History depth (default: 1 = latest only, max: 90)

curl "https://finmagine.com/api/v1/market/breakout-conditions" \
  -H "X-Api-Key: fmk_YOUR_KEY"

MCP Server

The Finmagine MCP server exposes all data as tools consumable by Claude, Cursor, VS Code, and any MCP-compatible AI agent. It is the only MCP server for Indian stock market data.

MCP endpoint: https://finmagine.com/api/mcp — Streamable HTTP (JSON-RPC 2.0 over POST). Same API key required.

MCP Tool reference

All 41 tools are visible in the tools/list manifest for discovery. Access is enforced at call time — calling a pro tool on a free key returns an error in the tool result, not a transport-level error.

Tool	Equivalent REST	Tier
search_companies	GET /companies	All
get_company_profile	GET /company/profile	All
get_financials	GET /company/financials	All
get_ratios	GET /company/ratios	All
get_momentum	GET /company/momentum	All
get_market_breadth	GET /market/breadth	All
get_market_momentum	GET /market/momentum	All
screen_stocks	GET /screener	api_max
get_ecs_score	GET /company/ecs	api_pro+
get_guidance_tone	GET /company/guidance-tone	api_pro+
get_order_wins	GET /company/order-wins	api_pro+
get_insider_trades	GET /company/insider-trades	api_pro+
get_banking_kpis	GET /company/banking-kpis	api_pro+
get_company_pead	GET /company/pead	api_pro+
get_conglomerate	GET /company/conglomerate	api_pro+
get_pledge_history	GET /company/pledge-history	api_pro+
get_ecs_leaderboard	GET /market/ecs	api_pro+
get_conviction_ranking	GET /market/conviction	api_pro+
get_pead_candidates	GET /market/pead	api_pro+
get_sector_rrg	GET /market/rrg	api_pro+
get_industry_stages	GET /market/industry-stages	api_pro+
get_rs_changes	GET /market/rs-changes	api_pro+
get_order_wins_feed	GET /feeds/order-wins	api_pro+
get_insider_feed	GET /feeds/insider	api_pro+
get_bulk_block_deals	GET /feeds/bulk-block-deals	api_pro+
get_circuit_stocks	GET /feeds/circuit	All
get_corporate_actions_feed	GET /feeds/corporate-actions	api_pro+
get_daily_prices	GET /company/daily-prices	api_pro+
get_shareholding	GET /company/shareholding	api_pro+
get_corporate_actions	GET /company/corporate-actions	api_pro+
get_index_constituents	GET /market/index-constituents	All
get_top_movers	GET /market/top-movers	All
get_company_scorecard	GET /company/scorecard	api_pro+
get_breakout_conditions	GET /market/breakout-conditions	All
get_ai_quarterly_summary	GET /company/ai-summary	api_max
get_management_tone	GET /company/management-tone	api_pro+
get_sector_kpis	GET /company/sector-kpis	api_pro+
get_ai_company_profile	GET /company/ai-profile	api_max
get_concall_decoder	GET /company/concall-decoder	api_max

Add to claude.ai (web)

The claude.ai web app supports custom MCP connectors natively. No extensions or config files needed.

Step 1 — Copy your connector URL

Append your API key as a query parameter to the MCP endpoint:

https://finmagine.com/api/mcp.php?apiKey=fmk_YOUR_KEY

Replace fmk_YOUR_KEY with your actual key from the API portal. The ?apiKey= param is required — do not use the Authorization field in Advanced settings (claude.ai treats that as an OAuth client ID, not a static header).

Step 2 — Add the connector

In claude.ai, go to Settings → Connectors and click the + button, then:

Field	Value
Name	`Finmagine Market Intelligence`
Remote MCP server URL	`https://finmagine.com/api/mcp.php?apiKey=fmk_YOUR_KEY`
Advanced settings	Leave empty

Click Add. The connector should appear under Web in your connectors list and show 41 available tools.

Step 3 — Enable it in a conversation

Open a new chat. Click the tools or connectors button in the input bar and toggle Finmagine Market Intelligence on. Claude will now call the tools automatically when you ask market questions.

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "finmagine": {
      "url": "https://finmagine.com/api/mcp.php",
      "headers": {
        "X-Api-Key": "fmk_YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop. The Finmagine tools will appear in the tools panel on the left.

Sample prompts

Paste either prompt into Claude (with the Finmagine connector active).

Quick start — core tools Free

Exercises: get_market_breadth · get_market_momentum · search_companies · get_company_profile · get_financials · get_ratios · get_momentum · screen_stocks

📋 Copy and paste into Claude with Finmagine connector enabled:

I want a complete market intelligence briefing for the Indian stock market. Please do the following in sequence:

1. Market context
Get the last 20 days of market breadth data. Summarise the trend — are we in a broad advance or a selective market? Is the % of stocks above their 40-day MA expanding or contracting?

2. Momentum leaders
Pull the top 20 momentum stocks by RS rating. Which sectors are dominating? Flag any with RS rating above 85.

3. Sector hunt
Search for companies in the "Capital Goods" sector with market cap above ₹5,000 Cr and RS rating above 60.

4. Deep dive — Pick the highest RS-rated stock from step 3 and simultaneously pull:
  a. Full company profile — note PE, ROCE, debt/equity, and proximity to 52-week high
  b. Last 6 quarters of financials — is revenue and OPM% expanding or compressing?
  c. Financial ratios — flag any red flags: Altman Z-score below 1.8, pledge above 20%, or D/E above 1
  d. Momentum signals — is it above its 10 and 21 EMA? Is RS improving or deteriorating over 30 days?

5. Quality screen
Screen for stocks with ROCE ≥ 20, PE ≤ 30, RS rating ≥ 70, market cap ≥ ₹2,000 Cr. Sort by RS rating descending. List the top 10.

Finally, synthesise: given the breadth environment from step 1, would you be aggressive or selective in new positions? Which stocks from step 5 look most actionable?

📄

Sample output — real run · 30 May 2026

India Market Intelligence Briefing

Nifty 50 @ 23,548 · Regime: SELECTIVE · Target: GVT&D (RS 98, ROCE 76.4%) · Quality screen: 12 stocks · 4 pages

Open PDF →

Full-coverage workflow — all 41 tools api_max

Works when the Finmagine connector is active — Claude calls each tool in turn and narrates results. Requires an api_max key for the screener and AI content steps; the market and intel steps work on api_pro.

⚠️ Do not ask Claude to build an artifact or write code — paste this as a plain question and let the connector do the work.

📋 Copy and paste into Claude with Finmagine connector enabled:

Using your Finmagine tools, give me a complete Indian market intelligence brief. Call the tools in the order below, share what each one returns, and weave the findings together as you go.

Market setup — Start by checking whether today is a good day for breakouts (get_breakout_conditions, last 5 days). Then pull 20 days of breadth data (get_market_breadth) and tell me whether the market is broadening or narrowing on the 10-day, 20-day and 40-day MA lines. Pull today's top movers (get_top_movers) and any circuit stocks (get_circuit_stocks) — flag if any circuit name is in the Nifty 500. Finally, get the top 30 momentum stocks (get_market_momentum) and call out any with RS ≥ 90.

Sector rotation — Call get_sector_rrg and tell me which sectors are Leading, Improving, Weakening, and Lagging right now. Then pull get_industry_stages and list every industry in Stage 2. Do the Stage 2 industries match the Leading sectors? Get the Nifty 50 constituents (get_index_constituents) and show which of the 50 large-caps sit in Stage 2 industries. Lastly, call get_rs_changes and flag any stock with an RS gain above 15 points in the last 20 days.

Event flow — Check the order wins feed (get_order_wins_feed, last 14 days), insider feed (get_insider_feed, last 14 days), bulk and block deals (get_bulk_block_deals, last 7 days), and upcoming corporate actions (get_corporate_actions_feed, next 30 days). Note any promoter buying in a top-RS stock. Then pull PEAD candidates (get_pead_candidates), the ECS leaderboard (get_ecs_leaderboard, top 15), and the conviction ranking (get_conviction_ranking, top 20). Is there any stock that appears in more than one of these three lists?

Single-stock deep dive — From the conviction ranking, pick the stock with the highest RS rating that is also in a Stage 2 industry. Call it TARGET. Now call every company-level tool on TARGET and summarise what each one reveals:
get_company_profile · get_financials (8 quarters) · get_ratios · get_momentum · get_company_scorecard · get_daily_prices (90 days)
get_ecs_score · get_company_pead · get_ai_quarterly_summary (latest quarter)
get_guidance_tone · get_management_tone · get_concall_decoder · get_ai_company_profile
get_sector_kpis (last 4 quarters) · get_shareholding (last 4 quarters) · get_pledge_history · get_insider_trades
get_corporate_actions · get_order_wins · get_conglomerate
If TARGET is a bank or NBFC, also call get_banking_kpis and report NIM, GNPA, CASA trends.

Screen and shortlist — Run screen_stocks with ROCE ≥ 18, PE ≤ 40, RS ≥ 65, MCap ≥ ₹1,000 Cr, D/E ≤ 1, sorted by RS descending — top 15 results. Then call search_companies filtered to the top Leading sector from the RRG, MCap above ₹2,000 Cr.

Synthesis — Combine everything into: (1) market regime verdict — offensive, defensive, or selective? (2) three actionable ideas — one from the screener, one from the conviction ranking, one from PEAD, each with a one-sentence thesis and the key risk; (3) a Strong Buy / Buy / Hold / Avoid verdict on TARGET with the single deciding factor; (4) a five-stock watchlist — RS improving, Stage 2, with a catalyst from the corporate actions feed.

📄

Sample output — real run · 30 May 2026

India Market Intelligence Brief

Nifty 50 @ 23,548 · Regime: SELECTIVE · Target: NATIONALUM (Hold) · Best idea: NATCOPHARM · 5 pages · all 39 tools called

Open PDF →

Tools exercised: get_breakout_conditions · get_market_breadth · get_top_movers · get_circuit_stocks · get_market_momentum · get_sector_rrg · get_industry_stages · get_index_constituents · get_rs_changes · get_order_wins_feed · get_insider_feed · get_bulk_block_deals · get_corporate_actions_feed · get_pead_candidates · get_ecs_leaderboard · get_conviction_ranking · get_company_profile · get_financials · get_ratios · get_momentum · get_company_scorecard · get_daily_prices · get_ecs_score · get_company_pead · get_ai_quarterly_summary · get_guidance_tone · get_management_tone · get_concall_decoder · get_ai_company_profile · get_sector_kpis · get_shareholding · get_pledge_history · get_insider_trades · get_corporate_actions · get_order_wins · get_conglomerate · get_banking_kpis · screen_stocks · search_companies

Cursor / VS Code setup

Add to .cursor/mcp.json or your VS Code MCP settings:

{
  "servers": {
    "finmagine-markets": {
      "url": "https://finmagine.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fmk_YOUR_KEY"
      }
    }
  }
}

cURL examples

# Company profile
curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/company/profile?symbol=INFY"

# Top 20 momentum stocks in IT sector
curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/market/momentum?sector=Information+Technology&limit=20"

# Screen: ROCE>20, PE<30, RS>60, sort by RS rating
curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/screener?min_roce=20&max_pe=30&min_rs=60&sort_by=rs_rating"

# Last 10 days of market breadth
curl -H "X-Api-Key: fmk_YOUR_KEY" \
  "https://finmagine.com/api/v1/market/breadth?days=10"

Python

import requests

API_KEY = "fmk_YOUR_KEY"
BASE    = "https://finmagine.com/api/v1"
HEADERS = {"X-Api-Key": API_KEY}

# Get profile
r = requests.get(f"{BASE}/company/profile", headers=HEADERS, params={"symbol": "RELIANCE"})
profile = r.json()["data"]
print(f"{profile['company_name']}: ROCE={profile['roce']}, RS={profile['rs_rating']}")

# Screen stocks (api_max)
r = requests.get(f"{BASE}/screener", headers=HEADERS, params={
    "min_roce": 20, "max_pe": 30, "min_rs": 70, "sort_by": "rs_rating"
})
for co in r.json()["data"]["companies"]:
    print(f"{co['symbol']:12} RS={co['rs_rating']}  ROCE={co['roce']}%")

JavaScript

const API_KEY = "fmk_YOUR_KEY";
const BASE    = "https://finmagine.com/api/v1";

async function getProfile(symbol) {
    const r = await fetch(`${BASE}/company/profile?symbol=${symbol}`, {
        headers: { "X-Api-Key": API_KEY }
    });
    const { data } = await r.json();
    return data;
}

async function getTopMomentum(sector, limit = 20) {
    const params = new URLSearchParams({ limit, ...(sector ? { sector } : {}) });
    const r = await fetch(`${BASE}/market/momentum?${params}`, {
        headers: { "X-Api-Key": API_KEY }
    });
    return (await r.json()).data.stocks;
}

// Usage
const profile = await getProfile("HDFCBANK");
console.log(`${profile.company_name}: PE=${profile.pe}, RS=${profile.rs_rating}`);

Developer portal · Questions? contact@finmagine.com

The MCP server for Indian stock market intelligence.

API & MCP Documentation

Overview

Authentication

Rate limits

Response format

Error handling

Free tier symbols

GET /status

GET /companies

GET /company/profile

Response fields

GET /company/financials

Response fields per period

GET /company/ratios

GET /company/momentum

Derived boolean signals

GET /market/breadth

GET /market/momentum

GET /market/sectors

GET /screener

GET /company/ecs

Response fields

GET /company/guidance-tone

GET /company/order-wins

GET /company/insider-trades

GET /company/banking-kpis

GET /company/pead

GET /company/conglomerate

GET /company/pledge-history

GET /market/ecs

GET /market/conviction

GET /market/pead

GET /market/rrg

GET /market/industry-stages

GET /market/rs-changes

GET /feeds/order-wins

GET /feeds/insider

GET /feeds/bulk-block-deals

GET /feeds/circuit

GET /company/daily-prices

GET /company/shareholding

GET /company/corporate-actions

GET /market/index-constituents

GET /market/top-movers

GET /feeds/corporate-actions

GET /company/ai-summary

GET /company/management-tone

GET /company/sector-kpis

GET /company/ai-profile

GET /company/concall-decoder

GET /company/scorecard

GET /market/breakout-conditions

MCP Server

MCP Tool reference

Add to claude.ai (web)

Step 1 — Copy your connector URL

Step 2 — Add the connector

Step 3 — Enable it in a conversation

Add to Claude Desktop

Sample prompts

Quick start — core tools Free

Full-coverage workflow — all 41 tools api_max

Cursor / VS Code setup

cURL examples

Python

JavaScript