期权 API 文档

连接应用（包括 Muse）

连接类型

REST API（HTTPS）

API 地址

https://freeoptionscreener.com

OpenAPI 规范

https://freeoptionscreener.com/connectors/openapi.json

API 文档

https://freeoptionscreener.com/api_docs

OAuth 服务发现

OAuth 服务器元数据

接入前，请将应用名称、客户端 ID 及确切的 HTTPS 回调地址发送至 [email protected]以完成注册。应用必须支持使用 S256 PKCE、无客户端密钥的公共 OAuth 客户端。不接受未注册客户端或通配回调，不支持动态客户端注册。规范公开不表示 Muse 注册或审批已经完成。

需要登录和用户授权

1. 生成 PKCE 校验值、S256 挑战值和随机 state。打开 /oauth/authorize，并传入response_type=code、已注册的 client_id以及redirect_uri, scope=options:read, state, code_challenge和 code_challenge_method=S256.
2. 用户使用 Google 登录并明确批准只读访问。请在回调中验证返回的 state 和 issuer。
3. 五分钟内向以下地址发送 URL 编码的 POST 请求，交换一次性授权码： /oauth/token。发送grant_type=authorization_code, client_id、完全匹配的redirect_uri, code和 code_verifier.
4. 发送Authorization: Bearer ACCESS_TOKEN随每次数据请求发送。网站会话 Cookie 或共享 API 密钥不能替代此用户令牌。

访问令牌有效期为 15 分钟。通过 URL 编码 POST 请求刷新： /oauth/token，使用grant_type=refresh_token, client_id以及refresh_token。请同时保存新的访问令牌和刷新令牌；刷新会轮换两者并使旧访问令牌失效。刷新操作须串行执行。重复使用已消耗的授权码或刷新令牌将撤销连接。授权最长持续 30 天，之后用户必须重新连接。

管理员登录后可在已连接的应用中撤销访问。客户端可将token以及client_id作为 URL 编码表单 POST 至/oauth/revoke。请保密令牌，不要将其放入 URL 或日志。连接器不能交易、写入数据、读取已保存的筛选方案或使用管理员工具。

只读接口

GET /api/connector/status

返回data_version, data_as_of, published_at, symbols以及providers，描述最新就绪的数据版本。

GET /api/connector/options

将symbols设为逗号分隔的股票代码，或使用*选择全部可用股票。过滤和排序方式与筛选器相同，例如： type（put、call 或 all）、dte_min, dte_max, delta_min, delta_max, absolute_delta, open_interest_min, volume_min, sort和 direction。OpenAPI 规范列出了全部参数和响应字段。

curl --get 'https://freeoptionscreener.com/api/connector/options' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'symbols=NVDA' \
  --data-urlencode 'type=put' \
  --data-urlencode 'dte_min=7' \
  --data-urlencode 'dte_max=45' \
  --data-urlencode 'delta_min=0.10' \
  --data-urlencode 'delta_max=0.30' \
  --data-urlencode 'absolute_delta=true' \
  --data-urlencode 'sort=provider_iv' \
  --data-urlencode 'direction=desc' \
  --data-urlencode 'page_size=50'

默认选择买价至少为每股 $0.10、相对买价的价差低于 20% 的看跌期权，按数据源 IV 降序。IV 是年化小数：0.25表示 25%。使用 absolute_delta=true时，Delta 边界比较绝对值。数据源 IV 和希腊值保留原值，缺失值仍为 null。单独的模型字段为估算。

结果包括rows, matched_contracts, returned_contracts, missing_symbols, data_version 和data_as_of。这些是已发布数据，不是实时行情，也不是按需刷新数据源数据。请检查数据截止时间与各行报价时间戳。DTE 相对于数据截止时间计算，而非当前时钟。

分页与使用限制

page从 1 开始。page_size默认为 50，每页最多 100 行。依次使用返回的next_page直至其为 null。这是每页上限，并非总共仅有 100 份合约。翻页时保持筛选和排序不变。如果data_version发生变化，请从第一页重新开始，避免混合数据版本。

目前连接器没有单独的请求配额。请求共享网站运行容量，请限定查询范围并避免不必要的轮询。

公开筛选器的列

公开筛选器接受/api/scan?symbols=AMD&columns=hv30,iv_rank。股票代码、类型、到期日、行权价、买价和卖价始终返回。可选列默认为标的价格、数据源 IV 和到期前有财报。传入逗号分隔的 columns列表即可更改；空列表只请求六个必需列。未知名称返回 HTTP 422。

可选历史字段为hv30, hv90, iv_rank和iv_percentile。HV 是年化小数；排名和百分位采用 0–100，描述标的 IV30 分布。缺失值为 null。响应包括应用的列列表、行标识、调整后行权条款及少量展示／分组辅助字段。CSV 会保留行权条款和选定列。

annualized_yield是可排序的可选列和数值规则，单位为百分点：10 表示 10%。公式为 100 ×（买价 − 内在价值）／担保金额 × 365／DTE；看跌使用行权价作为担保金额，看涨使用股价。输入缺失、报价无效、合约已调整或 DTE 非正时返回 null。保留零和负的时间价值收益率。这是不含费用的简单年化值，并非预期收益。

错误与支持

• 401：用户授权缺失、无效、过期或已撤销。
• 403：尝试写入；连接器为只读。
• 422：查询参数无效，包括每页数量超过 100。
• 503：数据、身份认证或存储暂不可用。

OAuth 端点返回标准 OAuth 错误对象。如需支持，请发送邮件至 [email protected]，附上端点、时间与时区、状态码及去除敏感信息后的错误。切勿发送令牌或授权码。请参阅我们的隐私政策以及服务条款.