跳转至

REST API

:22222/api/* 暴露 41 个 HTTP 接口，全部 JSON。

调用形式

# 不带鉴权（本地开发）
curl http://localhost:22222/api/accounts

# Bearer Token 鉴权
curl -H "Authorization: Bearer fc_xxxx..." http://localhost:22222/api/accounts

# 大部分写接口用 POST + JSON body
curl -X POST http://localhost:22222/api/quote \
  -H 'Content-Type: application/json' \
  -d '{"security_list":[{"market":1,"code":"00700"}],"sub_type_list":[1]}'

路由表

系统

方法 路径 Scope 用途
GET /api/global-state qot:read 全局状态（服务器时间、市场状态）
GET /api/user-info qot:read 当前用户信息
GET /api/delay-statistics qot:read 协议延迟统计

行情

方法 路径 Scope
POST /api/subscribe qot:read
GET /api/sub-info qot:read
POST /api/quote qot:read
POST /api/kline qot:read
POST /api/orderbook qot:read
POST /api/broker qot:read
POST /api/ticker qot:read
POST /api/rt qot:read
POST /api/snapshot qot:read
POST /api/static-info qot:read
POST /api/plate-set qot:read
POST /api/plate-security qot:read
POST /api/reference qot:read
POST /api/owner-plate qot:read
POST /api/option-chain qot:read
POST /api/warrant qot:read
POST /api/capital-flow qot:read
POST /api/capital-distribution qot:read
POST /api/user-security qot:read
POST /api/stock-filter qot:read
POST /api/ipo-list qot:read
POST /api/future-info qot:read
POST /api/market-state qot:read
POST /api/history-kline qot:read

交易

方法 路径 Scope
GET /api/accounts acc:read
POST /api/sub-acc-push acc:read
POST /api/funds acc:read
POST /api/positions acc:read
POST /api/orders acc:read
POST /api/order-fills acc:read
POST /api/max-trd-qtys acc:read
POST /api/history-orders acc:read
POST /api/history-order-fills acc:read
POST /api/margin-ratio acc:read
POST /api/order-fee acc:read
POST /api/unlock-trade trade:real
POST /api/order trade:real
POST /api/modify-order trade:real

运维

方法 路径 Scope 用途
GET /metrics 无 Prometheus 抓取
GET /health 无 liveness probe
GET /ws qot:read（握手） WebSocket 推送升级

错误码

HTTP 含义
200 成功
400 body JSON 格式错 / 必填字段缺
401 没带 Bearer / token 无效 / 过期
403 scope 不够
404 路径不在路由表（fail-closed，不漏信息）
429 限额触发（rate / daily / per-order / 市场白名单 / 时段等）
500 服务端 bug / 网关 disconnect

错误 body 统一：

{"error": "limit check failed: rate limit exceeded: 3 orders in the last 60s (cap 3)"}

请求 body 格式

路由层接 Json<Value> 然后交给 adapter::proto_request，里面把 JSON 转 protobuf 调 RequestRouter。所以 body 结构 和 Futu protobuf 定义完全一致 —— 直接看 proto/ 目录下的 .proto 文件。

下单的 body 结构（proto/Trd_PlaceOrder.proto 的 C2S）：

{
  "packet_id": { "conn_id": 12345, "serial_no": 1 },
  "header":   { "trd_env": 1, "acc_id": 987654, "trd_market": 1 },
  "trd_side": 1,
  "order_type": 1,
  "code": "00700",
  "qty": 100,
  "price": 300.0,
  "sec_market": 1
}

主要 enum 值（与 Futu 官方 Trd_Common.proto 一致，协议兼容）：

  • trd_env：1 = 模拟，2 = 真实
  • trd_side：1 = BUY，2 = SELL，3 = SELL_SHORT，4 = BUY_BACK
  • trd_market：1 = HK，2 = US，3 = CN，4 = HKCC，5 = FUTURES，6 = SG，7 = JP
  • order_type：1 = NORMAL（限价），2 = MARKET，5 = ABSOLUTE_LIMIT，6 = AUCTION，7 = AUCTION_LIMIT，8 = SPECIAL_LIMIT

参考实现

真实调用样例可以参考：