价格与指标提醒设置¶
启动网关时用 --enable-desktop-phase2-reads 启用读取；设置还需 --enable-desktop-phase2-writes。两项默认关闭，且不会增加 API Key 的权限。真实后端行为尚未验证。
| 操作 | REST POST | MCP | CLI | 权限 |
|---|---|---|---|---|
| 读取提醒 | /api/reminder-settings |
futu_get_reminder_settings |
reminder-settings |
qot:read |
| 批量修改 | /api/mutate-reminder-settings |
futu_mutate_reminder_settings |
mutate-reminder-settings |
qot:write |
两项均使用 --c2s-json / c2s_json，extension_version 必须为 1。CLI 与 MCP 的设置操作通过配置的 REST 地址转发实际调用者的 API Key；调用者必须具有写权限。Gateway 与通用 gRPC 使用对应公开协议消息。
读取¶
省略 stock_id 读取当前用户全部提醒；传入时必须非零。返回价格、指标及实际收到的通用/组合提醒原始字段。缺失字段、未知枚举、64 位标识及整数精度保持不变；价格与指标的 key 属于不同类别，不能混用。JavaScript 调用方应使用能保留 64 位整数精度的 JSON 工具。
设置¶
{"extension_version":1,"intent_key":"disable-reminder-example","quote_broker_id":0,"operations":[{"operation":5,"stock_id":0,"kind":2,"key":0}]}
⚠️ 示例中的股票和 key 的 0 是故意无效的占位；先读取当前用户提醒，再填入真实身份。quote_broker_id 必须显式提供 0、1001、1007 或 1008，不会自动选择。operations 是非空有序数组；每项包含 operation、stock_id、kind。kind=1 表示价格提醒，kind=2 表示指标提醒。
| operation | 含义 | 附加字段 |
|---|---|---|
| 1 | 新增指标 | kind 必须为 2；提供 indicator，不传 key/price |
| 2 | 修改同类指标内容 | kind 为 2；提供 key、indicator |
| 3 | 切换提醒类别 | 提供原类别 kind、key，以及 indicator/price 中恰好一个目标定义 |
| 4 / 5 / 6 | 启用 / 停用 / 删除 | 提供 key，不传目标定义 |
内容修改与类别切换会重新启用提醒。新增普通价格提醒继续使用既有价格提醒接口。一个批次可以包含多只股票及价格/指标混合操作；类别切换在同一批次中删除旧项、增加新项，后端不承诺原子回滚。
指标定义要求 indicator_type、freq_type、note，以及支持的形态或左右比较条件。写入只支持日线，频率为 1/2/4；MA/EMA 周期支持 5/10/20/30/60/120/250，RSI 为 6/12/24，KDJ 为 [9,3,3]、MACD 为 [12,26,9]、BOLL 为 [20,2]。自定义比较保留有符号整数，不接受浮点近似。参数组合由接口验证；读取到未知类型不代表允许新建该类型。
| indicator_type | Indicator |
|---|---|
| 1 / 2 | MA / EMA |
| 3 / 4 | KDJ / RSI |
| 5 / 6 | MACD / BOLL |
原始数值的单位¶
本接口接收已换算好的整数，不自动处理“万／千／K”、百分比、小数舍入或股票价格精度。请使用十进制定点运算，避免浮点误差。
| warn_type | 含义 | fine_warn_param |
|---|---|---|
| 4、8、14、15 | 涨到价、跌到价、买一价、卖一价 | 报价数值 × 10^9 |
| 1、2、9、10、19、20 | 日／5分钟／3分钟涨跌幅 | 百分点 × 1000；5% 为 5000 |
| 13 | 换手率 | 百分点 × 1000 |
| 11 | 成交量 | 非期权期货：以万为单位的数量 × 1000；期权期货：张数 × 1000 |
| 12 | 成交额 | 以万为单位的成交额 × 1000 |
| 16、17 | 买一量、卖一量 | 非期权期货：以千为单位的数量 × 1000；期权期货：张数 × 1000 |
| 18 | 公告 | 0 |
数量单位：期权、期货为张；其他标的在 CN 市场为手，在其他市场为股，不额外进行 lot-size 换算。例如，成交量的 25K 与 2.5万都对应 raw 2500。股票价格精度影响原客户端允许输入的小数位，不改变价格的 10^9 倍率。
指标自定义固定右值使用原值 × 1000。原客户端允许范围为 ±99,999,999.999，超过三位的小数向零截断，例如 -12.3456 对应 -12345。这里要求直接提供 raw 整数，网关不会代做 UI 字符串转换或舍入。
结果与重入¶
HTTP 成功或 ret_type=0 表示获得回执。必须读取 s2c.receipt.ack_state：
ack_success：收到成功结果。ack_rejected：收到失败结果，不表示所有项均未执行或已回滚。ack_partial：收到部分失败结果，不能推断每一项的最终状态。submitted_unknown：无法确定发送结果，不会自动重发。
回执另含 receipt_id、replayed、原始结果码及 observation_state（not_observed、observed、unavailable）。读回与 ACK 独立；读回一致不会把 unknown 改成已确认，也不能据此认领新建 key。
同一 intent_key 重入返回原回执；不同请求使用同 key 会冲突。跨重启仍不会重发已开始发送的操作。unknown 保留其目标股票占用，阻止重叠修改；不阻塞无关股票。收到明确结果后，新的用户决定应使用新的 intent key。