Preparation

Environment Requirements

Operating System Requirements:
- Windows
- MacOS
- Linux
- Solaris
Programming Language Version Requirements: Java JDK 1.7 (64-bit) and above.

Installing Java Development Kit

For best support and to reduce compatibility issues, we recommend installing JDK 1.8+.

Install the latest version of JDK:

Visit the Oracle official website download page: https://www.oracle.com/java/technologies/downloads/;
Note that you need to select the corresponding installation package according to your operating system, download the installation package and install it following the prompts.

Getting Tiger Open API Java SDK

Method 1: Using Maven Repository (Recommended)

We recommend that you obtain the SDK by adding Maven dependencies. Java developers can get the Java SDK through Maven repository. The Maven repository is updated periodically. The current latest version is as follows:

Please add the following code to your pom.xml file:

<dependency>
  <groupId>io.github.tigerbrokers</groupId>
  <artifactId>openapi-java-sdk</artifactId>
  <version>2.4.3</version>
</dependency>

If the SDK cannot be downloaded, please try adding the following repository to your local project's pom.xml file:

<repositories>
  <repository>
    <id>sonatype-public</id>
    <name>sonatype-public</name>
    <url>https://oss.sonatype.org/content/groups/public/</url>
  </repository>
</repositories>

Method 2: Github/Gitee Code Repository

The source code of the SDK project is published on both Github and Gitee code repositories.

Github address: https://github.com/tigerbrokers/openapi-java-sdk
Gitee address: https:// gitee.com/tigerbrokers/openapi-java-sdk

You can choose to clone or download the source code from the code repository and manually add dependencies.

Installing IDE

We recommend using IntelliJ IDEA as your integrated development environment.

Official download link: https://www.jetbrains.com/idea/download/

For Retail users, Register through Personal Center

Before using the API, please first open permissions. Individual users should visit the API official website to register developer identity. We recommend using Chrome browser to open.

Note: Opening Open API requires opening an account with Tiger and making a deposit, and the developer and user will be required to sign an API authorization agreement.

You will then need to complete the registration of developer information on this page. Please fill in and submit your information.

After successful registration, you can obtain the following information on this page:

tigerId: A unique ID assigned by the open platform to each developer, used to identify a developer. All API interface calls will use tigerId.
account: The user's fund account, which needs to be used when requesting trading-related interfaces. Specifically divided into Global Account, Prime Account, and Paper Account:
- Global Account: Starts with uppercase letter U, such as: U12300123,
- Prime Account: A shorter string of numbers (5 to 10 digits), such as: 51230321,
- Paper Trading Account: 17 digits, such as: 20191106192858300,

After successfully registering developer information, only fund accounts and paper accounts that have been successfully deposited will be returned. If both the user's Global Account and Prime Account have been successfully deposited, both will be returned.

Developer Registration Page: You can register with your mobile phone number and verification code.

Developer Information Page: Tiger ID, live account, paper account, license and other information need to be used in OpenAPI.

Note: You need to save the private key part shown in the image below locally and keep it safe to prevent leakage. If leakage is discovered, please update it in time. The private key will not be saved on the Tiger server, and users need to save it properly before refreshing the page. After the page is refreshed, the private key will automatically disappear. If the private key is not saved properly, you can use the Regenerate button to replace it.

After regenerating, download the tiger_openapi_config.properties file locally. Copy the tiger_openapi_config.properties file to the directory configured by ClientConfig.DEFAULT_CONFIG.configFilePath.

The content format of the tiger_openapi_config.properties file is as follows. The account is the default account, which can be switched between live fund account and paper account.

private_key_pk1=MIICXgIBAAKBgQCodM4fM5cz+tj8SUuxxSbSMFxNHM23hftjAuXr9THweyFtTmA/mxwo9HYEhYjxCgYAJt78xbzw7aiKu+pI45O8il8ns6UL3mT59QlCKu0+FZmF2g54teyqoiol71xcM096D3ss0oJzKGt+btvlBzdcrXM6+pZqbK14ASWGE4uBEQIDAQABAoGAX5iBjFVTngzhbDIQAZ73C9qj1qLc3yPqZ+KyJbgskeLeMlCC8DWOwnMQMjqxXtAoXZexfVKdiT/lIG3JY3m6URzfYwJt5VUD9LeIcyPxuj7Eg2vxlZwJ6slT7DQ6LJCbUe1PUDlKKXYe/wEUNJ3dEJ/eFEhR8vNyFlW8DJj+az0CQQDhQwYUZIcq+9WDcSen5Sm5oS765aMAyWcOdkpokau+fZ/H9NwT0U+jaEHyswZMJBTDJ42iS8HV0MuGdtLJ7JzHAkEAv3Fq1AHHJ1Tyxtf/VWHBRfx304NFlDX87Ji7uyv1t+05ZYVT0U8Q5CUPdBA3QexMBKd1i6BXUH/xOY5aX+UrZwJBAKR7ej79wK0kQh2+TESOUs9W4KUXdNSoO3YV7fM5Gvz3Yepx4xkdZ1dcU3tSObDzT63IfeUaCCmGUnaW4QfMnBUCQQCMOsK6mrbLe7D9sBgK7bkJz73iA+UChG1IzTOuDaxGVpDVaU0VI2pHA1KHfJ1NP44LVrKGXSO4Bo+mzjwqxA3/AkEApA8roUKXtKTqC2rb8hs5AscMpHFUl7ZbVeKX14gAg9QPWxkh8BcB1dljAsrp7irEtq4VezD2Cf40b52Fcx+pvA==
private_key_pk8=MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAKh0zh8zlzP62PxJS7HFJtIwXE0czbeF+2MC5ev1MfB7IW1OYD+bHCj0dgSFiPEKBgAm3vzFvPDtqIq76kjjk7yKXyezpQveZPn1CUIq7T4VmYXaDni17KqiKiXvXFwzT3oPeyzSgnMoa35u2+UHN1ytczr6lmpsrXgBJYYTi4ERAgMBAAECgYBfmIGMVVOeDOFsMhABnvcL2qPWotzfI+pn4rIluCyR4t4yUILwNY7CcxAyOrFe0Chdl7F9Up2JP+UgbcljebpRHN9jAm3lVQP0t4hzI/G6PsSDa/GVnAnqyVPsNDoskJtR7U9QOUopdh7/ARQ0nd0Qn94USFHy83IWVbwMmP5rPQJBAOFDBhRkhyr71YNxJ6flKbmhLvrlowDJZw52SmiRq759n8f03BPRT6NoQfKzBkwkFMMnjaJLwdXQy4Z20snsnMcCQQC/cWrUAccnVPLG1/9VYcFF/HfTg0WUNfzsmLu7K/W37TllhVPRTxDkJQ90EDdB7EwEp3WLoFdQf/E5jlpf5StnAkEApHt6Pv3ArSRCHb5MRI5Sz1bgpRd01Kg7dhXt8zka/Pdh6nHjGR1nV1xTe1I5sPNPrch95RoIKYZSdpbhB8ycFQJBAIw6wrqatst7sP2wGArtuQnPveID5QKEbUjNM64NrEZWkNVpTRUjakcDUod8nU0/jgtWsoZdI7gGj6bOPCrEDf8CQQCkDyuhQpe0pOoLatvyGzkCxwykcVSXtltV4pfXiACD1A9bGSHwFwHV2WMCyunuKsS2rhV7MPYJ/jRvnYVzH6m8
tiger_id=20150001
account=12345678
license=TBHK
env=PROD

Token (Optional)

TBHK License (users with other licenses can ignore this), you need to generate a token. After the token expires, you need to regenerate it and download the tiger_openapi_token.properties file locally. Copy the tiger_openapi_token.properties file to the directory configured by ClientConfig.DEFAULT_CONFIG.configFilePath.

The token is valid for 30 days. If it expires, you need to go to the developer information page to regenerate and export a new token file. Before expiration, you can renew it through the token refresh API interface. The SDK does not automatically refresh by default. If you configure clientConfig.isAutoRefreshToken = true, the default mechanism is: refresh the token every 5 days. After successful refresh, the local tiger_openapi_token.properties file will be updated simultaneously. You can configure the automatic refresh cycle days (refreshTokenIntervalDays) and specific time (refreshTokenTime). If you need to refresh the token yourself, please configure clientConfig.isAutoRefreshToken = false.

Additional Configuration (Optional):

Information	Required	Description
IP Whitelist	No	Only IPs in the whitelist can access API interfaces. Multiple IPs are separated by ";". Optional
Callback URL	No	The callback address of the user application, which can be used to receive order, position, and asset change messages. Optional, users can also directly receive callback messages through the subscription interface provided by the SDK

For Institutional user, Register through Institution Center

Institutional users please visit Institution Account Center

After the account is opened and funds are injected, you can log in to the Tiger account in the institution account center and go to "Trading Settings > Open OpenAPI" to complete the opening process.

You can obtain public and private keys on the basic configuration page

When enabling or regenerating public and private keys, you only need to click "Get Public and Private Keys" to automatically generate the key information.
If you don't need the keys we generate, you can choose custom, copy and paste your public key into the form to complete saving and confirmation.

Note: You need to save the private key part locally and keep it properly to prevent leakage. If leakage is discovered, please update it promptly. The private key will not be saved on Tiger's servers, and clients need to save or download it themselves. If clients accidentally lose or forget the private key, they can regenerate it.

Private Key Format Instructions:

Java SDK: Requires PKCS#8 format private key
Python SDK: Requires PKCS#1 format private key

Note: When SDK calls encounter exceptions, please first check private key format compatibility

The generated configuration file tiger_openapi_config.properties has the following format. The account is the default account, which can be switched between live trading account and paper trading account. For institutional accounts, you also need to configure secret_key (obtain from the institutional center).

private_key_pk1=MIICXgIBAAKBgQCodM4fM5cz+tj8SUuxxSbSMFxNHM23hftjAuXr9THweyFtTmA/mxwo9HYEhYjxCgYAJt78xbzw7aiKu+pI45O8il8ns6UL3mT59QlCKu0+FZmF2g54teyqoiol71xcM096D3ss0oJzKGt+btvlBzdcrXM6+pZqbK14ASWGE4uBEQIDAQABAoGAX5iBjFVTngzhbDIQAZ73C9qj1qLc3yPqZ+KyJbgskeLeMlCC8DWOwnMQMjqxXtAoXZexfVKdiT/lIG3JY3m6URzfYwJt5VUD9LeIcyPxuj7Eg2vxlZwJ6slT7DQ6LJCbUe1PUDlKKXYe/wEUNJ3dEJ/eFEhR8vNyFlW8DJj+az0CQQDhQwYUZIcq+9WDcSen5Sm5oS765aMAyWcOdkpokau+fZ/H9NwT0U+jaEHyswZMJBTDJ42iS8HV0MuGdtLJ7JzHAkEAv3Fq1AHHJ1Tyxtf/VWHBRfx304NFlDX87Ji7uyv1t+05ZYVT0U8Q5CUPdBA3QexMBKd1i6BXUH/xOY5aX+UrZwJBAKR7ej79wK0kQh2+TESOUs9W4KUXdNSoO3YV7fM5Gvz3Yepx4xkdZ1dcU3tSObDzT63IfeUaCCmGUnaW4QfMnBUCQQCMOsK6mrbLe7D9sBgK7bkJz73iA+UChG1IzTOuDaxGVpDVaU0VI2pHA1KHfJ1NP44LVrKGXSO4Bo+mzjwqxA3/AkEApA8roUKXtKTqC2rb8hs5AscMpHFUl7ZbVeKX14gAg9QPWxkh8BcB1dljAsrp7irEtq4VezD2Cf40b52Fcx+pvA==
private_key_pk8=MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAKh0zh8zlzP62PxJS7HFJtIwXE0czbeF+2MC5ev1MfB7IW1OYD+bHCj0dgSFiPEKBgAm3vzFvPDtqIq76kjjk7yKXyezpQveZPn1CUIq7T4VmYXaDni17KqiKiXvXFwzT3oPeyzSgnMoa35u2+UHN1ytczr6lmpsrXgBJYYTi4ERAgMBAAECgYBfmIGMVVOeDOFsMhABnvcL2qPWotzfI+pn4rIluCyR4t4yUILwNY7CcxAyOrFe0Chdl7F9Up2JP+UgbcljebpRHN9jAm3lVQP0t4hzI/G6PsSDa/GVnAnqyVPsNDoskJtR7U9QOUopdh7/ARQ0nd0Qn94USFHy83IWVbwMmP5rPQJBAOFDBhRkhyr71YNxJ6flKbmhLvrlowDJZw52SmiRq759n8f03BPRT6NoQfKzBkwkFMMnjaJLwdXQy4Z20snsnMcCQQC/cWrUAccnVPLG1/9VYcFF/HfTg0WUNfzsmLu7K/W37TllhVPRTxDkJQ90EDdB7EwEp3WLoFdQf/E5jlpf5StnAkEApHt6Pv3ArSRCHb5MRI5Sz1bgpRd01Kg7dhXt8zka/Pdh6nHjGR1nV1xTe1I5sPNPrch95RoIKYZSdpbhB8ycFQJBAIw6wrqatst7sP2wGArtuQnPveID5QKEbUjNM64NrEZWkNVpTRUjakcDUod8nU0/jgtWsoZdI7gGj6bOPCrEDf8CQQCkDyuhQpe0pOoLatvyGzkCxwykcVSXtltV4pfXiACD1A9bGSHwFwHV2WMCyunuKsS2rhV7MPYJ/jRvnYVzH6m8
tiger_id=20150001
account=12345678
license=TBHK
env=PROD
secret_key=fcfca571-71db-35c1-9352-9a557cc8258d

After successful registration, you can obtain the following information in user profile:

Username: The name used when logging into the institution center
User ID: User ID
Tiger ID: Developer unique identifier (required parameter for all API calls)
Secret Key: Trader key, institutional users need to set this key in the config.properties configuration file for secure authentication of API requests
Account ID: User's fund account ID, which needs to be used when requesting trading-related interfaces. Click the "Edit" button on the page to view the corresponding Account ID under the user

Special Note

Each User ID corresponds to one Tiger ID, and each Tiger ID can establish one long connection. If multiple long connections are needed, you can achieve this by creating multiple Users. You can go to User Management - Manage User Permissions to add new users, then go to the API permissions interface and click Add New User Profile to add new users.

The API request permissions corresponding to each User ID are subject to the permission settings in the manage user permissions. You can limit the user's view, trading, assets and other permissions for each account according to roles.

Market Data Purchase (Optional)

We provide free delayed market data interfaces, but real-time market data requires separate purchase. Open API market data permissions are independent from APP and PC clients. Even if you have already purchased APP or PC market data, you need to separately purchase Open API market data permissions to get real-time data. The specific purchase methods are as follows:

Retail Customers

There are two purchase methods:

Log in to Personal Center to purchase market data
Purchase through the mobile APP: Tiger Trade APP - My - Market Data Permissions - OpenAPI Permissions

Institutional Customers

Purchase through Institutional Center - Market Data Permissions

API Configuration

Before making formal API requests, you need to complete the API interface configuration. The specific configuration information (including tigerId, account, license, privateKey, etc., with priority given to values in the tiger_openapi_config.properties file) can be viewed on the developer information page.

For Hong Kong stock licenses, the tiger_openapi_token.properties file is required and should also be placed in the path specified by configFilePath.

public static ClientConfig clientConfig = ClientConfig.DEFAULT_CONFIG;
public static TigerHttpClient client;
static {
        // Enable logging. log file name: tiger_openapi.2023-02-22.log
        ApiLogger.setEnabled(true, "/data/tiger_openapi/logs/");
        // ApiLogger.setDebugEnabled(false);        // Enable debug level logging
        // The tiger_openapi_config.properties file is stored in your local directory.
        clientConfig.configFilePath = "/data/tiger_config"; // your local directory
        // clientConfig.isSslSocket = true;         // default is true
        // clientConfig.isAutoGrabPermission = true;// default is true
        // clientConfig.failRetryCounts = 2;        // fail retry count, default is 2
        // clientConfig.timeZone = TimeZoneId.Shanghai; // default time zone
        // clientConfig.language = Language.en_US;  // default language
        // clientConfig.isAutoRefreshToken = false;  // default is false, only support 'TBHK' license
        // clientConfig.refreshTokenIntervalDays = 5; // default is 5; refresh the token every 5 days
        // clientConfig.refreshTokenTime = "12:30:00";  // default is empty, format: HH:mm:ss
        // clientConfig.secretKey = "xxxxxx";// Institutional user private key
  
        // Old usage method (without tiger_openapi_config.properties file), must configure tigerId, defaultAccount, privateKey. If configFilePath is configured, properties file content takes priority
        // clientConfig.tigerId = "your tiger id";
        // clientConfig.defaultAccount = "your account";
        // clientConfig.privateKey = FileUtil.readPrivateKey("/Users/tiger/rsa_private_key_pkcs8.pem");
        client = TigerHttpClient.getInstance().clientConfig(clientConfig);
}

Configuration Description:

clientConfig.configFilePath: Directory for storing tiger_openapi_config.properties and tiger_openapi_token.properties files

clientConfig.tigerId: Developer ID (tiger_openapi_config.properties file configuration takes priority)

clientConfig.defaultAccount: Capital account, can be either integrated account or paper trading account (tiger_openapi_config.properties file configuration takes priority)

clientConfig.privateKey: RSA private key generated on the page when registering developer information (tiger_openapi_config.properties file configuration takes priority)

clientConfig.secretKey: Institutional trader secret key. Required for institutional users; individual users should not set this field

clientConfig.isSslSocket: Whether persistent connections use SSL

clientConfig.isAutoGrabPermission: Whether to grab market data permissions once at startup for this device

clientConfig.failRetryCounts: API request failure retry count, maximum 5 times

clientConfig.timeZone: Default time zone, used when requesting parameters

clientConfig.language: Default language, used when requesting parameters

The clientConfig and client variables in the above example can be configured as global static variables and placed in a separate configuration class, then referenced directly where needed. This makes calling convenient while also reducing overhead.