跳转至

gRPC API 完整参考

v1.4.85 新增. 本文件由 FutuOpenD-rs 自动生成工具产出, 跟随 daemon 每个 release 版本更新.

架构

futu-opend 的 gRPC 接口采用单一 Request RPC 设计: 所有业务通过 proto_id 分发到内部 handler, 避免为每个业务重复定义 RPC method.

Service 定义

service FutuOpenD {
  // 通用请求-响应 (覆盖所有行情 / 交易 / 系统接口)
  rpc Request(FutuRequest) returns (FutuResponse);

  // 流式推送 (行情更新 / 订单更新 / 到价提醒等)
  rpc SubscribePush(SubscribePushRequest) returns (stream PushEvent);
}

Message 结构

FutuRequest

message FutuRequest {
  uint32 proto_id = 1;   // 协议 ID (如 3004 = GetBasicQot)
  bytes body = 2;        // protobuf 编码的业务 body (Request.c2s)
}

FutuResponse

message FutuResponse {
  int32 ret_type = 1;     // 0=成功, 其他=错误码
  string ret_msg = 2;     // 错误信息 (ret_type != 0 时有值)
  uint32 proto_id = 3;    // echo proto_id
  bytes body = 4;         // protobuf 编码的业务 body (Response.s2c)
}

PushEvent (streaming)

message PushEvent {
  uint32 proto_id = 1;    // 推送协议 ID (如 3005 = UpdateBasicQot)
  string sec_key = 2;     // 证券标识 (行情推送, 格式 "market_code" 如 "1_00700")
  int32 sub_type = 3;     // 订阅类型 (Qot_Common.SubType)
  bytes body = 4;         // protobuf 编码的推送数据
  string event_type = 5;  // "quote" / "trade" / "notify"
  uint64 acc_id = 6;      // 交易账户 ID (trade push 时有值)
}

使用模式

1. 单次请求 (Request RPC)

# Python grpc 客户端示例
import grpc
from futu_service_pb2 import FutuRequest
from futu_service_pb2_grpc import FutuOpenDStub
from qot_get_basic_qot_pb2 import Request as GetBasicQotRequest

channel = grpc.insecure_channel('localhost:22500')
stub = FutuOpenDStub(channel)

# 构 GetBasicQot 请求
c2s = GetBasicQotRequest.C2S(
    security_list=[{'market': 1, 'code': '00700'}]
)
body = GetBasicQotRequest(c2s=c2s).SerializeToString()

# 通过 proto_id 分发
rsp = stub.Request(FutuRequest(proto_id=3004, body=body))
if rsp.ret_type == 0:
    # 解析 Response
    from qot_get_basic_qot_pb2 import Response as GetBasicQotResponse
    result = GetBasicQotResponse().FromString(rsp.body)
    print(result.s2c)

2. 订阅推送 (Streaming)

from futu_service_pb2 import SubscribePushRequest

push_stream = stub.SubscribePush(SubscribePushRequest())
for event in push_stream:
    if event.event_type == "quote":
        # event.body 是 Qot_UpdateBasicQot / Qot_UpdateOrderBook 等 push
        print(f"proto_id={event.proto_id} sec_key={event.sec_key}")

先通过 Request RPC 调用 3001 (QOT_SUB) 订阅具体证券, 再通过 SubscribePush 接收推送.

Auth

与 REST / MCP 一致: gRPC metadata authorization: Bearer <API_KEY>. 参见 docs/guide/grpc.md 和 docs/guide/auth.md.

全量 proto_id 表 (共 78 个)

按 category 分组. client 业务代码查这个表确认 proto_id 数值, 对应的 Request/Response proto 参考 Futu 官方 proto 定义.

连接管理

连接初始化、心跳、全局状态查询。

proto_id 常量名 说明
1001 INIT_CONNECT —
1002 GET_GLOBAL_STATE —
1003 NOTIFY —
1004 KEEP_ALIVE —

额度查询

历史 K 线 quota 查询。

proto_id 常量名 说明
1010 GET_USED_QUOTA —

行情协议

实时订阅、K 线、摆盘、经纪队列、分时、逐笔成交等。

proto_id 常量名 说明
1005 GET_USER_INFO —
1006 GET_DELAY_STATISTICS —
1008 TEST_CMD —
1009 REMOTE_CMD —
2223 TRD_GET_MARGIN_RATIO 交易新版 API
2225 TRD_GET_ORDER_FEE —
2226 TRD_FLOW_SUMMARY —
3000 VERIFICATION 其他
3001 QOT_SUB —
3002 QOT_REG_QOT_PUSH —
3003 QOT_GET_SUB_INFO —
3004 QOT_GET_BASIC_QOT —
3005 QOT_UPDATE_BASIC_QOT —
3006 QOT_GET_KL —
3007 QOT_UPDATE_KL —
3008 QOT_GET_RT —
3009 QOT_UPDATE_RT —
3010 QOT_GET_TICKER —
3011 QOT_UPDATE_TICKER —
3012 QOT_GET_ORDER_BOOK —
3013 QOT_UPDATE_ORDER_BOOK —
3014 QOT_GET_BROKER —
3015 QOT_UPDATE_BROKER —
3016 QOT_GET_ORDER_DETAIL —
3017 QOT_UPDATE_ORDER_DETAIL —
3019 QOT_UPDATE_PRICE_REMINDER —
3100 QOT_GET_HISTORY_KL —
3101 QOT_GET_HISTORY_KL_POINTS —
3103 QOT_REQUEST_HISTORY_KL —
3104 QOT_REQUEST_HISTORY_KL_QUOTA —
3105 QOT_REQUEST_REHAB —
3200 QOT_GET_TRADE_DATE —
3201 QOT_GET_SUSPEND —
3202 QOT_GET_STATIC_INFO —
3203 QOT_GET_SECURITY_SNAPSHOT —
3204 QOT_GET_PLATE_SET —
3205 QOT_GET_PLATE_SECURITY —
3206 QOT_GET_REFERENCE —
3207 QOT_GET_OWNER_PLATE —
3208 QOT_GET_HOLDING_CHANGE_LIST —
3209 QOT_GET_OPTION_CHAIN —
3210 QOT_GET_WARRANT 新版 API
3211 QOT_GET_CAPITAL_FLOW —
3212 QOT_GET_CAPITAL_DISTRIBUTION —
3213 QOT_GET_USER_SECURITY —
3214 QOT_MODIFY_USER_SECURITY —
3215 QOT_STOCK_FILTER —
3216 QOT_GET_CODE_CHANGE —
3217 QOT_GET_IPO_LIST —
3218 QOT_GET_FUTURE_INFO —
3219 QOT_REQUEST_TRADE_DATE —
3220 QOT_SET_PRICE_REMINDER —
3221 QOT_GET_PRICE_REMINDER —
3222 QOT_GET_USER_SECURITY_GROUP —
3223 QOT_GET_MARKET_STATE —
3224 QOT_GET_OPTION_EXPIRATION_DATE —
3702 QOT_GET_REHAB —

交易协议

账户列表、资金、持仓、下单、改单 / 撤单、解锁、历史查询。

proto_id 常量名 说明
2001 TRD_GET_ACC_LIST —
2005 TRD_UNLOCK_TRADE —
2008 TRD_SUB_ACC_PUSH —
2101 TRD_GET_FUNDS —
2102 TRD_GET_POSITION_LIST —
2111 TRD_GET_MAX_TRD_QTYS —
2201 TRD_GET_ORDER_LIST —
2202 TRD_PLACE_ORDER —
2205 TRD_MODIFY_ORDER —
2208 TRD_UPDATE_ORDER —
2211 TRD_GET_ORDER_FILL_LIST —
2218 TRD_UPDATE_ORDER_FILL —
2221 TRD_GET_HISTORY_ORDER_LIST —
2222 TRD_GET_HISTORY_ORDER_FILL_LIST —
2237 TRD_RECONFIRM_ORDER —
2240 TRD_NOTIFY —

更多