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.