Vibe-Trading 期权链数据获取深入解析 yahoo_client.get_options 与 v7 期权接口【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading导读本文围绕 Vibe-Trading 内置 Yahoo 公共 API 客户端中的backtest.loaders.yahoo_client.get_options函数展开完整讲解其 v7 期权链接口的调用方式、参数约定、返回结构、符号映射规则与底层实现原理。读完本文你将掌握如何直接调用该函数获取指定标的的到期日列表与 call/put 期权阶梯strike、bid/ask、成交量、未平仓量、隐含波动率等字段理解其背后 cookiecrumb 握手、进程级限流与 401 自动重试机制并学会在 Agent 场景中通过get_options_chain工具安全消费这些数据。一、接口总览从文档到端点yahoo_client.get_options是 Vibe-Trading 为期权链数据提供的底层数据访问接口它直接对接 Yahoo Finance 的 v7 期权链端点接口签名backtest.loaders.yahoo_client.get_optionsHTTP 端点GET https://query2.finance.yahoo.com/v7/finance/options/{symbol}用途获取某个标的underlying的期权链——包括全部可用到期日expirations以及指定到期日对应的 calls/puts 报价阶梯认证无需 API Key未认证的公共端点限流所有请求经由共享的进程级限流闸门throttle放行因为 Yahoo 会按源 IP 进行限速在代码层面该函数定义于 agent/backtest/loaders/yahoo_client.py是同一个客户端模块中与get_chartv8 K 线、get_quote_summaryv10 行情摘要、searchv1 搜索并列的四个核心接口之一。模块 docstring 明确指出该模块只是 provider 专属的粘合层返回纯 Python dict/list由下游 loader 或工具负责映射成项目所需的统一结构。它与 get_options_chain 工具的关系文档中特别强调了两条消费路径的分工路径适用场景get_options_chain工具Agent/CLI 场景返回有上限每侧 60 个合约、snake_case 字段的 JSON 信封直接喂给模型yahoo_client.get_options直接调用需要原始链数据时例如全部合约字段、strikes 数组或 quote 块也就是说get_options是数据源头工具层只是它的一个受控、裁剪、校验过的投影。工具实现见 agent/src/tools/options_chain_tool.py其 docstring 印证了这一分层所有 HTTP 都经由yahoo_client.get_options路由保证 Agent 永远不会以无间隔的方式直击 Yahoo。二、输入参数详解get_options(symbol: str, *, expiration: Optional[int] None)接受两个参数名称类型必填说明symbolstr是项目侧标的代码如AAPL.US内部通过map_symbol映射为 Yahoo 形式expirationint否到期日Unix 纪元秒必须是expirationDates中的某个值省略时返回最近到期日从源码看agent/backtest/loaders/yahoo_client.pyexpiration被转换为params[date] int(expiration)拼入请求省略时请求不带date参数Yahoo 默认返回最近到期日对应的链。符号映射规则map_symbol由于项目使用统一 ticker 约定如AAPL.US、700.HK而 Yahoo 使用自己的惯例所有请求前都会调用map_symbol做转换。从 map_symbol 实现 可以提取出完整的映射表项目侧符号Yahoo 形式规则说明AAPL.USAAPL去掉.US后缀美国分类股连字符化BRK.B.US→BRK-B源码注释点号形式会返回空链实测验证00700.HK0700.HK去掉前导零并补足 4 位数字RELIANCE.NS/500325.BO原样Yahoo 原样保留.NS/.BO后缀TD.TO/PNG.V原样Yahoo 原样保留.TO/.V后缀VIC.VN原样Yahoo 原样保留.VN后缀仅 HOSE 主板上市其他如BTC-USD、^GSPC原样透传—这一映射规则在 agent/src/skills/yfinance/SKILL.md 的 Ticker Format Conversion 一节中亦有对照表适用于 yfinance 全部接口。三、返回结构optionChain.result[0]函数返回optionChain.result[0]映射当 Yahoo 对某标的没有任何期权链时返回{}空 dict。字段类型说明underlyingSymbolstr解析后的 Yahoo 标的代码expirationDateslist[int]全部可用到期日Unix 纪元秒strikeslist[float]返回到期日对应的全部行权价optionslist[dict]指定到期日的一个块block含expirationDate、calls、putscalls/puts中的每一个元素都是一个合约 dict包含及其他字段contractSymbol、strike、lastPrice、bid、ask、volume、openInterest、impliedVolatility、inTheMoney、expiration。这些字段的含义与用途如下contractSymbol合约唯一标识格式为AAPL240613C00190000标的 到期日 C/P 标记 行权价编码可用于精确索引合约strike行权价lastPrice/bid/ask最新成交价与买卖盘报价volume当日成交量openInterest未平仓量衡量该行权价的流动性深度impliedVolatility隐含波动率小数形式如0.224表示 22.4%inTheMoney是否价内实值布尔标记expiration合约对应到期日Unix 秒数据示例原文档附带的真实结构{ underlyingSymbol: AAPL, expirationDates: [1718236800, 1718841600, 1719446400], options: [{ expirationDate: 1718236800, calls: [{contractSymbol: AAPL240613C00190000, strike: 190.0, lastPrice: 4.05, bid: 3.95, ask: 4.10, volume: 1203, openInterest: 8821, impliedVolatility: 0.224, inTheMoney: true}], puts: [{contractSymbol: AAPL240613P00190000, strike: 190.0, lastPrice: 1.85, bid: 1.80, ask: 1.90, volume: 642, openInterest: 5104, impliedVolatility: 0.231, inTheMoney: false}] }] }完整示例代码原文档给出的用法示例可直接复制运行from backtest.loaders import yahoo_client # 最近到期日 chain yahoo_client.get_options(AAPL.US) expirations chain.get(expirationDates, []) block (chain.get(options) or [{}])[0] print(len(block.get(calls, [])), calls) # 指定更远的到期日 if len(expirations) 1: later yahoo_client.get_options(AAPL.US, expirationexpirations[1])两个实用要点健壮取数惯用法chain.get(options) or [{}]保证无链时不会 IndexErrorblock.get(calls, [])保证空链安全遍历。到期日必须来自返回值expiration参数应取自上一步返回的expirationDates列表而不是随意猜测时间戳。四、错误处理契约函数按以下规则抛出异常异常类型触发条件requests.RequestException网络/HTTP 失败含非 401 的 HTTP 错误以及第二次 401ValueErrorYahoo 对指定标的返回了符号级错误从 源码 _parse_options 可以看到ValueError的具体触发点当 Yahoo 负载中的optionChain.error非空时抛出错误描述会携带标的符号如Yahoo options error for AAPL: description而当result数组为空时则安静地返回{}——即标的无期权与请求失败被明确区分。五、底层实现原理源码级剖析5.1 cookiecrumb 握手v7 端点并非裸奔文档中 v7 接口标注为无需认证的公共端点但这并不等于裸请求即可访问。源码模块注释与 get_options 的实现 明确指出v7/finance/options端点现在会拒绝裸请求HTTP 401要求携带会话 cookie 以及匹配的crumb令牌。整个握手由进程级_CrumbStore管理agent/backtest/loaders/yahoo_client.py首次需要时先请求https://fc.yahoo.com拿到同意/会话 cookie再携带 cookie 请求https://query2.finance.yahoo.com/v1/test/getcrumb获取 crumb 令牌后续请求以params{crumb: crumb}headers{Cookie: ...}发出若收到 401crumb 过期/未授权的信号自动刷新一次 crumb 并重试第二次 401 才向上传播。整个握手由threading.Lock串行化因此并发调用者突发请求时握手最多执行一次不会出现重复握手风暴。调用方完全无需关心这套状态机。5.2 共享限流闸门按源 IP 的礼貌间隔Yahoo 与其他免费行情源一样按源 IP 限速因此所有请求都路由经过 agent/backtest/loaders/_http.py 中的throttled_get。要点所有 Yahoo 端点共享同一个 host 桶HOST_KEY yahoo因此 chart/quote/options/search 之间也保持最小间隔默认最小间隔_DEFAULT_MIN_INTERVAL_S 0.6秒可通过环境变量VIBE_TRADING_YAHOO_MIN_INTERVAL覆盖批处理任务需要更慢节奏时可调大限流器会在间隔之上叠加至多 0.4 秒随机抖动jitter避免并发 worker 齐步走撞车每个 host 桶复用独立的requests.Session摊销 TCP/TLS 建连成本默认 User-Agent 为桌面浏览器字符串规避免费行情端点对裸 requests UA 的拒绝。这些机制保证了 Agent 在真实运行中不会因突发请求触发 Yahoo 的临时封禁。六、Agent 工具层get_options_chain 的封装与安全护栏作为本函数的典型消费方get_options_chain工具agent/src/tools/options_chain_tool.py展示了在生产场景中如何安全地使用原始链数据。其行为契约详见技能参考文档 agent/src/skills/yfinance/references/tool_get_options_chain.md。输入名称类型必填说明tickerstr是美股标的AAPL或AAPL.US.US后缀会被剥离expirationint否到期日Unix 秒来自返回的expirations列表省略取最近到期日输出信封成功时返回 JSON 字符串信封{ok: true, market: us, source: yahoo, data: {...}}其中字段类型说明tickerstr回显输入的 tickerexpirationint返回的到期日Unix 秒expirationslist[int]全部可用到期日Unix 秒calls_count/puts_countintcall/put 行数≤ 60calls/putslist[dict]合约列表snake_case 字段contract_symbol、strike、last_price、bid、ask、volume、open_interest、implied_volatility、in_the_money、expiration失败时返回{ok: false, error: message}错误一律以信封形式返回而绝不抛出——例如 ticker 缺失/空白、expiration 非整数、上游 Yahoo 请求错误。三层面护栏合约数封顶_MAX_CONTRACTS_PER_SIDE 60每侧最多取 60 个合约agent/src/tools/options_chain_tool.py深度链不会撑爆喂给模型的载荷。字段白名单归一化_CONTRACT_FIELDS元组把 Yahoo 的 camelCase 字段显式映射为 snake_case 信封键只透出模型需要的 10 个字段。到期日严格校验当调用方显式传入expiration时工具会验证该日期确实存在于expirationDates、options非空、且返回块的expirationDate与请求一致agent/src/tools/options_chain_tool.py。因为 Yahoo 在日期不匹配时会静默返回空或过期链而工具层要保证信封内容对应当前请求的到期日这一承诺。这些行为均有测试用例背书见 agent/tests/test_options_chain_tool.py包括成功信封归一化test_success_envelope_normalizes_contracts、60 合约封顶test_contracts_capped、坏到期日返回错误信封test_bad_expiration_returns_error_envelope、显式到期日与返回链不匹配时的六类异常分支test_invalid_expiration_returns_error_with_available_dates、test_block_expiration_mismatch_is_an_error等。所有测试均在yahoo_client.get_options处 mock HTTP不触碰真实 Yahoo 端点。七、实战场景与最佳实践场景一Agent 做期权快照分析在 swarm 预设或 Agent 会话中调用工具get_options_chain(tickerAAPL) get_options_chain(tickerAAPL.US, expiration1718236800)先取最近到期日的链做快照如需对比远期合约用返回的expirations列表中的值做第二次调用。参考预设见 agent/src/swarm/presets/derivatives_strategy_desk.yaml 等 swarm 工作流对get_options_chain的编排使用。场景二脚本级原始数据采集需要完整原始链如全部合约字段、strikes 数组时直接调用函数并按需处理错误from backtest.loaders import yahoo_client import requests try: chain yahoo_client.get_options(AAPL.US, expiration1718236800) strikes chain.get(strikes, []) block (chain.get(options) or [{}])[0] itm_calls [c for c in block.get(calls, []) if c.get(inTheMoney)] print(f{len(strikes)} strikes, {len(itm_calls)} in-the-money calls) except requests.RequestException as exc: print(f网络/HTTP 失败: {exc}) except ValueError as exc: print(f标的级错误: {exc})实践建议到期日永远来自expirationDates该列表是 Yahoo 当前披露的完整到期集合硬编码时间戳极易命中非交易日或过期日期批量抓取要调大限流间隔多标的循环拉链时通过VIBE_TRADING_YAHOO_MIN_INTERVAL环境变量提高最小间隔或优先复用工具层的单次快照语义避免触发 IP 级限速区分无链与失败返回{}表示该标的无期权链正常业务状态异常则是请求层面问题处理策略完全不同原始数据与工具信封各有适用场景给模型消费用get_options_chain封顶 snake_case 严格校验做策略回测的数据管道用get_options直接取原始链。结语yahoo_client.get_options是 Vibe-Trading 期权数据管线的事实标准入口它用一个函数封装了 Yahoo v7 期权链端点的全部复杂性——符号映射、cookiecrumb 握手、401 自动重试、进程级限流与会话复用。理解它的接口契约与底层机制既能帮助你直接构建期权策略回测与期权快照分析的数据层也能让你在get_options_chain工具层之上安全地编排 Agent 工作流从而把期权市场数据稳定、礼貌、可控地接入你的交易研究体系。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考