Reference data and news extension reads¶

This page covers five versioned reads: forex rates, related stocks, earnings expected moves, news translation, and forex constituents. Start the gateway with --enable-desktop-phase2-reads to opt in; the flag is OFF by default. Authenticated access requires qot:read. Live backend validation is UNVERIFIED, pending authorized testing. Enabling the flag does not establish coverage for every market, account, or data boundary.

Entry points¶

API	CLI command	REST (POST)	MCP tool
`GetForexRates`	`forex-rates`	`/api/forex-rates`	`futu_get_forex_rates`
`GetRelatedStocks`	`related-stocks`	`/api/related-stocks`	`futu_get_related_stocks`
`GetEarningsExpectedMove`	`earnings-expected-move`	`/api/earnings-expected-move`	`futu_get_earnings_expected_move`
`GetNewsTranslation`	`news-translation`	`/api/news-translation`	`futu_get_news_translation`
`GetForexConstituents`	`forex-constituents`	`/api/forex-constituents`	`futu_get_forex_constituents`

The same operations are available through gateway and gRPC requests. Use the C2S JSON below directly as the REST POST body. CLI commands take --c2s-json; MCP tools take a JSON string in c2s_json. Examples use snake_case: the protocol field extensionVersion becomes extension_version. All five requests require this field to equal 1. Unknown fields and unsupported versions are rejected.

futucli forex-rates --c2s-json '{"extension_version":1}'
futucli related-stocks --c2s-json '{"extension_version":1,"security":{"market":1,"code":"00700"}}'
futucli forex-constituents --c2s-json '{"extension_version":1,"list_id":1,"data_from":0,"data_max_count":20}'

Example MCP arguments:

{"c2s_json":"{\"extension_version\":1}"}

Request parameters¶

Every row below also requires extension_version: 1.

Operation	Required fields	Optional fields
Forex rates	No additional fields	None
Related stocks	`security`: object containing numeric `market` and string `code`	None
Earnings expected move	`stock_id`: nonzero numeric security identifier	None
News translation	Nonempty string `news_id`; boolean `is_translate`; integer `list_type`; boolean `skip_image_crop`	None
Forex constituents	`list_id`: 1–12; nonnegative `data_from`; `data_max_count`: 1–500	`sort_id`: 0–38, default 0 (weight); `sort_type`: 1 ascending or 2 descending, default 2

Related stocks requires a structured security, such as {"market":1,"code":"00700"}, rather than a standalone security string. Obtain security identifiers and forex list identifiers from available data; a ticker is not a stock_id. Related-stock and forex-constituent requests use the current session's broker context; callers do not supply broker IDs.

Both forex pagination fields are required, including on the first page. Read if_last_page and all_count, then advance data_from by the number of rows returned. A list may contain an empty stock_info array; a response without any list object is an error.

is_translate: true requests translation into the client language; false requests the original. list_type retains its integer meaning, and skip_image_crop must be explicit. Replace the example news identifier with one obtained from a news query:

{"extension_version":1,"news_id":"REPLACE_WITH_NEWS_ID","is_translate":true,"list_type":0,"skip_image_crop":false}

Responses and precision¶

Responses contain ret_type, optional ret_msg and err_code, and successful data in s2c. Upstream rejection, malformed responses, invalidated sessions, or changes to the relevant broker context produce errors rather than empty success. Missing optional values remain distinct from explicit zero values.

Operation	Success data	Interpretation
Forex rates	`backend_ret_code`, `rate_items`	Each row preserves optional `base_currency`, `quote_currency`, `price`, and `stock_id`. Currencies are raw integers and `price` is decimal text. Duplicate pairs, row order, and missing fields are retained. This is not a deduplicated conversion cache; validate prices before using them.
Related stocks	`backend_ret_code`, `related_stock_info`	Each row preserves optional `stock_id`, `name`, and `adr_info`. Raw ADR integers `ads_base` and `ads_convertion` are retained: 1000:5000 means one underlying share to five ADRs. No relationship-classification field is returned.
Earnings expected move	`backend_ret_code`, `detail`	Preserves fiscal year, financial type, publication times, expected moves, and optional `price_info`. Prices are integers scaled by 10⁹; `option_iv` and `option_hv` use 10⁵. An expected-move value of 12345 means 12.345%. Volume uses 10 raised to `volume_precision`.
News translation	`backend_code`, `single_news_translate_info`	Preserves optional `title`, `abstract`, `cover_image`, `source`, `url`, `video_url`, `interaction_tag`, and `ai_subtitle`. Missing text is distinct from an empty string.
Forex constituents	`backend_ret`, `lists`	Preserves list/sort identifiers, pagination metadata, security fields, multilingual names, financial indicators, and 24-hour statistics. Prices use 10⁹, ratios 10⁵, turnover 10³, and volume uses `volume_precision`.

For earnings, pub_time is a timestamp in seconds. trading_day and pub_trading_day represent midnight in the relevant market's trading-day context; do not infer dates using the local machine's timezone. Use JSON clients and numeric types that preserve 64-bit integers exactly. Avoid converting decimal rate strings to low-precision floating point before storage.

Compatible additions to existing news reads¶

Filter options in latest-news / POST /api/latest-news / futu_get_latest_news gain optional string_info containing complete label metadata:

string_id, template_data, lang_spec_temp_data, and template_map.
Language templates contain language_tag, template_data, and language_id.
Template map entries contain key and value.

Existing option-level string_id remains available for older clients. Request metadata with include_flash_filter and/or include_market_filter, and provide filter_version; first_visit applies only to the flash filter. Pagination still requires page_size (1–50), page_flip (0 older, 1 newer), and extension_version: 1. Continue with the returned seq_mark or latest_seq_mark. This addition and the plate-news read below retain --enable-v18-experimental-reads, which is OFF by default; the new reference-read flag does not replace it.

stock-news / POST /api/stock-news / futu_get_stock_news already supports id_type: 1 for securities and id_type: 2 for plates. Required fields are stock_id, page_size (1–50), id_type, and extension_version: 1. Optional seq_from and seq_to are forwarded as raw unsigned integers; when both are supplied, seq_from <= seq_to is required. Do not infer local dates or apply timezone conversion to these raw bounds. Existing scene_id, audio_only, source, translate, seq_mark, caller_biz, track_info, and dedup_ids retain their request contracts.

Account history and futures reads