### Initial Deployment (Recommended Flow)

Source: https://www.futuapi.com/tutorials/cheatsheet

First, run setup in the foreground to complete SMS verification and cache credentials. Then, start the production instance, which will automatically use cached credentials to bypass SMS.

```bash
# Step 1: Run setup in foreground (daemon sends SMS immediately and waits for code)
./futu-opend --setup-only \
  --login-account X --login-pwd Y --platform moomoo

# Step 2: Start normally (automatically uses cached credentials to skip SMS)
./futu-opend --login-account X --login-pwd Y --platform moomoo \
  --rest-port 22222 --grpc-port 33333
```

--------------------------------

### Systemd Deployment Steps

Source: https://www.futuapi.com/tutorials/cheatsheet

Steps to deploy FutuOpenD using systemd. First, run setup to cache credentials, then enable and start the systemd service.

```bash
# 1. Run setup in foreground to write credentials (as futu user)
sudo -u futu /usr/local/bin/futu-opend --setup-only \
  --login-account X --login-pwd Y --platform moomoo

# 2. Enable and start the systemd service
sudo systemctl enable --now futu-opend
```

--------------------------------

### Install futucli

Source: https://www.futuapi.com/tutorials/api-key-setup

Install the futucli tool to manage API keys and configurations.

```bash
./futucli --help

```

--------------------------------

### Enable and Start futu Services

Source: https://www.futuapi.com/tutorials/deploy-production

Reloads systemd configuration, enables the futu-opend and futu-mcp services to start on boot, and starts them immediately. Includes a command to view service logs.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now futu-opend.service
sudo systemctl enable --now futu-mcp.service

# 看日志
sudo journalctl -u futu-opend -f
```

--------------------------------

### Install Futu API with Homebrew

Source: https://www.futuapi.com/download

Recommended installation method for macOS and Linux users. This command installs the futu-opend-rs package, making futu-opend, futu-mcp, and futucli available in your PATH.

```bash
brew install futuleaf/tap/futu-opend-rs

```

--------------------------------

### Install FutuOpenD via Homebrew

Source: https://www.futuapi.com/quick-start

Use Homebrew to install the FutuOpenD gateway. This is the recommended method for automatic handling of macOS Gatekeeper.

```bash
brew install futuleaf/tap/futu-opend-rs
```

--------------------------------

### Download and Install futu-opend Binaries

Source: https://www.futuapi.com/tutorials/deploy-production

Downloads the futu-opend, futu-mcp, and futucli binaries from a specified URL, verifies their integrity using SHA256 checksums, and installs them to /usr/local/bin.

```bash
cd /tmp
curl -LO https://futuapi.com/releases/rs-v1.4.84/futu-opend-rs-1.4.84-linux-x86_64.tar.gz
curl -LO https://futuapi.com/releases/rs-v1.4.84/futu-opend-rs-1.4.84-linux-x86_64.tar.gz.sha256
sha256sum -c futu-opend-rs-1.4.84-linux-x86_64.tar.gz.sha256
tar xf futu-opend-rs-1.4.84-linux-x86_64.tar.gz
sudo install -m 0755 futu-opend  /usr/local/bin/
sudo install -m 0755 futu-mcp    /usr/local/bin/
sudo install -m 0755 futucli     /usr/local/bin/
```

--------------------------------

### Minimal Read-Only KeyRecord Example

Source: https://www.futuapi.com/guide/keys-json

Example of a basic KeyRecord with only read permissions for market data.

```json
{
  "id": "research",
  "hash": "a1b2...",
  "scopes": ["qot:read"],
  "created_at": "2026-04-15T10:00:00Z"
}

```

--------------------------------

### Start MCP with HTTP Transport

Source: https://www.futuapi.com/guide/mcp

Configure and launch the futu-mcp server for HTTP transport, including a listening port for HTTP requests. This setup allows for JSON-RPC frames to be transmitted via stdin/stdout.

```bash
./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json \
  --http-listen 127.0.0.1:38765
```

--------------------------------

### Start FutuOpenD Gateway

Source: https://www.futuapi.com/quick-start

Start the FutuOpenD gateway with your login account and password. The gateway will prompt for a SMS verification code on first login to a new device. Login credentials are cached in `~/.config/futu/`.

```bash
./futu-opend \
  --login-account 12345678 \
  --login-pwd 'your_password' \
  --rest-port 22222 \
  --grpc-port 33333
```

--------------------------------

### gRPC Request Method Example (grpcurl)

Source: https://www.futuapi.com/guide/grpc

Demonstrates how to call the Request RPC method using grpcurl, including examples for basic requests and authenticated requests with a Bearer token.

```APIDOC
## Calling Examples (grpcurl)

```bash
# v1.4.31+ release tarball includes .proto, can be used with -proto directly:
grpcurl -plaintext \
  -import-path examples -proto futu_service.proto \
  -d '{"proto_id":1002}' \
  localhost:33333 futu.service.FutuOpenD/Request

# Authentication (scope mode)
grpcurl -plaintext \
  -import-path examples -proto futu_service.proto \
  -H 'authorization: Bearer fc_xxxx...' \
  -d '{"proto_id":1002}' \
  localhost:33333 futu.service.FutuOpenD/Request
```
```

--------------------------------

### Streaming Push Subscription Usage Example (Python)

Source: https://www.futuapi.com/reference/grpc-api

Example demonstrating how to subscribe to data streams using the `SubscribePush` gRPC method. It shows iterating over the `PushEvent` stream to receive real-time updates.

```APIDOC
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}")


```

--------------------------------

### Start Futu MCP in stdio Mode

Source: https://www.futuapi.com/quick-start

Start the Futu MCP (Multi-Client Proxy) in stdio mode, which is suitable for LLM clients that directly launch child processes. Set the `FUTU_MCP_API_KEY` environment variable.

```bash
# stdio 模式（LLM 客户端直接启子进程）
export FUTU_MCP_API_KEY="fc_xxxxxx..."   # 用上面生成的 key
./futu-mcp --gateway 127.0.0.1:11111 --keys-file ~/.config/futu/keys.json
```

--------------------------------

### Deploy FutuAPI with Password Security

Source: https://www.futuapi.com/tutorials/cheatsheet

Examples for deploying futu-opend with secure password handling across different environments.

```bash
# A. Local long-term use (most recommended)
futucli set-login-pwd --account 12345678          # Store once
./futu-opend --login-account 12345678 ...         # Reads from keychain on startup
```

```bash
# B. Docker (mount secret to a file)
docker run -v pwd-file:/run/secrets/futu-pwd:ro \
  ghcr.io/futuleaf/futu-opend-rs \
  --login-account X --login-pwd-file /run/secrets/futu-pwd ...
```

```bash
# C. systemd (LoadCredential from EncryptedDir / TPM)
# /etc/systemd/system/futu-opend.service
[Service]
LoadCredential=login-pwd:/etc/futu/pwd
ExecStart=/usr/local/bin/futu-opend \
  --login-account X \
  --login-pwd-file ${CREDENTIALS_DIRECTORY}/login-pwd ...
```

```bash
# D. CI / cron (FUTU_PWD env var)
FUTU_PWD='...' ./futu-opend --login-account X ...
```

```bash
# E. Local ad-hoc run (no config, will prompt)
./futu-opend --login-account 12345678 ...
# → "Login password for account 12345678: "
```

--------------------------------

### Start Futu MCP in HTTP Mode

Source: https://www.futuapi.com/quick-start

Start the Futu MCP in HTTP mode for scenarios where multiple LLMs share a single server instance. This mode is available from v1.0+.

```bash
# HTTP 模式（多 LLM 共享一个 server，v1.0+）
./futu-mcp --gateway 127.0.0.1:11111 \
           --keys-file ~/.config/futu/keys.json \
           --http-listen 127.0.0.1:38765
```

--------------------------------

### Single Request RPC Usage Example (Python)

Source: https://www.futuapi.com/reference/grpc-api

Example demonstrating how to make a single request using the gRPC `Request` method. It shows constructing a `GetBasicQotRequest`, serializing it, sending it via `FutuRequest`, and deserializing the `FutuResponse`.

```APIDOC
# 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)


```

--------------------------------

### Python: gRPC Request with Authentication

Source: https://www.futuapi.com/guide/grpc

Example of making a gRPC request in Python, including setting up credentials for authentication.

```python
import grpc
from futu_pb2 import FutuRequest
from futu_pb2_grpc import FutuOpenDStub

creds = grpc.metadata_call_credentials(
    lambda ctx, cb: cb((("authorization", "Bearer fc_xxxx..."),), None)
)
channel = grpc.secure_channel("localhost:33333", grpc.ssl_channel_credentials())
stub = FutuOpenDStub(channel)

# 打包 proto_id=3004 (QOT_GET_BASIC_QOT) body
body = build_get_basic_qot_request(code="00700")  # protobuf encode
resp = stub.Request(FutuRequest(proto_id=3004, body=body))


```

--------------------------------

### grpcurl: Subscribe to Push Events

Source: https://www.futuapi.com/guide/grpc

Example of subscribing to streaming push events using grpcurl, including authentication headers.

```bash
grpcurl -plaintext \
  -H 'authorization: Bearer fc_xxxx...' \
  -d '{}' \
  localhost:33333 futu.service.FutuOpenD/SubscribePush


```

--------------------------------

### Initial Futu Gateway and CLI Setup

Source: https://www.futuapi.com/cases/trading-bot

Follow these steps to set up your Futu OpenD gateway and CLI for the first time. This includes storing credentials, performing initial SMS verification, and launching the gateway in a headless mode. Ensure you note the account ID for subsequent commands.

```bash
# 1. 凭据一次性存 OS keychain（避免 --login-pwd 泄漏到 ps aux）
futucli set-login-pwd --account 12345678
#   提示：输入密码 → 密码进 Keychain / Secret Service / Credential Manager

# 2. 首次启动，前台跑 SMS 验证（服务端首次会发短信到你绑定手机）
futu-opend --setup-only --login-account 12345678 --platform futunn
#   SMS 到手输验证码，看到 "credentials cached" 即可 Ctrl-C 退出

# 3. 启动网关（无人值守，systemd / Docker / nohup 都行）
futu-opend --login-account 12345678 --platform futunn \
           --rest-port 22222 --grpc-port 33333 \
           --audit-log /var/log/futu/
#   监听：FTAPI(11111) / REST(22222) / gRPC(33333)

# 4. 看账户列表（v1.4.26 修好后能看到所有 broker 的全部 real/sim 账户）
futucli account
#   输出示例（8 列：Acc ID / Card / Env / Broker / Type / Status / Role / Markets）
#   记下要交易的 acc_id

# 5. 确认行情能拉（订阅 + 拉一次 basic quote）
futucli quote HK.00700,HK.09988

# 6. 实盘交易前先解锁（real 环境必做，sim 跳过）
futucli unlock-trade --trade-pwd-md5 <32位小写hex>

# 7. 下第一单（sim 环境练手，推荐先跑这条）
futucli place-order \
  --env simulate --market HK --acc-id <sim_acc_id> \
  --code 00700 --side BUY --qty 100 --price 300 --order-type NORMAL

# 8. 查订单 + 成交
futucli order --env simulate --market HK --acc-id <sim_acc_id>
futucli deal --env simulate --market HK --acc-id <sim_acc_id>

```

--------------------------------

### Verify Installation and Place a Test Order

Source: https://www.futuapi.com/

Use futucli and curl to verify the gateway is running, check account status, and place a simulated trade. Ensure trading is unlocked before placing orders.

```bash
# 查 HK 报价
futucli quote HK.00700

```

```bash
# 账户列表
curl http://127.0.0.1:22222/api/trd/get-acc-list

```

```bash
# 解锁交易后可下模拟单
futucli unlock-trade --env simulate
futucli place-order --symbol HK.00700 --side buy --qty 100 --env simulate

```

--------------------------------

### MCP Server Startup

Source: https://www.futuapi.com/guide/mcp

Instructions for starting the MCP server using either stdio or HTTP transport, including necessary environment variables and command-line arguments.

```APIDOC
## Starting the MCP Server

### stdio Transport
This transport uses standard input/output for JSON-RPC frames and is typically launched as a subprocess by the LLM client.

```bash
export FUTU_MCP_API_KEY="fc_xxxx..."
./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json
```

### HTTP Transport (v1.0+)
This transport listens on a specified HTTP port for incoming requests.

```bash
export FUTU_MCP_API_KEY="fc_xxxx..."
./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json \
  --http-listen 127.0.0.1:38765
```

**HTTP Endpoints**:
- `POST /mcp`: Handles streamable HTTP transport for MCP requests.
- `GET /metrics`: Exposes Prometheus metrics (no token required).
- `GET /.well-known/oauth-protected-resource`: (v1.4+) OAuth2 Protected Resource Metadata endpoint as per RFC 9728, used for automatic discovery of scope requirements by MCP clients.

```

--------------------------------

### Show Help for CLI Tools

Source: https://www.futuapi.com/guide/cli

Run the --help flag on futu-opend, futu-mcp, or futucli to view their available command-line options.

```bash
futu-opend --help
futu-mcp --help
futucli --help
```

--------------------------------

### Get Delay Statistics (GET)

Source: https://www.futuapi.com/reference/rest-api

Retrieves delay statistics for API requests. No authentication is required.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/delay-statistics
```

--------------------------------

### gRPC Request Method Example (Go)

Source: https://www.futuapi.com/guide/grpc

Illustrates how to use the Go client to connect to the FutuOpenD gRPC service and invoke the Request method, including setting up context with authorization metadata.

```APIDOC
```go
conn, _ := grpc.Dial("localhost:33333", grpc.WithInsecure())
client := futu.NewFutuOpenDClient(conn)

md := metadata.Pairs("authorization", "Bearer fc_xxxx...")
ctx := metadata.NewOutgoingContext(context.Background(), md)

resp, _ := client.Request(ctx, &futu.FutuRequest{
    ProtoId: 1002,
})

```
```

--------------------------------

### Get Subscription Info (GET)

Source: https://www.futuapi.com/reference/rest-api

Retrieves detailed subscription information. Requires 'qot:read' scope.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/sub-info
```

--------------------------------

### Configure futu-opend gateway with keys

Source: https://www.futuapi.com/tutorials/api-key-setup

Start the futu-opend gateway, specifying login credentials and the paths to the keys.json file for REST, gRPC, and WebSocket interfaces. Audit logging is also enabled.

```bash
./futu-opend \
  --login-account 12345678 --login-pwd 'your_pwd' \
  --rest-port 22222 --rest-keys-file ~/.config/futu/keys.json \
  --grpc-port 33333 --grpc-keys-file ~/.config/futu/keys.json \
  --ws-keys-file ~/.config/futu/keys.json \
  --audit-log /var/log/futu-audit.jsonl

```

--------------------------------

### Restricted Simulated Trading KeyRecord Example

Source: https://www.futuapi.com/guide/keys-json

Example of a KeyRecord configured for simulated trading with specific market, symbol, and order limits.

```json
{
  "id": "sim-bot",
  "hash": "c4d5...",
  "scopes": ["qot:read", "acc:read", "trade:simulate"],
  "limits": {
    "allowed_markets": ["HK"],
    "allowed_symbols": ["HK.00700", "HK.09988"],
    "max_order_value": 100000,
    "max_daily_value": 500000,
    "max_orders_per_minute": 3,
    "hours_window": "09:30-16:00",
    "allowed_trd_sides": ["SELL"]
  },
  "allowed_machines": ["fp_bot_host_abc123"],
  "created_at": "2026-04-15T10:00:00Z",
  "expires_at": "2026-05-15T10:00:00Z",
  "note": "simulate 卖出止盈 bot"
}

```

--------------------------------

### Start FUTU-OpenD-rs Gateway

Source: https://www.futuapi.com/

Launch the FUTU-OpenD-rs gateway, specifying your Futu account credentials and the desired REST API port. Logs will indicate successful connection.

```bash
futu-opend \
  --login-account 你的富途账号 \
  --login-pwd 你的密码 \
  --rest-port 22222

```

--------------------------------

### Prometheus Metrics Examples

Source: https://www.futuapi.com/guide/observability

Examples of Prometheus counter metrics exposed by Futu API. These metrics provide aggregated data for monitoring and alerting.

```prometheus
# HELP futu_auth_events_total Auth / trade events by iface, outcome, key_id
# TYPE futu_auth_events_total counter
futu_auth_events_total{iface="rest",outcome="allow",key_id="bot_a"} 1234

# HELP futu_auth_limit_rejects_total Limit-check rejects by iface, key_id, reason
# TYPE futu_auth_limit_rejects_total counter
futu_auth_limit_rejects_total{iface="grpc",key_id="bot_b",reason="rate"} 7

# HELP futu_ws_filtered_pushes_total Pushes filtered out for client lacking scope
# TYPE futu_ws_filtered_pushes_total counter
futu_ws_filtered_pushes_total{required_scope="trade",key_id="bot_c"} 42


```

--------------------------------

### Start Futu MCP HTTP Server

Source: https://www.futuapi.com/tutorials/mcp-integration

Launch the Futu MCP as an HTTP server for multi-LLM access. Configure gateway, keys file, listening address, and audit logging.

```bash
# 在服务端启一个 HTTP MCP server
./futu-mcp --gateway 127.0.0.1:11111 \
           --keys-file /etc/futu/keys.json \
           --http-listen 0.0.0.0:38765 \
           --audit-log /var/log/futu-mcp-audit.jsonl

```

--------------------------------

### Copy New Binary and Restart Services

Source: https://www.futuapi.com/tutorials/deploy-production

Steps to upgrade Futu OpenD by replacing the binary and restarting the services.

```bash
# 新版 binary 覆盖到 /usr/local/bin（同名）
sudo cp futu-opend-new /usr/local/bin/futu-opend

# 重启
sudo systemctl restart futu-opend
sudo systemctl restart futu-mcp

```

--------------------------------

### Get Delay Statistics (POST)

Source: https://www.futuapi.com/reference/rest-api

Submits a request to get delay statistics, allowing for specific type lists and push stages. No authentication is required.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"type_list":[1],"qot_push_stage":1}' \
  http://127.0.0.1:22499/api/delay-statistics
```

--------------------------------

### gRPC Request Method Example (Python)

Source: https://www.futuapi.com/guide/grpc

Provides a Python code snippet demonstrating how to establish a gRPC connection and make a Request to the FutuOpenD service, including authentication.

```APIDOC
```python
import grpc
from futu_pb2 import FutuRequest
from futu_pb2_grpc import FutuOpenDStub

creds = grpc.metadata_call_credentials(
    lambda ctx, cb: cb((("authorization", "Bearer fc_xxxx..."),), None)
)
channel = grpc.secure_channel("localhost:33333", grpc.ssl_channel_credentials())
stub = FutuOpenDStub(channel)

# Pack proto_id=3004 (QOT_GET_BASIC_QOT) body
body = build_get_basic_qot_request(code="00700")  # protobuf encode
resp = stub.Request(FutuRequest(proto_id=3004, body=body))

```
```

--------------------------------

### Run Baseline Benchmark

Source: https://www.futuapi.com/guide/performance

Run the initial benchmark to establish a baseline performance metric for the futu-auth crate. This is useful for future comparisons.

```bash
cargo bench -p futu-auth -- --save-baseline v1.3
```

--------------------------------

### gRPC SubscribePush Method Example (grpcurl)

Source: https://www.futuapi.com/guide/grpc

Shows how to use grpcurl to subscribe to push events from the FutuOpenD service, including the necessary authorization header.

```APIDOC
## Streaming Push

```bash
grpcurl -plaintext \
  -H 'authorization: Bearer fc_xxxx...' \
  -d '{}' \
  localhost:33333 futu.service.FutuOpenD/SubscribePush

```

Each `PushEvent` contains `event_type` (`quote` / `notify` / `trade`) and `body` (protobuf).
**v1.1+**: Server filters pushes by client key's scope — keys with `qot:read`-only won't receive `trade` events (trading returns). Filtered events are counted by `futu_ws_filtered_pushes_total`.
```

--------------------------------

### Running Multiple Instances (Futunn + Moomoo)

Source: https://www.futuapi.com/tutorials/cheatsheet

Run FutuOpenD for both Futunn and Moomoo accounts simultaneously. Ensure distinct ports for each instance to avoid conflicts, especially when using `futucli`.

```bash
# Instance A: Futunn account (default ports)
./futu-opend --login-account 12345678 --login-pwd Y1 \
  --rest-port 22222 --grpc-port 33333 &

# Instance B: moomoo account (shifted ports)
./futu-opend --login-account '+86-13900000000' --login-pwd Y2 --platform moomoo \
  --port 11112 --rest-port 22223 --grpc-port 33334 &

# Client access:
# curl http://localhost:22222/api/accounts   # Futunn
# curl http://localhost:22223/api/accounts   # moomoo
```

--------------------------------

### GET /api/accounts

Source: https://www.futuapi.com/reference/rest-api

Retrieves a list of trading accounts.

```APIDOC
## GET /api/accounts

### Description
Retrieves a list of trading accounts.

### Method
GET

### Endpoint
/api/accounts

### Parameters
(No specific parameters mentioned for this GET request, refer to proto definition for details)

### Request Example
```
curl -H 'Authorization: Bearer $FUTU_API_KEY' http://127.0.0.1:22499/api/accounts
```

### Response
#### Success Response (200)
- **Details**: See proto definition. Fields are snake_case, supporting v1.4.83+ alias and v1.4.84+ enum int/string dual-mode.

#### Response Example
(Response structure depends on proto definition)
```

--------------------------------

### Get User Info

Source: https://www.futuapi.com/reference/rest-api

Fetches user-specific information. No authentication is required.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/user-info
```

--------------------------------

### Verify FutuOpenD Gateway Startup

Source: https://www.futuapi.com/quick-start

Successful startup of the FutuOpenD gateway is indicated by log messages showing the REST and gRPC services are running.

```bash
INFO  addr=0.0.0.0:11111 starting FutuOpenD Rust Gateway
INFO  listen_addr=0.0.0.0:22222 REST API 服务已启动 (WebSocket: /ws)
INFO  addr=0.0.0.0:33333 gRPC 服务已启动
```

--------------------------------

### Get Reference

Source: https://www.futuapi.com/reference/rest-api

Retrieves reference data for a security, such as related warrants or futures.

```APIDOC
## POST /api/get-reference

### Description
Retrieves reference data for a security, such as related warrants or futures.

### Method
POST

### Endpoint
/api/get-reference

### Parameters
#### Request Body
- **security** or **symbol** (object/string) - Required - The security symbol (e.g., "HK.00700")
- **reference_type** (int) - Required - Type of reference data: `1`=Warrant, `2`=Future

### Request Example
```json
{
  "symbol": "HK.00700",
  "reference_type": 1
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Start Futu OpenD Gateway

Source: https://www.futuapi.com/cases/llm-analyst

Launches the Futu OpenD gateway service. This command requires login credentials and specifies the REST API port and the file containing API keys.

```bash
# 网关
futu-opend \
  --login-account 12345678 --login-pwd "$FUTU_PWD" \
  --rest-port 22222 \
  --rest-keys-file ~/.config/futu/keys.json

```

--------------------------------

### Get IPO List

Source: https://www.futuapi.com/reference/rest-api

Retrieves a list of IPOs. Supports filtering by market.

```APIDOC
## POST /api/ipo-list

### Description
Retrieves a list of IPOs. Supports filtering by market.

### Method
POST

### Endpoint
/api/ipo-list

### Parameters
#### Request Body
- **market** (int) - Required - `QotMarket`: `1`=HK / `11`=US / `21`=CN_SH / `22`=CN_SZ (沪深合并返 A 股)

### Request Example
```json
{
  "c2s": {
    "market": 1
  }
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Start Core WS Server

Source: https://www.futuapi.com/guide/websocket

Launch the Futu OpenD server with the core WS endpoint enabled. This port is used for full-duplex communication and is compatible with Futu API SDKs.

```bash
# 启动时开这个端口
./futu-opend --websocket-port 44444 --ws-keys-file keys.json

```

--------------------------------

### GET /api/accounts

Source: https://www.futuapi.com/reference/rest-api

Retrieves a list of trading accounts. Requires `acc:read` scope.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/accounts
```

--------------------------------

### Get Push Subscriber Info

Source: https://www.futuapi.com/reference/rest-api

Retrieves information about push subscribers. No authentication is required.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/push-subscriber-info
```

--------------------------------

### Create futu User and Directories

Source: https://www.futuapi.com/tutorials/deploy-production

Creates a dedicated system user 'futu' and necessary directories for logs and data. Ensures proper ownership and permissions for security.

```bash
sudo useradd --system --shell /usr/sbin/nologin futu
sudo install -d -o futu -g futu -m 0750 /var/lib/futu /var/log/futu
sudo install -d -o root -g futu -m 0750 /etc/futu-opend
```

--------------------------------

### Get Global State

Source: https://www.futuapi.com/reference/rest-api

Fetches the global state of the FutuOpenD service. No authentication is required.

```curl
curl -H 'Authorization: Bearer $FUTU_API_KEY' \
  http://127.0.0.1:22499/api/global-state
```

--------------------------------

### Start MCP with stdio Transport

Source: https://www.futuapi.com/guide/mcp

Configure and launch the futu-mcp server for stdio transport. Ensure FUTU_MCP_API_KEY is set and specify the gateway and keys file.

```bash
export FUTU_MCP_API_KEY="fc_xxxx..."
./futu-mcp \
  --gateway 127.0.0.1:11111 \
  --keys-file ~/.config/futu/keys.json
```

--------------------------------

### futu_get_kline

Source: https://www.futuapi.com/reference/mcp-tools

Get historical K-line (OHLCV). Supports day/week/month/quarter/year plus ⅓/5/15/30/60 minute bars.

```APIDOC
## futu_get_kline

### Description
Get historical K-line (OHLCV). Supports day/week/month/quarter/year plus ⅓/5/15/30/60 minute bars.

### Method
MCP JSON-RPC `tools/call`

### Endpoint
tools/call

### Parameters
#### Arguments
- **symbol** (string) - Required - Security symbol (MARKET.CODE); alias: code / stock
- **kl_type** (string) - Optional - K-line type: day|week|month|quarter|year|1min|3min|5min|15min|30min|60min (alias: ktype / k_type / kl_type for SDK compat)
- **count** (i32) - Optional - Number of candles to return (default 100); alias: num / max_count / req_count
- **begin** (string) - Optional - Start date yyyy-MM-dd (optional; default computed from count); alias: begin_time / from
- **end** (string) - Optional - End date yyyy-MM-dd (optional; default today); alias: end_time / to

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "futu_get_kline",
    "arguments": {
      "symbol": "HK.00700",
      "kl_type": "day"
    }
  }
}
```

### Response
#### Success Response
Returns a JSON text consistent with the corresponding REST endpoint / Python SDK return structure. Failure results in MCP `CallToolResult.is_error=true` with content `{"error": "...", "status": "error"}`.
```

--------------------------------

### Python gRPC Client: Single Request Example

Source: https://www.futuapi.com/reference/grpc-api

Demonstrates how to make a single gRPC request using the FutuOpenDStub in Python. Ensure you have the necessary protobuf generated files.

```python
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)

```

--------------------------------

### Get Future Info

Source: https://www.futuapi.com/reference/rest-api

Fetches information about future contracts. Requires a list of security symbols.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"securityList":[{"market":1,"code":"HSImain"}]}}' \
  http://127.0.0.1:22499/api/future-info

```

--------------------------------

### Get Bond Trade Reminder

Source: https://www.futuapi.com/reference/rest-api

Retrieves bond trade reminders. Requires `acc:read` scope.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"c2s":{"header":{"acc_id":123456,"trd_env":1}}}' \
  http://127.0.0.1:22499/api/bond-trade-reminder
```

--------------------------------

### Get Suspended Stocks

Source: https://www.futuapi.com/reference/rest-api

Fetches information about suspended stocks. Requires a list of symbols and a time range.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"symbols":["HK.00700"],"begin_time":"2026-01-01","end_time":"2026-04-01"}' \
  http://127.0.0.1:22499/api/suspend

```

--------------------------------

### Get Plate Set

Source: https://www.futuapi.com/reference/rest-api

Retrieves information about a plate set. Requires market and plate set type.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"market":1,"plate_set_type":0}' \
  http://127.0.0.1:22499/api/plate-set

```

--------------------------------

### Go: gRPC Request with Metadata

Source: https://www.futuapi.com/guide/grpc

Example of making a gRPC request in Go, including setting up outgoing context with metadata for authorization.

```go
conn, _ := grpc.Dial("localhost:33333", grpc.WithInsecure())
client := futu.NewFutuOpenDClient(conn)

md := metadata.Pairs("authorization", "Bearer fc_xxxx...")
ctx := metadata.NewOutgoingContext(context.Background(), md)

resp, _ := client.Request(ctx, &futu.FutuRequest{
    ProtoId: 1002,
})


```

--------------------------------

### Get Plate Securities

Source: https://www.futuapi.com/reference/rest-api

Fetches securities belonging to a specific plate. Requires market and plate code.

```curl
curl -X POST -H 'Authorization: Bearer $FUTU_API_KEY' -H 'Content-Type: application/json' \
  -d '{"plate":{"market":1,"code":"BK1001"}}' \
  http://127.0.0.1:22499/api/plate-security

```