# 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](/introduction.md): Decision-grade US-equity context over REST and MCP, with JSON shaped for apps and agents to act on.
- [Quickstart](/quickstart.md): Create a key, call /v2/snapshot, and parse the response from server-side code.
- [Hosted MCP quickstart](/mcp/hosted.md): Get a key, add the StockContext server to your client, and confirm stockcontext_snapshot returns AAPL.
- [Agent instructions](/agents/instructions.md): The copy-paste system prompt that makes an agent use StockContext correctly.
- [Agent recipes](/agents/recipes.md): Prompt-to-call sequences and answer templates for the questions agents get asked most.

## Guides

- [Choose endpoints](/guides/choose-endpoints.md): The route picker every other guide defers to: one question, one smallest route set.
- [Valuation check](/guides/valuation-check.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](/guides/reverse-dcf.md): Read the FCF growth a stock's current price already requires, the sensitivity grid, and the company's own realized growth — without quoting an implied number as a forecast or price target.
- [Compare basket](/guides/compare-basket.md): Score 2–12 symbols side by side in one call, then deepen only the names that survive.
- [Decision brief](/guides/decision-brief.md): Assemble one symbol's context (coverage, snapshot, valuation, optional filings or insider) into a single answer-first brief.
- [SEC risk review](/guides/sec-risk-review.md): Walk a filings list to one accession, read a single section, and summarize risk from primary SEC text only.
- [Insider scan](/guides/insider-scan.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](/guides/technical-timing.md): Answer 'is it extended?' from technicals plus price action, in two calls, without reaching for the raw series.
- [Build an equity agent](/guides/build-an-agent.md): Trace one user question through tool calls, real responses, and a cited answer.
- [Errors and retries](/guides/errors-and-retries.md): Branch on the envelope, retry only retryable:true, and honor Retry-After.
- [Production patterns](/guides/production-patterns.md): Cache by data family, keep keys server-side, and treat freshness metadata as product data.
- [Batch workflows](/guides/batch-workflows.md): Run many symbols with bounded concurrency, coverage checks first, and no quota burn.

## Contracts

- [Response model](/reference/response-model.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](/reference/freshness.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](/reference/units-and-fields.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](/reference/error-codes.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](/reference/authentication.md): How to send your API key, where keys live, and what a bad key returns.
- [Plans and limits](/reference/plans-and-limits.md): The three plans, which routes each can call, the rate-limit headers, and what hitting a ceiling returns.
- [Coverage and known gaps](/reference/coverage-and-gaps.md): The supported universe by the numbers, what each symbol can return, and what StockContext does not cover.

## MCP

- [MCP overview](/mcp/overview.md): 21 read-only public stockcontext_* tools that hand an agent typed US-equity context: same envelopes as REST, no client code.
- [MCP tools](/mcp/tools.md): All 21 public stockcontext_* tools, their REST routes, plan access, and argument conventions.
- [Prompts and resources](/mcp/prompts-and-resources.md): Built-in MCP resources (small JSON reference docs) and client-side prompt templates.

## API reference

- [API reference overview](/api-reference/overview.md): Base URL, auth header, the full route table, and how the reference examples are captured.
- [Stock symbol search API](/api-reference/endpoints/discovery/search.md)
- [Stock data coverage API](/api-reference/endpoints/discovery/coverage.md)
- [Stock quote & snapshot API](/api-reference/endpoints/core-context/snapshot.md)
- [Stock valuation API (vs 5-year history)](/api-reference/endpoints/core-context/valuation.md)
- [Reverse-DCF API (what is priced in)](/api-reference/endpoints/core-context/priced-in.md)
- [Stock comparison API](/api-reference/endpoints/core-context/compare.md)
- [Company profile API](/api-reference/endpoints/company-context/profile.md)
- [Company fundamentals API](/api-reference/endpoints/financials/fundamentals.md)
- [Stock earnings API](/api-reference/endpoints/financials/earnings.md)
- [Dividend data API](/api-reference/endpoints/financials/dividends.md)
- [Technical indicators API (RSI, MACD, SMA)](/api-reference/endpoints/market-context/technicals.md)
- [Stock price action API](/api-reference/endpoints/market-context/price-action.md)
- [Historical stock price API (30 years)](/api-reference/endpoints/market-context/history.md)
- [Earnings calendar API (per symbol)](/api-reference/endpoints/events/calendar.md)
- [SEC filings API (EDGAR)](/api-reference/endpoints/sec-filings/filings-list.md)
- [SEC filing lookup API](/api-reference/endpoints/sec-filings/filing.md)
- [SEC filing text API (risk factors, MD&A)](/api-reference/endpoints/sec-filings/filing-section.md)
- [Insider trading API (Form 4)](/api-reference/endpoints/sec-filings/insider.md)

## 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