REST API Complete Reference¶

Added in v1.4.85. Auto-generated by the FutuOpenD-rs build pipeline and refreshed with every daemon release.

This page covers all 220 REST endpoints of futu-opend, organized into 9 functional groups. Each endpoint documents:

HTTP method + URL
Backend proto_id
Required auth scope
Parameter docs (in proto definitions)
Error hints
curl example

Quick nav:

Group	Endpoints	Link
System / Status	7	System / Status
Quote Subscriptions	5	Quote Subscriptions
Quote Queries	26	Quote Queries
Plates / Filter / Metadata	8	Plates / Filter / Metadata
Reference / Derivatives	49	Reference / Derivatives
Price Reminders	2	Price Reminders
Trading Accounts (Read)	28	Trading Accounts (Read)
Trading Write	8	Trading Write
Admin	87	Admin

Global conventions¶

Legacy read-only Base URL: http://127.0.0.1:22499 (default REST port; change it with --rest-port). Credential-free reads remain available over HTTP when no keys file is configured:
```
curl http://127.0.0.1:22499/health
```
Scope mode Base URL: https://127.0.0.1:22499. Configuring rest_keys_file enables REST scope mode and requires both rest_tls_cert and rest_tls_key. The daemon validates the certificate/private key before broker login and refuses to bind authenticated REST over plaintext.
WebSocket: use wss://127.0.0.1:22499/ws for /ws on the same listener in scope mode. Legacy no-key compatibility may continue to use ws://.
Content-Type: application/json
Auth: Authorization: Bearer <API_KEY> (if keys.json is configured; otherwise legacy mode without auth — and since v1.4.86 fail-closed is the production default)

Response envelope:

{
  "ret_type": 0,
  "ret_msg": null,
  "err_code": null,
  "s2c": { ...business payload... }
}

ret_type == 0 means success; other values see common error codes.

Field naming: v1.4.83+ accepts aliases (SDK-style code / stocks / trd_env); canonical is snake_case (symbol / symbols / env). At the REST layer, enum fields (trd_market / trd_env / kl_type / op / reference_type …) accept int only (½/3...); the string form ("HK"/"US"/"day") is supported only at the MCP layer (futu_* tools) which auto-converts to int. Unknown fields since v1.4.84 loud fail (unknown field error).
Rate / limits: Controlled via startup flags (--allowed-markets, --max-order-value, etc.). See docs/guide/auth.en.md.

System / Status¶

Health checks are public. /api/* system read endpoints stay public in legacy mode without keys.json, and use the listed scope in scope-mode.

`GET /api/delay-statistics`¶

proto_id: GET_DELAY_STATISTICS (1007)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/delay-statistics

`POST /api/delay-statistics`¶

proto_id: GET_DELAY_STATISTICS (1007)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"type_list":[1],"qot_push_stage":1}' \
  https://127.0.0.1:22499/api/delay-statistics

`GET /api/global-state`¶

proto_id: GET_GLOBAL_STATE (1002)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/global-state

`GET /api/ping`¶

proto_id: GET_GLOBAL_STATE (1002)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/ping

`GET /api/push-subscriber-info`¶

proto_id: — (non-proto / no backend forwarding)

Scope: legacy/public: —; scope-mode: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/push-subscriber-info

`GET /api/quote-rights`¶

proto_id: TEST_CMD (1008)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/quote-rights

`GET /api/user-info`¶

proto_id: GET_USER_INFO (1005)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/user-info

Quote Subscriptions¶

Subscribe/unsubscribe quote push, query subscription state, and receive push via WebSocket /ws. All three use qot:read.

`POST /api/query-subscription`¶

proto_id: QOT_GET_SUB_INFO (3003)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"is_req_all_conn":true}' \
  https://127.0.0.1:22499/api/query-subscription

`GET /api/sub-info`¶

proto_id: QOT_GET_SUB_INFO (3003)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/sub-info

`POST /api/subscribe`¶

proto_id: QOT_SUB (3001)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"],"sub_types":[1],"is_sub_or_un_sub":true}' \
  https://127.0.0.1:22499/api/subscribe

`POST /api/unsubscribe`¶

proto_id: QOT_SUB (3001)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"],"sub_types":[1],"is_sub_or_un_sub":false}' \
  https://127.0.0.1:22499/api/unsubscribe

`GET /ws`¶

proto_id: — (non-proto / no backend forwarding)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Legacy mode without keys.json stays public for compatibility. In scope-mode, the handshake must carry ?token= or Authorization: Bearer <key>, and the key must have qot:read.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/ws

Quote Queries¶

Real-time quotes, K-line, order book, broker queue, time-sharing, ticker, ticker statistics, risk-free rate, spread table, and quote quota. Requires qot:read.

`POST /api/broker`¶

proto_id: QOT_GET_BROKER (3014)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/broker

`POST /api/capital-distribution`¶

proto_id: QOT_GET_CAPITAL_DISTRIBUTION (3212)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/capital-distribution

`POST /api/capital-flow`¶

proto_id: QOT_GET_CAPITAL_FLOW (3211)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","period_type":1}' \
  https://127.0.0.1:22499/api/capital-flow

`POST /api/history-kl-quota`¶

proto_id: QOT_REQUEST_HISTORY_KL_QUOTA (3104)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Quota source: used_quota / remain_quota use the account's dynamic historical K-line quota returned by CMD6024 after login. FUTU_HISTORY_KL_QUOTA_MAX only overrides that dynamic quota when explicitly set. Before the dynamic quota arrives, Rust uses the C++ cold-start default 100 as a fail-closed fallback.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"b_get_detail":false}' \
  https://127.0.0.1:22499/api/history-kl-quota

`POST /api/history-kline`¶

proto_id: QOT_REQUEST_HISTORY_KL (3103)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Note: REST kl_type accepts integers only (e.g. 1=Day / 2=Week / 3=Month / 5=Min1 / 6=Min5 / 7=Min15 / 8=Min30 / 9=Min60 / 10=Min3 / 11=Min4); the string form ("day") is supported only at the MCP layer. Field count is alias-mapped to proto req_num (both accepted).

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","rehab_type":0,"kl_type":1,"max_count":100,"begin_time":"2026-01-01 00:00:00","end_time":"2026-04-01 23:59:59"}' \
  https://127.0.0.1:22499/api/history-kline

`POST /api/kline`¶

proto_id: QOT_GET_KL (3006)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Note: Same as /api/history-kline — REST kl_type accepts integers only; proto field is canonical req_num, count is the v1.4.83+ alias.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","rehab_type":0,"kl_type":1,"req_num":100}' \
  https://127.0.0.1:22499/api/kline

`POST /api/kline-pattern`¶

proto_id: QOT_GET_KLINE_PATTERN (2131755021)

Scope: qot:read

Disabled by default: requires --enable-v18-kline-patterns. Evidence is source-aligned + local-green; live backend behavior remains unverified. Point/line values are restored from 1e9 scale and field presence is preserved.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_id":7001,"kline_type":2,"extension_version":1}' \
  https://127.0.0.1:22499/api/kline-pattern

`POST /api/kline-pattern-catalog`¶

proto_id: QOT_GET_KLINE_PATTERN_CATALOG (2131755025)

Scope: qot:read

Disabled by default: requires --enable-v18-kline-patterns. count<=0 requests all rows (Desktop sends -1); URLs/strings are returned unchanged and are not opened or validated by the daemon.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"filter":0,"count":-1,"start_count":0,"color":0,"extension_version":1}' \
  https://127.0.0.1:22499/api/kline-pattern-catalog

`POST /api/kline-pattern-performance`¶

proto_id: QOT_GET_KLINE_PATTERN_PERFORMANCE (2131755024)

Scope: qot:read

Independently disabled / UNVERIFIED: requires --enable-v18-kline-pattern-performance. The pinned Desktop source has a proto and registry entry but no business caller, so responses must explicitly contain ret_code=0; profit fields remain signed raw values because the source defines no scale.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"shape":1,"duration":0,"extension_version":1}' \
  https://127.0.0.1:22499/api/kline-pattern-performance

`POST /api/kline-pattern-statistics`¶

proto_id: QOT_GET_KLINE_PATTERN_STATISTICS (2131755022)

Scope: qot:read

Disabled by default: requires --enable-v18-kline-patterns. Forecast/backtest fields are descriptive statistics, not deterministic investment advice. URLs/strings are opaque metadata and are neither fetched nor rewritten by the daemon.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_id":7001,"kline_type":2,"shape":1,"color":0,"extension_version":1}' \
  https://127.0.0.1:22499/api/kline-pattern-statistics

`POST /api/kline-pattern-stocks`¶

proto_id: QOT_GET_KLINE_PATTERN_STOCKS (2131755023)

Scope: qot:read

Disabled by default: requires --enable-v18-kline-patterns. sort_type=-1 preserves backend-default ordering; count<=0 requests all rows; watchlist/holding ID order and duplicates are sent unchanged.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"kline_type":2,"shape":1,"market":3,"sort_order":1,"sort_type":-1,"count":-1,"start_count":0,"user_stock_list_mode":0,"extension_version":1}' \
  https://127.0.0.1:22499/api/kline-pattern-stocks

`POST /api/market-state`¶

proto_id: QOT_GET_MARKET_STATE (3223)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"]}' \
  https://127.0.0.1:22499/api/market-state

`POST /api/orderbook`¶

proto_id: QOT_GET_ORDER_BOOK (3012)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","depth":10}' \
  https://127.0.0.1:22499/api/orderbook

`POST /api/quote`¶

proto_id: QOT_GET_BASIC_QOT (3004)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/quote

`GET /api/quote-capability`¶

proto_id: TEST_CMD (1008)

Scope: legacy/public: —; scope-mode: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/quote-capability

`GET /api/risk-free-rate`¶

proto_id: QOT_GET_RISK_FREE_RATE (20231)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Purpose: Risk-free rate for HK / US / JP, required for Black-Scholes option pricing.

Field table (no required field):

Field	Type	Required	Description
`rate_time`	int64	optional	Unix ms timestamp; omit for latest rate

Response: s2c includes hk_rate_pct / us_rate_pct / jp_rate_pct (percent, e.g. 4.5 for 4.5%). The raw uint64 (×10^9) values are also exposed so callers can verify on their own.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/risk-free-rate

`POST /api/risk-free-rate`¶

proto_id: QOT_GET_RISK_FREE_RATE (20231)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Purpose: Risk-free rate for HK / US / JP, required for Black-Scholes option pricing.

Field table (no required field):

Field	Type	Required	Description
`rate_time`	int64	optional	Unix ms timestamp; omit for latest rate

Response: s2c includes hk_rate_pct / us_rate_pct / jp_rate_pct (percent, e.g. 4.5 for 4.5%). The raw uint64 (×10^9) values are also exposed so callers can verify on their own.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/risk-free-rate

`POST /api/rt`¶

proto_id: QOT_GET_RT (3008)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/rt

`POST /api/snapshot`¶

proto_id: QOT_GET_SECURITY_SNAPSHOT (3203)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/snapshot

`GET /api/spread-table`¶

proto_id: QOT_GET_SPREAD_TABLE (6503)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Purpose: Spread table for tick-size lookup across price bands (e.g. HK stocks 0.01~0.25 → step 0.001). Required for client-side price validation in PlaceOrder / ModifyOrder.

Field table (no business parameter):

Field	Type	Required	Description
`reserved`	int	optional	Placeholder; always returns the full spread tables

Response: s2c.spread_table_list contains each spread table (spread_code + spread_item_list); each item carries price_from / price_to / value as f64 (raw int64 ÷ 1e9 already applied).

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/spread-table

`POST /api/spread-table`¶

proto_id: QOT_GET_SPREAD_TABLE (6503)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Purpose: Spread table for tick-size lookup across price bands (e.g. HK stocks 0.01~0.25 → step 0.001). Required for client-side price validation in PlaceOrder / ModifyOrder.

Field table (no business parameter):

Field	Type	Required	Description
`reserved`	int	optional	Placeholder; always returns the full spread tables

Response: s2c.spread_table_list contains each spread table (spread_code + spread_item_list); each item carries price_from / price_to / value as f64 (raw int64 ÷ 1e9 already applied).

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/spread-table

`POST /api/static-info`¶

proto_id: QOT_GET_STATIC_INFO (3202)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700","US.AAPL"]}' \
  https://127.0.0.1:22499/api/static-info

`POST /api/ticker`¶

proto_id: QOT_GET_TICKER (3010)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","count":50}' \
  https://127.0.0.1:22499/api/ticker

`POST /api/ticker-statistic`¶

proto_id: QOT_GET_TICKER_STATISTIC (6365)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Purpose: Ticker statistics. Aggregates per-tick deals into time intervals (cumulative volume / turnover / avg price).

Field table:

Field	Type	Required	Description
`security` or `symbol`	object/string	✅	Underlying; shorthand `"HK.00700"`
`interval_type`	int	✅	Aggregation granularity enum (see proto)

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","interval_type":1}' \
  https://127.0.0.1:22499/api/ticker-statistic

`POST /api/ticker-statistic-detail`¶

proto_id: QOT_GET_TICKER_STATISTIC_DETAIL (6366)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/ticker-statistic-detail

`POST /api/used-quota`¶

proto_id: GET_USED_QUOTA (1010)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/used-quota

Plates / Filter / Metadata¶

Plate list/stocks, stock filter, trading days, suspend, code change, IPO calendar.

`POST /api/code-change`¶

proto_id: QOT_GET_CODE_CHANGE (3216)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"search":{"code_change_type_list":[1],"time_filter_list":[{"type":1,"begin_time":"2026-01-01","end_time":"2026-04-01"}]}}' \
  https://127.0.0.1:22499/api/code-change

`POST /api/ipo-list`¶

proto_id: QOT_GET_IPO_LIST (3217)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`market`	int/string	✅	IPO endpoint-local market: `1`/`HK`, `2`/`HK_FUTURE`, `11`/`US`, `21`/`CN`/`SH`, `22`/`SZ`, `31`/`SG`, `41`/`JP`, `61`/`MY`

Note: The backend distinguishes HK / US / A-share / SG / JP / MY. Wrong market returns invalid-market.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"market":1}}' \
  https://127.0.0.1:22499/api/ipo-list

`POST /api/list-plates`¶

proto_id: QOT_GET_PLATE_SET (3204)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"plate_set_type":0}' \
  https://127.0.0.1:22499/api/list-plates

`POST /api/plate-security`¶

proto_id: QOT_GET_PLATE_SECURITY (3205)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"plate":{"market":1,"code":"BK1001"}}' \
  https://127.0.0.1:22499/api/plate-security

`POST /api/plate-set`¶

proto_id: QOT_GET_PLATE_SET (3204)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"plate_set_type":0}' \
  https://127.0.0.1:22499/api/plate-set

`POST /api/stock-filter`¶

proto_id: QOT_STOCK_FILTER (3215)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"begin":0,"num":50,"market":1,"plate":{"market":1,"code":"BK1001"}}' \
  https://127.0.0.1:22499/api/stock-filter

`POST /api/suspend`¶

proto_id: QOT_GET_SUSPEND (3201)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"],"begin_time":"2026-01-01","end_time":"2026-04-01"}' \
  https://127.0.0.1:22499/api/suspend

`POST /api/trading-days`¶

proto_id: QOT_REQUEST_TRADE_DATE (3219)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"begin_time":"2026-01-01","end_time":"2026-04-01"}' \
  https://127.0.0.1:22499/api/trading-days

Reference / Derivatives¶

Warrant references, option chain, option expiration dates, future info, rehab, watchlist, holding change, and v10.6 F10/financials/research/valuation/corporate-actions/shareholders/insider/screen/unusual endpoints. Since v1.8.0 /api/modify-user-security uses qot:write; this major still accepts qot:read for compatibility.

`POST /api/company-executive-background`¶

proto_id: QOT_GET_COMPANY_EXECUTIVE_BACKGROUND (3245)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"},"leader_name":"Pony Ma"}' \
  https://127.0.0.1:22499/api/company-executive-background

`POST /api/company-executives`¶

proto_id: QOT_GET_COMPANY_EXECUTIVES (3244)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/company-executives

`POST /api/company-operational-efficiency`¶

proto_id: QOT_GET_COMPANY_OPERATIONAL_EFFICIENCY (3246)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/company-operational-efficiency

`POST /api/company-profile`¶

proto_id: QOT_GET_COMPANY_PROFILE (3243)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/company-profile

`POST /api/corporate-actions-buybacks`¶

proto_id: QOT_GET_CORPORATE_ACTIONS_BUYBACKS (3235)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/corporate-actions-buybacks

`POST /api/corporate-actions-dividends`¶

proto_id: QOT_GET_CORPORATE_ACTIONS_DIVIDENDS (3234)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/corporate-actions-dividends

`POST /api/corporate-actions-stock-splits`¶

proto_id: QOT_GET_CORPORATE_ACTIONS_STOCK_SPLITS (3236)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/corporate-actions-stock-splits

`POST /api/daily-short-volume`¶

proto_id: QOT_GET_DAILY_SHORT_VOLUME (3248)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/daily-short-volume

`POST /api/derivative-unusual`¶

proto_id: QOT_GET_DERIVATIVE_UNUSUAL (3803)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/derivative-unusual

`POST /api/financial-unusual`¶

proto_id: QOT_GET_FINANCIAL_UNUSUAL (3802)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/financial-unusual

`POST /api/financials-earnings-price-history`¶

proto_id: QOT_GET_FINANCIALS_EARNINGS_PRICE_HISTORY (3226)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/financials-earnings-price-history

`POST /api/financials-earnings-price-move`¶

proto_id: QOT_GET_FINANCIALS_EARNINGS_PRICE_MOVE (3225)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/financials-earnings-price-move

`POST /api/financials-revenue-breakdown`¶

proto_id: QOT_GET_FINANCIALS_REVENUE_BREAKDOWN (3228)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/financials-revenue-breakdown

`POST /api/financials-statements`¶

proto_id: QOT_GET_FINANCIALS_STATEMENTS (3227)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/financials-statements

`POST /api/future-info`¶

proto_id: QOT_GET_FUTURE_INFO (3218)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`security_list` or `symbols`	array	✅	Futures contracts; e.g. `["HK.HSImain", "US.NQmain"]`

Note: An empty security_list triggers a backend no stock specified error; supply at least one contract.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"securityList":[{"market":1,"code":"HSImain"}]}}' \
  https://127.0.0.1:22499/api/future-info

`POST /api/get-reference`¶

proto_id: QOT_GET_REFERENCE (3206)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`security` or `symbol`	object/string	✅	Underlying stock; shorthand `"HK.00700"`
`reference_type`	int	✅	`1`=Warrant / `2`=Future (main-continuous related contracts)

Option NOT supported: The backend ReferenceType proto only defines Warrant / Future. Passing "reference_type":3 returns unsupported reference type. The MCP tool futu_get_reference likewise rejects anything other than warrant / future.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","reference_type":1}' \
  https://127.0.0.1:22499/api/get-reference

`POST /api/holding-change`¶

proto_id: QOT_GET_HOLDING_CHANGE_LIST (3208)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

⚠️ Deprecated: The upstream backend abandoned this endpoint after 2020-12-21. Calls return ret_type=-1 with "will be abandoned after 2020-12-21". No longer guaranteed to work; do not use in new code.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","holder_category":1,"begin_time":"2026-01-01","end_time":"2026-04-01"}' \
  https://127.0.0.1:22499/api/holding-change

`POST /api/insider-holder-list`¶

proto_id: QOT_GET_INSIDER_HOLDER_LIST (3241)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/insider-holder-list

`POST /api/insider-trade-list`¶

proto_id: QOT_GET_INSIDER_TRADE_LIST (3242)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/insider-trade-list

`POST /api/modify-user-security`¶

proto_id: QOT_MODIFY_USER_SECURITY (3214)

Scope: qot:write (qot:read accepted for v1.8 compatibility)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Stateful write: Mutates the user's watchlist. Unknown fields are loud-fail rejected since v1.4.84, but a successful call cannot be rolled back.

Field table (REST accepts int enums only):

Field	Type	Required	Description
`group_name`	string	✅	Group name; ties resolve to first match
`op`	int	✅	`1`=Add / `2`=Del / `3`=MoveOut
`security_list`	array	✅	Stock list; each item `{market: int, code: string}`

No top-level symbol/symbols shorthand: must use explicit security_list.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"group_name":"自选","op":1,"security_list":[{"market":1,"code":"00700"}]}' \
  https://127.0.0.1:22499/api/modify-user-security

`POST /api/option-chain`¶

proto_id: QOT_GET_OPTION_CHAIN (3209)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`owner` or `symbol`	object/string	✅	Underlying stock (HK/US blue chips, HSI/HSCEI/major US indices); shorthand `"HK.00700"`
`begin_time`	string	✅	Strike date start (`YYYY-MM-DD`)
`end_time`	string	✅	Strike date end (`YYYY-MM-DD`)
`condition`	object	optional	Option filter (type / strike range / quote)

Owner shorthand: Only top-level "owner":"HK.00700" auto-expands to a Security object; do not pass "security":{...} explicitly (proto field is owner, not security).

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner":"HK.00700","begin_time":"2026-05-01","end_time":"2026-06-01"}' \
  https://127.0.0.1:22499/api/option-chain

`POST /api/option-exercise-probability`¶

proto_id: QOT_GET_OPTION_EXERCISE_PROBABILITY (3251)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":11,"code":"AAPL260116C200000"}}' \
  https://127.0.0.1:22499/api/option-exercise-probability

`POST /api/option-expiration-date`¶

proto_id: QOT_GET_OPTION_EXPIRATION_DATE (3224)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`owner` or `symbol`	object/string	✅	Underlying stock; shorthand `"HK.00700"`
`index_option_type`	int	optional	HSI / HSCEI only: `IndexOptionType`

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner":"HK.00700"}' \
  https://127.0.0.1:22499/api/option-expiration-date

`POST /api/option-quote`¶

proto_id: QOT_GET_OPTION_QUOTE (3255)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"multi_legs":[{"security":{"market":11,"code":"AAPL260116C200000"},"side":1,"qty_ratio":1.0}]}}' \
  https://127.0.0.1:22499/api/option-quote

`POST /api/option-screen`¶

proto_id: QOT_OPTION_SCREEN (3253)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_from":0,"page_count":20}' \
  https://127.0.0.1:22499/api/option-screen

`POST /api/option-strategy`¶

proto_id: QOT_GET_OPTION_STRATEGY (3256)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"owner":{"market":11,"code":"AAPL"},"option_strategy":1}}' \
  https://127.0.0.1:22499/api/option-strategy

`POST /api/option-strategy-analysis`¶

proto_id: QOT_GET_OPTION_STRATEGY_ANALYSIS (3257)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"multi_legs":[{"security":{"market":11,"code":"AAPL260116C200000"},"side":1,"qty_ratio":1.0}]}}' \
  https://127.0.0.1:22499/api/option-strategy-analysis

`POST /api/option-strategy-spread`¶

proto_id: QOT_GET_OPTION_STRATEGY_SPREAD (3258)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"owner":{"market":11,"code":"AAPL"},"option_strategy":4}}' \
  https://127.0.0.1:22499/api/option-strategy-spread

`POST /api/option-volatility`¶

proto_id: QOT_GET_OPTION_VOLATILITY (3250)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":11,"code":"AAPL260116C200000"},"query_time_period":2,"hv_time_period":30}' \
  https://127.0.0.1:22499/api/option-volatility

`POST /api/owner-plate`¶

proto_id: QOT_GET_OWNER_PLATE (3207)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table:

Field	Type	Required	Description
`security_list` or `symbols`	array	✅	Stock array; shorthand `["HK.00700"]` auto-expands

Note: Empty security_list returns empty plate list with no business meaning; supply at least one stock.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"]}' \
  https://127.0.0.1:22499/api/owner-plate

`POST /api/reference`¶

proto_id: QOT_GET_REFERENCE (3206)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Note: /api/reference is equivalent to /api/get-reference (same proto_id 3206); /api/get-reference is the v1.4.74 alias. Same field contract — see /api/get-reference section.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","reference_type":1}' \
  https://127.0.0.1:22499/api/reference

`POST /api/rehab`¶

proto_id: QOT_REQUEST_REHAB (3105)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"]}' \
  https://127.0.0.1:22499/api/rehab

`POST /api/research-analyst-consensus`¶

proto_id: QOT_GET_RESEARCH_ANALYST_CONSENSUS (3229)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/research-analyst-consensus

`POST /api/research-morningstar-report`¶

proto_id: QOT_GET_RESEARCH_MORNINGSTAR_REPORT (3231)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/research-morningstar-report

`POST /api/research-rating-summary`¶

proto_id: QOT_GET_RESEARCH_RATING_SUMMARY (3230)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/research-rating-summary

`POST /api/shareholders-holder-detail`¶

proto_id: QOT_GET_SHAREHOLDERS_HOLDER_DETAIL (3239)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/shareholders-holder-detail

`POST /api/shareholders-holding-changes`¶

proto_id: QOT_GET_SHAREHOLDERS_HOLDING_CHANGES (3238)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/shareholders-holding-changes

`POST /api/shareholders-institutional`¶

proto_id: QOT_GET_SHAREHOLDERS_INSTITUTIONAL (3240)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/shareholders-institutional

`POST /api/shareholders-overview`¶

proto_id: QOT_GET_SHAREHOLDERS_OVERVIEW (3237)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/shareholders-overview

`POST /api/short-interest`¶

proto_id: QOT_GET_SHORT_INTEREST (3249)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/short-interest

`POST /api/stock-screen`¶

proto_id: QOT_STOCK_SCREEN (3252)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_from":0,"page_count":20}' \
  https://127.0.0.1:22499/api/stock-screen

`POST /api/technical-unusual`¶

proto_id: QOT_GET_TECHNICAL_UNUSUAL (3801)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/technical-unusual

`POST /api/top-ten-buy-sell-brokers`¶

proto_id: QOT_GET_TOP_TEN_BUY_SELL_BROKERS (3247)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/top-ten-buy-sell-brokers

`POST /api/user-security`¶

proto_id: QOT_GET_USER_SECURITY (3213)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"group_name":"自选"}' \
  https://127.0.0.1:22499/api/user-security

`POST /api/user-security-groups`¶

proto_id: QOT_GET_USER_SECURITY_GROUP (3222)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"group_type":3}' \
  https://127.0.0.1:22499/api/user-security-groups

`POST /api/valuation-detail`¶

proto_id: QOT_GET_VALUATION_DETAIL (3232)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/valuation-detail

`POST /api/valuation-plate-stock-list`¶

proto_id: QOT_GET_VALUATION_PLATE_STOCK_LIST (3233)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":1,"code":"00700"}}' \
  https://127.0.0.1:22499/api/valuation-plate-stock-list

`POST /api/warrant`¶

proto_id: QOT_GET_WARRANT (3210)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Core field table:

Field	Type	Required	Description
`begin`	int	✅	Start row (pagination)
`num`	int	✅	Page size (≤200)
`sort_field`	int	✅	`WarrantField` sort enum
`ascend`	bool	✅	Ascending order
`owner` or `symbol`	object/string	optional	Underlying; shorthand `"HK.00700"`

Full field set: includes type_list / issuer_list / strike-price ranges and other filters; see proto definition.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"begin":0,"num":50,"sort_field":1,"ascend":false,"owner":"HK.00700"}' \
  https://127.0.0.1:22499/api/warrant

`POST /api/warrant-screen`¶

proto_id: QOT_WARRANT_SCREEN (3254)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market_type":1,"page_from":0,"page_count":20}' \
  https://127.0.0.1:22499/api/warrant-screen

Price Reminders¶

Query/set/modify/delete price reminders. Since v1.8.0 /api/set-price-reminder uses qot:write (qot:read remains compatible for this major); /api/price-reminder reads stay on qot:read.

`POST /api/price-reminder`¶

proto_id: QOT_GET_PRICE_REMINDER (3221)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22499/api/price-reminder

`POST /api/set-price-reminder`¶

proto_id: QOT_SET_PRICE_REMINDER (3220)

Scope: qot:write (qot:read accepted for v1.8 compatibility)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Stateful write: Add / modify / delete a price alert.

Field table (REST accepts int enums only; proto field is type, not reminder_type):

Field	Type	Required	Description
`security` or `symbol`	object/string	✅	Stock; shorthand `"HK.00700"`
`op`	int	✅	`1`=Add / `2`=Del / `3`=Enable / `4`=Disable / `5`=Modify / `6`=DelAll
`key`	int64	for Modify/Del	Alert key from `GetPriceReminder`
`type`	int	for Add	`PriceReminderType` (1=PriceUp / 2=PriceDown / ...)
`freq`	int	for Add	`PriceReminderFreq` (1=Always / 2=OnceADay / 3=OnlyOnce); on Modify the backend preserves the old value when omitted
`value`	f64	for Add	Alert value (3 decimals max); on Modify the backend preserves the old value when omitted
`note`	string	optional	Note (≤20 chars in CN)

Add (op=1) required: type + freq + value. The gateway aligns with the reference implementation and rejects Add without all three.

Modify (op=5) does not require type / freq / value: the gateway fetches the existing alert first, applies user-provided field overrides, and preserves omitted fields (aligning with the overwrite-style Modify semantics).

reminder_session_list (optional, array): PriceReminderMarketStatus values — 1=Open / 2=USPre / 3=USAfter / 4=USOverNight. Any value outside 1..4 is loud-rejected by the gateway (-1 + error text). For US stocks an empty list defaults to [1, 2, 3]; for non-US securities the list is cleared.

Note: REST does not accept "op":"SetAdd" string form; only MCP layer maps strings to int.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700","op":1,"type":1,"freq":1,"value":300.0}' \
  https://127.0.0.1:22499/api/set-price-reminder

Trading Accounts (Read)¶

Account list, funds, positions, today orders/deals, history orders/deals, max trade qty, margin ratio, order fee. Requires acc:read.

`POST /api/acc-cash-flow`¶

proto_id: TRD_FLOW_SUMMARY (2226)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"clearing_date":"2026-04-01"}' \
  https://127.0.0.1:22499/api/acc-cash-flow

`POST /api/account-flag`¶

proto_id: TRD_GET_ACCOUNT_FLAG (22705)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/account-flag

`GET /api/accounts`¶

proto_id: TRD_GET_ACC_LIST (2001)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/accounts

`POST /api/biz-group`¶

proto_id: TRD_GET_BIZ_GROUP (22703)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"market":1}' \
  https://127.0.0.1:22499/api/biz-group

`POST /api/bond-answer-state`¶

proto_id: TRD_GET_BOND_ANSWER_STATE (22709)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/bond-answer-state

`POST /api/bond-position-list`¶

proto_id: TRD_GET_BOND_POSITION_LIST (22708)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/bond-position-list

`POST /api/bond-screen`¶

proto_id: QOT_BOND_SCREEN (2131755020)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. data_max_count is 1..100; source_types accepts only 1 (Hong Kong) or 2 (Singapore). String-screen factor_id values are dynamic backend catalogs; range screens accept intervals only. Per the source contract, the single sort takes precedence over sorts.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"conditions":[{"type_id":2,"intervals":[{"lower":{"value":0}}]}],"data_from":0,"data_max_count":20,"source_types":[1],"extension_version":1}' \
  https://127.0.0.1:22499/api/bond-screen

`POST /api/bond-single-asset`¶

proto_id: TRD_GET_BOND_SINGLE_ASSET (22707)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/bond-single-asset

`POST /api/bond-total-asset`¶

proto_id: TRD_GET_BOND_TOTAL_ASSET (22706)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/bond-total-asset

`POST /api/bond-trade-reminder`¶

proto_id: TRD_GET_BOND_TRADE_REMINDER (22710)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/bond-trade-reminder

`POST /api/cash-detail`¶

proto_id: TRD_GET_CASH_DETAIL (22702)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"flow_id":"<flow_id>"}' \
  https://127.0.0.1:22499/api/cash-detail

`POST /api/cash-log`¶

proto_id: TRD_GET_CASH_LOG (22701)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"begin_time":"2026-01-01","end_time":"2026-04-01"}' \
  https://127.0.0.1:22499/api/cash-log

`POST /api/combo-max-trd-qtys`¶

proto_id: TRD_GET_COMBO_MAX_TRD_QTYS (2112)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"header":{"trd_env":1,"acc_id":123456,"trd_market":2},"combo_legs":[{"security":{"market":11,"code":"AAPL260116C200000"},"side":1,"qty_ratio":1.0},{"security":{"market":11,"code":"AAPL260116C205000"},"side":2,"qty_ratio":1.0}],"qty":1.0,"price":1.0,"order_type":1}}' \
  https://127.0.0.1:22499/api/combo-max-trd-qtys

`POST /api/flow-summary`¶

proto_id: TRD_FLOW_SUMMARY (2226)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"clearing_date":"2026-04-01"}' \
  https://127.0.0.1:22499/api/flow-summary

`POST /api/funds`¶

proto_id: TRD_GET_FUNDS (2101)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/funds

`POST /api/history-order-fills`¶

proto_id: TRD_GET_HISTORY_ORDER_FILL_LIST (2222)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"begin_time":"2026-01-01 00:00:00","end_time":"2026-04-01 23:59:59"}' \
  https://127.0.0.1:22499/api/history-order-fills

`POST /api/history-orders`¶

proto_id: TRD_GET_HISTORY_ORDER_LIST (2221)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"begin_time":"2026-01-01 00:00:00","end_time":"2026-04-01 23:59:59"}' \
  https://127.0.0.1:22499/api/history-orders

`GET /api/list-accounts`¶

proto_id: TRD_GET_ACC_LIST (2001)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/list-accounts

`POST /api/margin-info`¶

proto_id: TRD_GET_MARGIN_INFO (22704)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"market":1}' \
  https://127.0.0.1:22499/api/margin-info

`POST /api/margin-ratio`¶

proto_id: TRD_GET_MARGIN_RATIO (2223)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"symbols":["HK.00700"]}' \
  https://127.0.0.1:22499/api/margin-ratio

`POST /api/max-trd-qtys`¶

proto_id: TRD_GET_MAX_TRD_QTYS (2111)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"code":"00700","price":300.0,"order_type":1}' \
  https://127.0.0.1:22499/api/max-trd-qtys

`POST /api/order-fee`¶

proto_id: TRD_GET_ORDER_FEE (2225)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"order_id_ex_list":["987"]}' \
  https://127.0.0.1:22499/api/order-fee

`POST /api/order-fills`¶

proto_id: TRD_GET_ORDER_FILL_LIST (2211)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/order-fills

`POST /api/orders`¶

proto_id: TRD_GET_ORDER_LIST (2201)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/orders

`POST /api/positions`¶

proto_id: TRD_GET_POSITION_LIST (2102)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1}' \
  https://127.0.0.1:22499/api/positions

`POST /api/reconfirm-order`¶

proto_id: TRD_RECONFIRM_ORDER (2237)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"order_id":"987","reconfirm_op":1}' \
  https://127.0.0.1:22499/api/reconfirm-order

`GET /api/token-state`¶

proto_id: GET_TOKEN_STATE (1326)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/token-state

`POST /api/token-state`¶

proto_id: GET_TOKEN_STATE (1326)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456}' \
  https://127.0.0.1:22499/api/token-state

Trading Write¶

Place order, modify order, cancel one order, cancel-all, unlock trade cipher, account push sub. Place/modify/cancel requires trade:real / trade:simulate (env-double-check) + --enable-trading. Since v1.4.104 /api/unlock-trade strictly requires trade:unlock (no longer satisfied by other trade super-scopes).

`POST /api/cancel-all-order`¶

proto_id: TRD_MODIFY_ORDER (2205)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":1,"market":1}' \
  https://127.0.0.1:22499/api/cancel-all-order

`POST /api/cancel-order`¶

proto_id: TRD_MODIFY_ORDER (2205)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Semantic single-order cancel endpoint: it still sends Trd_ModifyOrder(Cancel) underneath, but REST clients only need the trading account, env, market, and either order_id or order_id_ex; low-level packet_id / modify_order_op are not required.

Friendly fields: flat bodies accept env (real / simulate / sim), market (US / HK / official non-fund trading-market int), and optional op (cancel / 2). If op is provided, it must mean cancel.

Response semantics: ret_type=0 only means the backend accepted the Cancel operation request; it is not proof of the final cancelled state. The Rust daemon runs one bounded authoritative order refresh before returning the ACK to help REST/CLI follow-up order reads converge sooner. It does not implicitly refresh positions after the cancel ACK; can_sell_qty still comes from later trade push events or an explicit positions query with refresh_cache=true. Final state still comes from push events or refresh queries.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id":123456,"env":"real","market":"US","order_id_ex":"FH1C8ABB517AE56000"}' \
  https://127.0.0.1:22499/api/cancel-order

`POST /api/combo-order`¶

proto_id: TRD_PLACE_COMBO_ORDER (2227)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Note: REST clients may omit packet_id; the daemon fills it from the current connection before forwarding.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"header":{"trd_env":1,"acc_id":123456,"trd_market":2},"combo_legs":[{"security":{"market":11,"code":"AAPL260116C200000"},"side":1,"qty_ratio":1.0},{"security":{"market":11,"code":"AAPL260116C205000"},"side":2,"qty_ratio":1.0}],"qty":1.0,"price":1.0,"order_type":1}}' \
  https://127.0.0.1:22499/api/combo-order

`POST /api/modify-order`¶

proto_id: TRD_MODIFY_ORDER (2205)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Field table (REST accepts int enums only):

Field	Type	Required	Description
`c2s.header.trd_env`	int	✅	`0`=Real / `1`=Simulate
`c2s.header.acc_id`	uint64	✅	Trading account ID
`c2s.header.trd_market`	int	✅	Trading market enum
`order_id` / `order_id_ex`	uint64 / string	✅	Order to modify / cancel; pass one of them
`modify_order_op`	int	✅	`1`=Normal modify / `2`=Cancel / `3`=Disable / `4`=Enable / `5`=DeleteOutofdate
`qty` / `price`	float	Required for Normal modify depending on original order type	New quantity / price

Single-order cancel: prefer the semantic /api/cancel-order endpoint. This low-level endpoint remains compatible with the historical modify_order_op: 2 cancel shape; /api/cancel-all-order is the bulk-cancel endpoint.

Low-level strict endpoint: /api/modify-order does not accept the flat env / market / op=cancel friendly fields from /api/cancel-order; when using the c2s shape, pass fields according to the low-level ModifyOrder contract. Normal REST single-order cancels should use /api/cancel-order directly.

Response semantics: ret_type=0 means the backend accepted the Modify/Cancel operation request; it is not proof of the final filled/cancelled state. Final order status should be read from trade push events or later order queries with refresh_cache=true; sellable quantity should be read from trade push events or explicit position refresh queries. This matches the official OpenD ModifyOrder ACK semantics. For a successful single-order cancel, the Rust daemon also runs one bounded authoritative order refresh before returning the ACK to help REST/CLI follow-up order reads converge sooner. It does not implicitly refresh positions after the cancel ACK, avoiding unrelated account-info query failures in cancel result handling. Refresh timeout/failure does not rewrite a backend-accepted cancel into a failure; final state still comes from push events or refresh queries.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"header":{"trd_env":1,"acc_id":123456,"trd_market":1},"order_id":987,"modify_order_op":2}}' \
  https://127.0.0.1:22499/api/modify-order

`POST /api/order`¶

proto_id: TRD_PLACE_ORDER (2202)

Scope: trade:real or trade:simulate (based on env)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"acc_id":123456,"env":1,"side":1,"code":"00700","qty":100,"price":300.0}' \
  https://127.0.0.1:22499/api/order

`POST /api/sub-acc-push`¶

proto_id: TRD_SUB_ACC_PUSH (2008)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id_list":[123456]}' \
  https://127.0.0.1:22499/api/sub-acc-push

`POST /api/unlock-trade`¶

proto_id: TRD_UNLOCK_TRADE (2005)

Scope: trade:unlock

Transport boundary: this endpoint only accepts loopback peers. For remote access, terminate HTTPS in a same-host reverse proxy and forward to the REST listener on 127.0.0.1. Direct non-loopback plaintext HTTP is rejected with 403 and diagnostic key rest.unlock_trade.local_transport_required. Loopback HTTP, like the official OpenD local FTAPI transport, does not defend against an administrator process with local packet-capture or debugging access.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"unlock":true,"pwd_md5":"<md5-of-trade-password>"}' \
  https://127.0.0.1:22499/api/unlock-trade

`POST /api/unsub-acc-push`¶

proto_id: — (non-proto / no backend forwarding)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"acc_id_list":[123456]}' \
  https://127.0.0.1:22499/api/unsub-acc-push

Admin¶

Daemon management endpoints. Requires admin scope.

Runtime contract: - GET /api/admin/status: Synchronous read-only snapshot. Includes last_reload_refresh field (never_run / running / succeeded / failed / skipped / not_applicable) for monitoring the background reload refresh task. - POST /api/admin/shutdown: Returns 200 synchronously, then triggers daemon exit through the internal shutdown signal. - POST /api/admin/reload: Synchronously clears cipher cache and returns immediately; credentials refresh runs in the background (check /api/admin/status → last_reload_refresh for outcome).

Body validation: POST /api/admin/shutdown + POST /api/admin/reload accept only empty body / {} / null. Any user-supplied field returns 400 (handler does not read body).

`POST /api/admin/reload`¶

proto_id: — (non-proto / no backend forwarding)

Scope: admin

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/admin/reload

`POST /api/admin/shutdown`¶

proto_id: — (non-proto / no backend forwarding)

Scope: admin

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/admin/shutdown

`GET /api/admin/status`¶

proto_id: — (non-proto / no backend forwarding)

Scope: admin

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

platform and every brokers[] entry also include lifecycle_state, lifecycle_generation, and optional last_lifecycle_event. Broker reconnect counters and the latest attempt/success/failure timestamps come from the same lifecycle snapshot, so operators can tell whether recovery is still progressing.

Example:

curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  https://127.0.0.1:22499/api/admin/status

`POST /api/ark-active-transaction`¶

proto_id: QOT_GET_ARK_ACTIVE_TRANSACTION (3425)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"holding_type":1,"cycle_type":1,"count":50}' \
  https://127.0.0.1:22499/api/ark-active-transaction

`POST /api/ark-fund-holding`¶

proto_id: QOT_GET_ARK_FUND_HOLDING (3423)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"holding_type":1,"count":20}' \
  https://127.0.0.1:22499/api/ark-fund-holding

`POST /api/ark-stock-dynamic`¶

proto_id: QOT_GET_ARK_STOCK_DYNAMIC (3424)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"security":{"market":11,"code":"AAPL"}}' \
  https://127.0.0.1:22499/api/ark-stock-dynamic

`POST /api/dividend-calendar`¶

proto_id: QOT_GET_DIVIDEND_CALENDAR (3408)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"date":"2026-06-24","count":20}' \
  https://127.0.0.1:22499/api/dividend-calendar

`POST /api/dividend-rank`¶

proto_id: QOT_GET_DIVIDEND_RANK (3407)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"rank_type":1,"count":10}' \
  https://127.0.0.1:22499/api/dividend-rank

`POST /api/earnings-beat-rank`¶

proto_id: QOT_GET_EARNINGS_BEAT_RANK (3406)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"beat_type":1,"count":30}' \
  https://127.0.0.1:22499/api/earnings-beat-rank

`POST /api/earnings-calendar`¶

proto_id: QOT_GET_EARNINGS_CALENDAR (3401)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"begin_date":"2026-06-24","end_date":"2026-06-25"}' \
  https://127.0.0.1:22499/api/earnings-calendar

`POST /api/economic-calendar`¶

proto_id: QOT_GET_ECONOMIC_CALENDAR (3409)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"begin_date":"2026-06-24","end_date":"2026-06-24","market_list":[11],"count":50}' \
  https://127.0.0.1:22499/api/economic-calendar

`POST /api/etf-screen`¶

proto_id: QOT_ETF_SCREEN (2131755017)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. data_max_count is 1..500; static market/field/period/content/sort catalogs are declared in the public proto. Dynamic issuer, region, sector, and holding subkeys are backend-owned selection data and must not be guessed locally.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"data_from":0,"data_max_count":20,"need_fields":[{"field_id":5}],"extension_version":1}' \
  https://127.0.0.1:22499/api/etf-screen

`POST /api/fed-watch-dot-plot`¶

proto_id: QOT_GET_FED_WATCH_DOT_PLOT (3405)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/fed-watch-dot-plot

`POST /api/fed-watch-target-rate`¶

proto_id: QOT_GET_FED_WATCH_TARGET_RATE (3404)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/fed-watch-target-rate

`POST /api/financial-calendar`¶

proto_id: QOT_GET_FINANCIAL_CALENDAR_VIEW_INTERNAL (20025)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market_list":[1],"count":20,"begin_date":"20260624","end_date":"20260625"}' \
  https://127.0.0.1:22499/api/financial-calendar

`POST /api/financial-calendar-target`¶

proto_id: QOT_SEARCH_TARGET_FINANCIAL_CALENDAR (20426)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_id":[7000700],"market_list":[1],"size":20,"start":0}' \
  https://127.0.0.1:22499/api/financial-calendar-target

`POST /api/fund-screen`¶

proto_id: QOT_FUND_SCREEN (2131755018)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. data_max_count is 1..500; the full 33-field fund contract does not share a DTO with ETF/future/bond screeners. Company, theme, and set IDs are dynamic backend catalogs. This public protocol preserves the full backend contract rather than one Desktop list widget's selected/no-search/region defaults. Per the source contract, non-empty sorts takes precedence over the single sort.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"fund_types":[1],"risk_levels":[1],"currency_units":[1],"data_from":0,"data_max_count":20,"field_ids":[3],"source_types":[1],"extension_version":1}' \
  https://127.0.0.1:22499/api/fund-screen

`POST /api/future-screen`¶

proto_id: QOT_FUTURE_SCREEN (2131755019)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. data_max_count is 1..100; crypto-future filtering is derived from the daemon's fresh quote entitlement. Fixed screen/factor catalogs are declared in the public proto; newly introduced factors remain owned by backend discovery. Per the source contract, the single sort takes precedence over sorts.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"conditions":[{"type_id":1,"factor_ids":[1]}],"data_from":0,"data_max_count":20,"extension_version":1}' \
  https://127.0.0.1:22499/api/future-screen

`POST /api/heat-map-data`¶

proto_id: QOT_GET_HEAT_MAP_DATA (3432)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"count":30}' \
  https://127.0.0.1:22499/api/heat-map-data

`POST /api/high-dividend-soe-rank`¶

proto_id: QOT_GET_HIGH_DIVIDEND_SOE_RANK (3417)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"count":50}' \
  https://127.0.0.1:22499/api/high-dividend-soe-rank

`POST /api/hot-list`¶

proto_id: QOT_GET_HOT_LIST (3414)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"count":50}' \
  https://127.0.0.1:22499/api/hot-list

`POST /api/hot-news`¶

proto_id: QOT_GET_HOT_NEWS (2131755011)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. Callers pass only page_size (1..50) and extension_version=1.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_size":20,"extension_version":1}' \
  https://127.0.0.1:22499/api/hot-news

`POST /api/indicator-list`¶

proto_id: QOT_GET_INDICATOR_LIST (3259)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{}' \
  https://127.0.0.1:22499/api/indicator-list

`POST /api/industrial-chain-by-plate`¶

proto_id: QOT_GET_INDUSTRIAL_CHAIN_BY_PLATE (3429)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"plate_id":1}' \
  https://127.0.0.1:22499/api/industrial-chain-by-plate

`POST /api/industrial-chain-detail`¶

proto_id: QOT_GET_INDUSTRIAL_CHAIN_DETAIL (3428)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain_id":1}' \
  https://127.0.0.1:22499/api/industrial-chain-detail

`POST /api/industrial-chain-list`¶

proto_id: QOT_GET_INDUSTRIAL_CHAIN_LIST (3427)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"count":20}' \
  https://127.0.0.1:22499/api/industrial-chain-list

`POST /api/industrial-plate-info`¶

proto_id: QOT_GET_INDUSTRIAL_PLATE_INFO (3430)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"plate_id":1}' \
  https://127.0.0.1:22499/api/industrial-plate-info

`POST /api/industrial-plate-stock`¶

proto_id: QOT_GET_INDUSTRIAL_PLATE_STOCK (3431)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"plate_id":1,"count":50}' \
  https://127.0.0.1:22499/api/industrial-plate-stock

`POST /api/institution-distribution`¶

proto_id: QOT_GET_INSTITUTION_DISTRIBUTION (3420)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"institution_id":700}' \
  https://127.0.0.1:22499/api/institution-distribution

`POST /api/institution-holding-change`¶

proto_id: QOT_GET_INSTITUTION_HOLDING_CHANGE (3421)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"institution_id":700,"count":20}' \
  https://127.0.0.1:22499/api/institution-holding-change

`POST /api/institution-holding-list`¶

proto_id: QOT_GET_INSTITUTION_HOLDING_LIST (3422)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":41,"institution_id":701,"count":20}' \
  https://127.0.0.1:22499/api/institution-holding-list

`POST /api/institution-list`¶

proto_id: QOT_GET_INSTITUTION_LIST (3418)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"count":20}' \
  https://127.0.0.1:22499/api/institution-list

`POST /api/institution-profile`¶

proto_id: QOT_GET_INSTITUTION_PROFILE (3419)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"institution_id":700}' \
  https://127.0.0.1:22499/api/institution-profile

`POST /api/ipo-calendar`¶

proto_id: QOT_GET_IPO_LIST (3217)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"event_types":["list"],"begin_date":"20260624","end_date":"20260630"}' \
  https://127.0.0.1:22499/api/ipo-calendar

`POST /api/latest-news`¶

proto_id: QOT_GET_LATEST_NEWS (2131755012)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. page_flip=0 pages older; page_flip=1 requires a nonempty newest cursor. An empty cursor always means the first page. Read-only filter sidecars use include_flash_filter / include_market_filter and require a nonnegative filter_version.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_size":20,"seq_mark":"","page_flip":0,"tag_indexes":[0],"extension_version":1}' \
  https://127.0.0.1:22499/api/latest-news

`POST /api/macro-indicator-history`¶

proto_id: QOT_GET_MACRO_INDICATOR_HISTORY (3403)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"indicator_id":88,"time":"2026-06-24","max_count":100}' \
  https://127.0.0.1:22499/api/macro-indicator-history

`POST /api/macro-indicator-list`¶

proto_id: QOT_GET_MACRO_INDICATOR_LIST (3402)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"region":2}' \
  https://127.0.0.1:22499/api/macro-indicator-list

`POST /api/market-trading-sessions`¶

proto_id: QOT_GET_MARKET_TRADING_SESSIONS (2131755010)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"items":[{"market_id":2,"begin_date":20261101,"num":1}],"extension_version":1}' \
  https://127.0.0.1:22499/api/market-trading-sessions

`POST /api/option-earnings-screener`¶

proto_id: QOT_GET_OPTION_EARNINGS_SCREENER (3313)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"count":50}' \
  https://127.0.0.1:22499/api/option-earnings-screener

`POST /api/option-event`¶

proto_id: QOT_GET_OPTION_EVENT (3307)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"count":50}' \
  https://127.0.0.1:22499/api/option-event

`POST /api/option-event-alert`¶

proto_id: QOT_GET_OPTION_EVENT_ALERT (3308)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"count":50}' \
  https://127.0.0.1:22499/api/option-event-alert

`POST /api/option-market-statistic`¶

proto_id: QOT_GET_OPTION_MARKET_STATISTIC (3301)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"data_type":0,"begin_time":"2026-08-01","end_time":"2026-08-30"}' \
  https://127.0.0.1:22499/api/option-market-statistic

`POST /api/option-rank`¶

proto_id: QOT_GET_OPTION_RANK (3306)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"sort_type":1,"count":50}' \
  https://127.0.0.1:22499/api/option-rank

`POST /api/option-seller-screener`¶

proto_id: QOT_GET_OPTION_SELLER_SCREENER (3314)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"seller_type":1}' \
  https://127.0.0.1:22499/api/option-seller-screener

`POST /api/option-underlying-his-statistic`¶

proto_id: QOT_GET_OPTION_UNDERLYING_HIS_STATISTIC (3302)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner":{"market":11,"code":"AAPL"},"begin_time":"2026-08-01","end_time":"2026-08-30"}' \
  https://127.0.0.1:22499/api/option-underlying-his-statistic

`POST /api/option-underlying-his-volatility`¶

proto_id: QOT_GET_OPTION_UNDERLYING_HIS_VOLATILITY (3304)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner":{"market":11,"code":"AAPL"},"begin_time":"2026-08-01","end_time":"2026-08-30"}' \
  https://127.0.0.1:22499/api/option-underlying-his-volatility

`POST /api/option-underlying-overview`¶

proto_id: QOT_GET_OPTION_UNDERLYING_OVERVIEW (3303)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner_list":[{"market":11,"code":"AAPL"}]}' \
  https://127.0.0.1:22499/api/option-underlying-overview

`POST /api/option-underlying-rank`¶

proto_id: QOT_GET_OPTION_UNDERLYING_RANK (3305)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"sort_type":1,"count":50}' \
  https://127.0.0.1:22499/api/option-underlying-rank

`POST /api/option-zero-dte-contract`¶

proto_id: QOT_GET_OPTION_ZERO_DTE_CONTRACT (3312)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"owner":{"market":11,"code":"AAPL"},"strike_date_timestamp":1800000000,"chain_info":{"strike_date_timestamp":1800000000,"product_code":"AAPL","multiplier":100.0,"contract_share_size":100.0,"expiration_type":1,"underlying":{"market":11,"code":"AAPL"}}}' \
  https://127.0.0.1:22499/api/option-zero-dte-contract

`POST /api/option-zero-dte-screener`¶

proto_id: QOT_GET_OPTION_ZERO_DTE_SCREENER (3311)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"option_market":1,"count":50}' \
  https://127.0.0.1:22499/api/option-zero-dte-screener

`POST /api/period-change-rank`¶

proto_id: QOT_GET_PERIOD_CHANGE_RANK (3416)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"count":50}' \
  https://127.0.0.1:22499/api/period-change-rank

`POST /api/preview-order-impact`¶

proto_id: TRD_PREVIEW_ORDER_IMPACT (22711)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":9001,"trd_market":2},"order":{"single":{"security":{"code":"AAPL","market_id":11,"stock_market":2,"exchange":"US","currency":"USD","security_type":1},"side":1,"order_type":2,"volume":{"quantity":"10"}}},"extension_version":1}' \
  https://127.0.0.1:22499/api/preview-order-impact

`POST /api/rating-change`¶

proto_id: QOT_GET_RATING_CHANGE (3426)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"count":10}' \
  https://127.0.0.1:22499/api/rating-change

`POST /api/rise-fall-distribution`¶

proto_id: QOT_GET_RISE_FALL_DISTRIBUTION (3433)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1}' \
  https://127.0.0.1:22499/api/rise-fall-distribution

`POST /api/search-news`¶

proto_id: QOT_GET_SEARCH_NEWS (3263)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"keyword":"earnings","max_count":10,"news_sub_type":0}' \
  https://127.0.0.1:22499/api/search-news

`POST /api/search-quote`¶

proto_id: QOT_GET_SEARCH_QUOTE (3262)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"keyword":"AAPL","max_count":10}' \
  https://127.0.0.1:22499/api/search-quote

`POST /api/security-trading-sessions`¶

proto_id: QOT_GET_SECURITY_TRADING_SESSIONS (2131755009)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"code":"AAPL","exchange":"US","begin_date":20261101,"num":1,"extension_version":1}' \
  https://127.0.0.1:22499/api/security-trading-sessions

`POST /api/set-option-event-alert`¶

proto_id: QOT_SET_OPTION_EVENT_ALERT (3309)

Scope: qot:write (qot:read accepted for v1.8 compatibility)

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"oper_type":1,"alert_list":[{"enable":true,"underlying":{"market":11,"code":"AAPL"}}]}' \
  https://127.0.0.1:22499/api/set-option-event-alert

`POST /api/set-stock-note`¶

proto_id: QOT_SET_STOCK_NOTE (2131755028)

Scope: qot:write (configured API key required; no qot:read fallback)

Private write / two independent default-off gates: requires both --enable-v18-stock-notes and --enable-v18-stock-note-writes, keys.json, and strict qot:write. The request is sent once and never auto-resubmitted. A route-fence rejection before writer admission is explicitly not sent; after the frame enters the writer queue, a route change or uncertain ACK returns SUBMITTED_UNKNOWN. Synchronous 0 means accepted only. DELETE may be confirmed by a private push that causes an actual state transition; CREATE/UPDATE must also pass 9432 reconciliation because 9430 carries no detail. Title/detail are never logged.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"operation":3,"stock_id":7001,"title":"watch","detail":"review later","is_display":1,"extension_version":1}' \
  https://127.0.0.1:22499/api/set-stock-note

`POST /api/short-selling-rank`¶

proto_id: QOT_GET_SHORT_SELLING_RANK (3415)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":11,"count":10}' \
  https://127.0.0.1:22499/api/short-selling-rank

`POST /api/stock-news`¶

proto_id: QOT_GET_STOCK_NEWS (2131755016)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. For pagination, echo the previous response's seq_mark, dedup_ids, and request-level track_info; id_type accepts only 1 (security) or 2 (plate).

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_id":7000700,"page_size":20,"id_type":1,"seq_mark":"","dedup_ids":[],"extension_version":1}' \
  https://127.0.0.1:22499/api/stock-news

`POST /api/stock-note-labels`¶

proto_id: QOT_GET_STOCK_NOTE_LABELS (2131755026)

Scope: acc:read (configured API key required)

Private data / disabled by default: requires --enable-v18-stock-notes, configured keys.json, and acc:read. FULL(1) is encoded by the daemon as is_full=1 + stock_id=[0]; IDS(2) preserves caller order and duplicates.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"mode":1,"stock_ids":[],"extension_version":1}' \
  https://127.0.0.1:22499/api/stock-note-labels

`POST /api/stock-notes`¶

proto_id: QOT_GET_STOCK_NOTES (2131755027)

Scope: acc:read (configured API key required)

Private data / disabled by default: requires --enable-v18-stock-notes and acc:read. Explicit nonzero IDs are sent unchanged; an ordinary query never mutates or persists the authoritative basic cache.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"stock_ids":[7001],"extension_version":1}' \
  https://127.0.0.1:22499/api/stock-notes

`POST /api/top-movers-rank`¶

proto_id: QOT_GET_TOP_MOVERS_RANK (3413)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"count":50}' \
  https://127.0.0.1:22499/api/top-movers-rank

`POST /api/trd/algo-order-logs`¶

proto_id: TRD_GET_ALGO_ORDER_LOGS (22723)

Scope: acc:read

Backend read disabled by default: requires --enable-v18-experimental-reads and acc:read. page_index is zero-based and page_size is 1..50. With fetch_all=true, the daemon uses only total_cnt to fetch all pages; there is no page_flag/completed. A later-page failure never returns a silent partial result.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"algo_order_id":"ORDER_ID","page_index":0,"page_size":50,"fetch_all":false,"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/algo-order-logs

`POST /api/trd/asset-trend`¶

proto_id: TRD_GET_ASSET_TREND (22712)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":9001,"trd_market":2},"range":{"query_type":3,"currency":"USD","start_date":"2026-08-01 00:00:00","end_date":"2026-08-30 23:59:59","time_location":"America/New_York","price_context":{"use_pre_market":true,"use_after_hours":false,"use_overnight":true}},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/asset-trend

`POST /api/trd/batch-close-positions`¶

proto_id: TRD_BATCH_CLOSE_POSITIONS (22727)

Scope: trade:real

Real-money write, disabled by default: accepts only explicit deduplicated non-portfolio positions in Desktop-supported markets and integer quantities within current closable quantity; FUTU_JP and unsupported markets reject. Side, order type, BA/TIF/session are derived from fresh position and stock-list facts, with short positions sent as source-aligned Buy. KRX uses collision-guarded local contracts TrdMarket=18, TrdSecMarket=121, and QotMarket=111. One CMD4737 requires one unique original-req_id 4718/push result.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"idempotency_key":"batch-demo-1","mode":1,"target_list":[{"position_id":9002,"qty":"10"}],"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/batch-close-positions

`POST /api/trd/cancel-order-group`¶

proto_id: TRD_CANCEL_ORDER_GROUP (22719)

Scope: trade:real

Real-money write, disabled by default: cancels only a complete authoritative current server order group; requires --enable-group-orders and trade:real.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"group-cancel-demo-1","group_type":3,"order_id_list":["ORDER_ID"]},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/cancel-order-group

`POST /api/trd/clear-futures-positions`¶

proto_id: TRD_CLEAR_FUTURES_POSITIONS (22726)

Scope: trade:real

Real-money write, disabled by default: explicit targets use custom_contract=true and may include supported futures options, but not calendar-spread futures. Account-wide clear requires both all_positions=true and daemon flag --allow-all-position-clear; any unsupported contract in scope rejects the whole action. A synchronous result=0 is admission only; final state requires one unique original-req_id 4718/push result.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":5},"idempotency_key":"clear-demo-1","position_id_list":[9001],"price_type":1,"all_positions":false,"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/clear-futures-positions

`POST /api/trd/delete-order-group`¶

proto_id: TRD_DELETE_ORDER_GROUP (22720)

Scope: trade:real

Real-money write, disabled by default: deletes only a complete authoritative current server order group; requires --enable-group-orders and trade:real.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"group-delete-demo-1","group_type":3,"order_id_list":["ORDER_ID"]},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/delete-order-group

`POST /api/trd/modify-algo-order`¶

proto_id: TRD_MODIFY_ALGO_ORDER (22722)

Scope: trade:real

Real-money write, disabled by default: modifies only a nonterminal authoritative current algorithm-order snapshot. Product, market, and algorithm market/limit shape cannot change; modify never overwrites the server vendor and revalidates static/live/customer-company facts. Requires --enable-algo-orders and trade:real.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"algo-modify-1","order_id":"ORDER_ID","order_version":1,"new_qty":"200","algo":{"algo_type":2,"start_time":1788138000000000,"end_time":1788141600000000,"vwap":{"participation_rate":"0.25"}}},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/modify-algo-order

`POST /api/trd/modify-order-group`¶

proto_id: TRD_MODIFY_ORDER_GROUP (22718)

Scope: trade:real

Real-money write, disabled by default: accepts only one authoritative current server order group; requires --enable-group-orders and trade:real. Never auto-resubmit an unknown result.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"group-modify-demo-1","group_type":3,"order_list":[{"order_id":"ORDER_ID","order_version":1,"new_price":"101"}]},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/modify-order-group

`POST /api/trd/order-relations`¶

proto_id: TRD_GET_ORDER_RELATIONS (22715)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":9001,"trd_market":2},"order_id_ex":"ORDER_ID","extension_version":1}' \
  https://127.0.0.1:22499/api/trd/order-relations

`POST /api/trd/place-algo-order`¶

proto_id: TRD_PLACE_ALGO_ORDER (22721)

Scope: trade:real

Real-money write, disabled by default: explicitly enable --enable-algo-orders and satisfy trade:real, the source-pinned product/market-limit/side/round-lot matrix, live order_ability_config_v3, dynamic customer-company and required BCAN facts, static-security, broker/cipher, and durable-intent gates. The API exposes typed market/limit variants for six algorithms, but sends only combinations allowed by the pinned rows (for example, US rejects Slicer/Peg and Iceberg market; CN, HK common, and HK futures use their own rows). Evidence is source-aligned + local-green; live backend is unverified. Unknown outcomes are never auto-resubmitted.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"algo-demo-1","client_order_id":"algo-client-1","code":"AAPL","sec_market":2,"trd_side":1,"qty":"100","price_mode":2,"limit_price":"100","lot_type":2,"order_trade_time_type":1,"position_open_type":1,"pdt_protection":true,"algo":{"algo_type":2,"start_time":1788138000000000,"end_time":1788141600000000,"vwap":{"participation_rate":"0.25"}}},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/place-algo-order

`POST /api/trd/place-order-group`¶

proto_id: TRD_PLACE_ORDER_GROUP (22717)

Scope: trade:real

Real-money write, disabled by default: explicitly enable --enable-group-orders and satisfy trade:real, account/broker/cipher/capability, and durable-intent gates. Evidence is source-aligned + local-green only; live backend behavior is unverified. Timeout/disconnect returns an unknown result and is never auto-resubmitted.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":2},"initial":{"idempotency_key":"group-demo-1","group_type":3,"order_list":[{"acc_id":900001,"client_order_id":"leg-1","code":"AAPL","sec_market":2,"trd_side":1,"order_type":1,"qty":"1","price":"100","lot_type":2,"time_in_force":0,"order_trade_time_type":1,"children_relation":0,"brother_relation":0}],"pdt_protection":true},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/place-order-group

`POST /api/trd/position-corporate-actions`¶

proto_id: TRD_GET_POSITION_CORPORATE_ACTIONS (22716)

Scope: acc:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. The instrument set comes only from the account's fresh position snapshot; callers cannot supply or override positions/symbols. The daemon queries yesterday through tomorrow in each market timezone and completes stock and derivative backend pagination independently. Mapping or per-job failures are explicit partial status.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900000001,"trd_market":2},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/position-corporate-actions

`POST /api/trd/return-calendar`¶

proto_id: TRD_GET_RETURN_CALENDAR (22714)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":9001,"trd_market":2},"currency":"USD","query_type":1,"method":2,"time":1788112000000,"calendar_date":"2026-08-01 00:00:00","time_location":"America/New_York","price_context":{"use_pre_market":true,"use_after_hours":false,"use_overnight":true},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/return-calendar

`POST /api/trd/reverse-position`¶

proto_id: TRD_REVERSE_POSITION (22724)

Scope: trade:real

Real-money write, disabled by default: accepts only a fresh authoritative position and complete stock-list facts for an ordinary monthly future. Close and implicit-open symbols, sides, and notionals are authorized atomically. After one CMD4732, success requires a fresh current-order snapshot plus 21056 to prove two distinct orders in one relation_type=1 group with exact symbol/side/qty/static identity; unknown outcomes are never auto-resubmitted.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":5},"initial":{"idempotency_key":"reverse-demo-1","position_id":9001,"price_type":1},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/reverse-position

`POST /api/trd/roll-position`¶

proto_id: TRD_ROLL_POSITION (22725)

Scope: trade:real

Real-money write, disabled by default: source and target must be different ordinary monthly futures sharing one non-zero linkage_future_id, and source-close/target-open symbols and sides are checked separately. CMD4733 carries no target price, so the daemon does not treat a quote cache as trade notional; API keys with per-order or daily value limits fail closed. After one CMD4733, a fresh current-order snapshot plus 21056 must prove both relation_type=2 members.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":900001,"trd_market":5},"initial":{"idempotency_key":"roll-demo-1","position_id":9001,"target_code":"HSI2610","target_sec_market":1},"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/roll-position

`POST /api/trd/yield-trend`¶

proto_id: TRD_GET_YIELD_TREND (22713)

Scope: acc:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"header":{"trd_env":1,"acc_id":9001,"trd_market":2},"range":{"query_type":3,"currency":"USD","start_date":"2026-08-01 00:00:00","end_date":"2026-08-30 23:59:59","time_location":"America/New_York","price_context":{"use_pre_market":true,"use_after_hours":false,"use_overnight":true}},"method":2,"extension_version":1}' \
  https://127.0.0.1:22499/api/trd/yield-trend

`POST /api/us-after-hours-rank`¶

proto_id: QOT_GET_US_AFTER_HOURS_RANK (3411)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"count":50}' \
  https://127.0.0.1:22499/api/us-after-hours-rank

`POST /api/us-overnight-rank`¶

proto_id: QOT_GET_US_OVERNIGHT_RANK (3412)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"count":50}' \
  https://127.0.0.1:22499/api/us-overnight-rank

`POST /api/us-pre-market-rank`¶

proto_id: QOT_GET_US_PRE_MARKET_RANK (3410)

Scope: qot:read

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"count":50}' \
  https://127.0.0.1:22499/api/us-pre-market-rank

`POST /api/verification`¶

proto_id: VERIFICATION (1006)

Scope: auth:setup

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"type":1,"op":1}' \
  https://127.0.0.1:22499/api/verification

`POST /api/watchlist-announcement`¶

proto_id: QOT_GET_WATCHLIST_ANNOUNCEMENT (2131755014)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. stock_ids are explicit. notice_types accepts 0..5; 0 means all and must be used alone.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_size":20,"seq_mark":"","stock_ids":[7000700],"notice_types":[0],"extension_version":1}' \
  https://127.0.0.1:22499/api/watchlist-announcement

`POST /api/watchlist-news`¶

proto_id: QOT_GET_WATCHLIST_NEWS (2131755013)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. stock_ids must be supplied explicitly and cannot be empty; there is no whole-market fallback.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_size":20,"seq_mark":"","stock_ids":[7000700],"extension_version":1}' \
  https://127.0.0.1:22499/api/watchlist-news

`POST /api/watchlist-rating`¶

proto_id: QOT_GET_WATCHLIST_RATING (2131755015)

Scope: qot:read

Enablement and evidence boundary: start with --enable-v18-experimental-reads; the feature is off by default. Current evidence is source-aligned + local-green; live backend behavior remains unverified. stock_ids must be supplied explicitly and cannot be empty; there is no whole-market fallback.

Parameters / Response: See proto definition. Fields use snake_case; v1.4.83+ alias support + v1.4.84+ enum int/string dual-accept.

Example:

curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"page_size":20,"seq_mark":"","stock_ids":[7000700],"extension_version":1}' \
  https://127.0.0.1:22499/api/watchlist-rating

REST API Complete Reference¶

Global conventions¶

System / Status¶

GET /api/delay-statistics¶

POST /api/delay-statistics¶

GET /api/global-state¶

GET /api/ping¶

GET /api/push-subscriber-info¶

GET /api/quote-rights¶

GET /api/user-info¶

Quote Subscriptions¶

POST /api/query-subscription¶

GET /api/sub-info¶

POST /api/subscribe¶

POST /api/unsubscribe¶

GET /ws¶

Quote Queries¶

POST /api/broker¶

POST /api/capital-distribution¶

POST /api/capital-flow¶

POST /api/history-kl-quota¶

POST /api/history-kline¶

POST /api/kline¶

POST /api/kline-pattern¶

POST /api/kline-pattern-catalog¶

POST /api/kline-pattern-performance¶

POST /api/kline-pattern-statistics¶

POST /api/kline-pattern-stocks¶

POST /api/market-state¶

POST /api/orderbook¶

POST /api/quote¶

GET /api/quote-capability¶

GET /api/risk-free-rate¶

POST /api/risk-free-rate¶

POST /api/rt¶

POST /api/snapshot¶

GET /api/spread-table¶

POST /api/spread-table¶

POST /api/static-info¶

POST /api/ticker¶

POST /api/ticker-statistic¶

POST /api/ticker-statistic-detail¶

POST /api/used-quota¶

Plates / Filter / Metadata¶

POST /api/code-change¶

POST /api/ipo-list¶

POST /api/list-plates¶

POST /api/plate-security¶

POST /api/plate-set¶

POST /api/stock-filter¶

POST /api/suspend¶

POST /api/trading-days¶

Reference / Derivatives¶

POST /api/company-executive-background¶

POST /api/company-executives¶

POST /api/company-operational-efficiency¶

POST /api/company-profile¶

POST /api/corporate-actions-buybacks¶

POST /api/corporate-actions-dividends¶

POST /api/corporate-actions-stock-splits¶

POST /api/daily-short-volume¶

POST /api/derivative-unusual¶

POST /api/financial-unusual¶

POST /api/financials-earnings-price-history¶

POST /api/financials-earnings-price-move¶

POST /api/financials-revenue-breakdown¶

POST /api/financials-statements¶

POST /api/future-info¶

POST /api/get-reference¶

POST /api/holding-change¶

POST /api/insider-holder-list¶

POST /api/insider-trade-list¶

POST /api/modify-user-security¶

POST /api/option-chain¶

POST /api/option-exercise-probability¶

POST /api/option-expiration-date¶

POST /api/option-quote¶

POST /api/option-screen¶

POST /api/option-strategy¶

POST /api/option-strategy-analysis¶

`GET /api/delay-statistics`¶

`POST /api/delay-statistics`¶

`GET /api/global-state`¶

`GET /api/ping`¶

`GET /api/push-subscriber-info`¶

`GET /api/quote-rights`¶

`GET /api/user-info`¶

`POST /api/query-subscription`¶

`GET /api/sub-info`¶

`POST /api/subscribe`¶

`POST /api/unsubscribe`¶

`GET /ws`¶

`POST /api/broker`¶

`POST /api/capital-distribution`¶

`POST /api/capital-flow`¶

`POST /api/history-kl-quota`¶

`POST /api/history-kline`¶

`POST /api/kline`¶

`POST /api/kline-pattern`¶

`POST /api/kline-pattern-catalog`¶

`POST /api/kline-pattern-performance`¶

`POST /api/kline-pattern-statistics`¶

`POST /api/kline-pattern-stocks`¶

`POST /api/market-state`¶

`POST /api/orderbook`¶

`POST /api/quote`¶

`GET /api/quote-capability`¶

`GET /api/risk-free-rate`¶

`POST /api/risk-free-rate`¶

`POST /api/rt`¶

`POST /api/snapshot`¶

`GET /api/spread-table`¶

`POST /api/spread-table`¶

`POST /api/static-info`¶

`POST /api/ticker`¶

`POST /api/ticker-statistic`¶

`POST /api/ticker-statistic-detail`¶

`POST /api/used-quota`¶

`POST /api/code-change`¶

`POST /api/ipo-list`¶

`POST /api/list-plates`¶

`POST /api/plate-security`¶

`POST /api/plate-set`¶

`POST /api/stock-filter`¶

`POST /api/suspend`¶

`POST /api/trading-days`¶

`POST /api/company-executive-background`¶

`POST /api/company-executives`¶

`POST /api/company-operational-efficiency`¶

`POST /api/company-profile`¶

`POST /api/corporate-actions-buybacks`¶

`POST /api/corporate-actions-dividends`¶

`POST /api/corporate-actions-stock-splits`¶

`POST /api/daily-short-volume`¶

`POST /api/derivative-unusual`¶

`POST /api/financial-unusual`¶

`POST /api/financials-earnings-price-history`¶

`POST /api/financials-earnings-price-move`¶

`POST /api/financials-revenue-breakdown`¶

`POST /api/financials-statements`¶

`POST /api/future-info`¶

`POST /api/get-reference`¶

`POST /api/holding-change`¶

`POST /api/insider-holder-list`¶

`POST /api/insider-trade-list`¶

`POST /api/modify-user-security`¶

`POST /api/option-chain`¶

`POST /api/option-exercise-probability`¶

`POST /api/option-expiration-date`¶

`POST /api/option-quote`¶

`POST /api/option-screen`¶

`POST /api/option-strategy`¶

`POST /api/option-strategy-analysis`¶

`POST /api/option-strategy-spread`¶

`POST /api/option-volatility`¶

`POST /api/owner-plate`¶

`POST /api/reference`¶

`POST /api/rehab`¶

`POST /api/research-analyst-consensus`¶

`POST /api/research-morningstar-report`¶