> ## 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.
# Core concepts
> The trust model: SEC-verified fundamentals, typed refusals, provenance levels, decimal-string magnitudes, and the two clocks.
StockContext is designed around one promise: an agent always knows whether a number is proven, and where it came from. This page explains the contracts that make that true. A client that respects them treats every tool the same way.
## Verified against SEC
Fundamentals are not scraped or estimated. Each value is extracted from the **statement face** of a specific filing — the income statement, balance sheet, or cash-flow statement as the filer tagged it in XBRL — and is then re-verified against SEC's own `companyconcept` API before it is published. A value that does not match SEC's record is never served.
That verification runs on a clock. `meta.last_verified_at` is when the served data was last checked against SEC, and `meta.published_at` is when this projection was built. `meta.build.fundamentals` is the source-hash of the underlying filing.
## Typed refusals
When a value cannot be proven from a filing, StockContext refuses it explicitly rather than guessing. Refusals are typed objects that replace the value in place:
```json theme={null}
{
"unavailable": "not_reported",
"recovery": { "action": "use_full_document" }
}
```
* **Always check `unavailable` first.** When it is present, there is no value field; never substitute `0` or `null`. A silent zero would be a wrong number; a refusal is honest.
* **`unavailable`** is a machine-readable token (for example `not_reported`, `cash_return_unavailable`, `ambiguous_candidate`).
* **`recovery.action`** tells an agent what to do next (for example `use_full_document`, `disambiguate`).
The full catalog of reasons and their recovery actions is served by `stock_reference` with `{ "catalog": "refusal_tokens" }`, so an agent can look them up at runtime.
A genuinely tagged `0` is served as a real `0`. A refusal only appears when the underlying value is unprovable — for example, a dividend yield refuses `cash_return_unavailable` rather than reporting `0` for a company whose dividend concept was never tagged, because a chain miss is indistinguishable from a real non-payer.
## Provenance levels
Different data classes carry different trust chains. Every payload tells you which one you are reading.
Statement-face values re-checked against SEC's own data. Exact cells are decimal strings in aligned arrays or compact `v` cells in overview. Clock: `meta.as_of.sec`.
End-of-day prices from a licensed feed. Its own market clock (`meta.as_of.market`); the vendor is never named. Never mixed into the SEC chain.
Values derived from a licensed price times a fundamentals input — market cap, P/E, EV multiples. Carries `provenance: "computed_from_prices"`.
Faithful transcriptions of a filing as submitted — insider Form 4 and 13F ownership. Cited to accession and filed date; no derivation.
### Exact values
Overview headline values use compact cells. `v` is exact; `d` is display-only:
```json theme={null}
{ "v": "112010000000", "d": "≈$112B" }
```
Financial statements are columnar. `data.periods` is the header and each field array aligns to it:
```json theme={null}
{
"periods": [{ "id": "FY2025" }],
"fields": { "revenue": ["416161000000"] }
}
```
Full provenance (`sources`, `source_hash`) appears when you request higher detail.
## Decimal-string magnitudes
Exact magnitudes are JSON **strings**, not numbers:
```json theme={null}
{ "v": "416161000000", "d": "≈$416.2B" }
```
Parse exact strings with a decimal type (`Decimal` in Python, a decimal library in JS) so no precision is lost between SEC's filing and your code. Ratios such as `effective_tax_rate` can be plain JSON numbers.
## The two clocks
Fundamentals and prices move on different timelines, so they carry different `as_of` clocks. Never assume one implies the other.
* **`meta.as_of.sec`** — the SEC knowledge cutoff: the latest date through which filings have been ingested for this response. It governs fundamentals, filings, insider, and ownership.
* **`meta.as_of.market`** — the market clock for the licensed price feed.
A valuation multiple such as P/E crosses both clocks: it pairs a fundamentals input on the SEC clock with a close on the market clock, and its `inputs` name both dates.
## Coverage semantics
`stock_search` resolves securities and reports whether each one is ingested yet. Use those coverage flags before calling deeper tools.
* **`is_covered: true`** — fundamentals are ingested and served for this security.
* **`is_covered: false` with `ingestion_pending`** — the ticker is a real, known security, but its fundamentals have not been ingested yet. This is a coverage fact, not an error; coverage grows automatically as filings land.
The per-security `coverage` block also flags availability by tool (`stock_financials`, `stock_prices`). In schema 2, query `stock_reference` with `{ "catalog": "coverage" }` for current coverage counts. See [Coverage and gaps](/docs/reference/coverage-and-gaps).
## period\_kind and vintage
`stock_financials` takes two axes that select which periods you get:
* **`period_kind`** is `annual` (10-K periods) or `quarter` (10-Q periods). On the wire, income-statement and cash-flow rows carry `period_kind: "annual"` (or `"quarter"`), while balance-sheet rows are point-in-time and carry `period_kind: "instant"`.
* **`vintage`** currently serves `latest_restated` only: the most recent restatement of each period. Restatement provenance is carried per value, so changed periods stay explicit without advertising an unsupported historical wire mode.
## One data source per fact
Fundamentals come from SEC and only SEC — there is no vendor fallback. Prices come from the licensed feed and only that feed. The two are never blended, so a value's provenance is always unambiguous. When the reference catalogs and this prose disagree, the live catalogs from `stock_reference` win.