API 参考¶
v1.4.85 新增 (响应 jackie 反馈). 过去
https://www.futuapi.com/guide/rest/只有概览 + 少量 endpoint, 缺完整参数 / 返回结构说明;/api/只有 rustdoc 无 REST endpoint 视角. 本 section 提供 3 个 API surface 的完整参数级 文档, 全部自动生成, 未来新 API 自动入档.
3 个 API surface 选择¶
本项目提供 3 个 surface 访问同一套 FutuOpenD 网关功能, 选哪个看场景:
| Surface | 最适合 | 延迟 | 依赖 |
|---|---|---|---|
| REST (HTTP + WS) | Web 前端 / curl 测试 / 其他 HTTP client | HTTP 单请求 + WS 推 | 仅 HTTP |
| gRPC (tonic) | 高性能 streaming / Python / Go / Java client | 单 TCP + binary frame, 最低 | protobuf runtime |
| MCP (JSON-RPC 2.0) | LLM agent (Claude Desktop / Cursor / Continue...) | JSON-RPC over stdio/HTTP | rmcp / 兼容 MCP client |
完整参考文档¶
REST API¶
- 70 route × 9 section (ping / auth / qot / trade / push / admin / ws / ...)
- 每 endpoint: URL / 方法 / scope / 参数 (字段 / 类型 / 必填 / 说明) / 返回结构 / 错误码 / curl 示例
gRPC API¶
- Service 定义 (
FutuOpenD.Request+FutuOpenD.SubscribePush) - 全量 proto_id 表 (90+ proto_id 分 6 category)
- Python grpc client 双示例 (单次请求 + stream 订阅)
MCP 工具¶
- 60 tool × 9 section (核心 / 订阅 / 行情 / 板块 / 衍生品 / 自选 / 账户 / 交易 / push)
- 每 tool: Scope / Python SDK 等价 / 请求参数 (含 v1.4.83/84 alias + v1.4.84 enum 双接 + deny_unknown_fields + runtime validate) / JSON-RPC 调用示例
保证自动同步¶
3 份 reference 文档均由 FutuOpenD-rs 构建流水线自动生成, 跟随 daemon 每个 release 版本更新. 不会漂移: 新加 endpoint / tool / proto_id 会随新版 daemon 自动出现在文档里.
3 个 surface 共享的概念¶
Scope (权限域)¶
所有 surface 请求都需对应 scope:
| Scope | 允许 | 默认开启 |
|---|---|---|
qot:read |
行情查询 (quote / kline / orderbook / ...) | ✅ |
acc:read |
账户只读 (funds / positions / orders / deals / ...) | ✅ |
trade:real |
实盘下单 / 改单 / 撤单 | ❌ (--enable-trading) |
trade:simulate |
模拟盘下单 / 改单 / 撤单 | ❌ (--enable-trading) |
trade:unlock |
解锁交易 (2FA) | ❌ (--enable-trading) |
详见 guide/auth.
共通错误码¶
所有 surface 返错时都会带 ret_type + ret_msg (REST / gRPC) 或
CallToolResult.is_error=true + {"error":...,"status":"error"} (MCP).
-1: 通用错误 (ret_msg 带详情)-100: 未解锁交易 (2FA 未通过)-101: 密码错-102: 不支持的 cmd (wrong channel / 老 API)unauthorized: API key 不带对应 scopeunknown field: v1.4.84+ deny_unknown_fields 命中 (typo 字段名 / camelCase 未归一化 / 未来 feature 预填字段等)
历史¶
- v1.4.81 (2026-04-24): jackie 反馈 "官网没有完整 REST/gRPC 接口文档"
- v1.4.85 (本版): REST + gRPC + MCP 3 surface 完整自动生成文档上线
- 未来: 新 API 自动入文档, 无 "写了代码忘了写 docs" 漂移