Quote analytics and instrument data¶
These 19 versioned reads require qot:read, extension_version: 1, and --enable-desktop-phase2-reads (default OFF). Live backend availability and content rights remain UNVERIFIED. They do not subscribe to quotes, enable credit billing, or start polling.
| API | CLI | REST POST | MCP |
|---|---|---|---|
GetOptionChainMetadata |
option-chain-metadata |
/api/option-chain-metadata |
futu_get_option_chain_metadata |
GetOptionGexByStrike |
option-gex-by-strike |
/api/option-gex-by-strike |
futu_get_option_gex_by_strike |
GetOptionGexProfile |
option-gex-profile |
/api/option-gex-profile |
futu_get_option_gex_profile |
GetOptionStrikePrices |
option-strike-prices |
/api/option-strike-prices |
futu_get_option_strike_prices |
GetOptionIvTermStructure |
option-iv-term-structure |
/api/option-iv-term-structure |
futu_get_option_iv_term_structure |
GetOptionIvSmile |
option-iv-smile |
/api/option-iv-smile |
futu_get_option_iv_smile |
GetOptionVolumeInterestDistribution |
option-volume-interest-distribution |
/api/option-volume-interest-distribution |
futu_get_option_volume_interest_distribution |
GetMarginRanking |
margin-ranking |
/api/margin-ranking |
futu_get_margin_ranking |
GetStockAdvancedIndicators |
stock-advanced-indicators |
/api/stock-advanced-indicators |
futu_get_stock_advanced_indicators |
GetCbbcBasicInfo |
cbbc-basic-info |
/api/cbbc-basic-info |
futu_get_cbbc_basic_info |
GetCbbcDistribution |
cbbc-distribution |
/api/cbbc-distribution |
futu_get_cbbc_distribution |
GetCalendarFutureUnderlyings |
calendar-future-underlyings |
/api/calendar-future-underlyings |
futu_get_calendar_future_underlyings |
GetCalendarFutureSpreads |
calendar-future-spreads |
/api/calendar-future-spreads |
futu_get_calendar_future_spreads |
GetStockHoldings |
stock-holdings |
/api/stock-holdings |
futu_get_stock_holdings |
GetFundTopHoldings |
fund-top-holdings |
/api/fund-top-holdings |
futu_get_fund_top_holdings |
GetFundInvestmentDistribution |
fund-investment-distribution |
/api/fund-investment-distribution |
futu_get_fund_investment_distribution |
GetBondQuoteInfo |
bond-quote-info |
/api/bond-quote-info |
futu_get_bond_quote_info |
GetChipDistribution |
chip-distribution |
/api/chip-distribution |
futu_get_chip_distribution |
GetOptionEventDetail |
option-event-detail |
/api/option-event-detail |
futu_get_option_event_detail |
REST takes the C2S object directly; CLI uses --c2s-json; MCP takes its JSON string in c2s_json with optional api_key. Gateway and gRPC expose the same contract. IDs and fixed-point values remain integers; use a parser that retains 64-bit integer precision.
| API | Fields beyond version (? optional) |
|---|---|
GetOptionChainMetadata |
stock_id, option_market; index_option_type? |
GetOptionGexByStrike |
stock_id, option_market, chains; index_option_type? |
GetOptionGexProfile |
stock_id, option_market, chains; index_option_type?, point_count? |
GetOptionStrikePrices |
stock_id, option_market; index_option_type? |
GetOptionIvTermStructure |
stock_id, option_market, strike_price; index_option_type? |
GetOptionIvSmile |
stock_id, option_market; index_option_type?, strike_date?, expiration?, strike_date_list? |
GetOptionVolumeInterestDistribution |
stock_id, option_market, distribution_type; index_option_type?, chains?, strike_date?, strike_date_list?, sort_field?, is_asc? |
GetMarginRanking |
margin_type, market_type, quote_info_type, fetch_pos; filters/sort/fetch_num? |
GetStockAdvancedIndicators |
stock_id_list, describe |
GetCbbcBasicInfo |
underlying_id |
GetCbbcDistribution |
underlying_id, trading_day; granularity?, count? |
GetCalendarFutureUnderlyings |
include_detail?, data_from?, data_max_count? |
GetCalendarFutureSpreads |
stock_id; filter?, data_from?, data_max_count? |
GetStockHoldings |
stock_id; item_count?, offset? |
GetFundTopHoldings |
stock_id |
GetFundInvestmentDistribution |
stock_id; distribution_type? |
GetBondQuoteInfo |
bond_id |
GetChipDistribution |
stock_id; time?, count?, kline_type? |
GetOptionEventDetail |
combine_event_key, from, market_type; count?, sort_field?, is_asc? |
Option selection and precision¶
option_market is US 0 / HK 1 / CME 2 / JP 3, and must match the authoritative stock metadata. Event-detail market_type uses a different enum: HK 1 / US 2 / US futures 3 / JP 4. These are not interchangeable.
Read GetOptionChainMetadata first. Each chains selector contains four required fields: strike_date, symbol, hp_multiplier, hp_contract_share_size. Copy these from the returned chain. GEX rechecks current metadata and uses the authoritative full chain; stale, forged or ambiguous selectors fail. Same-day nonstandard contracts remain distinct. Metadata retains 13 fields, including strike_date_ymd and real_expiration_time. CME needs complete linkage and related-contract metadata; missing prerequisites fail rather than treating a partial record as a real contract.
Empty GEX chains, term strikes, smile dates or distribution selection produce a successful empty response with no backend request, including while disconnected. Basic field and version validation still applies. These empty lists do not mean “all chains.” Profile point_count accepts 0–20000; omission has the same non-interpolating meaning as 0, not 5000. Returned point count is not guaranteed to equal the requested count.
GEX prices/walls/flip points scale by 1e9, exposures by 1e3. Signed put/net values remain signed. IV values scale by 1e5; raw zero means unavailable, not zero volatility. Server average IV is retained. Smile legacy strike_date and batch strike_date_list cannot be mixed; expiration remains usable with batch dates. Both response shapes are preserved. Volume/interest selection precedence is chains, date list, then legacy date; type 1 is volume, 2 is open interest. Quantities remain raw unsigned contract counts. HK index IV behavior is not confirmed live.
Rankings, indicators and CBBC¶
Margin ranking uses current ordered broker metadata. Margin type 0 and quote type 0 are valid explicit values. Margin type supports 0–5, market type 1–8, quote type 0/1, sort type 0/1 and sort column 0–11. Price bounds require explicit price_filter_type=0; market-cap and PE bounds may be one-sided. Bounds are inclusive. Prices/price changes scale by 1e9; change ratios by 1e5; turnover/market-cap/PE by 1e3. Margin doubles use 1=100%; short_fee_rate is already a percentage string. Preserve has_more/count for single-page navigation.
Advanced indicators accept 1–1000 stock IDs and nonempty describe entries with indicator_id 1 (Pearson) or 2 (Beta); each may have an empty underlying whitelist to request all supported targets. Beta and empty-whitelist requests are explicit protocol-declared extensions: no Desktop Beta caller or live result is claimed. Only returned supported items exist; do not synthesize zeros. Actual indicator IDs, duplicates, values (scale 1e5) and opaque next_request_ts are retained.
CBBC distribution first validates the selected trading day and granularity against fresh basic data. Omitted granularity selects the reported default index, falling back to the first value only when that index is out of range and the list is nonempty. Reuse raw trading-day values returned by the basic endpoint. count is a number of intervals, not pagination. Prices and granularity scale by 1e3; keep local/global heavy-cargo and increase flags distinct, and absent index-only fields absent.
Futures, holdings, bonds and chips¶
Calendar-future underlyings return all IDs when include_detail=false; pagination applies only to detail mode. Spreads require the stock to appear in the current supported universe. filter.contract_interval=0 means omit the interval filter; allowed intervals are returned dynamically. FieldValue retains signed value, precision, text and content type: NUMBER scale 1e9, PERCENT ratio scale 1e9, PLAIN unscaled, TEXT uses text. Unknown fields/types remain available.
Full holdings are paginated; top holdings and investment distribution are not. All nine distribution classes are retained, including currency and investment. Rows without stock IDs, duplicate rows and name_key/holding_id survive. Holding/change ratios scale by 1e5; no 1e9 scale is implied for holding money. These responses do not provide a supplier field, so no provider is invented. Update/date fields retain their own service values.
Bond details retain the full header, raw optional KV pairs, risk/trading rules and redemption information. The four price/amount fields use 1e9. A returned link may be a link identifier rather than a navigable URL; the daemon does not open or invent URLs. Text follows the daemon's backend language context.
Chip time is a seconds timestamp at the requested market day's start; 0/omission uses the current query point. No timezone is guessed from a date string. Kline mapping: 1min=1, 3min=10, 5min=6, 15min=7, 30min=8, 60min=9, day=2, week=3, month=4, quarter=11, year=5. Prices scale by 1e9, profit/coincidence ratios by 1e4, price precision by 1e6. update_time is a refresh interval in seconds, not an as-of timestamp. Full language templates and any credit response are preserved; outer result and auxiliary credit status are separate. No credit activation/payment or automatic retry is performed.
Event-detail workflow¶
With the switch enabled, existing GetOptionEvent results additionally expose combine_event_key, is_combine_event, and new_id when supplied. Pass the nonempty key to GetOptionEventDetail. With the switch off, these fields are absent from the original wire/JSON output.
Detail from is nonnegative; count defaults to 300 and accepts 1–500. Sort values follow the public event sort contract, excluding 11 and internal value 23. next_from=0 or absent ends paging. Ticker.time/latest_time use milliseconds; other documented event dates use seconds. Detail preserves all raw ticker fields and u64 quantity; it does not reuse the older display-oriented conversions or list truncation. Transport, malformed response and source-change failures are errors, not successful empty pages.