TradingAgents/.planning/phases/01-tradier-data-layer/01-CONTEXT.md

Phase 1: Tradier Data Layer - Context

Gathered: 2026-03-29 Status: Ready for planning

## Phase Boundary

Integrate Tradier as a new data vendor for options chain retrieval with 1st-order Greeks and IV. Register options-specific tools and categories in the existing vendor routing system. Provide filtered, structured chain data for downstream options analysis agents.

## Implementation Decisions

API Authentication

• D-01: Use TRADIER_API_KEY env var for credentials, matching existing pattern (OPENAI_API_KEY, ALPHA_VANTAGE_KEY)
• D-02: Support sandbox via TRADIER_SANDBOX=true env var — auto-detect base URL (sandbox.tradier.com vs api.tradier.com)

Data Fetching Strategy

• D-03: Pre-fetch all expirations within DTE range upfront at the start of an analysis run, cache for the session. Do NOT let individual agents make separate API calls for the same data.
• D-04: Default DTE filter range: 0-50 DTE (covers Tastytrade methodology sweet spot ~30–50 DTE plus weeklies and near-term options)
• D-05: Always pass greeks=true on chain requests. Sandbox: Tradier sandbox often returns no Greeks (empty/null greeks object). Implementations must still call with greeks=true and treat missing fields as None without failing. Production: expect populated Greeks. Do not gate greeks=true on TRADIER_SANDBOX — only the response handling differs.

Data Structure

• D-06: Canonical representation: typed OptionsContract / OptionsChain in memory; bulk analysis uses OptionsChain.to_dataframe() (pandas). Optional helpers may add from_dataframe / reconstruction utilities if a round-trip is needed; avoid maintaining two divergent sources of truth — derive the DataFrame from the dataclass list.

Claude's Discretion

• Caching strategy: Claude picks the best caching approach. In-memory per-session is simpler; disk TTL helps during development. Choose based on what fits the existing architecture best.
• Rate limit handling: Claude picks the best approach based on existing AlphaVantageRateLimitError fallback pattern. Options include retry with backoff, pre-emptive throttling, or both.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Existing Data Layer (follow these patterns)

• tradingagents/dataflows/interface.py — Vendor routing system: TOOLS_CATEGORIES, VENDOR_METHODS, VENDOR_LIST, route_to_vendor()
• tradingagents/dataflows/config.py — Config module pattern for vendor settings
• tradingagents/default_config.py — Default config with data_vendors and tool_vendors dicts
• tradingagents/dataflows/y_finance.py — Reference implementation for a data vendor module
• tradingagents/dataflows/alpha_vantage.py — Second vendor reference with rate limit error handling

Tradier API

• https://docs.tradier.com/reference/brokerage-api-markets-get-options-chains — Options chains endpoint
• https://docs.tradier.com/reference/brokerage-api-markets-get-options-expirations — Expirations endpoint
• https://docs.tradier.com/reference/brokerage-api-markets-get-options-strikes — Strikes endpoint
• https://docs.tradier.com/docs/rate-limiting — Rate limiting (120 req/min for market data)

Project Research

• .planning/research/STACK.md — Stack recommendations including Tradier integration approach
• .planning/research/PITFALLS.md — Data quality pitfalls (stale Greeks, hourly update frequency)

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• interface.py::route_to_vendor() — Vendor routing with automatic fallback on rate limit errors
• interface.py::TOOLS_CATEGORIES — Tool category registration pattern (add new options_chain category)
• interface.py::VENDOR_METHODS — Method-to-vendor mapping (add new options methods)
• config.py — Config management with get_config(), set_config() pattern
• AlphaVantageRateLimitError — Rate limit error pattern to replicate for Tradier

Established Patterns

• Vendor module: One Python file per vendor (y_finance.py, alpha_vantage.py) with exported functions
• Function naming: get_* prefix for data retrieval (get_stock_data, get_fundamentals)
• Config: Category-level defaults in data_vendors dict, tool-level overrides in tool_vendors
• No SDK dependency: Use requests directly for Tradier (consistent with keeping deps lean)

Integration Points

• interface.py — Register new options_chain category in TOOLS_CATEGORIES, add "tradier" to VENDOR_LIST, add options methods to VENDOR_METHODS
• default_config.py — Add "options_chain": "tradier" to data_vendors
• tradingagents/agents/utils/ — New tool functions for options data (like core_stock_tools.py pattern)

</code_context>

## Specific Ideas

• Tradier OCC symbology format: AAPL220617C00270000 (symbol + date + C/P + strike*1000)
• Greeks fields from Tradier: delta, gamma, theta, vega, rho, phi, bid_iv, mid_iv, ask_iv, smv_vol
• Response format: {"data": {"options": {"option": [...]}}} — nested JSON requiring extraction
• Sandbox has no Greeks — production account required for full testing

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 01-tradier-data-layer Context gathered: 2026-03-29