# StockContext

Decision-grade US stock and ETF market context for AI agents and the apps that run them, over REST and a hosted MCP server. One call returns context an agent can reason on: live quotes and performance, valuation read against a symbol's OWN history (percentiles and a window-scoped label like near_5y_low ... near_5y_high — a rank within the symbol's own range, never a cheap/undervalued verdict, with a price-vs-fundamentals decomposition for why a multiple moved), a reverse-DCF that solves the FCF growth today's price already requires (an implied requirement, not a forecast or price target), fundamentals, technicals, SEC filings with primary text and sections, insider activity, dividends, earnings, events, multi-symbol compare, and search/coverage. REST routes are authenticated GET /v2/* calls against https://api.stockcontext.com. Hosted MCP is at https://api.stockcontext.com/mcp and uses the same X-API-Key header. Every page below has a markdown variant at the listed URL; any /docs/* page also returns markdown when requested with "Accept: text/markdown".

Agent rules:
- Success is {"data": ...}; failure is {"error": {"code", "message", "retryable"}}.
- Preserve freshness, as_of, market_status, units, signs, periods, accessions, filing dates, unavailable reasons, and calls/tools used.
- Treat freshness: "unsupported" as a product fact, not an outage.
- Do not invent missing ETF holdings or private-beta ownership/governance/segment facts. Report unavailable reasons when a subfamily is absent. Do not invent analyst consensus, price targets, transcripts, news, options, execution, or investment advice.
- Branch on error.code. Non-retryable: UNAUTHORIZED, PLAN_UPGRADE_REQUIRED, SYMBOL_INVALID, SYMBOL_UNKNOWN, PARAM_INVALID, PREREQUISITE_MISSING. Retryable: RATE_LIMITED, UPSTREAM_UNAVAILABLE, AUTH_UPSTREAM_UNAVAILABLE.
- Retry only when error.retryable is true and respect Retry-After when present.
- Every response that passes key verification carries X-RateLimit-Limit/Remaining/Reset, including 4xx; throttle as Remaining approaches 0 and honor Retry-After on 429.
- /v2/compare takes 2-12 symbols. /version is a root liveness marker (not under /v2).

## Start here

- [StockContext docs](https://stockcontext.com/llms.mdx/docs/content.md): Decision-grade US stock and ETF market context for AI agents and the apps that run them, over REST and a hosted MCP server.
- [Quickstart](https://stockcontext.com/llms.mdx/docs/quickstart/content.md): Create a key, call /v2/snapshot, and parse the response from server-side code.
- [Hosted MCP quickstart](https://stockcontext.com/llms.mdx/docs/mcp/hosted/content.md): Get a key, add the StockContext server to your client, and confirm stockcontext_snapshot returns AAPL.
- [Agent instructions](https://stockcontext.com/llms.mdx/docs/agents/instructions/content.md): The copy-paste system prompt that makes an agent use StockContext correctly.
- [Agent recipes](https://stockcontext.com/llms.mdx/docs/agents/recipes/content.md): Prompt-to-call sequences and answer templates for the questions agents get asked most.

## Guides

- [Choose endpoints](https://stockcontext.com/llms.mdx/docs/guides/choose-endpoints/content.md): The route picker every other guide defers to: one question, one smallest route set.
- [Valuation check](https://stockcontext.com/llms.mdx/docs/guides/valuation-check/content.md): Answer "is it expensive?" by reading every multiple against the symbol's OWN history: percentiles, a window-scoped label, and a price-vs-fundamentals decomposition that tells you why the multiple moved.
- [Reverse DCF: what is priced in](https://stockcontext.com/llms.mdx/docs/guides/reverse-dcf/content.md): Use /v2/priced-in to read the FCF growth a stock's current price already requires, the discount-rate sensitivity grid, and the company's own realized growth — without ever quoting an implied number as a forecast or price target.
- [Compare basket](https://stockcontext.com/llms.mdx/docs/guides/compare-basket/content.md): Score 2–12 symbols side by side in one call, then deepen only the names that survive.
- [Decision brief](https://stockcontext.com/llms.mdx/docs/guides/decision-brief/content.md): Assemble one symbol's context (coverage, snapshot, valuation, optional filings or insider) into a single answer-first brief.
- [SEC risk review](https://stockcontext.com/llms.mdx/docs/guides/sec-risk-review/content.md): Walk a filings list to one accession, read a single section, and summarize risk from primary SEC text only.
- [Insider scan](https://stockcontext.com/llms.mdx/docs/guides/insider-scan/content.md): Read the trailing 90-day Form 4 rollup, separate open-market signal from routine activity, and report it without turning it into advice.
- [Technical timing check](https://stockcontext.com/llms.mdx/docs/guides/technical-timing/content.md): Answer 'is it extended?' from technicals plus price action, in two calls, without reaching for the raw series.
- [Build an equity agent](https://stockcontext.com/llms.mdx/docs/guides/build-an-agent/content.md): Trace one user question through tool calls, real responses, and a cited answer.
- [Errors and retries](https://stockcontext.com/llms.mdx/docs/guides/errors-and-retries/content.md): Branch on the envelope, retry only retryable:true, and honor Retry-After.
- [Production patterns](https://stockcontext.com/llms.mdx/docs/guides/production-patterns/content.md): Cache by data family, keep keys server-side, and treat freshness metadata as product data.
- [Batch workflows](https://stockcontext.com/llms.mdx/docs/guides/batch-workflows/content.md): Run many symbols with bounded concurrency, coverage checks first, and no quota burn.

## Contracts

- [Response model](https://stockcontext.com/llms.mdx/docs/reference/response-model/content.md): The two top-level envelopes, the common fields on every data object, the three ways a value can be absent, and parser code that branches on retryable.
- [Freshness](https://stockcontext.com/llms.mdx/docs/reference/freshness/content.md): The five freshness values, what as_of and market_status mean, and how to detect staleness from as_of plus cache_age_seconds.
- [Units and fields](https://stockcontext.com/llms.mdx/docs/reference/units-and-fields/content.md): What the field-name suffixes mean, how signs work, how timestamps are formatted, and how to read the columnar /v2/history shape.
- [Error codes](https://stockcontext.com/llms.mdx/docs/reference/error-codes/content.md): Every error code with its HTTP status, whether it is retryable, the live message, and what to do, plus a retry loop that honors Retry-After.
- [Authentication](https://stockcontext.com/llms.mdx/docs/reference/authentication/content.md): How to send your API key, where keys live, and what a bad key returns.
- [Plans and limits](https://stockcontext.com/llms.mdx/docs/reference/plans-and-limits/content.md): The three plans, which routes each can call, the rate-limit headers, and what hitting a ceiling returns.
- [Coverage and known gaps](https://stockcontext.com/llms.mdx/docs/reference/coverage-and-gaps/content.md): The supported universe by the numbers, what each symbol can return, and where the data ends so an agent never guesses.

## MCP

- [MCP overview](https://stockcontext.com/llms.mdx/docs/mcp/overview/content.md): MCP-native US-equity context for AI agents: 21 public stockcontext_* tools that return the same typed envelopes as REST, no client code.
- [MCP tools](https://stockcontext.com/llms.mdx/docs/mcp/tools/content.md): All 21 public stockcontext_* tools, their REST routes, plan access, and argument conventions.
- [Prompts and resources](https://stockcontext.com/llms.mdx/docs/mcp/prompts-and-resources/content.md): Built-in MCP resources (JSON reference docs) and client-side prompt templates.

## API reference

- [API reference overview](https://stockcontext.com/llms.mdx/docs/api-reference/overview/content.md): Base URL, auth header, the full route table, and how the reference examples are captured.
- [Stock symbol search API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/discovery/search/content.md): Search US stocks and ETFs by ticker fragment or company name. Returns ranked matches with symbol, name, asset type, and exchange.
- [Stock data coverage API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/discovery/coverage/content.md): Check which data families a US stock or ETF supports — snapshot, valuation, fundamentals, SEC filings, insider — before you call them.
- [Stock quote & snapshot API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/core-context/snapshot/content.md): Snapshot API with live quote when available, quote-unavailable envelopes, performance over seven windows, 52-week range position, and quick fundamentals.
- [Stock valuation API (vs own history)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/core-context/valuation/content.md): Stock valuation API: P/E, P/S, P/B, EV/EBITDA, and PEG ranked against the symbol's own multi-year history, with percentiles, price-vs-fundamental attribution, and yields.
- [Reverse-DCF API (what is priced in)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/core-context/priced-in/content.md): Reverse-DCF API: solve the free-cash-flow growth rate a US stock's current price already requires, with a discount-rate sensitivity grid and the company's own trailing realized growth.
- [Stock comparison API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/core-context/compare/content.md): Compare 2–12 US stocks or ETFs in one call: performance, valuation, and technical fields side by side in a single scorecard response.
- [Company profile API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/company-context/profile/content.md): Company profile API for US stocks and ETFs: description, sector, industry, exchange, headquarters, CIK, market cap, and shares outstanding.
- [Company fundamentals API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/financials/fundamentals/content.md): Fundamentals API with curated income statement, balance sheet, and cash flow rows for 8 quarters or 5 fiscal years, plus TTM margins.
- [Stock earnings API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/financials/earnings/content.md): Earnings API for US stocks: latest EPS and revenue with year-over-year change, an estimated next report date, and per-quarter history.
- [Dividend data API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/financials/dividends/content.md): Dividend API with current yield, annual rate, frequency, next estimated ex-date, growth streaks, and a dividend-health grade.
- [Technical indicators API (RSI, MACD, SMA)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/market-context/technicals/content.md): Technical analysis API: RSI, MACD, stochastic, SMA/EMA crosses, ADX, Bollinger bands, ATR, beta, and relative strength — computed server-side.
- [Stock price action API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/market-context/price-action/content.md): Price action API: volume vs averages, 30/90-day extremes, gaps, streaks, biggest single-day moves, and max drawdowns up to five years.
- [Historical stock price API (30 years)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/market-context/history/content.md): Historical stock data API: daily prices up to 30 years, plus volume, RSI, financial ratios, and dividends as compact columnar series.
- [Earnings calendar API (per symbol)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/events/calendar/content.md): Earnings calendar API: estimated next earnings date and ex-dividend date for a symbol, derived from its own reporting history.
- [SEC filings API (EDGAR)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filings-list/content.md): EDGAR API for SEC filings: recent 10-K, 10-Q, and 8-K filings for any US-listed stock, newest first, with accessions for full-text retrieval.
- [SEC filing lookup API](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filing/content.md): Look up one SEC filing by accession number: 10-K/10-Q section indexes, 8-K items and press-release availability, or Form 4 filing facts.
- [SEC filing text API (risk factors, MD&A)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filing-section/content.md): Full-text API for SEC filing sections: risk factors, MD&A, and business from 10-K/10-Q filings, or the press release from an 8-K.
- [Insider trading API (Form 4)](https://stockcontext.com/llms.mdx/docs/api-reference/endpoints/sec-filings/insider/content.md): Insider trading API: trailing-90-day Form 4 rollup with buy/sell counts, net value, the 10b5-1 planned-sale ratio, and recent transactions.

## Machine-readable

- [Agent skill (SKILL.md)](https://stockcontext.com/SKILL.md): drop-in skill file for coding agents
- [OpenAPI spec](https://stockcontext.com/api/openapi): the REST contract of record
- [Full docs as one file](https://stockcontext.com/llms-full.txt)