Skip to content

US equity, ETF and read-only option domain

P3 adds five registry-backed read tools: equity_etf_master, us_market_session, etf_data, equity_market_data, and option_chain. CLI + Skill, MCP, and REST use the same registry definitions and governed core operations.

Under requirements 3.1, consumer connections read prices only through the consumer tools get_quote and get_price_history, which return end-of-day closes and daily bars. Quotes, trades, intraday bars and option data are not consumer-visible (config/consumer_rights.yaml), and EODHD real-time, websocket and intraday capture is stopped. option_chain, market_quote and market_trades are advanced tools that need an explicit grant.

Prepared security master reader

The prepared ETF database writer requires existing security master records. It does not insert hardcoded SPY issuer, exchange, industry or security rows while saving ETF observations. A missing parent fails the transaction; a failed batch commits no prefix. Test parent records are explicitly synthetic fixtures. Existing legacy master records still need source-evidence reconciliation, and this change does not establish current or historical ETF master coverage.

The prepared production etf_data package also verifies each typed record against one intact latest normalized source capture, including the raw checksum link and captured license terms. It rejects mismatched values, missing fields, late captures and unresolved same-time revisions. Its typed payload retains the four ETF record variants and replaces storage-only evidence labels with public source locators. Legacy missing license snapshots remain unknown. Typed rows alone cannot establish authorization, complete holdings or a verified permanent security identity; these gaps remain explicit partial results. Deployment and ordinary-user acceptance completed with the 1.1.15 release; the coded partial status above is the accepted production state.

The prepared production equity_etf_master implementation reads captured OpenFIGI mapping facts for an exact permanent identifier such as figi:BBG000B9XRY4. It returns original FIGI, composite/share-class identifiers, ticker, name, provider exchange code and security classifications, with source checksums, license scopes and evidence locators. The latest eligible capture is selected as one snapshot; missing fields are not taken from older responses. Both capture and public-known times must precede as_of. The prepared website request uses the actual AAPL FIGI and omits optional as_of to use the server's current query time. For historical queries, supply an explicit cutoff with verified captured coverage.

A mapping response alone does not establish listing status, the listing validity interval, trading currency or an issuer/company association. These remain explicit security_master_*_unavailable coverage gaps and the result is partial. An exchange code such as US is retained as the provider code; it is not reported as an ISO MIC. Unresolved identifiers and records without verified raw-capture links yield an empty result, with no fixture fallback.

This source change still requires verification of the promised universe and history. The deployed 1.1.15 service runs this reader against persisted captures, and release and ordinary-user production verification have completed for the captured subjects. The reader remains an implementation step toward the full security master contract; its partial records do not satisfy that contract's production completion criteria for every subject.

Point-in-time rules

ETF holdings are snapshots, not reconstructed estimates. Every holding has an effective_date, published_at, and known_at. A query includes a snapshot only when both its effective date is within the requested cutoff and its known_at is no later than as_of. It returns the latest eligible snapshot; it never relabels the current portfolio as an older snapshot. NAV and distributions use the same visibility rule. NAV premium/discount is validated against market price and NAV.

Corporate actions are visible only after known_at. Each adjustment factor names an adjustment_policy_id, policy version, and one or more corporate action IDs. An adjustment is returned only if all referenced actions are themselves visible. Symbol mapping events retain the permanent security ID and source action.

US sessions use America/New_York and return timezone-aware pre-market, regular, and post-market timestamps. Closed sessions contain no trading timestamps; early close sessions are explicitly typed.

The deterministic contract fixture currently carries the complete 2024 US market calendar under us-market-calendar-2024.1. Requests for another calendar year, or requests whose as_of predates publication of that calendar version, return an empty session set with structured provider_status.coverage_status=unavailable instead of extrapolating or fabricating a session.

The prepared production us_market_session reader uses persisted official calendar facts, with an exact MIC and session date. It shares the existing permission, output-policy, audit and source-evidence boundary. The 2024 fixture is confined to contract tests. A schedule may describe a future trading day already published by the exchange; its public-known and actual capture times must still precede as_of. Missing dates remain empty, and records lacking verified historical raw-capture links report partial coverage. They are not reconstructed from the fixture.

The production DataPackage exposes original normalized fields such as market_calendar.value.session_type, regular_open, regular_close, and calendar_version, with source licenses and evidence locators. Existing normalization represents a source JSON null as the string "null"; a closed session has no usable trading timestamp. Its coverage still requires verification.

Provider, quality, latency, and license status

The prepared market_session_fact_package implementation assembles actual captured market observations and the cited XNYS reference calendar for the requested US date. It does not turn the supplied symbols, session or date into vendor facts. Supply up to 100 distinct US symbols; SPY and SPY.US select the same explicitly US-qualified symbol, without inferring another market or a historical ticker mapping.

us_pre_market_close selects source pre-market open up to regular open, us_midday selects regular open up to noon in America/New_York, and us_regular_close includes the actual exchange close. Source half-days and DST times govern these boundaries. Daily bars are eligible only for regular close; they cannot prove an intraday result. Observations and their capture, known and license times must all be visible at as_of. Request parameters never replace missing calendar hours or source observations.

Returned market_observation.value.* fields retain provider timestamps, currency, interval, adjustment policy, source evidence, and captured license terms. Prices and quantities preserve decimal lexical values; missing quantity units are not inferred. Missing symbols have individual coverage gaps. A finite capture without a complete-session manifest remains partial, even when every requested symbol has observations. This reader still requires ordinary-user verification and full range/provider coverage; an UNKNOWN EODHD license is not an entitlement.

The prepared equity_market_data, market_bars, market_quote, and market_trades wrapper keeps the existing payload JSON fact. Each returned observation must match an intact eligible raw-linked normalization capture for the actual permanent security ID, observation ID, provider, license, source values and extraction/mapping versions. It uses the latest capture, rejects conflicting captures, and preserves decimal strings. A later correction cannot be bypassed by matching an older capture. Receive/known and license capture times are taken from the selected capture rather than the query timestamp.

The package also returns its contributing market_observation.value.* facts, their actual source checksums and license scopes. These fields let the shared boundary enforce source field restrictions on the nested JSON result. Its observation evidence IDs are replaced with the exact source locators so evidence lookup closes against the raw capture. Captured UNKNOWN or missing license terms remain UNKNOWN, including in nested provider metadata; a successful query does not establish subscription or redistribution rights. Typed records without a matching source capture are omitted with an explicit coverage gap. Corporate actions, adjustments and mapping events without their own verified captures are also omitted with a gap. A finite capture remains partial until coverage is verified. These behaviors are deployed in 1.1.15 and read persisted captures. Existing market record filters still require source policy eligibility; an administrative gate being disabled does not verify EODHD rights.

Every ETF, market, and option payload has a structured provider_status array. Each entry reports coverage, delay class and seconds, missing fields, license ID and status, redistribution, and availability restrictions. Missing or delayed fields are never hidden by a prose fallback.

Option boundary

Option output is limited to contract master, chain membership, quote values, open interest, volume, and provider-supplied greeks. Greek metadata includes provider, model name and version, input version and observation time, underlying price, and available rate, yield, and volatility inputs.

All option models are closed schemas. Strategy, signal, recommendation, position, portfolio, trade, account, order, ranking, or explanatory fields are invalid. Argus does not calculate trading meaning from option data.

P3 does not add screeners, sorting/ranking, dataset export, derived indicators, strategy execution, or any write-side market capability.

Bounded market observation pages

Registry v17 introduces input v2 for equity_market_data, market_bars, market_quote, and market_trades. Each request returns at most 100 observations by default as the requested upper bound; limit accepts 1 through 200. The service currently reads at most 25 typed observations per actual page because every observation includes its complete governed source-field bundle. The actual bound is reported in pagination.limit; follow continuation to obtain the remainder. Optional inclusive start_time and end_time filter observation event times. Source fields for one observation remain together, with their precision, checksums and captured source terms.

Set an explicit as_of for the first query and preserve it on every continuation. Read result.next_cursor (also in the typed payload's pagination.next_cursor) and send it with the same security ID, time window, purpose and authenticated identity. Continue until it is absent. The page orders observations by event time and observation ID. pagination.scanned includes invalid rows that were skipped; pagination.returned counts verified observations. A page can contain no verified facts and still carry a continuation. A changed cutoff or identity invalidates the cursor. Current permission and source-field policies are checked again.

The final page means that the visible stored window was consumed. It does not prove a complete tape, full US stock/ETF coverage, continuous capture or historical backfill. Those gaps remain partial even after next_cursor becomes null. Use the actual production cutoff from your invocation; verify available sources and capture windows through the diagnostic agent_data_preflight and data_freshness_manifest tools.

market_session_fact_package also accepts limit (default 100, maximum 200) and cursor. Its limit counts normalized market observation facts; one captured observation can supply several source fields across pages. Preserve the explicit as_of, market, session, date, symbol set, purpose and authenticated identity. Follow result.next_cursor until null and combine observation fact IDs without duplicates. The cited calendar facts repeat on every page as context. Latest visible captured license versions and current permissions apply on every page. Exhausting this stored session keeps its complete-session coverage gap.