# 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](https://noxstock.com/llms.mdx/docs/content.md): A read-only US-equity context API over REST and MCP, with JSON shaped for apps and agents.
- [Quickstart](https://noxstock.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://noxstock.com/llms.mdx/docs/mcp/hosted/content.md): Get a key, add the noxstock server to your client, and confirm noxstock_snapshot returns AAPL.
- [Agent instructions](https://noxstock.com/llms.mdx/docs/agents/instructions/content.md): The copy-paste system prompt that makes an agent use noxstock correctly.
- [Agent recipes](https://noxstock.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://noxstock.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://noxstock.com/llms.mdx/docs/guides/valuation-check/content.md): Answer "is it expensive?" with snapshot plus valuation on a Free key, reading multiples against their own 5-year history.
- [Compare basket](https://noxstock.com/llms.mdx/docs/guides/compare-basket/content.md): Score 2–4 symbols side by side in one call, then deepen only the names that survive.
- [Decision brief](https://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.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://noxstock.com/llms.mdx/docs/reference/coverage-and-gaps/content.md): The supported universe by the numbers, what each symbol can return, and what noxstock does not cover.

## MCP

- [MCP overview](https://noxstock.com/llms.mdx/docs/mcp/overview/content.md): 17 read-only noxstock_* tools that hand an agent typed US-equity context — same envelopes as REST, no client code.
- [MCP tools](https://noxstock.com/llms.mdx/docs/mcp/tools/content.md): All 17 noxstock_* tools, their REST routes, plan access, and argument conventions.
- [Local stdio setup](https://noxstock.com/llms.mdx/docs/mcp/local-stdio/content.md): Run the noxstock MCP server locally for development or localhost testing.
- [Prompts and resources](https://noxstock.com/llms.mdx/docs/mcp/prompts-and-resources/content.md): Built-in MCP resources (small JSON reference docs) and client-side prompt templates.

## API reference

- [API reference overview](https://noxstock.com/llms.mdx/docs/api-reference/overview/content.md): Base URL, auth header, the full route table, and how the reference examples are captured.
- [Search supported symbols](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/discovery/search/content.md)
- [Check symbol coverage](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/discovery/coverage/content.md)
- [Get decision snapshot](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/core-context/snapshot/content.md)
- [Get valuation context](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/core-context/valuation/content.md)
- [Compare symbols](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/core-context/compare/content.md)
- [Get company or ETF profile](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/company-context/profile/content.md)
- [Get fundamentals](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/financials/fundamentals/content.md)
- [Get earnings context](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/financials/earnings/content.md)
- [Get dividends](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/financials/dividends/content.md)
- [Get technical indicators](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/market-context/technicals/content.md)
- [Get price action](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/market-context/price-action/content.md)
- [Get selected history series](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/market-context/history/content.md)
- [Get symbol calendar](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/events/calendar/content.md)
- [List SEC filings](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filings-list/content.md)
- [Get filing metadata](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filing/content.md)
- [Get filing section text](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/sec-filings/filing-section/content.md)
- [Get insider activity](https://noxstock.com/llms.mdx/docs/api-reference/endpoints/sec-filings/insider/content.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
- [Full docs as one file](https://noxstock.com/llms-full.txt)