Latest or dated ETF snapshot

Single ETF snapshot at the latest cycle (default) or at a specific calendar date via ?date=YYYY-MM-DD. Returns the full payload: pricing (nav, price, premium/discount), fund characteristics (AUM, expense ratio, yields), top-10 holdings sample, sector weightings (both raw + canonical), asset-class and country exposure, and trailing returns. Returns 410 Gone when the symbol is flagged as delisted_candidate by the upstream cycle, and also when its universe row carries removed_at - the fund was delisted and the date in the response body is its own Form 25, the exchange's notice of removal from listing. Those rows stay listed by /etf/snapshot/universe with status removed rather than vanishing, so a client that integrated against a covered symbol gets a dated explanation instead of unknown_symbol.

The canonical snapshot is rebuilt purely from Tier S sources (regulated-exchange price + SEC NPORT-P holdings), with no commercial aggregator in the chain. A field with no source yet is returned as null and tagged in the internal _sources.deferred map. That set has SHRUNK: nav/aum_usd and expense_ratio_pct/yield_dividend_pct/yield_distribution_pct/inception_date are now POPULATED from SEC filings, and premium_discount_pct is derived from the SEC NAV against the regulated-exchange price above. All are re-deferred only PER SYMBOL when that symbol's own input is missing. The following exceptions are deliberate rather than gaps: premium_discount_pct is null for a daily-reset leveraged or inverse fund because its NAV is period-stale; premium_discount_pct is also null where the fund's share basis moved by a split that the filing we read for it does not carry, so the NAV and the price are on different bases and a ratio between them would be the split factor rather than a premium (that symbol's deferred reason names the filing and the split's effective date); and inception_date is null wherever the filing states none for that fund. Still deferred for every symbol: returns_* and fifty_two_week_high/fifty_two_week_low.

When price is null but a NAV is available, an additive price_proxy block surfaces the NAV as an explicitly-stale proxy (basis = nav with an as_of SEC-filing date that can be months old and a note disclaiming a current quote). price itself stays null - the proxy is never presented as a live quote. The block is absent when price is present or when nav is also null.

price is also null when a quote WAS read and refused because nothing in it establishes that it is current. Five reasons, named in _sources.deferred.price with the upstream instant appended when one can be stated: no_trade_time (the feed's own placeholder instead of a last-trade time), last_trade_stale and quote_stale (the feed's timestamps are past the ceiling), quote_not_refetched (our own ingest has not re-read the symbol), and freshness_unverifiable (timestamps present but unreadable). On a refusal the _sources.price entry is ABSENT - it exists only for a published value - so read deferred.price, not a missing as_of, to detect the case. When price IS published, _sources.price.as_of is the feed's own timestamp in UTC (when it last rebuilt that quote), never our download time, which rides beside it as fetched_at; as_of can be null when no upstream instant is available, and it does not fall back.