Go SDK (Beta)

老虎证券 OpenAPI Go SDK，提供行情查询、交易下单、账户管理和实时推送等功能。

要求 Go 1.20 或更高版本
源码仓库：openapi-go-sdk

安装

go get github.com/tigerfintech/openapi-go-sdk

要求 Go 1.20 或更高版本。

配置

SDK 支持多种配置方式，优先级：环境变量 > 代码设置（含配置文件） > 自动发现配置文件 > 默认值。

SDK 会自动搜索以下路径的配置文件（无需显式指定）：

当前目录 ./tiger_openapi_config.properties
用户目录 ~/.tigeropen/tiger_openapi_config.properties

方式一：从 properties 配置文件加载（推荐）

// 指定配置文件路径
cfg, err := config.NewClientConfig(
	config.WithPropertiesFile("/path/to/tiger_openapi_config.properties"),
)

// 或不传任何参数，SDK 自动搜索默认路径
cfg, err := config.NewClientConfig()

配置文件格式：

tiger_id=你的开发者ID
private_key=你的RSA私钥
account=你的交易账户
license=TBUS

方式二：代码直接设置

cfg, err := config.NewClientConfig(
	config.WithTigerID("your tiger_id"),
	config.WithPrivateKey("your RSA content"),
	config.WithAccount("your account id"),
)

方式三：环境变量

export TIGEROPEN_TIGER_ID=你的开发者ID
export TIGEROPEN_PRIVATE_KEY=你的RSA私钥
export TIGEROPEN_ACCOUNT=你的交易账户
export TIGEROPEN_TOKEN=你的Token            # 直接设置 Token（TBHK 牌照需要）
export TIGEROPEN_TOKEN_FILE=/path/to/tiger_openapi_token.properties  # 或指定 Token 文件路径

配置项说明

配置项	说明	必填	默认值
tiger_id	开发者 ID	是	-
private_key	RSA 私钥（PK1与PK8都兼容）	是	-
account	交易账户	否	-
license	牌照类型（如 TBUS）	否	-
language	语言（zh_CN/zh_TW/en_US）	否	zh_CN
timeout	请求超时	否	15s
token	TBHK 牌照 Token（直接写入）	否	-
token_file	Token 文件路径（与 token 二选一，文件内容优先由 SDK 管理）	否	`tiger_openapi_token.properties`
token_refresh_duration	Token 刷新阈值（`WithTokenRefreshDuration`），大于 0 时自动启动后台刷新	否	0（禁用）
token_check_interval	后台 token 刷新检查间隔（`WithTokenCheckInterval`）	否	5m

自动检测

设备 ID：SDK 自动从网卡 MAC 地址获取，无需手动设置
动态域名：SDK 自动从域名花园获取最新服务器地址，默认启用
行情服务器：SDK 自动解析独立的行情服务器地址（LICENSE-QUOTE 域名键）
签名验证：SDK 内置 Tiger 公钥，自动验证 HTTP 响应签名

Token 自动刷新

TBHK 牌照的 Token 有有效期，只需在 config 里设置刷新阈值，NewHttpClient 会自动启动后台刷新。

基本用法

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour), // Token 生成超过 7 天则刷新
)
hc := client.NewHttpClient(cfg) // 后台刷新已自动启动

默认每 5 分钟检查一次，可通过 WithTokenCheckInterval 调整：

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenCheckInterval(1 * time.Hour), // 改为每小时检查一次
)

刷新后回调

如果需要在 token 刷新后执行自定义逻辑，通过 WithTokenWriter 注册回调：

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenWriter(func(token string) {
        // token 写入完成后触发
    }),
)
hc := client.NewHttpClient(cfg)
defer hc.Close() // 停止后台刷新 goroutine，避免泄漏

手动刷新

// 仅获取新 Token，不修改任何状态
newToken, err := hc.QueryToken()

// 获取新 Token 并更新内存（不写文件）
err = hc.RefreshToken(nil)

自定义加载逻辑

如果 token 存储在自定义来源（如数据库、KV 存储）而非本地文件，通过 WithTokenLoader 注入加载函数：

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenLoader(func() (string, error) {
        // 从自定义来源读取 token（初始化时也会自动调用）
        return myStore.GetToken()
    }),
    config.WithTokenWriter(func(token string) {
        // 刷新后写入自定义来源
        myStore.SaveToken(token)
    }),
)
hc := client.NewHttpClient(cfg)
defer hc.Close()

生命周期管理

NewHttpClient 在 TokenRefreshDuration > 0 时自动启动后台 goroutine。使用完毕后调用 Close() 停止它：

hc := client.NewHttpClient(cfg)
defer hc.Close()

配置参数

选项	说明	默认值
`WithTokenRefreshDuration(d)`	Token 生成时间超过此值时触发刷新；0 表示不刷新	0（禁用）
`WithTokenCheckInterval(d)`	后台检查间隔	5m
`WithTokenWriter(fn)`	Token 刷新写入后的回调（可选）	-
`WithTokenLoader(fn)`	自定义 token 加载函数，替代默认的文件加载；初始化时自动调用（可选）	-

行情客户端

SDK 提供独立的行情 HTTP 客户端 NewQuoteHttpClient，自动使用行情专用服务器地址：

cfg, _ := config.NewClientConfig()
quoteHttpClient := client.NewQuoteHttpClient(cfg)
qc := quote.NewQuoteClient(quoteHttpClient)

请求与响应

响应全部为强类型

所有接口直接返回 model 包中定义好的结构体（或其切片/指针），无需用户再手动 json.Unmarshal：

briefs, _ := qc.GetBrief(model.BriefRequest{Symbols: []string{"AAPL", "TSLA"}})
for _, b := range briefs {
    fmt.Printf("%s latestPrice=%.2f\n", b.Symbol, b.LatestPrice)
}

placed, _ := tc.PlaceOrder(order)
fmt.Println("order id:", placed.ID)

常见返回类型：

数据形态	返回类型示例
多标的行情 / 持仓 / 订单	`[]model.Brief` / `[]model.Position` / `[]model.Order`
单个资产对象	`model.PrimeAsset` / `model.CapitalDistribution` / `*model.PreviewResult`
下单 / 改单 / 撤单	`model.PlaceOrderResult` / `model.OrderIDResult`

请求参数风格（Go 惯例）

参数少（≤3 个且全必填） — 位置参数：GetBrief(symbols) / GetKline(symbol, period) / GetCapitalFlow(symbol, market, period)。
参数多或有可选字段 — Request 结构体：GetFinancialDaily(FinancialDailyRequest{...}) / GetFutureKline(FutureKlineRequest{...}) / MarketScanner(MarketScannerRequest{...}) / PlaceOrder(OrderRequest{...})。
Request 结构体的 json tag 使用 snake_case，与服务端 wire format 对齐；响应结构体的 json tag 使用 camelCase。