Crate thetadatadx

Expand description

§thetadatadx — No-JVM `ThetaData` Terminal

Native Rust SDK that connects directly to ThetaData’s upstream servers, eliminating the Java terminal entirely. No JVM, no subprocess, no local proxy — just your application speaking the same wire protocol the terminal uses.

§Data types live in `tdbe`

Tick types (TradeTick, EodTick, …), Price, enums (SecType, DataType), the FIT/FIE codecs, and the Greeks calculator have been extracted into the tdbe crate. This crate re-exports what it needs, but if you only want types and offline Greeks, depend on tdbe directly.

§Architecture

ThetaData exposes two upstream services:

MDDS (Market Data Distribution Server) — historical data via gRPC at mdds-01.thetadata.us:443
FPSS (Feed Processing Streaming Server) — real-time streaming via custom TCP at nj-a.thetadata.us:20000

This crate speaks both protocols natively, handling authentication, request building, response decompression, and tick parsing entirely in Rust.

§Quick Start

The recommended entry point is ThetaDataDxClient, which authenticates once and provides both historical and streaming through a single object:

use thetadatadx::{ThetaDataDxClient, Credentials, DirectConfig};
use thetadatadx::fpss::{FpssData, FpssEvent};
use thetadatadx::fpss::protocol::Contract;

let creds = Credentials::from_file("creds.txt")?;
// Or inline: let creds = Credentials::new("user@example.com", "your-password");

// Connect -- authenticates once, historical ready immediately
let tdx = ThetaDataDxClient::connect(&creds, DirectConfig::production()).await?;

// Historical (MDDS gRPC) -- every generated method via Deref
let ticks = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;

// Streaming (FPSS TCP) -- connects lazily on first call
tdx.start_streaming(|event: &FpssEvent| {
    if let FpssEvent::Data(FpssData::Trade { contract, price, size, .. }) = event {
        println!("Trade: {} @ {price} x {size}", contract.symbol);
    }
})?;

tdx.subscribe(Contract::stock("AAPL").quote())?;

// ... when done:
tdx.stop_streaming();

For historical-only usage, just skip start_streaming() – every historical methods are available directly on ThetaDataDxClient via Deref<Target = MddsClient>:

use thetadatadx::{ThetaDataDxClient, Credentials, DirectConfig};

let creds = Credentials::from_file("creds.txt")?;
// Or inline: let creds = Credentials::new("user@example.com", "your-password");
let tdx = ThetaDataDxClient::connect(&creds, DirectConfig::production()).await?;
let ticks = tdx.stock_history_eod("AAPL", "20240101", "20240301").await?;

§Wire protocol

Proto definitions: crates/thetadatadx/proto/mdds.proto — single BetaEndpoints package, 60 RPCs, BetaThetaTerminal service.
Auth flow: POST to https://nexus-api.thetadata.us/identity/terminal/auth_user with header TD-TERMINAL-KEY and JSON {email, password} → SessionInfoV3 with UUID.
MDDS: Standard gRPC server-streaming over TLS. Session UUID embedded in QueryInfo.auth_token field of every request (in-band, not metadata).
FPSS: Custom TLS-over-TCP protocol. 1-byte length + 1-byte message code + payload. FIT nibble encoding (4-bit variable-length integers) with delta compression for ticks.

See proto/MAINTENANCE.md for how to update the proto file and regenerate stubs when ThetaData ships a new version.

Re-exports§

pub use mdds::endpoint_args as endpoint;
pub use mdds::decode;
pub use auth::Credentials;
pub use fpss::protocol::Contract;
pub use fpss::protocol::ContractParseError;
pub use fpss::protocol::FullSubscriptionKind;
pub use fpss::protocol::SecTypeExt;
pub use fpss::protocol::Subscription;
pub use fpss::protocol::SubscriptionKind;
pub use fpss::EventIterator;
pub use fpss::NextEvent;
pub use config::DirectConfig;
pub use config::FallbackPolicy;
pub use config::FlatFilesConfig;
pub use config::FpssFlushMode;
pub use config::ReconnectAttemptClass;
pub use config::ReconnectAttemptLimits;
pub use config::ReconnectPolicy;
pub use config::RetryPolicy;
pub use config::RuntimeConfig;
pub use config::DEFAULT_REST_BASE_URL;
pub use error::AuthErrorKind;
pub use error::Error;
pub use error::FpssErrorKind;
pub use flatfiles::default_output_filename as flatfile_default_filename;
pub use flatfiles::flatfile_request;
pub use flatfiles::flatfile_request_decoded;
pub use flatfiles::flatfile_request_raw;
pub use flatfiles::FlatFileFormat;
pub use flatfiles::FlatFileRow;
pub use flatfiles::FlatFileValue;
pub use flatfiles::FlatFilesUnavailableReason;
pub use flatfiles::ReqType as FlatFileReqType;
pub use flatfiles::SecType as FlatFileSecType;
pub use mdds::endpoint_args::EndpointArgValue;
pub use mdds::endpoint_args::EndpointArgs;
pub use mdds::endpoint_args::EndpointError;
pub use mdds::endpoint_args::EndpointOutput;
pub use mdds::MddsClient;
pub use mdds::SubscriptionTier;

Modules§

auth: Authentication for ThetaData direct server access.
config: Server configuration for direct ThetaData access.
error
flatfiles: FLATFILES: whole-universe daily snapshots over the legacy MDDS port. Pulls one INDEX + DATA blob per (SecType, ReqType, date) tuple and emits CSV, JSONL, or Vec<FlatFileRow>.
fpss: FPSS real-time streaming client.
framesarrow or polars: DataFrame extension traits — .to_polars() / .to_arrow() on &[Tick].
mdds: MDDS (Market Data Distribution Server) gRPC client.
prelude: Convenience prelude for the fluent contract-first API.
rest: REST transport for the local ThetaTerminal HTTP API.
util: Cross-cutting utilities shared by multiple subsystems.
utils
wire: gRPC wire-payload re-exports for offline-decode callers.

Structs§

CalendarDay: Calendar day – 5 fields. Market open/close schedule.
EndpointMeta: Metadata for a single endpoint.
EodTick: End-of-day tick – 17 fields. Full EOD snapshot with OHLC + quote.
GreeksAllTick: Full union Greeks tick – every Greek the v3 server publishes on the option_*_greeks_all and option_*_greeks_eod endpoints.
GreeksEodTick: End-of-day union Greeks tick – every Greek the v3 server publishes on option_history_greeks_eod, paired with the twelve EOD trade/quote context columns (open, high, low, close, volume, count, bid_size, bid_exchange, bid_condition, ask_size, ask_exchange, ask_condition) that identify the daily bar + closing NBBO snapshot the Greeks were calculated against.
GreeksFirstOrderTick: First-order Greeks tick – the strict column subset emitted by the vendor’s option_*_greeks_first_order endpoints (delta / theta / vega / rho / epsilon / lambda) plus the bid/ask quote pair, the IV pair, and the underlying snapshot used to derive each Greek.
GreeksResult: All Greeks computed in a single struct.
GreeksSecondOrderTick: Second-order Greeks tick – the strict column subset emitted by the vendor’s option_*_greeks_second_order endpoints (gamma / vanna / charm / vomma / veta) plus the bid/ask quote pair, the IV pair, and the underlying snapshot.
GreeksThirdOrderTick: Third-order Greeks tick – the strict column subset emitted by the vendor’s option_*_greeks_third_order endpoints (speed / zomma / color / ultima) plus the bid/ask quote pair, the IV pair, and the underlying snapshot. The vendor’s third-order schema does not publish vera.
IndexPriceAtTimeTick: Index price-at-time tick – the trade-shaped row the v3 server publishes on index_at_time_price. The bare PriceTick (3 fields: ms_of_day, price, date) silently dropped seven server-emitted columns – sequence, ext_condition1..4, condition, size, exchange – including the SIP-exchange attribution field.
InterestRateTick: Interest rate tick – 2 fields. End-of-day interest rate (percent).
IvTick: Implied volatility tick – 11 fields.
MarketValueTick: Market value tick – quoted bid/ask/price for a symbol.
OhlcTick: OHLC tick – 9 fields. Aggregated bar data including SIP-rule VWAP.
OpenInterestTick: Open interest tick – 3 fields.
OptionContract: Option contract – 4 fields. Contract specification.
ParamMeta: Metadata for a single parameter.
Price: Fixed-point price with variable decimal precision.
PriceTick: Price tick – 3 fields. Generic price data point.
QuoteTick: Quote tick – 10 fields + midpoint. NBBO quote data.
SubscriptionInfo: Subscription tier information captured at authentication time.
ThetaDataDxClient: Unified ThetaData client.
TradeGreeksAllTick: Per-trade union Greeks tick – every Greek the v3 server publishes on option_history_trade_greeks_all, paired with the trade-side execution columns (sequence, ext_condition1..4, condition, size, exchange, price) that identify which OPRA print each Greek was calculated against.
TradeGreeksFirstOrderTick: Per-trade first-order Greeks tick (delta / theta / vega / rho / epsilon / lambda) paired with the trade-side execution columns identifying the OPRA print each Greek was calculated against. Wire layout verified-live against terminal jar build 202605221.
TradeGreeksImpliedVolatilityTick: Per-trade implied-volatility tick (single implied_volatility + iv_error pair, NOT the bid/mid/ask IV triple of the interval-sampled IvTick) paired with the trade-side execution columns identifying the OPRA print the IV was calculated against. Wire layout verified-live against terminal jar build 202605221.
TradeGreeksSecondOrderTick: Per-trade second-order Greeks tick (gamma / vanna / charm / vomma / veta) paired with the trade-side execution columns identifying the OPRA print each Greek was calculated against. Wire layout verified-live against terminal jar build 202605221.
TradeGreeksThirdOrderTick: Per-trade third-order Greeks tick (speed / zomma / color / ultima) paired with the trade-side execution columns identifying the OPRA print each Greek was calculated against. The vendor’s third-order schema does not publish vera. Wire layout verified-live against terminal jar build 202605221.
TradeQuoteTick: Combined trade + quote tick – 24 fields.
TradeTick: Trade tick – 15 fields. Core unit of trade data.

Enums§

ConnectionStatus: Current state of the streaming connection.
DataType: Data field types returned in responses.
Interval: Wire string enum Interval.
ParamType
ParsedRight: Parsed representation of the option right parameter.
RateType: Wire string enum RateType.
RemoveReason: Disconnect reason codes.
RequestType: Wire string enum RequestType.
ReturnType
Right: Wire string enum Right.
SecType: Security type identifier.
StreamMsgType: Streaming message types for real-time data.
StreamResponseType: Streaming subscription response.
Venue: Wire string enum Venue.
Version: Wire string enum Version.

Constants§

CATEGORIES

Statics§

ENDPOINTS

Functions§

all_greeks: Compute all 23 Greeks at once with maximally shared intermediates.
by_category: All endpoints in a category.
find: Find an endpoint by its method name.
implied_volatility: Implied volatility solver using bisection. Returns (iv, error) on success.
param_type_to_json_type
parse_right: Parse a user-supplied right string.
parse_right_strict: Parse a right that must resolve to a single side (call or put).