@fullstackcraftllc/floe 0.0.2 → 0.0.4

package/dist/client/brokers/TradierClient.js

@@ -48,6 +48,21 @@ class TradierClient {
         this.tickerCache = new Map();
         /** Cached option data (for merging quote and trade events) */
         this.optionCache = new Map();
+        /**
+         * Base open interest from REST API - used as t=0 reference for live OI calculation
+         * Key: OCC symbol, Value: open interest at start of day / time of fetch
+         */
+        this.baseOpenInterest = new Map();
+        /**
+         * Cumulative estimated OI change from intraday trades
+         * Key: OCC symbol, Value: net estimated change (positive = more contracts opened)
+         */
+        this.cumulativeOIChange = new Map();
+        /**
+         * History of intraday trades with aggressor classification
+         * Key: OCC symbol, Value: array of trades
+         */
+        this.intradayTrades = new Map();
         /** Event listeners */
         this.eventListeners = new Map();
         /** Reconnection attempt counter */
@@ -64,6 +79,7 @@ class TradierClient {
         // Initialize event listener maps
         this.eventListeners.set('tickerUpdate', new Set());
         this.eventListeners.set('optionUpdate', new Set());
+        this.eventListeners.set('optionTrade', new Set());
         this.eventListeners.set('connected', new Set());
         this.eventListeners.set('disconnected', new Set());
         this.eventListeners.set('error', new Set());
@@ -138,6 +154,165 @@ class TradierClient {
     isConnected() {
         return this.connected;
     }
+    /**
+     * Fetches options chain data from Tradier REST API.
+     *
+     * @param symbol - Underlying symbol (e.g., 'QQQ')
+     * @param expiration - Expiration date in YYYY-MM-DD format
+     * @param greeks - Whether to include Greeks data (default: true)
+     * @returns Array of option chain items, or empty array on failure
+     */
+    async fetchOptionsChain(symbol, expiration, greeks = true) {
+        try {
+            const params = new URLSearchParams({
+                symbol,
+                expiration,
+                greeks: String(greeks),
+            });
+            const url = `${this.apiBaseUrl}/markets/options/chains?${params.toString()}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.authKey}`,
+                    'Accept': 'application/json',
+                },
+            });
+            // log raw response for debugging
+            const rawResponse = await response.clone().text();
+            console.log('Raw options chain response:', rawResponse);
+            if (!response.ok) {
+                this.emit('error', new Error(`Failed to fetch options chain: ${response.statusText}`));
+                return [];
+            }
+            const data = await response.json();
+            if (!data.options || !data.options.option) {
+                return [];
+            }
+            // Handle case where API returns single object instead of array
+            const options = Array.isArray(data.options.option)
+                ? data.options.option
+                : [data.options.option];
+            return options;
+        }
+        catch (error) {
+            this.emit('error', error instanceof Error ? error : new Error(String(error)));
+            return [];
+        }
+    }
+    /**
+     * Fetches open interest and other static data for subscribed options via REST API.
+     * Call this after subscribing to options to populate open interest.
+     *
+     * @param occSymbols - Array of OCC option symbols to fetch data for
+     * @returns Promise that resolves when all data is fetched
+     *
+     * @remarks
+     * Open interest is only available via the REST API, not streaming.
+     * This method groups options by underlying and expiration to minimize API calls.
+     */
+    async fetchOpenInterest(occSymbols) {
+        // Group symbols by underlying and expiration to minimize API calls
+        const groups = new Map();
+        for (const occSymbol of occSymbols) {
+            try {
+                const parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+                const key = `${parsed.symbol}:${parsed.expiration.toISOString().split('T')[0]}`;
+                if (!groups.has(key)) {
+                    groups.set(key, new Set());
+                }
+                groups.get(key).add(occSymbol);
+            }
+            catch {
+                // Skip invalid OCC symbols
+                continue;
+            }
+        }
+        // Fetch chains for each underlying/expiration combination
+        const fetchPromises = Array.from(groups.entries()).map(async ([key, symbols]) => {
+            const [underlying, expiration] = key.split(':');
+            const chain = await this.fetchOptionsChain(underlying, expiration);
+            // Update cache with open interest data
+            for (const item of chain) {
+                // Tradier returns symbols in the same format we use (compact OCC)
+                if (symbols.has(item.symbol)) {
+                    // Store base open interest for live OI calculation (t=0 reference)
+                    this.baseOpenInterest.set(item.symbol, item.open_interest);
+                    // Initialize cumulative OI change if not already set
+                    if (!this.cumulativeOIChange.has(item.symbol)) {
+                        this.cumulativeOIChange.set(item.symbol, 0);
+                    }
+                    const existing = this.optionCache.get(item.symbol);
+                    if (existing) {
+                        // Update existing cache entry with REST data
+                        existing.openInterest = item.open_interest;
+                        existing.liveOpenInterest = this.calculateLiveOpenInterest(item.symbol);
+                        existing.volume = item.volume;
+                        existing.impliedVolatility = item.greeks?.mid_iv ?? existing.impliedVolatility;
+                        // Also update bid/ask if not yet populated
+                        if (existing.bid === 0 && item.bid > 0) {
+                            existing.bid = item.bid;
+                            existing.bidSize = item.bidsize;
+                        }
+                        if (existing.ask === 0 && item.ask > 0) {
+                            existing.ask = item.ask;
+                            existing.askSize = item.asksize;
+                        }
+                        if (existing.last === 0 && item.last !== null) {
+                            existing.last = item.last;
+                        }
+                        if (existing.mark === 0) {
+                            existing.mark = (item.bid + item.ask) / 2;
+                        }
+                        this.optionCache.set(item.symbol, existing);
+                        this.emit('optionUpdate', existing);
+                    }
+                    else {
+                        // Create new cache entry from REST data
+                        const parsedSymbol = (0, occ_1.parseOCCSymbol)(item.symbol);
+                        const option = {
+                            occSymbol: item.symbol,
+                            underlying: item.underlying,
+                            strike: item.strike,
+                            expiration: item.expiration_date,
+                            expirationTimestamp: parsedSymbol.expiration.getTime(),
+                            optionType: item.option_type,
+                            bid: item.bid,
+                            bidSize: item.bidsize,
+                            ask: item.ask,
+                            askSize: item.asksize,
+                            mark: (item.bid + item.ask) / 2,
+                            last: item.last ?? 0,
+                            volume: item.volume,
+                            openInterest: item.open_interest,
+                            liveOpenInterest: this.calculateLiveOpenInterest(item.symbol),
+                            impliedVolatility: item.greeks?.mid_iv ?? 0,
+                            timestamp: Date.now(),
+                        };
+                        this.optionCache.set(item.symbol, option);
+                        this.emit('optionUpdate', option);
+                    }
+                }
+            }
+        });
+        await Promise.all(fetchPromises);
+    }
+    /**
+     * Returns the cached option data for a symbol.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Cached option data or undefined
+     */
+    getOption(occSymbol) {
+        return this.optionCache.get(occSymbol);
+    }
+    /**
+     * Returns all cached options.
+     *
+     * @returns Map of OCC symbols to option data
+     */
+    getAllOptions() {
+        return new Map(this.optionCache);
+    }
     /**
      * Registers an event listener.
      *
@@ -256,6 +431,10 @@ class TradierClient {
             else if (event.type === 'trade') {
                 this.handleTradeEvent(event);
             }
+            else if (event.type === 'timesale') {
+                this.handleTimesaleEvent(event);
+            }
+            // 'summary' events don't have data we need for NormalizedTicker/Option
         }
         catch (error) {
             // Ignore parse errors for heartbeat/status messages
@@ -289,6 +468,21 @@ class TradierClient {
             this.updateTickerFromTrade(symbol, event, timestamp);
         }
     }
+    /**
+     * Handles timesale events (trade with bid/ask at time of sale).
+     * This is particularly useful for options where quote events may be sparse.
+     */
+    handleTimesaleEvent(event) {
+        const { symbol } = event;
+        const timestamp = parseInt(event.date, 10) || Date.now();
+        const isOption = this.isOptionSymbol(symbol);
+        if (isOption) {
+            this.updateOptionFromTimesale(symbol, event, timestamp);
+        }
+        else {
+            this.updateTickerFromTimesale(symbol, event, timestamp);
+        }
+    }
     /**
      * Updates ticker data from a quote event.
      */
@@ -401,6 +595,247 @@ class TradierClient {
         this.optionCache.set(occSymbol, option);
         this.emit('optionUpdate', option);
     }
+    /**
+     * Updates ticker data from a timesale event.
+     * Timesale events include bid/ask at the time of the trade.
+     */
+    updateTickerFromTimesale(symbol, event, timestamp) {
+        const existing = this.tickerCache.get(symbol);
+        const bid = parseFloat(event.bid);
+        const ask = parseFloat(event.ask);
+        const last = parseFloat(event.last);
+        const size = parseInt(event.size, 10);
+        const ticker = {
+            symbol,
+            spot: (bid + ask) / 2,
+            bid,
+            bidSize: existing?.bidSize ?? 0, // timesale doesn't include bid/ask size
+            ask,
+            askSize: existing?.askSize ?? 0,
+            last,
+            volume: (existing?.volume ?? 0) + size, // Accumulate volume
+            timestamp,
+        };
+        this.tickerCache.set(symbol, ticker);
+        this.emit('tickerUpdate', ticker);
+    }
+    /**
+     * Updates option data from a timesale event.
+     * Timesale events include bid/ask at the time of the trade, enabling aggressor side detection.
+     *
+     * This is the primary method for calculating live open interest:
+     * - Aggressor side is determined by comparing trade price to NBBO
+     * - Buy aggressor (lifting ask) typically indicates new long positions → OI increases
+     * - Sell aggressor (hitting bid) typically indicates closing longs or new shorts → OI decreases
+     */
+    updateOptionFromTimesale(occSymbol, event, timestamp) {
+        const existing = this.optionCache.get(occSymbol);
+        // Parse OCC symbol to extract option details
+        let parsed;
+        try {
+            parsed = (0, occ_1.parseOCCSymbol)(occSymbol);
+        }
+        catch {
+            // Invalid OCC symbol, skip
+            return;
+        }
+        const bid = parseFloat(event.bid);
+        const ask = parseFloat(event.ask);
+        const last = parseFloat(event.last);
+        const size = parseInt(event.size, 10);
+        // Determine aggressor side by comparing trade price to NBBO
+        const aggressorSide = this.determineAggressorSide(last, bid, ask);
+        // Calculate estimated OI change based on aggressor side
+        // Buy aggressor (lifting the offer) → typically opening new long positions → +OI
+        // Sell aggressor (hitting the bid) → typically closing longs or opening shorts → -OI
+        const estimatedOIChange = this.calculateOIChangeFromTrade(aggressorSide, size, parsed.optionType);
+        // Update cumulative OI change
+        const currentChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        this.cumulativeOIChange.set(occSymbol, currentChange + estimatedOIChange);
+        // Record the trade for analysis
+        const trade = {
+            occSymbol,
+            price: last,
+            size,
+            bid,
+            ask,
+            aggressorSide,
+            timestamp,
+            estimatedOIChange,
+        };
+        if (!this.intradayTrades.has(occSymbol)) {
+            this.intradayTrades.set(occSymbol, []);
+        }
+        this.intradayTrades.get(occSymbol).push(trade);
+        // Emit trade event with aggressor info
+        this.emit('optionTrade', trade);
+        const option = {
+            occSymbol,
+            underlying: parsed.symbol,
+            strike: parsed.strike,
+            expiration: parsed.expiration.toISOString().split('T')[0],
+            expirationTimestamp: parsed.expiration.getTime(),
+            optionType: parsed.optionType,
+            bid,
+            bidSize: existing?.bidSize ?? 0, // timesale doesn't include bid/ask size
+            ask,
+            askSize: existing?.askSize ?? 0,
+            mark: (bid + ask) / 2,
+            last,
+            volume: (existing?.volume ?? 0) + size, // Accumulate volume
+            openInterest: existing?.openInterest ?? 0,
+            liveOpenInterest: this.calculateLiveOpenInterest(occSymbol),
+            impliedVolatility: existing?.impliedVolatility ?? 0,
+            timestamp,
+        };
+        this.optionCache.set(occSymbol, option);
+        this.emit('optionUpdate', option);
+    }
+    /**
+     * Determines the aggressor side of a trade by comparing trade price to NBBO.
+     *
+     * @param tradePrice - The executed trade price
+     * @param bid - The bid price at time of trade
+     * @param ask - The ask price at time of trade
+     * @returns The aggressor side: 'buy' if lifting offer, 'sell' if hitting bid, 'unknown' if mid
+     *
+     * @remarks
+     * The aggressor is the party that initiated the trade by crossing the spread:
+     * - Buy aggressor: Buyer lifts the offer (trades at or above ask) → bullish intent
+     * - Sell aggressor: Seller hits the bid (trades at or below bid) → bearish intent
+     * - Unknown: Trade occurred mid-market (could be internalized, crossed, or negotiated)
+     */
+    determineAggressorSide(tradePrice, bid, ask) {
+        // Use a small tolerance for floating point comparison (0.1% of spread)
+        const spread = ask - bid;
+        const tolerance = spread > 0 ? spread * 0.001 : 0.001;
+        if (tradePrice >= ask - tolerance) {
+            // Trade at or above ask → buyer lifted the offer
+            return 'buy';
+        }
+        else if (tradePrice <= bid + tolerance) {
+            // Trade at or below bid → seller hit the bid
+            return 'sell';
+        }
+        else {
+            // Trade mid-market - could be either side or internalized
+            return 'unknown';
+        }
+    }
+    /**
+     * Calculates the estimated open interest change from a single trade.
+     *
+     * @param aggressorSide - The aggressor side of the trade
+     * @param size - Number of contracts traded
+     * @param optionType - Whether this is a call or put
+     * @returns Estimated OI change (positive = OI increase, negative = OI decrease)
+     *
+     * @remarks
+     * This uses a simplified heuristic based on typical market behavior:
+     *
+     * For CALLS:
+     * - Buy aggressor (lifting offer) → typically bullish, opening new longs → +OI
+     * - Sell aggressor (hitting bid) → typically closing longs or bearish new shorts → -OI
+     *
+     * For PUTS:
+     * - Buy aggressor (lifting offer) → typically bearish/hedging, opening new longs → +OI
+     * - Sell aggressor (hitting bid) → typically closing longs → -OI
+     *
+     * Note: This is an estimate. Without knowing if trades are opening or closing,
+     * we use aggressor side as a proxy. SpotGamma and similar providers use
+     * more sophisticated models that may incorporate position sizing, strike
+     * selection patterns, and other heuristics.
+     */
+    calculateOIChangeFromTrade(aggressorSide, size, optionType) {
+        if (aggressorSide === 'unknown') {
+            // Mid-market trades are ambiguous - assume neutral impact on OI
+            return 0;
+        }
+        // Simple heuristic: buy aggressor = new positions opening, sell aggressor = positions closing
+        // This applies to both calls and puts since we're measuring contract count, not direction
+        if (aggressorSide === 'buy') {
+            return size; // New positions opening
+        }
+        else {
+            return -size; // Positions closing
+        }
+    }
+    /**
+     * Calculates the live (intraday) open interest estimate for an option.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Live OI estimate = base OI + cumulative estimated changes
+     *
+     * @remarks
+     * Live Open Interest = Base OI (from REST at t=0) + Cumulative OI Changes (from trades)
+     *
+     * This provides a real-time estimate of open interest that updates throughout
+     * the trading day as trades occur. The accuracy depends on:
+     * 1. The accuracy of aggressor side detection
+     * 2. The assumption that aggressors are typically opening new positions
+     *
+     * The official OI is only updated overnight by the OCC clearing house,
+     * so this estimate fills the gap during trading hours.
+     */
+    calculateLiveOpenInterest(occSymbol) {
+        const baseOI = this.baseOpenInterest.get(occSymbol) ?? 0;
+        const cumulativeChange = this.cumulativeOIChange.get(occSymbol) ?? 0;
+        // Live OI cannot go negative
+        return Math.max(0, baseOI + cumulativeChange);
+    }
+    /**
+     * Returns the intraday trades for an option with aggressor classification.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Array of intraday trades, or empty array if none
+     */
+    getIntradayTrades(occSymbol) {
+        return this.intradayTrades.get(occSymbol) ?? [];
+    }
+    /**
+     * Returns summary statistics for intraday option flow.
+     *
+     * @param occSymbol - OCC option symbol
+     * @returns Object with buy/sell volume, net OI change, and trade count
+     */
+    getFlowSummary(occSymbol) {
+        const trades = this.intradayTrades.get(occSymbol) ?? [];
+        let buyVolume = 0;
+        let sellVolume = 0;
+        let unknownVolume = 0;
+        for (const trade of trades) {
+            switch (trade.aggressorSide) {
+                case 'buy':
+                    buyVolume += trade.size;
+                    break;
+                case 'sell':
+                    sellVolume += trade.size;
+                    break;
+                case 'unknown':
+                    unknownVolume += trade.size;
+                    break;
+            }
+        }
+        return {
+            buyVolume,
+            sellVolume,
+            unknownVolume,
+            netOIChange: this.cumulativeOIChange.get(occSymbol) ?? 0,
+            tradeCount: trades.length,
+        };
+    }
+    /**
+     * Resets intraday tracking data. Call this at market open or when re-fetching base OI.
+     *
+     * @param occSymbols - Optional specific symbols to reset. If not provided, resets all.
+     */
+    resetIntradayData(occSymbols) {
+        const symbolsToReset = occSymbols ?? Array.from(this.intradayTrades.keys());
+        for (const symbol of symbolsToReset) {
+            this.intradayTrades.delete(symbol);
+            this.cumulativeOIChange.set(symbol, 0);
+        }
+    }
     /**
      * Checks if a symbol is an OCC option symbol.
      */

package/dist/impliedpdf/index.d.ts

@@ -0,0 +1,148 @@
+import { NormalizedOption } from '../types';
+/**
+ * Strike-level probability from the implied PDF
+ */
+export interface StrikeProbability {
+    /** Strike price */
+    strike: number;
+    /** Probability density at this strike (normalized to sum to 1) */
+    probability: number;
+}
+/**
+ * Implied probability distribution derived from option prices
+ * using Breeden-Litzenberger style numerical differentiation
+ */
+export interface ImpliedProbabilityDistribution {
+    /** Underlying symbol */
+    symbol: string;
+    /** Expiration timestamp in milliseconds */
+    expiryDate: number;
+    /** Timestamp when the distribution was calculated (milliseconds) */
+    calculationTimestamp: number;
+    /** Current underlying price */
+    underlyingPrice: number;
+    /** Strike probabilities (the PDF) */
+    strikeProbabilities: StrikeProbability[];
+    /** Most likely price (mode of the distribution) */
+    mostLikelyPrice: number;
+    /** Median price (50th percentile) */
+    medianPrice: number;
+    /** Expected value (mean) of the distribution */
+    expectedValue: number;
+    /** Expected move (standard deviation) */
+    expectedMove: number;
+    /** Tail skew ratio (right tail / left tail relative to mean) */
+    tailSkew: number;
+    /** Cumulative probability of finishing above current spot */
+    cumulativeProbabilityAboveSpot: number;
+    /** Cumulative probability of finishing below current spot */
+    cumulativeProbabilityBelowSpot: number;
+}
+/**
+ * Result of estimating implied probability distribution
+ */
+export type ImpliedPDFResult = {
+    success: true;
+    distribution: ImpliedProbabilityDistribution;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Estimate an implied probability density function (PDF) for a single expiry
+ * using Breeden-Litzenberger style numerical differentiation of call prices.
+ *
+ * This method computes the second derivative of call option prices with respect
+ * to strike price, which under risk-neutral pricing gives the probability density
+ * of the underlying ending at each strike.
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param underlyingPrice - Current spot/mark price of the underlying
+ * @param callOptions - Array of call options for a single expiry (must have bid > 0 and ask > 0)
+ * @returns ImpliedProbabilityDistribution with strike-level probabilities and summary statistics
+ *
+ * @example
+ * ```typescript
+ * const result = estimateImpliedProbabilityDistribution(
+ *   'QQQ',
+ *   500.00,
+ *   callOptionsForExpiry
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Mode:', result.distribution.mostLikelyPrice);
+ *   console.log('Expected move:', result.distribution.expectedMove);
+ * }
+ * ```
+ */
+export declare function estimateImpliedProbabilityDistribution(symbol: string, underlyingPrice: number, callOptions: NormalizedOption[]): ImpliedPDFResult;
+/**
+ * Estimate implied probability distributions for all expirations in an option chain
+ *
+ * @param symbol - Underlying ticker symbol
+ * @param underlyingPrice - Current spot/mark price of the underlying
+ * @param options - Array of all options (calls and puts, all expirations)
+ * @returns Array of ImpliedProbabilityDistribution for each expiration
+ *
+ * @example
+ * ```typescript
+ * const distributions = estimateImpliedProbabilityDistributions(
+ *   'QQQ',
+ *   500.00,
+ *   chain.options
+ * );
+ *
+ * for (const dist of distributions) {
+ *   console.log(`Expiry: ${new Date(dist.expiryDate).toISOString()}`);
+ *   console.log(`Mode: ${dist.mostLikelyPrice}`);
+ * }
+ * ```
+ */
+export declare function estimateImpliedProbabilityDistributions(symbol: string, underlyingPrice: number, options: NormalizedOption[]): ImpliedProbabilityDistribution[];
+/**
+ * Get the probability of the underlying finishing between two price levels
+ *
+ * @param distribution - Implied probability distribution
+ * @param lowerBound - Lower price bound
+ * @param upperBound - Upper price bound
+ * @returns Probability of finishing between the bounds
+ *
+ * @example
+ * ```typescript
+ * // Probability of QQQ finishing between 490 and 510
+ * const prob = getProbabilityInRange(distribution, 490, 510);
+ * console.log(`${(prob * 100).toFixed(1)}% chance of finishing in range`);
+ * ```
+ */
+export declare function getProbabilityInRange(distribution: ImpliedProbabilityDistribution, lowerBound: number, upperBound: number): number;
+/**
+ * Get the cumulative probability up to a given price level
+ *
+ * @param distribution - Implied probability distribution
+ * @param price - Price level
+ * @returns Cumulative probability of finishing at or below the price
+ *
+ * @example
+ * ```typescript
+ * // Probability of QQQ finishing at or below 495
+ * const prob = getCumulativeProbability(distribution, 495);
+ * console.log(`${(prob * 100).toFixed(1)}% chance of finishing <= 495`);
+ * ```
+ */
+export declare function getCumulativeProbability(distribution: ImpliedProbabilityDistribution, price: number): number;
+/**
+ * Get the quantile (inverse CDF) for a given probability
+ *
+ * @param distribution - Implied probability distribution
+ * @param probability - Probability value between 0 and 1
+ * @returns Strike price at the given probability quantile
+ *
+ * @example
+ * ```typescript
+ * // Find the 5th and 95th percentile strikes
+ * const p5 = getQuantile(distribution, 0.05);
+ * const p95 = getQuantile(distribution, 0.95);
+ * console.log(`90% confidence interval: [${p5}, ${p95}]`);
+ * ```
+ */
+export declare function getQuantile(distribution: ImpliedProbabilityDistribution, probability: number): number;