API Reference¶
New in v1.4.85 (response to jackie's feedback). Previously
https://www.futuapi.com/guide/rest/was overview-only with a few endpoint samples;/api/had rustdoc but no REST-endpoint view. This section provides complete, parameter-level documentation for all 3 API surfaces, fully auto-generated, so future APIs auto-land into the docs without drift.
Which surface to pick¶
This project exposes 3 surfaces to the same FutuOpenD gateway functionality. Pick based on scenario:
| Surface | Best for | Latency | Dependency |
|---|---|---|---|
| REST (HTTP + WS) | Web frontends / curl tests / any HTTP client | HTTP req + WS push | HTTP only |
| gRPC (tonic) | High-throughput streaming / Python / Go / Java client | Single TCP + binary frame, lowest | protobuf runtime |
| MCP (JSON-RPC 2.0) | LLM agents (Claude Desktop / Cursor / Continue...) | JSON-RPC over stdio/HTTP | rmcp / compatible MCP client |
Full reference docs¶
REST API¶
- 70 routes × 9 sections (ping / auth / qot / trade / push / admin / ws / ...)
- Per endpoint: URL / method / scope / parameters (field / type / required / description) / return structure / error codes / curl example
gRPC API¶
- Service definition (
FutuOpenD.Request+FutuOpenD.SubscribePush) - Complete proto_id table (90+ proto_ids across 6 categories)
- Python grpc client dual examples (single-shot request + stream subscribe)
MCP Tools¶
- 60 tools × 9 sections (core / subscribe / quote / plate / derivative / watchlist / account / trade / push)
- Per tool: Scope / Python SDK equivalent / request parameters (with v1.4.83/84 aliases + v1.4.84 enum dual-accept + deny_unknown_fields + runtime validate) / JSON-RPC invocation example
Guaranteed auto-sync¶
All 3 reference documents are auto-generated by the FutuOpenD-rs build pipeline and refreshed with every daemon release. No drift — new endpoints / tools / proto_ids appear in the docs automatically with each new daemon version.
Shared concepts across all 3 surfaces¶
Scope (permission domain)¶
All surface requests require a matching scope:
| Scope | Allows | Enabled by default |
|---|---|---|
qot:read |
Quote queries (quote / kline / orderbook / ...) | ✅ |
acc:read |
Account read-only (funds / positions / orders / deals / ...) | ✅ |
trade:real |
Live trading (place / modify / cancel order) | ❌ (--enable-trading) |
trade:simulate |
Paper trading (place / modify / cancel order) | ❌ (--enable-trading) |
trade:unlock |
Unlock trading (2FA) | ❌ (--enable-trading) |
See guide/auth for detail.
Shared error codes¶
All surfaces return ret_type + ret_msg (REST / gRPC) or
CallToolResult.is_error=true + {"error":...,"status":"error"} (MCP)
on failure.
-1: Generic error (ret_msg carries detail)-100: Trading not unlocked (2FA not passed)-101: Wrong password-102: Unsupported cmd (wrong channel / legacy API)unauthorized: API key lacks the required scopeunknown field: v1.4.84+ deny_unknown_fields triggered (typo in field name / un-normalized camelCase / pre-filled future-feature fields...)
History¶
- v1.4.81 (2026-04-24): jackie reported "official site lacks complete REST/gRPC API docs"
- v1.4.85 (this release): REST + gRPC + MCP — all 3 surfaces shipped with fully auto-generated reference docs
- Future: New APIs auto-land into docs, no more "wrote the code, forgot the docs" drift