News and alert settings¶
The two read APIs require qot:read and --enable-desktop-phase2-reads. The two setters require qot:write and both --enable-desktop-phase2-reads --enable-desktop-phase2-writes. Both flags default OFF; enabling a flag never adds API-key permissions. Live backend behavior remains UNVERIFIED.
| API / CLI | REST POST |
|---|---|
GetNewsPushSettings / news-push-settings |
/api/news-push-settings |
SetNewsPushSettings / set-news-push-settings |
/api/set-news-push-settings |
GetAlertSystemNotifySetting / alert-system-notify-setting |
/api/alert-system-notify-setting |
SetAlertSystemNotifySetting / set-alert-system-notify-setting |
/api/set-alert-system-notify-setting |
All requests require extension_version: 1. Reads have no other fields. News SET requires all six fields: switch, push_freq, personalized_news_switch, notice_switch, news_notification, notice_notification. Booleans must be explicit, including false. push_freq is 0 disabled/hidden, 1 selected news, 2 important news. Notification enums are 0 unset, 1 off, 2 on. System SET requires system_notify_enable. Every SET additionally requires a nonempty intent_key.
futucli news-push-settings --c2s-json '{"extension_version":1}'
futucli set-alert-system-notify-setting --rest-url http://127.0.0.1:33333 --api-key "$FUTU_API_KEY" --c2s-json '{"system_notify_enable":false,"extension_version":1,"intent_key":"notify-off-001"}'
CLI setters use authenticated REST (--rest-url/--rest-port, --api-key; FUTU_REST_URL and FUTU_API_KEY are supported). MCP setter tools require --opend-rest-url or FUTU_MCP_OPEND_REST_URL; caller API-key overrides/HTTP bearer are forwarded without replacing them with the shared startup connection identity. Tool names are the snake-case API names prefixed with futu_; supply c2s_json and optional api_key. Gateway and gRPC use the same protobuf contracts and write-scope checks.
Receipts and retry¶
Each setter returns s2c.receipt with mandatory ack_state, opaque receipt_id, replayed, readback_status, and comparison, plus optional numeric backend_code/readback_code. The three ACK states are ack_success, ack_rejected, and submitted_unknown. ret_type=0 means a receipt was obtained; it does not mean the setting succeeded.
A successful ACK is followed by one readback. The original optional response is returned as s2c.readback. Readback failure or disagreement never changes the known ACK and never causes another SET. Comparison is matched, mismatched, or inconclusive; missing fields stay inconclusive. With news disabled, a present frequency value is inactive and may differ; other fields still need presence and equality. System setting absent, empty setting, and explicit false are distinct. Disabling system notifications does not stop message reception.
Reuse exactly the same intent_key and settings to retrieve the original receipt without another SET. A previously successful intent may perform a fresh GET; rejected/unknown replay does neither SET nor GET. A new user action needs a new key: on→off→on uses three distinct intents. Different content under an old key is rejected. An unknown outcome continues to block new keys for the same target; a same-value GET cannot prove that an unknown write completed exactly once.
If admission was rejected before sending, only its unsent target reservation is released; the immutable intent remains. Nothing already send-started or unknown is released this way. Same-user connection loss retains known receipts; a replaced user/authority/route does not disclose old user data. No raw backend error text or credentials are returned.
News reads preserve optional fields and numeric status: status 1001 may carry no data; status 1002 or missing status is an error. Alert reads preserve both setting-container and boolean presence; an omitted status is accepted. The API never turns these absences into a confirmed user preference.