Skip to content

gRPC API Complete Reference

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

Architecture

futu-opend's gRPC interface uses a single Request RPC design: all business calls are dispatched via proto_id to internal handlers, avoiding repeating RPC definitions for each business.

Service Definition

service FutuOpenD {
  // Universal request-response (covers all quote / trade / system APIs)
  rpc Request(FutuRequest) returns (FutuResponse);

  // Streaming push (quote updates, order updates, price alerts, etc.)
  rpc SubscribePush(SubscribePushRequest) returns (stream PushEvent);
}

Message Structure

FutuRequest

message FutuRequest {
  uint32 proto_id = 1;   // Protocol ID (e.g. 3004 = GetBasicQot)
  bytes body = 2;        // protobuf-encoded business body (Request.c2s)
}

FutuResponse

message FutuResponse {
  int32 ret_type = 1;     // 0=success, other=error code
  string ret_msg = 2;     // error message (when ret_type != 0)
  uint32 proto_id = 3;    // echoed proto_id
  bytes body = 4;         // protobuf-encoded business body (Response.s2c)
}

PushEvent (streaming)

message PushEvent {
  uint32 proto_id = 1;    // Push protocol ID (e.g. 3005 = UpdateBasicQot)
  string sec_key = 2;     // Security key (quote push, format "market_code" e.g. "1_00700")
  int32 sub_type = 3;     // Subscription type (Qot_Common.SubType)
  bytes body = 4;         // protobuf-encoded push data
  string event_type = 5;  // "quote" / "trade" / "notify"
  uint64 acc_id = 6;      // Trade account ID (for trade push)
}

Usage Patterns

1. Unary Request (Request RPC)

# Python grpc client example
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)

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

# Dispatch via proto_id
rsp = stub.Request(FutuRequest(proto_id=3004, body=body))
if rsp.ret_type == 0:
    from qot_get_basic_qot_pb2 import Response as GetBasicQotResponse
    result = GetBasicQotResponse().FromString(rsp.body)
    print(result.s2c)

2. Streaming Push

from futu_service_pb2 import SubscribePushRequest

push_stream = stub.SubscribePush(SubscribePushRequest())
for event in push_stream:
    if event.event_type == "quote":
        print(f"proto_id={event.proto_id} sec_key={event.sec_key}")

First call Request RPC with 3001 (QOT_SUB) to subscribe specific securities, then receive push via SubscribePush.

Auth

Same as REST / MCP: gRPC metadata authorization: Bearer <API_KEY>. See docs/guide/grpc.en.md and docs/guide/auth.en.md.

Full proto_id Table (78 total)

Grouped by category. Client code looks up this table for proto_id values; the corresponding Request/Response proto comes from Futu's official proto definitions.

Connection Management

Connection init, keep-alive, global state.

proto_id Name Hint
1001 INIT_CONNECT —
1002 GET_GLOBAL_STATE —
1003 NOTIFY —
1004 KEEP_ALIVE —

Quota Query

History K-line quota query.

proto_id Name Hint
1010 GET_USED_QUOTA —

Quote Protocol

Real-time subscriptions, K-line, order book, broker queue, time-sharing, ticker.

proto_id Name Hint
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 —

Trading Protocol

Account list, funds, positions, place / modify / cancel orders, unlock, history.

proto_id Name Hint
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 —

Further