fix: align endpoint docs with upstream operations + interval normaliser (#527)

* docs(option/history): align option_history_quote with upstream

Mirror the upstream operation spec at docs.thetadata.us/operations/
option_history_quote.html. The previous doc claimed `interval="0"`
returned every quote change tick-by-tick; that value is not in the
upstream enum and the SDK silently normalises it to `100ms`. Replace
with the documented presets (tick / 10ms / .../ 1h) and default 1s.

Mark `strike` and `right` optional (default `*` and `both`); they are
optional at the wire level and the SDK builder treats them the same
way. Correct `start_time` / `end_time` to HH:MM:SS.SSS wall-clock with
the upstream defaults (09:30:00 / 16:00:00). Add `start_date` /
`end_date` for multi-day requests and document the one-month / must-
specify-expiration constraints called out by the upstream spec.

Refs ThetaData v3 spec for /v3/option/history/quote.

* docs(option/history): align trade/ohlc/eod/open_interest/trade_quote

Mirror the upstream operation specs at docs.thetadata.us/operations/
for the option_history_{trade, ohlc, eod, open_interest, trade_quote}
endpoints.

Common fixes across the family:
- strike and right are optional with default `*` and `both` (the SDK
  was already constructing the wire wildcards through wire_strike_opt
  / wire_right_opt; only the doc badge was wrong).
- start_time / end_time take HH:MM:SS.SSS wall-clock with defaults
  09:30:00 / 16:00:00, not 'milliseconds from midnight'.
- expiration accepts YYYY-MM-DD as well as YYYYMMDD, plus `*` for
  all expirations.
- Add start_date / end_date as builder optionals; document the
  single-`date` override semantics from upstream.
- Call out the upstream one-month / must-specify-expiration ceiling
  on multi-day requests.

ohlc additionally pulls the new `tick` and `10ms` presets into the
interval enum and marks interval optional with default `1s`.
trade_quote additionally documents the `exclusive` flag with its
upstream `true` default.

* docs(option/history): align greeks family with upstream

Apply the same parity sweep to the 11 greeks endpoints:
option_history_greeks_{all, eod, implied_volatility, first_order,
second_order, third_order} and
option_history_trade_greeks_{all, implied_volatility, first_order,
second_order, third_order}.

For each:
- strike / right marked optional with upstream defaults (`*` / `both`)
- start_time / end_time documented as HH:MM:SS.SSS with the upstream
  09:30:00 / 16:00:00 defaults
- expiration accepts YYYY-MM-DD and YYYYMMDD plus `*`
- interval (where applicable) marked optional, default `1s`, enum
  extended to include `tick` and `10ms`
- Greeks inputs (annual_dividend, rate_type with full Treasury enum,
  rate_value, version) documented with their upstream defaults and
  allowed values
- start_date / end_date listed as builder optionals on the intraday
  greeks endpoints; greeks_eod keeps start_date / end_date required
  per upstream
- underlyer_use_nbbo (greeks_eod only) documents its `false` default

Multi-day one-month / must-specify-expiration ceiling called out where
upstream documents it.

* docs(option/{at_time,snapshot,list}): align param surface with upstream

Same parity sweep as the option/history family — strike and right are
optional with default `*` and `both`; min_time on snapshot endpoints
is HH:MM:SS.SSS, not milliseconds; expiration accepts YYYY-MM-DD and
wildcard `*`; Greeks-input defaults documented.

option_list_dates and option_list_contracts: request_type lower-case
trade/quote is the upstream enum; SDK still accepts the historical
TRADE/QUOTE casing.

option_list_strikes already mirrored upstream exactly — no change
needed.

* docs(stock,index): align interval / time / venue surface with upstream

Apply the same parity sweep to the stock and index history /
snapshot / at_time pages. interval is optional with a `1s` default
and the upstream enum extended to `tick` and `10ms`. start_time /
end_time are documented as HH:MM:SS.SSS ET wall-clock with the
upstream 09:30:00 / 16:00:00 defaults instead of 'milliseconds from
midnight'. The `Use "0"` claim is removed across the board — the
SDK does not have a tick-by-tick sentinel that maps to a real
upstream value, and the doc was implying behaviour the wire does
not expose.

venue (stock-only) is documented with the upstream `nqb` / `utp_cta`
enum and `nqb` default. min_time on stock snapshots takes the same
HH:MM:SS.SSS form.

stock_history_trade_quote: exclusive flag documented with the `true`
upstream default.

* fix(mdds): align interval normalisation and validator with upstream

normalize_interval now maps `"0"` to `"tick"` instead of `"100ms"`.
The historical mapping contradicted the previously-documented
every-event semantics — the upstream enum spells that as `tick`, and
the SDK silently downgraded user requests to a 100ms sample without
warning. Mapping `0` to `tick` makes the behaviour match the doc
without breaking callers that picked an interval explicitly. The
small-ms snap range now also exposes `10ms`, which is the upstream
preset between `tick` and `100ms` that the SDK previously skipped.

validate_interval (CLI / MCP entry point) now enforces the upstream
enum verbatim plus the SDK's millisecond shorthand. Garbage strings
like `"twosec"` are rejected up front with a typed error listing the
accepted values, instead of being passed through to the gRPC layer
where they used to surface as opaque server-side rejections.

Mirrors the upstream operation specs at
`docs.thetadata.us/operations/option_history_quote.html` (and the
other 14 endpoints that carry an `interval` parameter).

* docs(option/history): drop duplicate greeks_eod param block + zero-sentinel

The earlier rewrite left a stale copy of the pre-alignment param
list at the bottom of greeks_eod.md, which broke the VitePress
build. Remove the duplicate and rewrite the option_history_eod
multi-strike note to use the upstream `strike="*"` wildcard
vocabulary instead of the SDK-only `"0"` sentinel that contradicted
the rest of the alignment sweep.

Author: userFRM

crates/thetadatadx/src/mdds/endpoints.rs

@@ -99,24 +99,35 @@ impl From<&[String]> for SymbolInput {
 /// Convert an interval to the format the MDDS gRPC server accepts.
 ///
 /// Users can pass either:
-/// - Milliseconds as a string: `"60000"`, `"300000"`, `"900000"`
-/// - Shorthand directly: `"1m"`, `"5m"`, `"1h"`
+/// - Shorthand directly: `"tick"`, `"10ms"`, `"100ms"`, `"500ms"`,
+///   `"1s"`, `"5s"`, `"10s"`, `"15s"`, `"30s"`, `"1m"`, `"5m"`,
+///   `"10m"`, `"15m"`, `"30m"`, `"1h"`.
+/// - Milliseconds as a string (e.g. `"60000"` or `"300000"`). Values
+///   are snapped to the nearest documented preset.
 ///
-/// The server accepts these specific presets:
-/// `100ms`, `500ms`, `1s`, `5s`, `10s`, `15s`, `30s`, `1m`, `5m`, `10m`,
-/// `15m`, `30m`, `1h`.
+/// The full upstream enum is reproduced verbatim in
+/// `docs.thetadata.us/operations/option_history_quote.html` (and every
+/// other endpoint with an `interval` parameter).
 ///
-/// If milliseconds are passed, they're converted to the nearest matching
-/// preset. If already a valid shorthand (contains 's', 'm', or 'h'), the
-/// value is passed through as-is.
+/// The historical SDK accepted `"0"` and silently mapped it to
+/// `"100ms"`. That contradicted the previously-documented behaviour
+/// (`"0"` was advertised as "every quote change"), so `"0"` now snaps
+/// to `"tick"` — which is the upstream every-event vocabulary. Calls
+/// that depended on the silent-100ms behaviour should switch to an
+/// explicit preset.
 fn normalize_interval(interval: &str) -> String {
     if interval.ends_with('s') || interval.ends_with('m') || interval.ends_with('h') {
         return interval.to_string();
     }
+    if interval == "tick" {
+        return "tick".to_string();
+    }
 
     match interval.parse::<u64>() {
         Ok(ms) => match ms {
-            0..=100 => "100ms".to_string(),
+            0 => "tick".to_string(),
+            1..=10 => "10ms".to_string(),
+            11..=100 => "100ms".to_string(),
             101..=500 => "500ms".to_string(),
             501..=1000 => "1s".to_string(),
             1_001..=5_000 => "5s".to_string(),
@@ -269,6 +280,8 @@ mod tests {
 
     #[test]
     fn normalize_interval_passes_shorthand_through() {
+        assert_eq!(normalize_interval("tick"), "tick");
+        assert_eq!(normalize_interval("10ms"), "10ms");
         assert_eq!(normalize_interval("1m"), "1m");
         assert_eq!(normalize_interval("5m"), "5m");
         assert_eq!(normalize_interval("1h"), "1h");
@@ -281,4 +294,22 @@ mod tests {
         assert_eq!(normalize_interval("900000"), "15m");
         assert_eq!(normalize_interval("3600000"), "1h");
     }
+
+    #[test]
+    fn normalize_interval_snaps_zero_to_tick() {
+        // The historical mapping was `0 -> 100ms`, which contradicted
+        // the previously-documented every-event semantics. The upstream
+        // `tick` keyword is the every-event vocabulary, so the zero
+        // sentinel snaps to it instead.
+        assert_eq!(normalize_interval("0"), "tick");
+    }
+
+    #[test]
+    fn normalize_interval_snaps_small_milliseconds_to_documented_presets() {
+        // 10ms-and-under -> 10ms; 11-100ms -> 100ms. The earlier
+        // 0..=100 -> 100ms mapping skipped the 10ms preset entirely.
+        assert_eq!(normalize_interval("10"), "10ms");
+        assert_eq!(normalize_interval("11"), "100ms");
+        assert_eq!(normalize_interval("100"), "100ms");
+    }
 }

crates/thetadatadx/src/mdds/validate.rs

@@ -88,13 +88,40 @@ pub(crate) fn validate_symbol(value: &str, param_name: &str) -> Result<(), Endpo
     Ok(())
 }
 
+/// The exact set of `interval` strings the v3 ThetaData server accepts.
+///
+/// Mirrors the upstream enum at
+/// `https://docs.thetadata.us/operations/option_history_quote.html`.
+/// The SDK additionally accepts decimal millisecond shorthand
+/// (`"60000"`, `"300000"`, ...) and snaps it to the nearest preset via
+/// [`crate::mdds::endpoints::normalize_interval`]; this validator
+/// recognises both shapes so the CLI / MCP layer rejects garbage
+/// before the gRPC dispatch.
+const VALID_INTERVAL_PRESETS: &[&str] = &[
+    "tick", "10ms", "100ms", "500ms", "1s", "5s", "10s", "15s", "30s", "1m", "5m", "10m", "15m",
+    "30m", "1h",
+];
+
 pub(crate) fn validate_interval(value: &str, param_name: &str) -> Result<(), EndpointError> {
-    if value.is_empty() || !value.bytes().all(|b| b.is_ascii_alphanumeric()) {
+    if value.is_empty() {
         return Err(EndpointError::InvalidParams(format!(
-            "'{param_name}' must be a non-empty alphanumeric string (e.g. '60000' or '1m'), got: '{value}'"
+            "'{param_name}' must be a non-empty string from the upstream enum ({}) or a millisecond value (e.g. '60000'), got empty string",
+            VALID_INTERVAL_PRESETS.join(", "),
         )));
     }
-    Ok(())
+    if VALID_INTERVAL_PRESETS.contains(&value) {
+        return Ok(());
+    }
+    if value.bytes().all(|b| b.is_ascii_digit()) {
+        // Millisecond shorthand: `normalize_interval` will snap to the
+        // nearest documented preset. Any positive integer is accepted
+        // here; the snap range covers `0` (-> "tick") through `1h`.
+        return Ok(());
+    }
+    Err(EndpointError::InvalidParams(format!(
+        "'{param_name}' must be one of the upstream presets ({}) or a millisecond value (e.g. '60000'), got: '{value}'",
+        VALID_INTERVAL_PRESETS.join(", "),
+    )))
 }
 
 pub(crate) fn validate_right(value: &str, param_name: &str) -> Result<(), EndpointError> {
@@ -241,4 +268,21 @@ mod tests {
             assert!(validate_strike(bad, "strike").is_err(), "{bad}");
         }
     }
+
+    #[test]
+    fn interval_accepts_upstream_enum_and_ms_shorthand() {
+        for good in [
+            "tick", "10ms", "100ms", "500ms", "1s", "5s", "10s", "15s", "30s", "1m", "5m", "10m",
+            "15m", "30m", "1h", "0", "60000", "300000",
+        ] {
+            assert!(validate_interval(good, "interval").is_ok(), "{good}");
+        }
+    }
+
+    #[test]
+    fn interval_rejects_garbage() {
+        for bad in ["", "twosec", "2sec", "1minute", "-1", "1.5s", "1 s", "*"] {
+            assert!(validate_interval(bad, "interval").is_err(), "{bad}");
+        }
+    }
 }

docs-site/docs/historical/index-data/history/ohlc.md

@@ -56,16 +56,16 @@ for (const auto& t : data) {
 <div class="param-desc">End date in <code>YYYYMMDD</code> format</div>
 </div>
 <div class="param">
-<div class="param-header"><code>interval</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Accepts milliseconds (<code>"60000"</code>) or shorthand (<code>"1m"</code>). Valid presets: <code>100ms</code>, <code>500ms</code>, <code>1s</code>, <code>5s</code>, <code>10s</code>, <code>15s</code>, <code>30s</code>, <code>1m</code>, <code>5m</code>, <code>10m</code>, <code>15m</code>, <code>30m</code>, <code>1h</code>.</div>
+<div class="param-header"><code>interval</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Sampling interval. Allowed values: <code>tick</code>, <code>10ms</code>, <code>100ms</code>, <code>500ms</code>, <code>1s</code>, <code>5s</code>, <code>10s</code>, <code>15s</code>, <code>30s</code>, <code>1m</code>, <code>5m</code>, <code>10m</code>, <code>15m</code>, <code>30m</code>, <code>1h</code>. Millisecond strings (e.g. <code>"60000"</code>) are accepted and snapped to the nearest preset. Default: <code>"1s"</code>. Sub-minute intervals are available only for single-day requests.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>start_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Start time of day as milliseconds from midnight</div>
+<div class="param-desc">Start time (inclusive) in <code>HH:MM:SS.SSS</code> ET wall-clock format. Default: <code>"09:30:00"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>end_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">End time of day as milliseconds from midnight</div>
+<div class="param-desc">End time (inclusive) in <code>HH:MM:SS.SSS</code> ET wall-clock format. Default: <code>"16:00:00"</code>.</div>
 </div>
 </div>
 

docs-site/docs/historical/index-data/history/price.md

@@ -49,16 +49,16 @@ for (const auto& t : data) {
 <div class="param-desc">Date in <code>YYYYMMDD</code> format</div>
 </div>
 <div class="param">
-<div class="param-header"><code>interval</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Accepts milliseconds (<code>"60000"</code>) or shorthand (<code>"1m"</code>). Valid presets: <code>100ms</code>, <code>500ms</code>, <code>1s</code>, <code>5s</code>, <code>10s</code>, <code>15s</code>, <code>30s</code>, <code>1m</code>, <code>5m</code>, <code>10m</code>, <code>15m</code>, <code>30m</code>, <code>1h</code>.</div>
+<div class="param-header"><code>interval</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Sampling interval. Allowed values: <code>tick</code>, <code>10ms</code>, <code>100ms</code>, <code>500ms</code>, <code>1s</code>, <code>5s</code>, <code>10s</code>, <code>15s</code>, <code>30s</code>, <code>1m</code>, <code>5m</code>, <code>10m</code>, <code>15m</code>, <code>30m</code>, <code>1h</code>. Millisecond strings (e.g. <code>"60000"</code>) are accepted and snapped to the nearest preset. Default: <code>"1s"</code>. Sub-minute intervals are available only for single-day requests.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>start_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Start time of day as milliseconds from midnight</div>
+<div class="param-desc">Start time (inclusive) in <code>HH:MM:SS.SSS</code> ET wall-clock format. Default: <code>"09:30:00"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>end_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">End time of day as milliseconds from midnight</div>
+<div class="param-desc">End time (inclusive) in <code>HH:MM:SS.SSS</code> ET wall-clock format. Default: <code>"16:00:00"</code>.</div>
 </div>
 </div>
 

docs-site/docs/historical/index-data/snapshot/market-value.md

@@ -49,7 +49,7 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>min_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Minimum time of day as milliseconds from midnight</div>
+<div class="param-desc">Filters snapshots to timestamps at or after this ET wall-clock time. Format <code>HH:MM:SS.SSS</code>; legacy millisecond strings are also accepted.</div>
 </div>
 </div>
 

docs-site/docs/historical/index-data/snapshot/ohlc.md

@@ -49,7 +49,7 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>min_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Minimum time of day as milliseconds from midnight</div>
+<div class="param-desc">Filters snapshots to timestamps at or after this ET wall-clock time. Format <code>HH:MM:SS.SSS</code>; legacy millisecond strings are also accepted.</div>
 </div>
 </div>
 

docs-site/docs/historical/index-data/snapshot/price.md

@@ -46,7 +46,7 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>min_time</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Minimum time of day as milliseconds from midnight</div>
+<div class="param-desc">Filters snapshots to timestamps at or after this ET wall-clock time. Format <code>HH:MM:SS.SSS</code>; legacy millisecond strings are also accepted.</div>
 </div>
 </div>
 

docs-site/docs/historical/option/at-time/quote.md

@@ -49,15 +49,15 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>expiration</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Expiration date in <code>YYYYMMDD</code> format</div>
+<div class="param-desc">Expiration date in <code>YYYYMMDD</code> or <code>YYYY-MM-DD</code> format, or <code>"*"</code> for all expirations</div>
 </div>
 <div class="param">
-<div class="param-header"><code>strike</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Strike price in dollars as a string</div>
+<div class="param-header"><code>strike</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Strike price in dollars (e.g. <code>"550"</code> or <code>"17.5"</code>), or <code>"*"</code> for all strikes. Default: <code>"*"</code>.</div>
 </div>
 <div class="param">
-<div class="param-header"><code>right</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc"><code>"C"</code> for call, <code>"P"</code> for put</div>
+<div class="param-header"><code>right</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Option side: <code>"call"</code>, <code>"put"</code>, or <code>"both"</code>. SDK also accepts <code>"C"</code>/<code>"P"</code>. Default: <code>"both"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>start_date</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
@@ -73,11 +73,11 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>max_dte</code><span class="param-type">int</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Maximum days to expiration</div>
+<div class="param-desc">Maximum days to expiration. Filters contracts returned when <code>expiration="*"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>strike_range</code><span class="param-type">int</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Strike range filter</div>
+<div class="param-desc">Returns <code>n</code> strikes above and below spot price plus one ATM strike (up to <code>2n + 1</code> strikes).</div>
 </div>
 </div>
 

docs-site/docs/historical/option/at-time/trade.md

@@ -47,15 +47,15 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>expiration</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Expiration date in <code>YYYYMMDD</code> format</div>
+<div class="param-desc">Expiration date in <code>YYYYMMDD</code> or <code>YYYY-MM-DD</code> format, or <code>"*"</code> for all expirations</div>
 </div>
 <div class="param">
-<div class="param-header"><code>strike</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc">Strike price in dollars as a string</div>
+<div class="param-header"><code>strike</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Strike price in dollars (e.g. <code>"550"</code> or <code>"17.5"</code>), or <code>"*"</code> for all strikes. Default: <code>"*"</code>.</div>
 </div>
 <div class="param">
-<div class="param-header"><code>right</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
-<div class="param-desc"><code>"C"</code> for call, <code>"P"</code> for put</div>
+<div class="param-header"><code>right</code><span class="param-type">string</span><span class="param-badge optional">optional</span></div>
+<div class="param-desc">Option side: <code>"call"</code>, <code>"put"</code>, or <code>"both"</code>. SDK also accepts <code>"C"</code>/<code>"P"</code>. Default: <code>"both"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>start_date</code><span class="param-type">string</span><span class="param-badge required">required</span></div>
@@ -71,11 +71,11 @@ for (const auto& t : data) {
 </div>
 <div class="param">
 <div class="param-header"><code>max_dte</code><span class="param-type">int</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Maximum days to expiration</div>
+<div class="param-desc">Maximum days to expiration. Filters contracts returned when <code>expiration="*"</code>.</div>
 </div>
 <div class="param">
 <div class="param-header"><code>strike_range</code><span class="param-type">int</span><span class="param-badge optional">optional</span></div>
-<div class="param-desc">Strike range filter</div>
+<div class="param-desc">Returns <code>n</code> strikes above and below spot price plus one ATM strike (up to <code>2n + 1</code> strikes).</div>
 </div>
 </div>