参考数据与新闻扩展读取¶
本页介绍五个版本化读取接口：外汇汇率、关联股、财报预期波动、新闻翻译和外汇成分列表。启动网关时需显式添加 --enable-desktop-phase2-reads；默认关闭。鉴权环境需要 qot:read。当前真实后端验证状态为 UNVERIFIED，待授权真机验证，启用开关不表示所有市场、账户和数据边界均已验证。
入口对应¶
| API | CLI 子命令 | REST（POST） | MCP 工具 |
|---|---|---|---|
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 |
这些接口也可通过统一网关和 gRPC 请求访问。REST 的 POST body 直接使用下述 C2S JSON；CLI 使用 --c2s-json；MCP 使用字符串参数 c2s_json。以下 JSON 字段采用 snake_case；协议字段 extensionVersion 对应 extension_version，五个接口均必填且只能为 1。未知字段或不支持的版本会被拒绝。
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}'
MCP 参数示例：
请求参数¶
除每项均需 extension_version: 1 外，参数如下。
| 接口 | 必填参数 | 可选参数 |
|---|---|---|
| 外汇汇率 | 无其他参数 | 无 |
| 关联股 | security：对象，含数字 market 和字符串 code |
无 |
| 财报预期波动 | stock_id：非零证券标识整数 |
无 |
| 新闻翻译 | news_id：非空字符串；is_translate：布尔值；list_type：整数；skip_image_crop：布尔值 |
无 |
| 外汇成分列表 | list_id：1–12；data_from：非负分页起点；data_max_count：1–500 |
sort_id：0–38，默认 0（权重）；sort_type：1 升序、2 降序，默认 2 |
关联股的 security 是结构化对象，例如 {"market":1,"code":"00700"}，不能替换为单独的证券字符串。证券标识和外汇列表编号应来自已经获取的数据；不要把证券代码当成 stock_id。关联股和外汇成分请求使用当前会话的券商上下文，无需传券商编号。
外汇成分列表的两个分页字段均为必填，包括第一页。使用结果中的 if_last_page、all_count 判断进度，按实际返回条数推进 data_from。一个列表内的 stock_info 可以为空；响应缺少列表对象会报错。
is_translate: true 请求按客户端语言翻译；false 请求原文。list_type 保留整数语义，skip_image_crop 必须显式选择。示例新闻标识仅用于展示参数结构，应替换为查询所得标识：
{"extension_version":1,"news_id":"REPLACE_WITH_NEWS_ID","is_translate":true,"list_type":0,"skip_image_crop":false}
返回值与精度¶
统一响应使用 ret_type、可选的 ret_msg、err_code 和成功数据 s2c。上游拒绝、响应无法解析、会话失效或相关券商上下文变化会返回错误，不应视为空结果成功。可选字段的缺失和显式零值含义不同，客户端不应自行把缺失补为零。
| 接口 | 成功数据 | 读取注意事项 |
|---|---|---|
| 外汇汇率 | backend_ret_code、rate_items |
每项含可选 base_currency、quote_currency、price、stock_id。币种为原始整数；price 为原始十进制字符串。保留重复币对、行序和缺失字段；这不是去重后的货币转换缓存，使用前需检查价格有效性。 |
| 关联股 | backend_ret_code、related_stock_info |
每项含可选 stock_id、name、adr_info。ADR 的 ads_base、ads_convertion 保留两个原始整数，例如 1000:5000 表示 1 股正股对应 5 份 ADR；不输出关联分类字段。 |
| 财报预期波动 | backend_ret_code、detail |
保留财年、报表类型、公布时间、预期波动和完整可选 price_info。价格为放大 10⁹ 的整数；option_iv、option_hv 为放大 10⁵ 的整数。预期波动整数 12345 表示 12.345%。成交量按 volume_precision 的 10 次幂缩放。 |
| 新闻翻译 | backend_code、single_news_translate_info |
保留可选 title、abstract、cover_image、source、url、video_url、interaction_tag、ai_subtitle。缺少某字段不代表空字符串。 |
| 外汇成分列表 | backend_ret、lists |
保留列表与排序标识、分页信息、证券字段、多语言名称、金融指标、24 小时统计等可选数据。价格放大 10⁹、比率放大 10⁵、成交额放大 10³，成交量按 volume_precision 缩放。 |
财报的 pub_time 是秒级时间戳；trading_day 和 pub_trading_day 表示对应市场交易日的午夜。不要用本机时区猜测交易日期。处理 64 位原始整数时，选择能够准确保留整数的 JSON 客户端和数值类型；汇率字符串不要先转为低精度浮点数再存储。
已有新闻接口的兼容扩展¶
latest-news / POST /api/latest-news / futu_get_latest_news 的筛选选项新增可选 string_info，保留完整标签元数据：
string_id、template_data、lang_spec_temp_data、template_map。- 每个语言模板含
language_tag、template_data、language_id。 - 每个模板映射项含
key、value。
原有选项上的 string_id 继续保留，旧客户端可以继续读取。使用 include_flash_filter、include_market_filter 请求对应元数据，并提供 filter_version；first_visit 仅作用于快讯筛选。分页仍需 page_size（1–50）、page_flip（0 向旧、1 向新）及 extension_version: 1，游标按返回的 seq_mark 或 latest_seq_mark 续传。该扩展与下述板块新闻读取均沿用 --enable-v18-experimental-reads，默认关闭；新参考数据开关不会替代它。
stock-news / POST /api/stock-news / futu_get_stock_news 已支持 id_type: 1（证券）和 id_type: 2（板块）。必填 stock_id、page_size（1–50）、id_type、extension_version: 1。可选 seq_from、seq_to 按原始无符号整数透传；同时提供时必须满足 seq_from <= seq_to。不要将这些原始边界自行解释为本地日期或做时区换算。scene_id、audio_only、source、translate、seq_mark、caller_biz、track_info、dedup_ids 继续沿用原有请求合同。