期权筛选

POST /v1/quote/option-screen

期权筛选器：在指定的市场品类（美股/港股/日股 x 股票/指数/期货）下，按 strategy 表达的多组条件（标的、行权价、到期日、期权方向、希腊字母、隐含波动率、链统计等）从全市场期权合约中筛选，支持排序与分页。

请求参数

参数	类型	位置	必填	说明
strategy	object	请求体	是	筛选策略，结构 {market_category_list, filter_group_list}。market_category_list 取值：0=US_STOCK / 1=US_INDEX / 2=US_FUTURE / 3=HK_STOCK / 4=HK_INDEX / 5=JP_STOCK / 6=JP_INDEX（多元素并集）。filter_group_list 多组取交集，单组内同字段 indicator 数组取并集；单组只能在 underlying_list / option_list / chain_list / combo_list 中选 1 个非空。
strategy_param	object	请求体	否	策略附加参数。仅当策略以自选股或选股策略结果作为标的来源时必传：watch_stock_id_list:[uint64] / stock_screener_stock_id_list:[uint64]。
field_filter	object	请求体	否	声明需要返回的指标字段。不传时仅返默认 4 字段（volume / price / chg_ratio / implied_volatility）+ option_id。int 字段用 1 占位，string 字段用字符串占位（如 "x"）。嵌套字段按 proto 字段名声明，例 underlying_info:{iv:1, hv:1}。
sort_obj	object	请求体	否	排序方式 {sort_field: OptionItem, is_asc}。sort_field 只设置 1 个字段（如 {"volume":1}）。is_asc 非 0 升序，0/不传降序。不传时按 volume 降序。
next_key	string	请求体	否	翻页游标，首页留空；回传上一页 pagination.next_key。
limit	int	请求体	否	单页返回条数，默认 100，最大 1000；可传 0（仅查询总数，配合 request_exact_data=0）。
request_exact_data	int	请求体	否	是否需要精确明细：0=只返回总数（option_list 为空），1=返回明细列表（默认）。

请求示例

curl -X POST "$ip/v1/quote/option-screen" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": {
      "market_category_list": [0],
      "filter_group_list": [
        {"underlying_list":[{"indicator_type":101,"indicator_value":{"value_list":[205189]}}]},
        {"option_list":[{"indicator_type":1003,"indicator_value":{"value_list":[1]}}]}
      ]
    },
    "field_filter": {
      "hp_strike_price": 1, "option_type": 1, "exercise_type": 1, "expiration_type": 1,
      "in_the_money": 1, "left_day": 1, "price": 1, "volume": 1, "delta": 1,
      "implied_volatility": 1, "option_name": "x",
      "underlying_info": {"price": 1, "iv": 1, "iv_rank": 1}
    },
    "sort_obj": {"sort_field": {"volume": 1}},
    "next_key": "",
    "limit": 5
  }' | jq

响应字段

合约通用字段：

字段	类型	说明
code	string	期权合约 code，例 US.AAPL260115C00200000。
option_name	string	期权合约名称，例 AAPL 260526 312.50C。
strike_price	double	行权价（已除 1e9 还原）。
strike_date	string	行权日期，格式 yyyyMMdd。
strike_date_timestamp	int64	行权日时间戳（毫秒）。
option_type	string	期权方向：CALL / PUT。
exercise_type	string	行权方式：AMERICAN / EUROPEAN。
expiration_type	string	到期类型：WEEK / MONTH / QUARTER 等。
in_the_money	string	实值/虚值：IN_THE_MONEY / OUT_OF_THE_MONEY。
left_day	int	距离到期天数。
multiplier	double	合约乘数（已除 1e9）。
contract_share_size	double	每张合约股数（已除 1e9）。
product_code	string	期权链 product_code。

行情与盘口字段：

字段	类型	说明
price	double	最新价（已除 1e9）。
mid_price	double	买卖中间价（已除 1e9）。
bid_price	double	买一价（已除 1e9）。
ask_price	double	卖一价（已除 1e9）。
bid_ask_spread	double	买卖价差（已除 1e9）。
bid_volume	int	买一量。
ask_volume	int	卖一量。
change_ratio	double	涨跌幅（百分数，已除 1e5）。
volume	int	成交量。
turnover	double	成交额（已除 1e3）。
open_interest	int	未平仓量。

波动率与希腊字母：

字段	类型	说明
implied_volatility	double	隐含波动率（百分数，已除 1e5）。
history_volatility	double	历史波动率（百分数，已除 1e5）。
delta	double	Delta（已除 1e5）。
gamma	double	Gamma（已除 1e5）。
vega	double	Vega（已除 1e5）。
theta	double	Theta（已除 1e5）。
rho	double	Rho（已除 1e5）。
leverage_ratio	double	杠杆比率（已除 1e5）。

标的统计 underlying：

字段	类型	说明
underlying.stock_id	uint64	标的 stock_id。
underlying.volume	int	标的全部期权总成交量。
underlying.open_interest	int	标的全部期权总持仓量。
underlying.iv	double	标的 IV（百分数，已除 1e5）。
underlying.hv	double	标的 HV-30 日（百分数，已除 1e5）。
underlying.iv_rank	double	IV Rank（百分数，已除 1e5）。
underlying.price	double	标的最新价（已除 1e9）。
underlying.change_ratio	double	标的涨跌幅（百分数，已除 1e5）。

分页：

字段	类型	说明
pagination.has_more	bool	是否还有更多数据。
pagination.next_key	string	下一页游标；无更多页为 "-1"。
pagination.total	int	满足条件的期权总数（request_exact_data=0 时上限 9999）。

限制范围

• 支持的市场品类：US_STOCK / US_INDEX / US_FUTURE / HK_STOCK / HK_INDEX / JP_STOCK / JP_INDEX。
• 非支持的 market_category 数值会被后端静默忽略，返回空 option_list 与 pagination.total=0。
• strategy 必填；filter_group_list 单组内 underlying_list / option_list / chain_list / combo_list 只能 1 个非空。
• 分页：不透明 next_key 游标；limit 取值范围 [0, 1000]。
• request_exact_data=0 时 pagination.total 上限 9999，且 option_list 必为空（仅查总数）。
• min_value / max_value 超过 2^53 时建议传字符串（行权价 x1e9 后易越界）。

错误码

ret_code	error.code	触发条件	处理建议
-3	invalid_parameter	缺必填 strategy；limit 越界（>1000）；next_key 非法；field_filter 子字段类型与 proto 不一致；strategy 内 indicator 取值非法。	校正请求体后重试。
1	permission_denied	用户无期权筛选权限。	检查账户行情/期权权限。
-5	backend_biz_error	后端业务异常。	稍后重试或联系服务方。

响应示例

{
  "ret_code": 0,
  "ret_msg": "success",
  "data": {
    "option_list": [
      {
        "code": "US.AAPL260526C00312500",
        "option_name": "AAPL 260526 312.50C",
        "strike_price": 312.5,
        "option_type": "CALL",
        "exercise_type": "AMERICAN",
        "expiration_type": "WEEK",
        "in_the_money": "IN_THE_MONEY",
        "left_day": 5,
        "price": 0.01,
        "volume": 108815,
        "delta": 0.01459,
        "implied_volatility": 3.27059,
        "underlying_info": {
          "price": 200.5,
          "iv": 32.5,
          "iv_rank": 45.3
        }
      }
    ]
  },
  "pagination": { "has_more": true, "next_key": "5", "total": 1923817 }
}