准备工作

环境要求

操作系统要求：
- Windows
- MacOS
- Linux
- Solaris
编程语言版本要求：Java JDK 1.7（64 位）及以上。

安装 Java Development Kit

推荐安装 JDK 1.8+。可在终端输入 java -version 检查版本。

访问 Oracle JDK 下载页面，选择操作系统对应的安装包，按提示完成安装。

获取 Tiger Open API Java SDK

在项目 pom.xml 中添加依赖：

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

如果无法下载，尝试添加仓库源：

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

SDK 源代码托管在 GitHub 和 Gitee：

GitHub: tigerfintech/openapi-java-sdk
Gitee: tigerbrokers/openapi-java-sdk

git clone https://github.com/tigerfintech/openapi-java-sdk.git
cd openapi-java-sdk
mvn clean install

开发工具

Tiger OpenAPI 支持主流 AI 编程工具（Cursor、Windsurf、Trae、VS Code + GitHub Copilot、Claude Code、Kiro 等）和传统 IDE（IntelliJ IDEA、VS Code）。将配置文件放入项目目录后，AI 工具可自动阅读文档并生成 SDK 代码。详见 AI Skill 和 MCP Server。

注册开发者信息

使用 API 之前请首先开通权限，个人用户访问 API 官网登记开发者身份
推荐使用 Chrome 浏览器打开。

注意：开通 Open API 需要在老虎开户并入金，同时会要求开发人员和用户签署 API 授权协议。

随后需要在此页面中完成开发者信息的登记，请填入并提交您的信息。

注册成功后您可在此页面中获取以下信息：

tigerId： 开放平台为每一位开发者分配的唯一 ID，用来标识一个开发者，所有 API 接口的调用都会用到 tigerId。
account： 用户的资金账号，在请求交易相关接口时需要用到资金账号。具体分为环球账号、综合账号与模拟账号，
- 环球资金账号（Global）：以大写字母 U 开头，如：U12300123，
- 综合资金账号（Prime）：为一串较短的数字（ 5 到 10 位），如：51230321，
- 模拟资金账号（Paper）：17 位数字，如：20191106192858300，

注册开发者信息成功后只会返回已成功入金的资金账号和模拟账号。如果用户的环球账号和综合账号都已成功入金，则都会返回。

开发者注册页面： 通过手机号和验证码注册即可。

开发者信息页面： 其中 Tiger ID，实盘账户，模拟盘账号，牌照等信息需要在 OpenAPI 中用到。

注意：需要把下图中的私钥部分保存到本地并妥善保管以防泄露，如发现泄露请及时更新。私钥不会在老虎服务端保存，用户在刷新页面前需要保存好。页面刷新后该私钥会自动消失，如私钥未保存好，可以通过重新生成按钮进行替换。

重新生成后，下载 tiger_openapi_config.properties 文件到本地。把 tiger_openapi_config.properties 文件拷贝到 ClientConfig.DEFAULT_CONFIG.configFilePath 配置的目录下。

优先使用开发者中心导出的真实配置；也可参考统一配置模板，复制后去掉 .example 后缀并替换占位符。请勿将凭证提交到版本库。

tiger_openapi_config.properties 文件内容格式如下，account 为默认账号，可以在实盘资金账号和模拟盘账号之间替换。

private_key_pk8=YOUR_PKCS8_PRIVATE_KEY
tiger_id=YOUR_TIGER_ID
account=YOUR_ACCOUNT_ID
license=TBHK
env=PROD

Token（可选）

TBHK 牌照(其他牌照用户可以忽略)，需要生成 token，token 失效后需重新生成，并下载 tiger_openapi_token.properties 文件到本地。把 tiger_openapi_token.properties 文件拷贝到 ClientConfig.DEFAULT_CONFIG.configFilePath 配置的目录下。

需要 Token 时，请参考统一 Token 模板。

Token 的有效期为 30 天，如果失效后需要到开发者信息页面重新生成并导出新的 Token 文件。在失效前，可以通过刷新 Token 的 API 接口续期。SDK 默认不自动刷新。如配置 clientConfig.isAutoRefreshToken = true ，默认机制为：每 5 天刷新一次 Token，刷新成功后会同时更新本地 tiger_openapi_token.properties 文件，可配置自动刷新周期的天数（refreshTokenIntervalDays）和具体时间（refreshTokenTime）。如需自行刷新 token，请配置clientConfig.isAutoRefreshToken = false。

额外配置，非必须：

信息	是否必填	说明
IP 白名单	否	只有在白名单内的 IP 才可以访问 API 接口，多个 IP 间以 “;” 分隔，非必填
回调 URL	否	用户应用程序的回调地址，可以用于接收订单、持仓、资产的变更消息。非必填，用户也可以直接通过 SDK 提供的订阅接口接收回调消息

机构中心

机构用户请访问机构账户中心

账户开通并注入资金后，可登录机构账户中心的老虎账户，并前往「交易设置 > 开通 OpenAPI」完成开通流程。

在基础配置页面可以获取公私钥匙

在开通或者重新生成公私钥时候，您只需点击「获取公私钥」，即可自动生成公私钥信息。
如果您不需要我们生成的公私钥，可以选择自定义，把您的公钥复制粘贴进表格完成保存确定即可。

注意：需要把私钥部分保存到本地并妥善保管以防泄露，如发现泄露请及时更新。私钥不会在老虎服务端保存，客户需自行保存或下载，。如客户不慎丢失或遗忘私钥，可重新获取。

私钥格式说明：

Java SDK 仅支持 PKCS#8 格式私钥（BEGIN PRIVATE KEY）

注意：SDK 调用异常时，请优先检查私钥格式是否为 PKCS#8

准备配置文件 tiger_openapi_config.properties，文件内容格式如下，其中：

优先使用开发者中心导出的真实配置；也可参考统一配置模板。请勿将凭证提交到版本库。

1）Java SDK 仅使用 private_key_pk8，请配置机构中心下载的 PKCS#8 私钥；2）account 可配置为您具备操作权限的目标账户，支持切换实盘及模拟盘账户；3）secret_key 可在机构中心获取。

如为 TBHK 牌照用户，还需参考统一 Token 模板创建 token 文件，token 可在机构中心获取。

private_key_pk8=YOUR_PKCS8_PRIVATE_KEY
tiger_id=YOUR_TIGER_ID
account=YOUR_ACCOUNT_ID
license=TBHK
env=PROD
secret_key=YOUR_SECRET_KEY

注册成功后您可在用户资料中获取以下信息：

用户名：登录机构中心时的名称
User ID：用户 ID
Tiger ID：开发者唯一标识符（所有 API 调用的必需参数）
Secret Key：交易员密钥，机构用户需在 config.properties 配置文件中设置此密钥，用于 API 请求的身份安全认证
Account ID：用户的资金账户 ID，在请求交易相关接口时需要用到资金账号，点击页面「编辑」按钮，可查看到用户下面对应的账户 ID（Account ID）

特殊说明

每个 User ID 对应着一个 Tiger ID，每个 Tiger ID 可以建立一个长连接，如果需要多个长连接，可以通过建立多个 User 来实现，可以前往用户管理 -管理用户权限 添加新的用户，然后再去 API 权限界面点击新增用户资料添加新的用户。

每个 User ID 对应的 API 请求权限都受制于管理用户权限里面的权限设置，可以按照角色去限制用户可调用每个账户的查看、交易、资产等权限。

购买行情（可选）

我们免费提供延迟行情接口，但实时行情需要另外购买。Open API 的行情权限独立与 APP 与 PC 端，如果您已经购买了 APP 或 PC 行情，也需要另外购买 Open API 的行情权限以获得实时数据。具体购买方法如下：

个人客户

有两种购买方式：

1、登录个人中心购买行情

2、在手机端 APP Tiger Trade APP - 我的 - 行情权限 - OpenAPI 权限 中进行购买

机构客户

在 机构中心-行情权限 中进行购买

API 相关配置

在正式请求接口前，需要完成 API 接口调用的相关配置。具体配置信息（包括 tigerId，account，license，privateKey 等配置，优先使用 tiger_openapi_config.properties 文件的值）可以在开发者信息页面查看。

对于港股牌照，tiger_openapi_token.properties 是必须的，此文件也需放入 configFilePath 指定的路径下。

public static ClientConfig clientConfig = ClientConfig.DEFAULT_CONFIG;
public static TigerHttpClient client;
static {
        // 开启日志. log file name: tiger_openapi.2023-02-22.log
        ApiLogger.setEnabled(true, "/data/tiger_openapi/logs/");
        // ApiLogger.setDebugEnabled(false);        // 开启debug级别日志
        // The tiger_openapi_config.properties file is stored in your local directory.
        clientConfig.configFilePath = "your_config_directory_path";
        // 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, 格式为：HH:mm:ss
        // clientConfig.secretKey = "xxxxxx";// 机构用户私钥
  
        // 原来旧的使用方式（不使用tiger_openapi_config.properties文件），必须配置tigerId, defaultAccount, privateKey三项，如果同时配置了configFilePath路径properties文件配置内容优先
        // clientConfig.tigerId = "your tiger id";
        // clientConfig.defaultAccount = "your account";
        // clientConfig.privateKey = FileUtil.readPrivateKey("/Users/tiger/rsa_private_key_pkcs8.pem");
  			// clientConfig.token = "xx";（TBHK牌照需要配置）
client = TigerHttpClient.getInstance().clientConfig(clientConfig);
}

配置说明：

clientConfig.configFilePath: tiger_openapi_config.properties 文件和 tiger_openapi_token.properties 文件存放目录

clientConfig.tigerId：开发者 ID（tiger_openapi_config.properties 文件配置优先）

clientConfig.defaultAccount：资金账号，可以填综合账号或者模拟账号（tiger_openapi_config.properties 文件配置优先）

clientConfig.privateKey：注册开发者信息时在页面上生成的 RSA 私钥（tiger_openapi_config.properties 文件配置优先）

clientConfig.secretKey：是机构交易员密钥，如果是机构用户，需要配置该信息; 个人用户请不要设置该字段

clientConfig.token = "xx"：是 TBHK 牌照用户需要配置的两步验证信息

clientConfig.isSslSocket：长连接是否使用 SSL

clientConfig.isAutoGrabPermission：是否启动时本设备抢占一次行情

clientConfig.failRetryCounts：API 请求失败重试次数，最多不超过 5 次

clientConfig.timeZone：默认时区，请求参数时使用

clientConfig.language：默认语言，请求参数时使用

如上示例中的 clientConfig 和 client 变量都可以配置成全局静态变量，放到单独的配置类中，在需要使用的地方直接引用即可。既可以方便调用，同时也可以降低开销。