US Options Data Fetcher
概述
独立 CLI 工具，直接从 Yahoo Finance 获取美股期权链数据并输出结构化 JSON 摘要。无需 Flask 服务器，可在自动化任务中直接调用。
调用方式
# 单个标的
"C:/Users/cheny/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/cheny/.workbuddy/skills/us-options-data/options_cli.py" --symbol SPY
# 多个标的（批量模式，自动限速）
"C:/Users/cheny/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/cheny/.workbuddy/skills/us-options-data/options_cli.py" --symbols SPY,QQQ,AAPL,NVDA,TSLA
# 指定到期日（Unix 时间戳）
"C:/Users/cheny/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/cheny/.workbuddy/skills/us-options-data/options_cli.py" --symbol SPY --expiry 1735689600
# 输出原始完整合约数据（不做摘要）
"C:/Users/cheny/.workbuddy/binaries/python/versions/3.13.12/python.exe" "C:/Users/cheny/.workbuddy/skills/us-options-data/options_cli.py" --symbol SPY --raw
依赖
- Python 3.12+（使用 WorkBuddy 管理 Python:
C:/Users/cheny/.workbuddy/binaries/python/versions/3.13.12/python.exe） requests库（已预装）- 网络连接（需访问 Yahoo Finance API）
输出格式
摘要模式（默认）
输出 JSON，每个标的包含以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
symbol |
string | 标的代码 |
underlying_price |
float | 标的最新价格 |
underlying_change_pct |
float | 标的涨跌幅(%) |
current_expiry |
string | 当前到期日(YYYY-MM-DD) |
num_expiries |
int | 可用到期日数量 |
num_calls / num_puts |
int | 看涨/看跌合约数量 |
total_call_volume / total_put_volume |
int | 看涨/看跌总成交量 |
total_call_oi / total_put_oi |
int | 看涨/看跌总未平仓量 |
total_volume / total_oi |
int | 总成交量 / 总未平仓量 |
put_call_ratio |
float | null | 看跌/看涨比率(put vol / call vol) |
avg_iv |
float | 平均隐含波动率(%) |
volume_leader_call / volume_leader_put |
object | 成交量最大的看涨/看跌合约 |
oi_leader_call / oi_leader_put |
object | 未平仓量最大的看涨/看跌合约 |
highest_iv_call / highest_iv_put |
object | IV最高的看涨/看跌合约 |
abnormal_high_iv |
array | 异常高IV合约列表(IV > 2x平均，最多5条) |
合约对象格式
{
"type": "call",
"strike": 777.0,
"expiry": "2026-08-17",
"volume": 107271,
"open_interest": 2098,
"iv": 4.8,
"last_price": 1.04
}
批量模式输出
{
"SPY": { ...摘要... },
"QQQ": { ...摘要... },
"AAPL": { ...摘要... }
}
错误处理
- 如果 Yahoo Finance 认证失败，返回
{"symbol": "SPY", "error": "Failed to obtain Yahoo Finance crumb token"} - 如果标的不存在，返回
{"symbol": "XXX", "error": "No results in optionChain"} - CLI 退出码：成功=0，失败=1
使用场景
- 美股日报自动化：获取 SPY/QQQ/AAPL/NVDA/TSLA 期权摘要，用于邮件中的期权市场速览部分
- 期权市场分析：检查 Put/Call Ratio 判断市场情绪，查看异常高IV合约
- 流动性检查：通过总成交量和未平仓量评估期权市场活跃度
Put/Call Ratio 解读
- < 0.7：偏多情绪（看涨期权交易活跃）
- 0.7 - 1.0：中性
- > 1.0：偏空情绪（看跌期权交易活跃）
- > 1.5：可能过度恐慌，反向指标
注意事项
- Yahoo Finance 返回的是最近到期日的期权链数据（默认）
- 周末/节假日获取的是上一个交易日的数据
- 批量模式下自动在请求间添加 0.8 秒延迟，避免被限流
- crumb token 缓存 25 分钟，过期自动刷新
- 深度虚值合约的 IV 可能异常高（如 >200%），这是正常现象，不代表市场预期
参考文档
- output-fields.md — 完整输出字段说明与示例
