yf-options: Yahoo Finance Options Chain CLI Tool

A Rust CLI tool for downloading options chain data from Yahoo Finance API with Black-Scholes Greeks calculation.

Features

• Options Chain Data - Fetch complete options chains from Yahoo Finance
• Greeks Calculation - Black-Scholes model: Delta, Gamma, Theta, Vega, Rho
• Flexible Filtering - By expiration date, strike range, ITM/OTM status
• Multiple Output Formats - JSON (pretty or compact) and CSV
• Multi-Symbol Support - Process multiple tickers with combined output
• Rate Limiting - Built-in throttling to avoid API limits
• Authenticated API Access - Handles Yahoo Finance cookie/crumb authentication

Installation

cd tools/yf-options
cargo build --release

The binary will be available at target/release/yf-options.

Quick Start

# Fetch all options for AAPL
./yf-options AAPL

# With Greeks calculation
./yf-options AAPL --greeks

# Multiple symbols, combined output
./yf-options AAPL MSFT GOOGL --combine --pretty

Usage

Basic Usage

# Fetch all options for a symbol
./yf-options AAPL

# Pretty-printed JSON output
./yf-options AAPL --pretty

# Fetch multiple symbols
./yf-options AAPL MSFT GOOGL

Filtering Options

# Filter by expiration date
./yf-options AAPL --expiration 2024-03-15

# Filter by option type
./yf-options AAPL --type calls
./yf-options AAPL --type puts

# Filter by strike range
./yf-options AAPL --strikes 150-200

# In-the-money only
./yf-options AAPL --itm

# Out-of-the-money only
./yf-options AAPL --otm

Greeks Calculation

# Calculate and include Greeks
./yf-options AAPL --greeks

# Custom risk-free rate (default: 5%)
./yf-options AAPL --greeks --risk-free-rate 0.045

Output Options

# Output to specific directory
./yf-options AAPL --output-dir /path/to/output

# CSV format
./yf-options AAPL --format csv

# Combine multiple symbols into one file
./yf-options AAPL MSFT --combine

Advanced Options

# Adjust rate limit (requests per minute)
./yf-options AAPL --rate-limit 10

# Verbose logging
./yf-options AAPL --verbose

# Debug logging via environment
RUST_LOG=debug ./yf-options AAPL

CLI Reference

Required Arguments

Filter Options

Greeks Options

Output Options

Other Options

Data Models

OptionChain

{
  "symbol": "AAPL",
  "underlying_price": 175.50,
  "expiration_dates": ["2024-03-15", "2024-03-22"],
  "strikes": [170.0, 175.0, 180.0],
  "options": [...]
}

OptionContract

{
  "contract_symbol": "AAPL240315C00175000",
  "strike": 175.0,
  "last_price": 3.25,
  "bid": 3.20,
  "ask": 3.30,
  "volume": 1500,
  "open_interest": 5000,
  "implied_volatility": 0.25,
  "in_the_money": false,
  "greeks": {
    "delta": 0.52,
    "gamma": 0.045,
    "theta": -0.15,
    "vega": 0.28,
    "rho": 0.12
  }
}

Greeks Calculation

The tool uses the Black-Scholes model to calculate option Greeks:

Mathematical Properties

• Call delta: 0 to 1 (approaches 1 as deep ITM)
• Put delta: -1 to 0 (approaches -1 as deep ITM)
• Gamma: Always positive, highest ATM
• Theta: Usually negative (time decay)
• Vega: Always positive for long options

API & Authentication

Endpoint

https://query2.finance.yahoo.com/v7/finance/options/{symbol}

Authentication Flow

Yahoo Finance requires cookie-based authentication with a crumb token. This tool handles it automatically:

1. Session Initialization - Connects to fc.yahoo.com to establish session cookies
2. Crumb Extraction - Fetches crumb from /v1/test/getcrumb endpoint
3. Authenticated Requests - Includes crumb parameter in API calls

This authentication is handled transparently - no user configuration required.

Project Structure

tools/yf-options/
├── Cargo.toml          # Package manifest with metadata
├── README.md           # This file
├── src/
│   ├── main.rs         # Entry point, argument validation
│   ├── lib.rs          # Library exports
│   ├── cli.rs          # Clap argument definitions
│   ├── client.rs       # Yahoo Finance API client with auth
│   ├── models.rs       # Data models (OptionChain, Greeks)
│   ├── greeks.rs       # Black-Scholes Greeks calculation
│   ├── output.rs       # JSON/CSV output formatting
│   └── error.rs        # Error types

Dependencies

Development

Build

cargo build           # Debug build
cargo build --release # Optimized release build

Run Tests

cargo test            # Run all tests
cargo test -- --nocapture  # With output

Test Coverage

The project includes 145+ comprehensive tests:

Test Areas:

• Black-Scholes Greeks mathematical properties
• CLI argument parsing and validation
• JSON serialization/deserialization
• Data filtering logic
• API response handling
• Edge cases and error scenarios

See TESTING.md and TEST_REPORT.md for details.

Code Quality

cargo clippy          # Linting
cargo fmt             # Formatting

Example Output

JSON (with Greeks)

./yf-options AAPL --greeks --pretty

{
  "symbol": "AAPL",
  "underlying_price": 175.50,
  "options": [
    {
      "expiration": "2024-03-15",
      "calls": [
        {
          "contract_symbol": "AAPL240315C00175000",
          "strike": 175.0,
          "last_price": 3.25,
          "implied_volatility": 0.25,
          "greeks": {
            "delta": 0.52,
            "gamma": 0.045,
            "theta": -0.15,
            "vega": 0.28,
            "rho": 0.12
          }
        }
      ]
    }
  ]
}

CSV Format

./yf-options AAPL --format csv --greeks

symbol,expiration,type,strike,last_price,bid,ask,volume,open_interest,iv,delta,gamma,theta,vega,rho
AAPL,2024-03-15,call,175.0,3.25,3.20,3.30,1500,5000,0.25,0.52,0.045,-0.15,0.28,0.12

License

MIT OR Apache-2.0 (dual license, standard for Rust projects)

Related Tools

• yf-quotes - Historical OHLCV stock data
• See ../docs/yf-tool-ideas.md for more planned tools

Contributing

Contributions welcome! Areas of interest:

• Additional output formats (Parquet, Arrow)
• Alternative Greeks models (Binomial, Monte Carlo)
• Support for index options
• Historical options data