# Others

# Q1:Experience exchange channels

  1. E-mail: openapi@moomoo.com
  • When feeding back questions through the mailbox channel, we recommend you provide your Futu ID, the time when the error occurred, a detailed description of the problem as well as relevant screenshhots. Transaction issues (e.g., place_order failed) require the order number to facilitate location and confirmation of problems.
  1. QQ Group: 108534288(OpenAPI I), 229850364(OpenAPI Ⅱ),567665692(OpenAPI Ⅲ) qq_group

    Note: To be validated, you should answer the questions about OpenAPI correctly, which can be found in the API Doc.

  2. Team support
    Investment teams or institutional clients can contact James (QQ: 522904020), providing you with a dedicated team to assist in solving technical challenges and achieving your specific product needs.

# Q2: Is there more complete strategy examples for reference?

A:

  • Python strategy examples are in the /futu/examples/ folder. You can find the path of Python API by executing the following command:
    import futu
    print(futu.__file__)
    
    1
    2
  • The C# strategy examples are in the /FTAPI4NET/Sample/ folder
  • The Java strategy examples are in the /FTAPI4J/sample/ folder
  • The C++ strategy examples are under the /FTAPI4CPP/Sample/ folder
  • The JavaScript strategy examples are in the /FTAPI4JS/sample/ folder

# Q3: Import error when using python API

A:

First Scene:
I have already installed futu-api, but still get error: No module named 'futu'?
It is possible that the interpreter your IDE currently uses is not the interpreter of the futu-api module you installed. In other words, your may have more than two Python environments installed on your computer. You can do the following 2 steps:

  1. Run the codes below to get the path of the current interpreter:
import sys
print(sys.executable)
1
2

Example diagram:
No module named 'futu'

  1. Run $ D:\software\anaconda3\python.exe -m pip install futu-api in command line (The first half of the command comes from the result of step 1). This will install a futu-api module in the current interpreter.

# Q4: Import successful, but you still cannot call the relevant interface.

A: Usually in this case, you need to check if the ‘futu’ that was successfully imported is a correct Futu API.

First Scene: There may be a file with the same name as 'futu'.

  1. The current file name is futu.py
  2. There is another file named futu.py under the path of the current file.
  3. There is a folder named /futu under the path of the current file.

Therefore, we strongly recommend that you do not name files / folders / projects as futu.

Second Scene: A third-party library called 'futu' was installed by mistake.

The correct name of the Futu API library is futu-api, not 'futu'.

If you have installed a third-party library named 'futu', please uninstall it and install futu-api.

Take PyCharm as an example: Check the installation of libraries.

settings
futuku

# Q5: Protocol Encryption-Related

A:

# Overview

To ensure privacy and confidentiality, you can use the asymmetric encryption algorithm RSA to encrypt the request and return between Strategy Scripts (Futu API) and OpenD.
If Strategy Scripts (Futu API) is on the same computer as OpenD, it is usually not necessary to encrypt.

# Protocol Encryption Process

You can try to solve this problem with the following steps:

  1. Generate the key file automatically through a third-party web platform.
    • To be specific: Search 'Online RSA Key Generator' on Baidu or Google. Set Key Format as PKCS#1. Set Key Length as 1024 bit. No password required. Then click the bottom 'Generate key pair' ui-config
  2. Copy and paste the private key into a text file. Save it to a specified path of the computer which OpenD is located in.
  3. Specify the path of the RSA private key file on the computer which OpenD is located in. The path is the specified path mentioned in Step 2.
    • Method 1: Specify the path mentioned in Step 2 through 'Encryption Private Key' in Visualization OpenD. As shown below: ui-config
    • Method 2: Specify the path mentioned in Step 2 through the code rsa_private_key in Command Line OpenD. As shown below: ui-config
  4. Save the text file in step 2 to a specified path of the computer which Strategy Scripts (Futu API) are located in, and set the path of private key in Strategy Scripts.
  5. Enable protocol encryption. There are two ways to enable protocol encryption.
    • Method 1: Encrypt the context independently (general). You can set encryption through the parameter is_encrypt when creating and initializing the connection in Quote Object or Transaction Objects.
    • Method 2: Encrypt the context globally (only Python). You can set encryption through the interface enable_proto_encrypt.

Tips

  • When specifying the path of RSA private key in OpenD or in Strategy Scripts (Futu API), the path needs to be complete and include the file name.
  • It is not necessary to save RSA public key which can be calculated by private key.

# Q6: Why is the DataFrame data I got incomplete?

A: When printing pandas.DataFrame data, if there are too many columns and rows, pandas will collapse the data by default, resulting in an incomplete display.
Therefore, it is not OpenD's fault. You can add the following code in front of your Python script to solve the problem.

import pandas as pd
pd.options.display.max_rows=5000
pd.options.display.max_columns=5000
pd.options.display.width=1000
1
2
3
4

# Q7: How to solve the problem that "Cannot open libFTAPIChannel.dylib" through C++ API on Mac?

A: Execute the following command in the directory where the file "libFTAPIChannel.dylib" is stored: $ xattr -r -d com.apple.quarantine libFTAPIChannel.dylib.

# Q8: For Python users, why do large log files continue to be generated under the log folder, after the log level is set to no in the OpenD configuration file?

A:The log_level parameter in OpenD parameter configuration is only used to control the logs generated by OpenD. Python API also generates logs by default.
If you do not like it, you can add the following codes to your Python script:

logger.file_level = logging.FATAL  # Used to stop Python API log files generating
logger.console_level = logging.FATAL  # Used to stop printing Python log in running console
1
2

# Q9: For versions 5.4 and above, the library name and configuration method of Java API have been changed.

A:

  • If you are a user of Java API 5.3 and below, please note the following changes when updating the version.
    Changes to the configuration process:

    1. Download Futu API from Futubull official website.
    2. Decompress the downloaded file. /FTAPI4J is the directory of Java API. Add /lib/futu-api-.x.y.z.jar file to your project settings. To establish a futu-api project, please refer to here.

    Changes to the directory:

    1. For the Java version of Futu API, the library name is changed from ftapi4j.jar to futu-api-x.y.z.jar, where "x.y.z" represents the version number.
    2. For the third-party library, the dependencies of /lib/jna.jar and /lib/jna-platform.jar are removed, and the dependencies of /lib/bcprov-jdk15on-1.68.jar and /lib/bcpkix-jdk15on-1.68.jar are added.
    +---ftapi4j                      FTAPI4J source code. If the JDK version used is not compatible, you can use the project to recompile the ftapi.jar.
    +---lib                          The folder with common libraries
    |    futu-api-x.y.z.jar          Java version of Futu API
    |    bcprov-jdk15on-1.68.jar     Third-party library, for encryption and decryption
    |    bcpkix-jdk15on-1.68.jar     Third-party library, for encryption and decryption
    |    protobuf-java-3.5.1.jar     Third-party library, for parsing protobuf data
    +---sample                       Sample project
    +---resources                    The default generated directory of the maven project
    
    1
    2
    3
    4
    5
    6
    7
    8
  • If you are a new user to the Futu API, we provide a more convenient way to configure Java API via maven repository for you. About the configuration process, please refer to here.

# Q10: For Python users, when using pyinstaller to package scripts that need to run api, an error is reported: Common_pb2 module cannot be found.

A: You can try to solve this problem with the following steps.
Step 1. Suppose you need to package main.py. Using a command-line statement and run the statement: pyinstaller path\main.py, without the "- F" parameter.

pyinstaller path\main.py
1

After main.py is packaged, the /main folder will be created in the /dist directory where it is located. main.exe is in this folder.
dist

Step 2. Run the following code to find the installation path of futu-api: /path/futu.

import futu
print(futu.__file__)
1
2

Results:

C:\Users\ceciliali\Anaconda3\lib\site-packages\futu\__init__.py
1

pathfutu

Step 3. Copy all the files in the /common/pb to /main.

Step 4. Create a folder in the /main and name it futu. Copy the /path/futu/VERSION.txt file to /main/futu.
main_futu
Step 5. Try running the statement pyinstaller main.py again.

# Q11: Why the interface result is success, but the return did not behave as expected?

A:

  • A successful interface result means that server has successfully received and responded to your request, but the return may not behave as your expected.

    Example: If you call the subscribe during non-trading hours, your request can be responded successfully, but the exchange will not update the ticker data during this period. So you will temporarily not receive real-time data until trading hours.

  • The interface result (definition: Interface Result) can be viewed from the field returned. A field of 0 means the interface result success, a non-zero means the interface result failed.

    For python user, the following two code statements are equivalent:

    if ret_code == RET_OK:
    
    1
    if ret_code == 0:
    
    1

# Q12: WebSocket Related

# Overview

In OpenAPI, WebSocket is mainly used in the following two aspects:

  • In Visualization OpenD, WebSocket is used to communicate between the UI interface and the underlying Command Line OpenD.
  • The communication between JavaScript API and OpenD uses WebSocket.

WebSocket-struct

  • When WebSocket starts, Command Line OpenD establishes a Socket connection (TCP) with the FTWebSocket transit service. This connection uses the default listening address and API protocol listening port.
  • At the same time, JavaScript API will establish a WebSocket connection (HTTP) with the FTWebSocket transit service. This connection will use the WebSocket listening address and WebSocket port.

# Usage

To ensure the security of your account, when WebSocket listens non-local requests, we strongly recommend that you enable SSL and configure the WebSocket authentication key

SSL is enabled by configuring the WebSocket certificate and the WebSocket private key. Command Line OpenD can set the file path by configuring OpenD.xml or configuring command line parameters. Visualization OpenD clicks the "more" drop-down menu to see the confifuration item.

ui-more-config

Tips

If the certificate is self-signed, you need to install the certificate on the machine where the JavaScript API is called, or set not to verify the certificate.

# Generate Self-signed Certificate

It is not convenient to expand the details of self-signed certificate generation in this document, please check it yourself. Simple and available build steps are provided here:

  1. Install openssl.
  2. Modify openssl.cnf and add the IP address or domain name under the alt_names node on the machine where OpenD locates.
    For example: IP.2 = xxx.xxx.xxx.xxx, DNS.2 = www.xxx.com
  3. Generate private key and certificate (PEM)。

The certificate generation parameters are as follows
openssl req -x509 -newkey rsa:2048 -out futu.cer -outform PEM -keyout futu.key -days 10000 -verbose -config openssl.cnf -nodes -sha256 -subj "/CN=Futu CA" -reqexts v3_req -extensions v3_req

Tips

  • openssl.cnf needs to be placed under the system path, or an absolute path needs to be specified in the build parameters.
  • Note that while generating a private key, you need to specify that the password is not set (-notes).

Attach the local self-signed certificate and the configuration file that generates the certificate for testing:

# Q13: Where are the quote servers and the trade servers of OpenAPI?

A:

  • Quote:
Futu ID Quote Server Location
Futubull ID Tencent Cloud Guangzhou and Hong Kong
moomoo ID Tencent Cloud Virginia, USA and Singapore
  • Trade:
Securities Firm Trade Server Location
FUTU HK Tencent Cloud Hong Kong
Moomoo US Tencent Cloud Virginia, USA
Moomoo SG Tencent Cloud Singapore
Moomoo AU AWS Cloud Sydney

# Q14: How to build C++ API?

A: futu-api c++ SDK is supported on Windows/MacOS/Linux. Pre-built libs are provided for the common build environment on each platform:

OS Building Environment
Windows Visual Studio 2013
Centos 7 g++ 4.8.5
Ubuntu 16.04 g++ 5.4.0
MacOS XCode 11

If different compiler version is used, or different protobuf version is used, FTAPI and protobuf may be re-built. FTAPI source directory layout is:

FTAPI directory structure:
+---Bin                               Libs for common build environment
+---Include                           Public headers, source files generated from proto files
+---Sample                            Sample project
\---Src
    +---FTAPI                         FTAPI source
    +---protobuf-all-3.5.1.tar.gz     protobuf source
1
2
3
4
5
6
7

# Build steps:

  1. Build protobuf to generate libprotobuf static lib and protoc executable.
  2. Generated C++ source files from proto files.
  3. Build FTAPI to generate libFTAPI static lib

# Step1: Build protobuf:

  • Windows:
    • Install CMake
    • Open Visual Studio command prompt, change directory to protobuf/cmake
    • Run:cmake -G "Visual Studio 12 2013" -DCMAKE_INSTALL_PREFIX=install -Dprotobuf_BUILD_TESTS=OFF  This will generate Visual Studio 2013 solution file. Change -G parameter for other Visual Studio versions.
    • Open Visual Studio solution file, set platform toolset to v120_xp, then build.
  • Linux(Refer to protobuf/src/README)
    • Run ./autogen.sh
    • Run CXXFLAGS="-std=gnu++11" ./configure --disable-shared
    • Run make
    • Put generated libprotobuf.a in Bin/Linux
  • MacOS(Refer to protobuf/src/README)
    • Install dependencies with brew:autoconf automake libtool
    • Run ./configure CC=clang CXX="clang++ -std=gnu++11 -stdlib=libc++" --disable-shared

# Step2: Generate C++ sources from proto files

  • Use protoc to convert protofiles under Include/Proto to C++ source files. For example, the following command converts Common.proto to Common.pb.h and Common.pb.cc:
    • protoc -I="path-to-FTAPI/Include/Proto" --cpp_out="." path-to-FTAPI/Include/Proto/Common.proto
  • Put the generated .h and .cc files in Include/Proto

# Step3: Build FTAPI

  • Windows:Create Visual Studio C++ static lib project,add source files under Src/FTAPI and Include,and set platform toolset to v120_xp.
  • Mac:Create XCode C++ static lib project,add source files under Src/FTAPI and Include
  • Linux:Use cmake to build FTAPI static lib, run following command under path-to-FTAPI/Src:
    • cmake -DTARGET_OS=Linux

# Q15: The Guide for Universal Account Upgrade

# 1. Universal Account Upgrade

The universal account allows trading securities, futures, and forex across various markets using multiple currencies within one account. Upgrading one or multiple single-market accounts to a universal account involves migrating under your old account. This includes:

  • Creating a universal account
  • Transferring assets from your existing single-market account to the universal account
  • Closing the single-market account

# 2. OpenD Version Upgrade

We are scheduled to upgrade your accounts to universal accounts on September 14th and 15th. Please check your OpenD and API versions in advance.

  • Version 7.01 and below
    Due to the outdated versions, OpenD will discontinue service on September 14th, during which you will be logged out of OpenD automatically. We recommend upgrading your OpenD and API to the latest version before September 14th, and stopping any live trading strategies over the weekend of September 14th to 15th.

  • Version 7.02 to 8.2
    Due to the older versions, OpenD no longer supports universal accounts. We recommend upgrading your OpenD and API to the latest version before September 14th, and stopping any live trading strategies over the weekend of September 14th to 15th.

  • Version 8.3 and above
    You can use these versions normally. However, we also recommend not running any live trading strategies over the weekend of September 14th to 15th.

After upgrading, your assets will be transferred to the new universal account, causing strategies targeting the old account to malfunction. We recommend conducting necessary checks and tests before live trading, to ensure everything is set up properly.

# 3. Changes in OpenAPI after the OpenD upgrade

  • Python API will no longer support creating transaction objects with OpenHKTradeContext, OpenUSTradeContext, OpenHKCCTradeContext, and OpenCNTradeContext. Please refer to the Create the connection, and use OpenSecTradeContext instead.

  • For non-Python API users, when using the Trd_GetAccList, please set the needGeneralSecAccount to true in order to get Universal account information.

  • Add Account Status
    When using the Get the List of Trading Accounts, the results will now include an acc_status field.

    • The universal accounts are marked as ACTIVE.
    • The old single-market accounts are marked as DISABLED.
  • Changes in Trading API: Place Orders, Modify or Cancel Orders, Query the Maximum Quantity that Can be Bought or Sold

    • Executing transactions and querying purchasing power can only be allowed via the acc_id or acc_index of ACTIVE accounts.
    • Using the acc_id or acc_index of DISABLED accounts will cause errors.
    • Python API:please specify the acc_id as the upgraded universal account.
    • Non-Python API:in the TrdHeader, please specify the accID as the upgraded universal account.

# 4. Need help?

  • Team Support
    If you encounter any issues during the upgrade process or while using the universal account, you can contact our technical/product teams through official channels.

  • Stay Focused
    We will continue to publish the latest notifications and assistance information through Futu API Doc, emails, APP messages, QQ, etc. Please pay attention to official updates.