# noxstock

noxstock is a read-only US-listed stock and ETF context API over REST and hosted MCP. REST routes are authenticated GET /v2/* calls against https://api.noxstock.com. Hosted MCP is at https://api.noxstock.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 ETF holdings, ownership/13F, analyst consensus, price targets, transcripts, news, options, execution, or investment advice.
- Retry only when error.retryable is true and respect Retry-After when present.

## Start here

- [noxstock docs](/introduction.md): A read-only US-equity context API over REST and MCP, with JSON shaped for apps and agents.
- [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 noxstock server to your client, and confirm noxstock_snapshot returns AAPL.
- [Agent instructions](/agents/instructions.md): The copy-paste system prompt that makes an agent use noxstock 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?" with snapshot plus valuation on a Free key, reading multiples against their own 5-year history.
- [Compare basket](/guides/compare-basket.md): Score 2–4 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 noxstock does not cover.

## MCP

- [MCP overview](/mcp/overview.md): 17 read-only noxstock_* tools that hand an agent typed US-equity context — same envelopes as REST, no client code.
- [MCP tools](/mcp/tools.md): All 17 noxstock_* tools, their REST routes, plan access, and argument conventions.
- [Local stdio setup](/mcp/local-stdio.md): Run the noxstock MCP server locally for development or localhost testing.
- [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.
- [Search supported symbols](/api-reference/endpoints/discovery/search.md)
- [Check symbol coverage](/api-reference/endpoints/discovery/coverage.md)
- [Get decision snapshot](/api-reference/endpoints/core-context/snapshot.md)
- [Get valuation context](/api-reference/endpoints/core-context/valuation.md)
- [Compare symbols](/api-reference/endpoints/core-context/compare.md)
- [Get company or ETF profile](/api-reference/endpoints/company-context/profile.md)
- [Get fundamentals](/api-reference/endpoints/financials/fundamentals.md)
- [Get earnings context](/api-reference/endpoints/financials/earnings.md)
- [Get dividends](/api-reference/endpoints/financials/dividends.md)
- [Get technical indicators](/api-reference/endpoints/market-context/technicals.md)
- [Get price action](/api-reference/endpoints/market-context/price-action.md)
- [Get selected history series](/api-reference/endpoints/market-context/history.md)
- [Get symbol calendar](/api-reference/endpoints/events/calendar.md)
- [List SEC filings](/api-reference/endpoints/sec-filings/filings-list.md)
- [Get filing metadata](/api-reference/endpoints/sec-filings/filing.md)
- [Get filing section text](/api-reference/endpoints/sec-filings/filing-section.md)
- [Get insider activity](/api-reference/endpoints/sec-filings/insider.md)

## Machine-readable

- [Agent skill (SKILL.md)](https://noxstock.com/SKILL.md): drop-in skill file for coding agents
- [OpenAPI spec](https://noxstock.com/api/openapi): the REST contract of record