# Yahoo Finance Options & Volatility Intelligence (`straightforward_hydra/yahoo-finance-options-volatility-intelligence`) Actor

Full option chains from Yahoo Finance plus derived signals: put/call ratios, ATM implied volatility, IV skew, max pain and unusual-activity flags. Keyless, any US-listed ticker.

- **URL**: https://apify.com/straightforward\_hydra/yahoo-finance-options-volatility-intelligence.md
- **Developed by:** [Dev D](https://apify.com/straightforward_hydra) (community)
- **Categories:** Integrations, Developer tools, Automation
- **Stats:** 8 total users, 7 monthly users, 28.6% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Yahoo Finance Options & Volatility Intelligence 📈

**Full option chains from Yahoo Finance — plus the derived signals traders actually screen on: put/call ratios, at-the-money IV, volatility skew, max pain, and unusual-activity flags. Any optionable US-listed ticker. No API key.**

Most scrapers hand you a wall of contracts and leave the analysis to you. This one ships the **metrics layer too**, so a run answers *"how is this name positioned?"* — not just *"what strikes exist?"*

Built for **options traders, quant researchers, trading-tool builders, newsletter writers and risk dashboards**.

***

### Modes

| Mode | What you get | Rows |
|---|---|---|
| **metrics** | The intelligence layer: put/call ratio (OI & volume), ATM implied volatility, IV skew, max pain, totals, most-active contract. | 1 per expiration |
| **chain** | Every contract: strike, bid/ask/mid, spread %, last price, IV, open interest, volume, moneyness, ITM flag. | 1 per contract |
| **unusual** | Only contracts where today's volume outruns standing open interest — the classic fresh-positioning tell. | 1 per flagged contract |

### What the metrics mean

| Field | Reading |
|---|---|
| `put_call_ratio_oi` / `_volume` | >1 = puts outweigh calls (defensive positioning). <1 = call-heavy. |
| `atm_iv_pct` | Implied volatility at the money — the market's expected move. |
| `iv_skew_10pct` | OTM put IV **minus** OTM call IV, in IV points. Positive = downside protection bid up (normal for equities); a spike means hedging demand. |
| `max_pain_strike` | Strike where option holders collectively collect the least at expiry. `max_pain_vs_spot_pct` shows how far that sits from the current price. |
| `vol_oi_ratio` | Volume ÷ open interest. Above 1 = today's trading exceeded every standing contract. |

### Examples

**Positioning snapshot across a watchlist**

```json
{ "symbols": ["AAPL", "SPY", "NVDA"], "mode": "metrics", "maxExpirations": 3 }
```

**Near-the-money chain for one expiration**

```json
{ "symbols": ["TSLA"], "mode": "chain", "maxExpirations": 1, "strikeRangePct": 10 }
```

**Unusual activity sweep**

```json
{ "symbols": ["NVDA", "AMD"], "mode": "unusual", "minVolume": 500, "minVolOiRatio": 2 }
```

**A specific expiration, puts only**

```json
{ "symbols": ["SPY"], "mode": "chain", "expirationDates": ["2026-09-18"], "optionType": "puts" }
```

### Controlling run size

A single liquid chain can run to 1,500+ contracts. Two inputs keep it sane:

- **`strikeRangePct`** (default `25`) — keep only strikes within ±X% of spot. The far wings rarely trade. Set `0` for the entire chain.
- **`maxExpirations`** (default `3`) — how many of the nearest expiries to pull. Or name exact dates with `expirationDates`.

### Notes

- **No API key.** Yahoo gates its options endpoint behind a per-session cookie + crumb handshake; the actor performs it automatically and re-negotiates if the crumb expires mid-run.
- **Proxy is on by default and recommended.** Yahoo rate-limits the handshake per IP. If you see handshake warnings, keep the proxy enabled.
- **Skew is moneyness-based, not delta-based.** Yahoo publishes no greeks, so `iv_skew_10pct` compares strikes by distance from spot rather than by 25-delta. Tune the distance with `skewPct`.
- **Metrics mode needs both sides** of the chain — leave `optionType` on `all` for it, since ratios and skew are undefined otherwise.
- Index options work using their Yahoo symbols (`^SPX`, `^VIX`). Tickers with no listed options are reported and skipped rather than failing the run.
- Data is delayed per Yahoo's public feed and is provided for research — not investment advice.

# Actor input Schema

## `symbols` (type: `array`):

One or more underlying symbols, e.g. AAPL, SPY, NVDA, TSLA. Index options use their Yahoo symbol (^SPX, ^VIX).

## `mode` (type: `string`):

chain = one row per contract. metrics = one summary row per expiration (put/call ratio, ATM IV, skew, max pain). unusual = only contracts whose volume outruns open interest.

## `maxExpirations` (type: `integer`):

How many of the nearest expirations to pull per ticker. Ignored if you set explicit expiration dates below.

## `expirationDates` (type: `array`):

Exact expiration dates as YYYY-MM-DD. Overrides "Expirations to fetch". Dates that aren't listed for a ticker are reported and skipped.

## `optionType` (type: `string`):

Restrict to one side of the chain. Metrics mode needs both sides to compute ratios and skew — leave on "All" for it.

## `strikeRangePct` (type: `integer`):

Keep only strikes within this percentage of the underlying price — the usual way to cut a 1,500-contract chain down to the strikes that trade. 0 = keep every strike.

## `skewPct` (type: `integer`):

Moneyness used for the IV skew measure: IV of the put this far below spot minus IV of the call this far above it. Yahoo publishes no greeks, so skew is measured by distance from spot, not by delta.

## `minVolume` (type: `integer`):

Ignore contracts trading fewer than this many times today.

## `minVolOiRatio` (type: `integer`):

Flag contracts whose volume is at least this multiple of open interest. 1 = today's trading exceeded every standing contract, the classic new-position tell.

## `proxyConfiguration` (type: `object`):

Yahoo rate-limits its cookie/crumb handshake per IP. Leave the proxy on if you see handshake or 401 warnings.

## Actor input object example

```json
{
  "symbols": [
    "AAPL",
    "SPY",
    "NVDA"
  ],
  "mode": "metrics",
  "maxExpirations": 3,
  "optionType": "all",
  "strikeRangePct": 25,
  "skewPct": 10,
  "minVolume": 100,
  "minVolOiRatio": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "symbols": [
        "AAPL",
        "SPY",
        "NVDA"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("straightforward_hydra/yahoo-finance-options-volatility-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "symbols": [
        "AAPL",
        "SPY",
        "NVDA",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("straightforward_hydra/yahoo-finance-options-volatility-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "symbols": [
    "AAPL",
    "SPY",
    "NVDA"
  ]
}' |
apify call straightforward_hydra/yahoo-finance-options-volatility-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=straightforward_hydra/yahoo-finance-options-volatility-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/l6Jz06xOwDvWcHQwh/builds/ShxjaMTXQ4a5icnhI/openapi.json