期權篩選

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 }
}