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.

2. QQ Group: 108534288(OpenAPI I), 229850364(OpenAPI Ⅱ)，567665692（OpenAPI Ⅲ）

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

3. 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.

1. E-mail: openapi@moomoo.com

• When feeding back questions through the mailbox channel, we recommend you provide your moomoo 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.

2. QQ Group: 108534288(OpenAPI I), 229850364(OpenAPI Ⅱ)，567665692（OpenAPI Ⅲ）

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

3. 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__)
  

• 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

A:

• Python strategy examples are in the /moomoo/examples/ folder. You can find the path of Python API by executing the following command:

  import moomoo
  print(moomoo.__file__)
  

• The C# strategy examples are in the /MMAPI4NET/Sample/ folder
• The Java strategy examples are in the /MMAPI4J/sample/ folder
• The C++ strategy examples are under the /MMAPI4CPP/Sample/ folder
• The JavaScript strategy examples are in the /MMAPI4JS/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)

Example diagram:

2. 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.

First Scene:
I have already installed moomoo-api, but still get error: No module named 'moomoo'?
It is possible that the interpreter your IDE currently uses is not the interpreter of the moomoo-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)

Example diagram:

2. Run $ D:\software\anaconda3\python.exe -m pip install moomoo-api in command line (The first half of the command comes from the result of step 1). This will install a moomoo-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.

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

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

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

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

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

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

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

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

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 Futu OpenD.
If Strategy Scripts (Futu API) is on the same computer as Futu 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'
2. Copy and paste the private key into a text file. Save it to a specified path of the computer which Futu OpenD is located in.
3. Specify the path of the RSA private key file on the computer which Futu 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 Futu OpenD. As shown below:
   • Method 2: Specify the path mentioned in Step 2 through the code rsa_private_key in Command Line Futu OpenD. As shown below:
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 Futu 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.

A:

Overview

To ensure privacy and confidentiality, you can use the asymmetric encryption algorithm RSA to encrypt the request and return between Strategy Scripts (moomoo API) and moomoo OpenD.
If Strategy Scripts (moomoo API) is on the same computer as moomoo 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'
2. Copy and paste the private key into a text file. Save it to a specified path of the computer which moomoo OpenD is located in.
3. Specify the path of the RSA private key file on the computer which moomoo 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 moomoo OpenD. As shown below:
   • Method 2: Specify the path mentioned in Step 2 through the code rsa_private_key in Command Line moomoo OpenD. As shown below:
4. Save the text file in step 2 to a specified path of the computer which Strategy Scripts (moomoo 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 moomoo OpenD or in Strategy Scripts (moomoo 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

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.

A: Execute the following command in the directory where the file "libFTAPIChannel.dylib" is stored: $ xattr -r -d com.apple.quarantine libAPIChannel.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

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
  

• 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.

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 moomoo API from moomoo official website.
  2. Decompress the downloaded file. /MMAPI4J is the directory of Java API. Add /lib/moomoo-api-.x.y.z.jar file to your project settings. To establish a moomoo-api project, please refer to here.

  Changes to the directory:

  1. For the Java version of moomoo API, the library name is changed from ftapi4j.jar to moomoo-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.

  +---mmapi4j                      MMAPI4J source code. If the JDK version used is not compatible, you can use the project to recompile the mmapi.jar.
  +---lib                          The folder with common libraries
  |    moomoo-api-x.y.z.jar          Java version of moomoo 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
  

• If you are a new user to the moomoo 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

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.

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

import futu
print(futu.__file__)

Results:

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

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.

Step 5. Try running the statement pyinstaller main.py again.

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

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.

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

import moomoo
print(moomoo.__file__)

Results:

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

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

Step 4. Create a folder in the /main and name it moomoo. Copy the /path/moomoo/VERSION.txt file to /main/moomoo.

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:
  

  if ret_code == 0:
  

Q12: WebSocket Related

Overview

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

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

• When WebSocket starts, Command Line Futu 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 Futu OpenD can set the file path by configuring OpenD.xml or configuring command line parameters. Visualization Futu OpenD clicks the "more" drop-down menu to see the confifuration item.

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 Futu 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:

• openssl.cnf
• futu.cer
• futu.key

Overview

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

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

• When WebSocket starts, Command Line moomoo OpenD establishes a Socket connection (TCP) with the MMWebSocket 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 MMWebSocket 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 moomoo OpenD can set the file path by configuring OpenD.xml or configuring command line parameters. Visualization moomoo OpenD clicks the "more" drop-down menu to see the confifuration item.

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 moomoo 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 moomoo.cer -outform PEM -keyout moomoo.key -days 10000 -verbose -config openssl.cnf -nodes -sha256 -subj "/CN=moomoo 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:

• openssl.cnf
• moomoo.cer
• moomoo.key

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 Financial Inc.	Tencent Cloud Virginia, USA
Moomoo Financial Singapore Pte. Ltd.	Tencent Cloud Singapore

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

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

A: moomoo-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, MMAPI and protobuf may be re-built. MMAPI source directory layout is:

MMAPI directory structure：
+---Bin                               Libs for common build environment
+---Include                           Public headers, source files generated from proto files
+---Sample                            Sample project
\---Src
    +---MMAPI                         MMAPI source
    +---protobuf-all-3.5.1.tar.gz     protobuf source

Build steps：

1. Build protobuf to generate libprotobuf static lib and protoc executable.
2. Generated C++ source files from proto files.
3. Build MMAPI to generate libMMAPI 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-MMAPI/Include/Proto" --cpp_out="." path-to-MMAPI/Include/Proto/Common.proto
• Put the generated .h and .cc files in Include/Proto

Step3: Build MMAPI

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