REST API¶

从一个读取请求开始，再按需要接入账户、交易与推送。接口路径、scope、请求字段和示例集中在 REST API 参考；本页说明调用顺序和结果判断。

调用形式¶

先确认连接模式¶

场景	连接方式
本机首次只读检查	按快速开始绑定 `127.0.0.1`，显式启用 `--rest-port 22222`；无 key 的 HTTP 请求不带 Bearer token
使用 API Key 的客户端	daemon 原生 HTTPS；配置 `rest_keys_file`、证书和私钥；客户端验证服务器证书并发送 Bearer token

即使监听 loopback，配置 API Key 后也必须启用 TLS。证书与 key 的完整配置步骤见 API Key 授权教程。REST 与同一 listener 的 /ws 共享传输模式：HTTPS 对应 WSS。

发出一个行情读取请求¶

以下示例与参考页 /api/quote 使用相同的 symbol 简写，适用于快速开始中的本机无 key 模式：

curl --fail-with-body -X POST http://127.0.0.1:22222/api/quote \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}'

POST 也用于读取，不代表交易写入。行情结果取决于登录、行情权限及接口的订阅前提；遇到业务错误时按响应诊断处理。

在已配置原生 HTTPS 的环境中，相同请求可写为：

curl --fail-with-body --cacert /path/to/ca.pem \
  -H "Authorization: Bearer $FUTU_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"HK.00700"}' \
  https://127.0.0.1:22222/api/quote

使用自己的 CA 文件、匹配证书的主机名和持有 qot:read 的 API Key。不要关闭证书校验。

请求 body 格式¶

从目标接口的参考条目复制请求形状。并非所有接口都要求 c2s 包装；也不能把订阅字段套到报价请求中。字段名、可用别名与枚举表示均以对应接口合同为准。

行情 market 与交易 trd_market 是不同枚举，例如美股分别为 11 与 2。不要跨接口复制数字；支持 symbol 的接口可使用 HK.00700 等明确市场的写法。

错误码¶

同时检查 HTTP 状态和业务响应中的 ret_type、ret_msg、err_code。HTTP 200 不等于业务成功，s2c 为空也不能直接推断为字段名错误。

观察到的结果	先检查
无法连接或 TLS 失败	进程、监听端口、URL 协议、证书主机名与 CA
HTTP 400	请求 JSON、必填字段和接口支持的字段
HTTP 401 / 403	key 是否有效、scope、账户白名单及接口传输要求
HTTP 404	路径与方法是否和参考一致
HTTP 429	限流与额度；不要无间隔重试
HTTP 5xx	网关与后端连接状态，结合健康探针和日志定位
HTTP 200 且 `ret_type` 非零	阅读业务诊断，检查权限、输入及前置条件

错误格式依端点与失败阶段而异；可能是 {"error":"..."}，也可能包含业务错误字段。更多排查见常见问题。

路由表¶

完整路由目录由 REST API 参考维护。下面保留调用时容易混淆的行为说明。

系统¶

用 /api/global-state 读取全局状态。进程与就绪探针的区别见下方运维说明；业务查询不能替代 liveness 检查。

行情¶

/api/sub-info 是当前连接视图，不代表网关内的全部订阅；不要把空列表直接当成全局订阅丢失。跨客户端检查时，按 /api/query-subscription 的请求合同设置 is_req_all_conn: true。

交易¶

远程 HTTPS 解锁流程：

按授权教程配置 daemon 原生 HTTPS，客户端验证证书；反向代理到 daemon 的上游也使用 HTTPS。
准备持有 trade:unlock 的 API Key，并核对账户白名单。其他交易 scope 不替代该权限。
在明确需要解锁时，按 POST /api/unlock-trade准备请求。交易密码及其 MD5 都属于凭据，不放入日志或前端代码。
检查响应后再判断解锁结果。解锁不代表获得下单权限；交易写入仍需对应 scope、交易开关与明确授权。

Forwarded / X-Forwarded-Proto 请求头不能替代真实 TLS。非 loopback 明文请求到达解锁路由时会被拒绝；向 TLS listener 发送明文则会在握手阶段失败。

单笔撤单使用 /api/cancel-order；/api/modify-order 保留 modify_order_op=2 的兼容形态。撤改单返回 ret_type=0 表示后端接受请求，最终订单状态以交易推送或 refresh_cache=true 的 /api/orders 查询为准。可卖数量以推送或显式刷新的 /api/positions 为准。

单笔撤单成功后，网关会在 ACK 前做一次有上限的订单刷新，不隐式刷新持仓。刷新失败不会将已接受的撤单改成失败，因此不要据此重复发送撤单。

运维¶

/livez 检查进程存活；/health 检查后端传输健康；/readyz 检查后端连接与网关调度就绪。它们不要求 Bearer，但共享 listener 的 TLS 配置。
/metrics 在 scope mode 要求 metrics:read 或 admin；legacy 无 key 模式公开，FUTU_METRICS_PUBLIC=1 也可显式公开。
/ws 在 scope mode 的握手要求 qot:read，通过 Bearer header 或 ?token= 鉴权；legacy 无 key 模式保持公开。浏览器用法见 WebSocket 指南。
管理接口要求 admin；部署、监控和认证恢复见运维入口。

参考实现¶

REST API 参考 · 网页前端案例 · 接入方式