Skip to main content
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:
  • 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.

SEC-verified fundamentals

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.

licensed_market_data

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.

computed_from_prices

Values derived from a licensed price times a fundamentals input — market cap, P/E, EV multiples. Carries provenance: "computed_from_prices".

sec_filing

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:
Financial statements are columnar. data.periods is the header and each field array aligns to it:
Full provenance (sources, source_hash) appears when you request higher detail.

​
Decimal-string magnitudes

Exact magnitudes are JSON strings, not numbers:
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.

​
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.