Overview

The Finmagine API covers both Indian and US equity markets. For India, the moat 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. For the US, 6,400+ NYSE/NASDAQ stocks with financials, ratios, momentum, ECS, insider trades, SEC filings, 13F superinvestor holdings, and AI research reports. All data is delivered via Model Context Protocol (MCP) so AI agents can run end-to-end research workflows without writing code.

REST API: 86 endpoints total — 60 Indian equities (/api/v1/company/…, /api/v1/market/…, /api/v1/account/…) plus 26 US markets (/api/v1/us/…). MCP: 86 tools (60 India + 26 US) via the same endpoint, covering the full feature set including natural language screening, 13F holdings, AI research reports, and BYO LLM key management.

Base URL	https://finmagine.com/api/v1
MCP endpoint	https://finmagine.com/api/mcp.php
Format	JSON (all responses)
Auth	API key — header or query param
Versioning	URL-based (/v1/)
Agent recipes	/agent-recipes.json — 10 curated, verified-executable multi-tool workflows with tier/status/quota/runtime/async/LLM requirements and step-by-step chaining hints (schema)

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 NSE blue chips + 25 S&P 500 mega-caps
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

MCP Server

The Finmagine MCP server exposes 86 tools consumable by Claude, Cursor, VS Code, and any MCP-compatible AI agent — 60 for Indian markets and 26 for US markets. It is the only MCP server covering both NSE/BSE and NYSE/NASDAQ equity intelligence.

MCP Tool reference — Indian (41 tools)

All 86 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. Full per-endpoint reference (params, examples): API Reference →

Tool	Equivalent REST	Tier
search_companies	GET /companies	All
get_company_profile	GET /company/profile	All (25 free symbols)
get_financials	GET /company/financials	All (25 free symbols)
get_ratios	GET /company/ratios	All (25 free symbols)
get_momentum	GET /company/momentum	All (25 free symbols)
get_ai_quarterly_summary	GET /company/ai-summary	api_max
get_market_breadth	GET /market/breadth	All
get_market_momentum	GET /market/momentum	All
get_market_sectors	GET /market/sectors	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_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
list_byo_keys	GET /account/byo-keys	All
save_byo_key	GET /account/byo-key/save	All
remove_byo_key	GET /account/byo-key/remove	All
set_preferred_byo_key	GET /account/byo-key/set-preferred	All
test_byo_key	GET /account/byo-key/test	All
market_trader_scan	GET /market/trader-scan	api_pro+
start_preset	GET /presets/start	api_pro+
check_preset_status	GET /presets/poll	api_pro+
list_preset_runs	GET /presets/list	api_pro+
list_preset_catalog	GET /presets/catalog	All
cancel_preset	GET /presets/cancel	api_pro+
fast_scan_committee	GET /committee/fast-scan	api_pro+
start_committee	GET /committee/start	api_pro+
check_committee_status	GET /committee/poll	api_pro+
get_committee_report	GET /committee/report	api_pro+
list_committee_runs	GET /committee/list	api_pro+
cancel_committee	GET /committee/cancel	api_pro+
compute_committee_risk	GET /committee/risk-audit/compute	api_pro+
allocate_committee_risk	GET /committee/risk-audit/allocate	api_pro+
screen_natural_language	MCP only, no REST route	All

MCP Tool reference — US Markets (24 tools)

US tools cover 6,400+ NYSE/NASDAQ stocks and each has a REST (/api/v1/us/…) equivalent too — see the API Reference page for full REST + MCP examples side by side. Free tier is restricted to 25 S&P 500 mega-caps (AAPL, MSFT, AMZN, NVDA, GOOGL, META, TSLA, JPM, V, UNH, AVGO, LLY, XOM, MA, HD, PG, COST, MRK, ABBV, CVX, KO, PEP, ORCL, BAC, JNJ). All pro/max tools require api_pro or api_max respectively.

Tool	Description	Tier
us_search_companies	Search US stocks by name or ticker symbol. Returns symbol, name, sector, industry, market cap (USD billions), and scorecard score. No tier restriction on search — free keys get 10 results, paid keys get up to 50.	All
us_get_company_profile	Full profile for a US stock: price, market cap (USD billions), 52-week range, RS rating, P/E, ROE, operating margin, scorecard score, index membership (SP500/NDX100/DOW30). Free tier restricted to 25 S&P 500 mega-caps: AAPL, MSFT, AMZN, NVDA, GOOGL, META, TSLA, JPM, V, UNH, AVGO, LLY, XOM, MA, HD, PG, COST, MRK, ABBV, CVX, KO, PEP, ORCL, BAC, JNJ.	All (25 free symbols)
us_get_market_breadth	US market breadth snapshot: percentage of stocks above SMA-50 and SMA-200, total stocks tracked, and sector-level breakdown. Use this to gauge overall US market health before screening.	All
us_get_market_sectors	US sector summary: stock count, average scorecard score, average RS rating, and breadth (% above SMA-50 and SMA-200) for each GICS sector. Use to identify leading vs lagging sectors.	All
us_get_top_movers	US top gainers or losers by recent price return. Direction: gainers (default) or losers. Period: 1w (1 week) or 1m (1 month, default). Returns symbol, name, sector, current price, return %, RS rating, market cap in USD billions.	All
us_get_breakout_conditions	S&P 500 (SPY) technical posture: is SPY above SMA-50 and SMA-200? Returns BULL_CONFIRMED, ABOVE_SMA50_ONLY, or BEAR_CONFIRMED regime with SPY price, EMA-20, and RSI-14.	All
us_get_financials	Historical financials for a US stock — income statement, balance sheet, or cash flow — annual or quarterly. Key income fields: revenue, netinc, epsdil, ncfo, capex, fcf. Key balance fields: assets, debtnc, assetsc. Requires api_pro.	api_pro+
us_get_ratios	Financial ratios for a US stock with classification (Excellent/Good/Average/Poor) and peer percentile. Covers valuation (P/E, P/B, EV/EBITDA), profitability (ROE, margins), growth, leverage, and liquidity. Requires api_pro.	api_pro+
us_get_momentum	Technical momentum profile for a US stock: RS rating, 1W/1M/3M returns, RSI-14, EMA-20, SMA-50, SMA-200 with above/below flags, distance from 52-week high, and latest ECS score. Requires api_pro.	api_pro+
us_get_company_scorecard	Finmagine scorecard for US stocks: 5-dimension score (financial_health, growth_prospects, competitive_position, management_quality, valuation) and overall 0–10 score. Omit symbol for ranked list. Requires api_pro.	api_pro+
us_screen_stocks	Screen US stocks by fundamentals, technicals, and scorecard. Filters: sector, market cap (USD billions), P/E, ROE, operating margin, RS rating, above SMA-50/200, debt/equity, minimum scorecard score. Returns up to 50 results. Requires api_pro.	api_pro+
us_get_ecs_score	Earnings Catalyst Score (ECS) for a US stock: composite 0–100 score reflecting quality and surprise of recent earnings. Includes revenue/net income YoY and QoQ, percentile ranks, PEAD signal, and actual vs expected EPS. Requires api_pro.	api_pro+
us_get_insider_trades	Recent SEC Form 4 insider transactions for a US stock: director/officer name, title, transaction type, shares, price per share, and total value USD. Requires api_pro.	api_pro+
us_get_conviction_ranking	US stocks appearing in multiple screener presets simultaneously — a quantitative measure of multi-factor conviction. Higher scan_count = passes more screens at once. Requires api_pro.	api_pro+
us_get_index_constituents	Members of SP500, NDX100 (Nasdaq 100), or DOW30 (Dow Jones 30). Returns symbol, name, GICS sector, RS rating, market cap, P/E, and scorecard score. Use index_name: SP500, NDX100, or DOW30. Requires api_pro.	api_pro+
us_get_order_wins	Contract wins and significant agreements for US companies sourced from SEC 8-K filings. Returns contract type, value (USD millions), client name, segment, geography, AI summary, and confidence. Omit symbol for recent cross-company feed. Requires api_pro.	api_pro+
us_get_management_tone	Management tone analysis across recent earnings calls for a US company: per-quarter tone_read, top messages, dodged topics, and investor lens. Derived from AI-decoded earnings calls. Requires api_pro.	api_pro+
us_get_ai_quarterly_summary	AI-generated one-pager for a US company's most recent earnings: verdict, key KPIs, what went right, what to watch, management guidance, and investor lens. Faster than reading the full report. Requires api_pro.	api_pro+
us_get_ai_company_profile	Deep AI-generated company profile for a US stock: 10-section analysis covering business model, financials, competitive moat, management quality, risks, and investment thesis. Updated each earnings cycle. Requires api_max.	api_max
us_get_full_report	Full AI research report for a US stock with COMPELLING/WATCHLIST/AVOID stance. Complete fundamental analysis narrative in plain text. Requires api_max.	api_max
us_screen_natural_language	Screen US stocks using plain English. Examples: "profitable large-cap tech stocks with low debt", "healthcare companies with high ROE and strong earnings growth". Converts the query to filter criteria and returns matching stocks. Uses Groq/Gemini (no Finmagine paid LLM keys). Requires api_max.	api_max
us_get_13f_holdings	Superinvestor 13F holdings data. If symbol provided: shows which tracked funds hold it with value and portfolio %. If no symbol: lists all 14 tracked superinvestors (Berkshire, Pershing, Scion, Appaloosa, Duquesne, etc.). Requires api_max.	api_max
us_get_sec_feed	Recent SEC filings from EDGAR: 8-K material events, 10-K annual reports, 10-Q quarterly reports. Filter by symbol, form type, and lookback days. Requires api_max.	api_max
us_get_concall_decoder	Structured earnings call decoder for a US company: tone_read, top 3 management messages, topics dodged or downplayed, tone shifts from prior quarter, key numbers from Q&A, management outlook, and investor lens. Requires api_max.	api_max
us_market_momentum	Top US stocks ranked by RS rating (IBD-style 1-99 vs full US universe). RS >= 90 = elite momentum. No tier gate — source data is fully public.	All
us_market_trader_scan	US stocks matching a precomputed technical scan: Stage 2, VCP, Near-High, High Volume, or Breakout Readiness Score (BRS). Mirrors /us/picks/?list=trader. Requires api_pro (source data is premium-gated on the web).	api_pro+

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 86 available tools (60 Indian + 26 US).

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": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://finmagine.com/api/mcp.php?apiKey=fmk_YOUR_KEY"]
    }
  }
}

Replace fmk_YOUR_KEY with your API key. Restart Claude Desktop — mcp-remote is downloaded automatically on first run (requires Node.js). The Finmagine tools will appear in the tools panel.

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

Full-coverage workflow — 42 of 60 India tools (read-only) api_max

Works when the Finmagine connector is active — Claude calls each tool in turn and narrates results. Scoped to read-only tools only — the remaining 18 (BYO LLM keys, Investment Committee, Research Presets) spend real quota or provider tokens and are covered in their own guides below.

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

Tools exercised: get_breakout_conditions · get_market_breadth · get_top_movers · get_circuit_stocks · get_market_momentum · market_trader_scan · get_sector_rrg · get_industry_stages · get_index_constituents · get_rs_changes · get_market_sectors · 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 · screen_natural_language · search_companies

The remaining 18 tools power 3 systems — BYO LLM key setup, Research Presets, and the Investment Committee. Each gets its own sample prompt below, since each genuinely exercises several tools together. Full technical detail (encryption, quotas, response shapes) lives in their dedicated guides: BYO LLM Key Management · Research Presets · Investment Committee. All 3 apply equally to US symbols via a market parameter.

BYO LLM Key Setup — walkthrough prompt Free

Exercises: list_byo_keys · save_byo_key · test_byo_key · set_preferred_byo_key — the required first step before either Research Presets or the Investment Committee will run.

⚠️ Have a real API key ready from whichever provider you plan to use — anthropic, openai, gemini, groq, deepseek, or openrouter all work identically. Claude will ask you to paste it mid-conversation. That's expected here; save_byo_key is the tool built for exactly this.

Run a Research Preset end-to-end api_pro

Exercises: list_preset_catalog · start_preset · check_preset_status (polled repeatedly).

⚠️ Spends real quota (10 runs/24h, shared with the web UI) and calls your saved LLM provider. Requires a saved BYO key — run the BYO Key prompt above first. This will genuinely take up to ~15 minutes to finish; don't close the conversation.

Investment Committee — Fast Scan, then a full run api_pro

Exercises: fast_scan_committee · start_committee · check_committee_status (polled repeatedly) · get_committee_report.

⚠️ Part 1 (Fast Scan) is completely free — zero LLM tokens, no quota, safe to run anytime. Part 2 (the real Committee run) spends real quota (5 runs/24h) and calls your saved LLM provider — requires a saved BYO key and can take up to ~10 minutes. Feel free to stop after Part 1 if you just want to see the free tooling work.

Cursor / VS Code setup

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

{
  "servers": {
    "finmagine-markets": {
      "url": "https://finmagine.com/api/mcp.php",
      "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 (api_max)
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"

# NL screen: plain-English query via MCP tools/call (api_base+)
curl -X POST "https://finmagine.com/api/mcp.php?apiKey=fmk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"screen_natural_language","arguments":{"query":"profitable mid-caps with low debt and strong momentum","limit":10}}}'

# 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}`);

curl -X POST "https://finmagine.com/api/mcp.php?apiKey=fmk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "us_get_company_profile",
      "arguments": { "symbol": "AAPL" }
    }
  }'

AAPL  MSFT  AMZN  NVDA  GOOGL
META  TSLA  JPM   V     UNH
AVGO  LLY   XOM   MA    HD
PG    COST  MRK   ABBV  CVX
KO    PEP   ORCL  BAC   JNJ