> ## Documentation Index
> Fetch the complete documentation index at: https://stockcontext.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# StockContext docs

> A truthful US-fundamentals and licensed-prices API for AI agents. Fundamentals are SEC-verified, prices are licensed EOD, and unprovable values are honestly refused.

StockContext gives an agent everything it needs to analyze a US-listed stock, with provenance on every value and honest refusals instead of confident wrong numbers. Fundamentals are extracted from each filer's own XBRL statement face and served only after they are re-verified against SEC's own data. Anything we cannot prove from a filing comes back as a typed refusal — never a guess, a `null`, or a silent `0`.

The API is a set of `POST` JSON tool endpoints under `https://api.stockcontext.com`. There is no query-string surface and no SDK to learn: send a symbol, read a typed response.

<Note>
  The default wire is **schema 2**. If you omit `schema`, you get schema 2. Send `{ "schema": 1 }` only when you intentionally need the frozen legacy wire.
</Note>

## The honesty model

This is the part worth understanding before you write any code.

* **Verified, not scraped.** Each fundamentals value is pulled off the statement face of a specific filing, then checked against SEC's `companyconcept` API before it is published. A value that fails verification is never served.
* **Refuse, never fabricate.** An unprovable schema-2 value is a typed refusal: `{ "unavailable": "...", "recovery": { "action": "..." } }`. Branch on `unavailable`; the token and recovery action are machine-readable.
* **Exact magnitudes stay exact.** Headline numbers use compact cells such as `{ "v": "112010000000", "d": "≈$112B" }`; parse `v` as a decimal string. Ratios can be plain JSON numbers.
* **Every cell carries provenance.** A value is `direct` (tagged on the filing) or `derived` (computed from tagged operands). At `detail: "full"` each cell names its `accession`, `concept`, `unit`, and period so you can trace it back to the source document.
* **Prices are a separate, licensed feed.** Market data carries `provenance: "licensed_market_data"` and its own market clock; the vendor is never named. It is never mixed with the SEC trust chain.

Read [Core concepts](/docs/concepts) for the full trust model.

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="terminal" href="/docs/quickstart">
    Create a key, resolve a symbol with `stock_search`, and read a verified `stock_financials` response — values and refusals — in a few minutes.
  </Card>

  <Card title="Core concepts" icon="shield" href="/docs/concepts">
    The trust model: SEC verification, typed refusals, provenance levels, decimal-string magnitudes, and the two clocks.
  </Card>

  <Card title="API reference" icon="braces" href="/docs/api-reference/overview">
    Base URL, the `X-API-Key` header, every tool's parameters, and live response examples.
  </Card>

  <Card title="Build an agent" icon="bot" href="/docs/guides/build-an-agent">
    Connect over hosted MCP, or wire the tools into a function-calling loop over plain HTTP with `fetch` or `httpx`.
  </Card>
</CardGroup>

## The endpoints

HTTP surface: 10 data tools + stock\_flag, a feedback endpoint. Every endpoint is a `POST` request to `/v1/tools/{name}` with a JSON body and the `X-API-Key` header. `stock_universe` and `stock_technicals` are schema-2 only; schema 1 remains frozen.

| Endpoint           | Body                                                                | Returns                                                                                              |
| ------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `stock_search`     | `{ query }`                                                         | Resolve a ticker, name, or CIK to securities, each with coverage flags.                              |
| `stock_universe`   | `{ coverage?, shape?, offset?, limit? }`                            | Enumerate active listings for a screen, with one database-derived coverage marker per row.           |
| `stock_financials` | `{ symbol, statement?, period_kind?, periods?, vintage?, detail? }` | Income statement, balance sheet, cash flow, and ratios with per-cell provenance.                     |
| `stock_overview`   | `{ symbol, detail? }`                                               | Company profile, DEI facts, latest filings, financials, valuation, and growth in one call.           |
| `stock_prices`     | `{ symbol, view?, range? }`                                         | Current/EOD bars, history, return/range context, dividends, and splits.                              |
| `stock_technicals` | `{ symbol, detail?, indicators?, range? }`                          | Indicators, drawdowns, beta versus SPY, relative returns, and optional indicator history.            |
| `stock_filings`    | `{ symbol, form?, limit? }`                                         | SEC filing inventory with accession, form, dates, and the primary document.                          |
| `stock_insider`    | `{ symbol, window_days?, limit? }`                                  | Form 4 insider transactions, faithfully transcribed.                                                 |
| `stock_ownership`  | `{ symbol }`                                                        | Tracked institutional 13F holders (a subset, never exhaustive).                                      |
| `stock_reference`  | `{ catalog }`                                                       | The API's self-describing catalogs: refusal tokens, concepts, units, shapes, and more.               |
| `stock_flag`       | `{ symbol, field, period?, reason?, claimed_value? }`               | Schema-2 feedback endpoint for reporting a served value to human triage. It never edits served data. |

## Coverage

Coverage is data, not a slogan. Use `stock_universe` to enumerate/filter listings, `stock_search` to resolve user-entered text, and `stock_reference {"catalog":"coverage"}` for measured aggregate rates. A listing without fundamentals is marked `prices_only` when bars are held, otherwise `discovery_only`; do not guess a value. About 54% of US common stocks serve the complete headline set today (coverage is published live at [/status](https://stockcontext.com/status)); large foreign ADR filers (20-F/40-F) often serve fundamentals in native currency with valuation ratios refused rather than converted. See [Coverage and gaps](/docs/reference/coverage-and-gaps).

## What this API does not do

* No options, futures, FX, or crypto, and no intraday tick stream or L2/order-book depth. The authoritative price feed is end-of-day; snapshots add an IEX last-sale quote overlay (a thin single venue, not a consolidated real-time feed).
* No analyst consensus, price targets, transcripts, news, sentiment, or earnings estimates.
* No forecasts, fair-value targets, or investment advice.
* Hosted MCP is available at `https://stockcontext.com/mcp`; plain HTTP remains available for direct REST integrations. See [MCP](/docs/mcp/overview).

## Next step

Start with the [Quickstart](/docs/quickstart). If you already know the shape of the data, the [API reference](/docs/api-reference/overview) lists every tool, parameter, and field.