Concepts

Data semantics

StockSync never returns an unlabeled price, a silent gap, or data without its age. This page defines what every result carries and what each value means. The CLI, the MCP server, the SDK and the website all follow it.

Provenance and freshness

Every result names the upstream it came from and when:

Field	Meaning
`source`	`robinhood-stock-token-api`, `robinhood-chain-rpc`, `chainlink-price-feed` or `chainlink-feed-directory`
`fetchedAt`	When StockSync received the data
`sourceTimestamp`	When the upstream says it produced the data (for example a quote’s `generatedAt`), or `null`
`maxAgeMs`	How old the data may be before it must be presented as stale
`cache`	`miss` (fetched for this request), `hit` (reused) or `stale-fallback`

assessFreshness(freshness) measures age from sourceTimestamp when the upstream provides one, otherwise from fetchedAt. Data is fresh while its age is within maxAgeMs, stale after that, and unknown if no timestamp can be parsed.

A stale-fallback result is always stale. It appears only when an upstream failed transiently and StockSync served an expired response instead, together with a SERVED_STALE_AFTER_UPSTREAM_ERROR warning.

Caching policy

Data	Reused for	Presented as stale after	Stale fallback window
Registry assets	1 min	10 min	1 h
Quotes	15 s	1 min	5 min
Corporate actions	15 min	2 h	6 h
Onchain state	10 s	1 min	none
Feed directory	1 h	24 h	7 days
Oracle reading	10 s	the feed’s heartbeat	none

The Stock Token API documents a 15-second cache for /prices and one hour for /corporate-actions; StockSync’s windows never claim data is newer than the upstream can provide.

Prices

A Stock Token represents a number of underlying shares given by its multiplier. StockSync keeps the different price bases apart and labels every value.

Underlying quote

UnderlyingQuote is the bid and ask of the underlying equity exactly as /prices publishes them. It has multiplierAdjusted: false and is not the price of one token.

One-token equivalent

PriceView.tokenEquivalent applies the documented conversion: bid and ask multiplied by the current multiplier, in exact decimal arithmetic. With a bid of 212.12 and a multiplier of 1.000775159164630595, the one-token bid is 212.2844267620014418114. The result names its formula.

Chainlink feed price

OraclePriceView.reading.price is the onchain Chainlink feed price of one token. Feeds already include the multiplier (multiplierAdjusted: true). Check withinHeartbeat and oraclePaused before relying on it.

OraclePriceView.underlyingEquivalent converts the feed price back to one underlying share: feed price divided by the onchain uiMultiplier(), rounded half-even to the feed’s decimals.

Exact decimals

Prices, multipliers and rates are decimal strings such as "1.000775159164630595". They are never parsed into floating-point numbers inside StockSync, and nothing is rounded except where a result states its rounding.

Trading capabilities

The Stock Token API has been observed describing tradability in two shapes, and StockSync models both instead of inventing a mapping:

per-session: whole and fractional tradability for the market, extended and overnight sessions. Live registry responses use this shape.
underlier-flags: fractional, allDay and extendedHoursFractional, as the API reference describes.

Tradability values are tradable, untradable, position-closing-only, position-opening-only, blank, not-set and unrecognized. The trading-halt flag comes from the latest quote and is null when no quote is available.

Warnings

Non-fatal problems travel with the data as DataWarnings: a code, a message, and the ticker they concern. Unknown enum values become unrecognized with a warning rather than being guessed. Every code is listed in Errors and warnings.