Struct MassiveRestClient 

pub struct MassiveRestClient { /* private fields */ }

REST client for Massive historical and intraday market data.

Example

use rustrade_data::exchange::massive::MassiveRestClient;
use chrono::{Utc, Duration};

let client = MassiveRestClient::from_env()?;
let to = Utc::now();
let from = to - Duration::days(1);

let mut stream = client.fetch_aggregates("X:BTCUSD", 1, "minute", from, to);
while let Some(candle) = stream.next().await {
    println!("{:?}", candle?);
}

Implementations

impl MassiveRestClient

pub async fn fetch_option_contracts( &self, query: &OptionContractQuery, ) -> Result<Vec<MassiveOptionContract>, MassiveError>

Fetch option contracts matching the query.

Automatically paginates through all results.

Subscription

Available on all Options plans including Basic (free tier).

Example

use rustrade_data::exchange::massive::{MassiveRestClient, OptionContractQuery};

let client = MassiveRestClient::from_env()?;
let query = OptionContractQuery::new()
    .underlying_ticker("AAPL")
    .contract_type(OptionKind::Call)
    .limit(100);

let contracts = client.fetch_option_contracts(&query).await?;
for c in &contracts {
    println!("{}: {} {} @ {}", c.ticker, c.expiration_date, c.contract_type, c.strike_price);
}

pub async fn fetch_option_chain_snapshot( &self, underlying: &str, query: &OptionSnapshotQuery, ) -> Result<Vec<MassiveOptionSnapshot>, MassiveError>

Fetch option chain snapshot for an underlying asset.

Returns all option contracts for the underlying with current market data including Greeks.

Subscription

Requires Options Starter or higher subscription. Data recency:

• Starter/Developer: 15-minute delayed
• Advanced/Business: Real-time

Note

Greeks may be None for deep ITM options. Rho is NOT available.

Example

use rustrade_data::exchange::massive::{MassiveRestClient, OptionSnapshotQuery};

let client = MassiveRestClient::from_env()?;
let query = OptionSnapshotQuery::new()
    .strike_price_gte(dec!(150))
    .strike_price_lte(dec!(200))
    .limit(50);

let snapshots = client.fetch_option_chain_snapshot("AAPL", &query).await?;
for snap in snapshots {
    if let Some(greeks) = &snap.greeks {
        println!("{}: delta={:?}", snap.contract.ticker, greeks.delta);
    }
}

pub async fn fetch_option_snapshot( &self, underlying: &str, contract: &str, ) -> Result<MassiveOptionSnapshot, MassiveError>

Fetch a single option contract snapshot.

Subscription

Requires Options Starter or higher subscription.

Arguments

• underlying - Underlying ticker (e.g., “AAPL”)
• contract - Option contract ticker (e.g., “O:AAPL251219C00150000”)

Example

let snapshot = client.fetch_option_snapshot("AAPL", "O:AAPL251219C00150000").await?;
println!("IV: {:?}, Delta: {:?}",
    snapshot.implied_volatility,
    snapshot.greeks.as_ref().and_then(|g| g.delta)
);

impl MassiveRestClient

pub fn fetch_tickers<'a>( &'a self, query: &'a TickerQuery, ) -> impl Stream<Item = Result<Ticker, MassiveError>> + 'a

Fetch all tickers matching the query.

Returns a stream that handles pagination automatically.

Example

let query = TickerQuery::new().market("stocks").active(true);
let mut stream = client.fetch_tickers(&query);
while let Some(ticker) = stream.next().await {
    println!("{:?}", ticker?);
}

pub async fn fetch_ticker_details( &self, ticker: &str, ) -> Result<TickerDetails, MassiveError>

Fetch detailed information for a single ticker.

Arguments

• ticker - Ticker symbol (e.g., “AAPL”, “X:BTCUSD”)

Example

let details = client.fetch_ticker_details("AAPL").await?;
println!("Market cap: {:?}", details.market_cap);

pub async fn fetch_exchanges( &self, asset_class: Option<&str>, locale: Option<&str>, ) -> Result<Vec<Exchange>, MassiveError>

Fetch all exchanges.

Arguments

• asset_class - Optional filter by asset class (stocks, crypto, fx, etc.)
• locale - Optional filter by locale (us, global)

Example

let exchanges = client.fetch_exchanges(Some("stocks"), Some("us")).await?;
for exchange in exchanges {
    println!("{}: {}", exchange.mic.unwrap_or_default(), exchange.name);
}

pub async fn fetch_market_status(&self) -> Result<MarketStatus, MassiveError>

Fetch current market status.

Returns the current trading status for various exchanges and overall markets.

Example

let status = client.fetch_market_status().await?;
println!("Market: {}, Crypto: {}", status.market, status.currencies.crypto);

pub async fn fetch_market_holidays( &self, ) -> Result<Vec<MarketHoliday>, MassiveError>

Fetch upcoming market holidays.

Returns a list of upcoming holidays with their corresponding open/close times.

Example

let holidays = client.fetch_market_holidays().await?;
for holiday in holidays {
    println!("{}: {} ({})", holiday.date, holiday.name, holiday.status);
}

pub fn fetch_dividends<'a>( &'a self, query: &'a DividendQuery, ) -> impl Stream<Item = Result<Dividend, MassiveError>> + 'a

Fetch dividends matching the query.

Returns a stream that handles pagination automatically.

Example

let query = DividendQuery::new().ticker("AAPL").limit(100);
let mut stream = client.fetch_dividends(&query);
while let Some(dividend) = stream.next().await {
    println!("{:?}", dividend?);
}

pub fn fetch_splits_raw<'a>( &'a self, query: &'a SplitQuery, ) -> impl Stream<Item = Result<StockSplit, MassiveError>> + 'a

Fetch stock splits matching the query.

Returns a stream that handles pagination automatically.

Example

let query = SplitQuery::new().ticker("AAPL").limit(100);
let mut stream = client.fetch_splits_raw(&query);
while let Some(split) = stream.next().await {
    println!("{:?}", split?);
}

impl MassiveRestClient

pub fn new(api_key: impl Into<String>) -> Result<Self, MassiveError>

Create a new client with explicit API key.

Arguments

• api_key - Massive API key from https://massive.com/dashboard/api-keys

Redirects

The client does not follow HTTP redirects. The API key is attached as an Authorization: Bearer header to each request, from a single origin-validated chokepoint, so auto-following a server-issued 3xx could carry it off the trusted origin. Massive uses explicit next_url cursor pagination and is not expected to redirect, so an unexpected 3xx surfaces as MassiveError::Api rather than being followed. A base URL set via Self::with_base_url must therefore serve responses directly, without redirect indirection.

Known limitation

Redirect-following is disabled wholesale (reqwest::redirect::Policy::none()), so this applies to same-origin redirects too: even a same-origin 301/308 — e.g. trailing-slash normalization by a load balancer or CDN — is surfaced as a terminal MassiveError::Api with the 3xx status rather than being transparently followed. This is a deliberate trade-off: a wholesale block keeps the “token never leaves the trusted origin” guarantee structural rather than dependent on reqwest’s cross-origin header-stripping. It relies on Massive serving next_url pages directly; a deployment fronted by a redirecting proxy is not supported.

pub fn from_env() -> Result<Self, MassiveError>

Create a new client from MASSIVE_API_KEY environment variable.

pub fn with_base_url( self, base_url: impl Into<String>, ) -> Result<Self, MassiveError>

Override the base URL (useful for testing or legacy polygon.io endpoint).

The base URL defines the trusted origin: a paginated next_url is followed only when it shares this scheme, host, and port, and redirects are never followed (see the “Redirects” note on Self::new). The origin is parsed and cached here, so a base_url that is not a valid URL is rejected up front with MassiveError::InvalidInput rather than deferred to the first request.

Errors

Returns MassiveError::InvalidInput if base_url does not parse as a URL, or if it parses but uses a scheme other than http/https — a non-special scheme (e.g. file:) yields an opaque origin that would reject every subsequent request, so it is refused up front.

pub fn fetch_aggregates<'a>( &'a self, ticker: &'a str, multiplier: u32, timespan: &'a str, from: DateTime<Utc>, to: DateTime<Utc>, ) -> impl Stream<Item = Result<Candle, MassiveError>> + 'a

Fetch aggregated OHLCV bars for a symbol.

Returns a stream that handles pagination automatically. Does not collect results into memory — processes each page as it arrives.

Each Candle’s close_time is the exclusive end-of-period boundary bar_open + interval (see Candle::close_time). Fixed units (second…week) are exact in UTC; calendar units (month/quarter/year) use leap-year-correct calendar arithmetic — e.g. a January monthly bar closes at Feb 1 00:00 UTC, aligning with Binance 1M / IBKR monthly boundaries (previously an approximate +30/91/365 days).

Range contract

Yields exactly the candles whose close_time ∈ [from, to] (both inclusive), matched on close_time — the field consumers receive. Massive’s endpoint natively filters by the bar’s open-time, so this method widens the request by one interval and trims by close_time, consistent with the library’s other historical fetches.

Arguments

• ticker - Symbol with asset class prefix (e.g., X:BTCUSD, C:EURUSD, AAPL)
• multiplier - Size of the timespan multiplier (e.g., 1, 5, 15)
• timespan - Size unit: second, minute, hour, day, week, month, quarter, year
• from - Start timestamp
• to - End timestamp

Example

let stream = client.fetch_aggregates("X:BTCUSD", 1, "minute", from, to);

pub fn fetch_trades<'a>( &'a self, ticker: &'a str, from: DateTime<Utc>, to: DateTime<Utc>, ) -> impl Stream<Item = Result<PublicTrade, MassiveError>> + 'a

Fetch tick-level trades for a symbol.

Returns a stream that handles pagination automatically.

Arguments

• ticker - Symbol with asset class prefix (e.g., X:BTCUSD, AAPL)
• from - Start timestamp
• to - End timestamp

pub fn fetch_quotes<'a>( &'a self, ticker: &'a str, from: DateTime<Utc>, to: DateTime<Utc>, ) -> impl Stream<Item = Result<OrderBookL1, MassiveError>> + 'a

Fetch quotes (BBO/NBBO) for a symbol.

Returns a stream that handles pagination automatically.

Arguments

• ticker - Symbol with asset class prefix (e.g., C:EURUSD, AAPL)
• from - Start timestamp
• to - End timestamp

Trait Implementations

impl Clone for MassiveRestClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MassiveRestClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl StockSplitSource for MassiveRestClient

fn fetch_splits( &self, filter: &CorporateActionFilter, ) -> impl Stream<Item = Result<CorporateAction<SmolStr>, Self::Error>> + Send

Fetch stock splits for filter’s symbols and effective-date range, mapped to CorporateAction<SmolStr> descriptors.

effective_date provenance: this impl maps it onto Massive’s execution_date — the split’s market execution date, satisfying the StockSplitSource::fetch_splits effective_date contract. (StockSplit exposes no other date field, so there is no ambiguity to resolve.) Massive’s /v3/reference/splits endpoint filters by a single ticker, so a multi-symbol filter fans out into one query per symbol, concatenated into a single stream in symbols order; an empty symbols list issues one unfiltered query (all splits in the date range, subject to provider page limits). Splits whose raw split_to / split_from yield a degenerate ratio (zero, negative, or division by zero) are logged and skipped — see CorporateActionKind::stock_split.

type Error = MassiveError

Error yielded as a stream item when a fetch fails (e.g. a transport or deserialisation error). Per-item so a partial result set is still observable up to the failure point.