Preparation

Environment Requirements

• Supported operating systems:
  • Windows
  • macOS
  • Linux
• Python 3.9 or later

Installing Python

We recommend installing Python 3.9 or above. Although the SDK's requires-python metadata declares ">=3.8", the code uses built-in generic syntax such as list[str] which is only supported in Python 3.9+. Running on 3.8 will raise a TypeError. You can check the version by entering python3 -V in the terminal.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS/Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# uv downloads the required Python version automatically

Installing the Tiger OpenAPI Python SDK

# Create project directory
mkdir my-tiger-project && cd my-tiger-project

# Initialize project (automatically creates virtual environment and pyproject.toml)
uv init
uv add tigeropen

# Run script
uv run python main.py

uv add tigeropen --upgrade

# Create project directory
mkdir my-tiger-project && cd my-tiger-project

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate        # macOS/Linux
.venv\Scripts\activate           # Windows

# Install SDK
pip install tigeropen

pip install tigeropen --upgrade

pip install tigeropen -i https://pypi.tuna.tsinghua.edu.cn/simple

# Create an independent Conda environment
conda create -n tiger python=3.12
conda activate tiger

# Install SDK
pip install tigeropen

git clone https://github.com/tigerfintech/openapi-python-sdk.git
cd openapi-python-sdk
pip install .

Development Tools

Tiger OpenAPI works with popular AI coding tools (Cursor, Windsurf, Trae, VS Code + GitHub Copilot, Claude Code, Kiro, etc.) and traditional IDEs (PyCharm, VS Code). Place the configuration file in your project directory and AI tools can automatically read the documentation to generate SDK code. See AI Skill and MCP Server for setup.

Retail Users: Register in the Developer Center

Before using the API, activate OpenAPI access by registering as a developer. We recommend opening the page in Chrome.

Note: Enabling OpenAPI requires a funded Tiger Brokers account and acceptance of the API authorization agreement.

Complete and submit the developer registration form.

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

• tiger_id: A unique developer ID assigned by the Open Platform and included in every API call.
• account: The funding account used by trading APIs. Account types include global, prime, and paper trading accounts:
  • Global Account: Starts with uppercase letter U, such as: U12300123
  • Prime Account: A string of shorter numbers (5 to 10 digits), such as: 51230321
  • Paper Trading Account: 17 digits, such as: 20191106192858300

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

Developer Registration Page: Registration can be completed with mobile phone number and verification code

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

Note: Save the private key locally before refreshing the page. Tiger Brokers does not store it, and it disappears after the page is refreshed. Keep it secure and use Regenerate immediately if it is lost or exposed.

Use a private-key format supported by your SDK. PKCS#8 is recommended for both the Java and Python SDKs. If authentication fails, verify the private-key format first.

The generated configuration file tiger_openapi_config.properties file content format is as follows. Account is the default account and can be switched between live funding account and paper trading account. If it is an institutional account, you also need to configure secret_key (needs to be obtained from the institutional center).

The configuration exported from the Developer Center takes precedence. You can also use the shared configuration template: copy it, remove the .example suffix, and replace the placeholders. Never commit credentials.

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=YOUR_TIGER_ID
account=12345678
license=TBHK
env=PROD

Token (Optional)

TBHK License (users with other licenses can ignore this): You need to generate a token. When the token expires, you need to regenerate it and download the tiger_openapi_token.properties file to your local machine. Copy the tiger_openapi_token.properties file to the directory configured in ClientConfig props_path.**

For an account that requires a local token file, use the shared token template, remove the .example suffix, and replace the placeholders.

The token is valid for 30 days. If it expires, regenerate and export a token file from the developer information page. Before expiration, you can extend its validity through the token refresh API. The SDK does not refresh tokens automatically by default.
After successful refresh, the local tiger_openapi_token.properties file will also be updated.
If you need automatic token refresh, please configure client_config.token_refresh_duration to a value greater than 0, with time unit in seconds.

Additional configuration, not required:

Institutional Users: Register in the Institution Center

Institutional users should visit the Institution Account Center.

After opening and funding the account, sign in to the Institution Center and select Trading Settings > Enable OpenAPI.

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: Save the private key locally and protect it from disclosure. Tiger Brokers does not store it. Regenerate the key immediately if it is lost or exposed.

Private Key Format Instructions:

• Java SDK: Requires PKCS#8 format private key
• Python SDK: Requires PKCS#8 format private key (PKCS#1 is also supported)

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

Prepare the configuration file named tiger_openapi_config.properties. The file format is as follows:

Use the shared configuration template as a reference; configuration exported from the Developer Center takes precedence. Never commit credentials.

• Fill in private_key_pk1 or private_key_pk8 based on the public/private key files downloaded from the Institution Center.
• account can be set to the target account you have permission to operate, and supports switching between live and paper trading accounts.
• secret_key can be obtained from the Institution Center.

If your account requires a local token file, use the shared token template, remove the .example suffix, replace the placeholders, and obtain the token from the Institution 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=YOUR_TIGER_ID
account=12345678
license=TBHK
env=PROD
secret_key=fcfca571-71db-35c1-9352-9a557cc8258d

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

• Username: Name used when logging into the institution center
• User ID: User ID
• Tiger ID: Unique developer identifier (required parameter for all API calls)
• Secret Key: Trader key, institution 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, needed when requesting trading APIs. 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 persistent connection. If multiple persistent connections are needed, you can create multiple Users by going to User Management - Manage User Permissions to add new users, then go to the API permissions page and click Add New User Profile to add new users.

The API request permissions for each User ID are subject to the permission settings in manage user permissions, where you can limit users' view, trading, and asset permissions for each account based on roles.

Purchase Market Data Access (Optional)

Delayed market data is available free of charge. Real-time OpenAPI market data access must be purchased separately from Tiger Trade app or desktop market data access.

Retail Customers

There are two purchase methods:

1. Log into Personal Center to purchase market data

   

2. In the mobile APP Tiger Trade APP - My - market data access - OpenAPI Permissions to make purchases

Institution Customers

Purchase in Institution Center - market data access

API Configuration

Before making API requests, complete the client configuration. The developer information page lists the required values, including tigerId, account, and license.

Methods 1 and 2 below use signature authentication and require a private key. Individual users who do not want to store a private key can use OAuth2 authorization (Method 3).

Choose one of the following configuration methods.

Method 1

Use configuration file.
Export the configuration file tiger_openapi_config.properties from the developer website and place it in an appropriate system path, such as /Users/demo/props/
Then fill this path into the props_path parameter of TigerOpenClientConfig (you can also place the configuration file in the program's current startup directory, the SDK will default to the current path).
Using this method, you no longer need to configure tiger_id, account, private_key and other information in the code.

Additionally, for Hong Kong stock licenses, tiger_openapi_token.properties is required, and this file also needs to be placed in the path specified by props_path.

from tigeropen.common.consts import (Language,        # Language
                                Market,           # Market
                                BarPeriod,        # bar period
                                QuoteRight)       # Adjustment type
from tigeropen.tiger_open_config import TigerOpenClientConfig
from tigeropen.common.util.signature_utils import read_private_key
from tigeropen.quote.quote_client import QuoteClient

def get_client_config():
    """
    https://developer.itigerup.com/profile Get developer information
    """
    # Hong Kong stock license requires props_path parameter to specify token path, such as '/Users/xxx/xxx/', if not specified, current path is used
    # Must use keyword argument to specify props_path
    client_config = TigerOpenClientConfig(props_path='your_config_directory_path')
    return client_config

# Call the function defined above to generate user configuration ClientConfig object
client_config = get_client_config()

Method 2

Alternatively, configure the client in code. Market data methods are exposed by QuoteClient, which must be initialized before use. TradeClient and PushClient use a similar initialization pattern.

Create a client_config object, pass it to QuoteClient, and then call the required market data methods. Initialize TradeClient and PushClient with the same configuration object.

from tigeropen.common.consts import (Language,        # Language
                                Market,           # Market
                                BarPeriod,        # bar period
                                QuoteRight)       # Adjustment type
from tigeropen.tiger_open_config import TigerOpenClientConfig
from tigeropen.common.util.signature_utils import read_private_key
from tigeropen.quote.quote_client import QuoteClient

def get_client_config():
    """
    https://developer.itigerup.com/profile Get developer information
    """
    client_config = TigerOpenClientConfig()
    # For a Hong Kong license, props_path identifies the directory containing the token properties file.
    # client_config = TigerOpenClientConfig(props_path='.')
    client_config.private_key = read_private_key('Fill in the private key PEM file path')
    client_config.tiger_id = 'Replace with Tiger ID'
    client_config.account = 'Replace with account ID; use a paper trading account for testing'
    client_config.license = 'TBSG'  # License code
    # Institutional accounts also require a user secret key.
    client_config.secret_key = 'Replace with user secret key'
    client_config.language = Language.zh_CN  # Optional; defaults to English
    # client_config.timezone = 'US/Eastern'  # Optional time zone setting
    return client_config

# Call the function defined above to generate user configuration ClientConfig object
client_config = get_client_config()

# Then pass the configuration parameter object to initialize QuoteClient
quote_client = QuoteClient(client_config)

# Get market data for stock 00700
stock_price = quote_client.get_stock_briefs(['00700'])

Method 3: OAuth2 authorization (individual users only)

OAuth2 requires tigeropen >= 3.8.0 and does not use a private key or tiger_id. Institutional users must use signature authentication.

from tigeropen.auth.oauth2 import OAuth2Authentication, OAuth2SessionManager
from tigeropen.tiger_open_config import TigerOpenClientConfig

sessions = OAuth2SessionManager()
sessions.login_if_needed(lambda url: print('Complete authorization:\n' + url))

client_config = TigerOpenClientConfig()
client_config.authentication = OAuth2Authentication(sessions)

Use client_config to create business clients. Trading requests must specify an authorized account.

Common ClientConfig Settings

After creating client_config = TigerOpenClientConfig(), set options through its attributes, for example client_config.timeout = 60.

# Developer information (recommended to use props_path method to configure developer information)
client_config.tiger_id = 1
client_config.account = '123456'
client_config.license = 'TBSG'
client_config.private_key = read_private_key('Private key path')  # Need from tigeropen.common.util.signature_utils import read_private_key
# Private key can also be filled with string content
client_config.private_key = 'MIICWwIBAAKBgQCSW+.....private key content'

# Log level and path
client_config.log_level = logging.DEBUG  # Need import logging
client_config.log_path = '/tmp/tigerapi.log'

# Language
client_config.language = 'zh_CN'
# Time zone for string-valued time parameters. Without this setting, the server interprets them as Beijing time.
client_config.timezone = 'US/Eastern'

# API timeout
client_config.timeout = 15
# Timeout retry settings
# Maximum retry time in seconds
client_config.retry_max_time = 60
# Maximum retry attempts
client_config.retry_max_tries = 5

# 2FA token refresh interval in seconds. Set to 0 for no automatic refresh. Default is no refresh
client_config.token_refresh_duration = 24 * 60 * 60