Options positioning data (put/call, IV skew, OI) as a point-in-time data category

Author: dearvnCreated Sep 11, 2026Updated Sep 11, 2026

Problem

TradingAgents simulates a trading firm, but no analyst currently sees derivatives positioning. Real desks routinely read put/call ratios, IV skew, unusual volume vs. open interest, and dealer gamma around catalysts like earnings. TOOLS_CATEGORIES has no options category today (core_stock_apis, technical_indicators, fundamental_data, news_data, macro_data, prediction_markets).

Why this isn't a one-liner: look-ahead

The obvious free source, yfinance Ticker.option_chain(), only returns the current snapshot. Calling it for a past trade_date would leak future data into backtests, the same class of issue fixed for FRED in 8b7ece8. So the category needs a point-in-time contract from day one.

Proposal

  1. New category options_data with get_options_positioning(ticker, curr_date), returning a compact text summary so the prompt stays small.
  2. Keyless baseline vendor: yfinance, live-only. For historical dates it returns the explicit "unavailable" sentinel (via NoMarketDataError) and never current data.
  3. Optional and off the critical path: in the prototype the tool is bound to the existing market analyst (smallest diff, no new graph node or CLI option). Happy to split it into a separate optional analyst instead (see question 1).
  4. Vendors that have true point-in-time options history can plug in through data_vendors like any other category.

Prototype

Branch: https://github.com/dearvn/TradingAgents/tree/feat/options-data-category (one commit on top of v0.4.2; 13 new tests; full suite 689 passed; ruff clean)

Questions

  1. Would you prefer a new optional analyst, or extending the market analyst?
  2. Is a live-only baseline that returns the sentinel for historical dates acceptable?

Disclosure

I build SocSwift, an options-flow data service. This proposal is vendor-neutral and I'll implement the keyless yfinance baseline first. A SocSwift vendor, if welcome at all, would be a separate opt-in PR behind an API key.

Source: TauricResearch/TradingAgents