Go SDK

Tiger Open API Go SDK, providing market data queries, order placement, account management, and real-time push notifications.

Requires Go 1.20 or higher
Source repository: openapi-go-sdk

Installation

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

Requires Go 1.20 or higher.

Configuration

The SDK supports multiple configuration methods. Priority: Environment Variables > Code Settings (including config file) > Auto-discovered config file > Defaults.

The SDK automatically searches for a config file at these locations (no explicit path needed):

Current directory: ./tiger_openapi_config.properties
Home directory: ~/.tigeropen/tiger_openapi_config.properties

Method 1: Load from properties file (recommended)

// Specify a config file path
cfg, err := config.NewClientConfig(
	config.WithPropertiesFile("/path/to/tiger_openapi_config.properties"),
)

// Or pass no arguments — SDK auto-discovers the config file
cfg, err := config.NewClientConfig()

Configuration file format:

tiger_id=your_developer_id
private_key=your_rsa_private_key
account=your_trading_account
license=TBUS

Method 2: Set directly in code

cfg, err := config.NewClientConfig(
	config.WithTigerID("your_tiger_id"),
	config.WithPrivateKey("your_rsa_private_key"),
	config.WithAccount("your_trading_account"),
)

Method 3: Environment variables

export TIGEROPEN_TIGER_ID=your_developer_id
export TIGEROPEN_PRIVATE_KEY=your_rsa_private_key
export TIGEROPEN_ACCOUNT=your_trading_account
export TIGEROPEN_SECRET_KEY=your_secret_key                   # Institutional account auth (optional)
export TIGEROPEN_TOKEN=your_token                             # Set token directly (required for TBHK license)
export TIGEROPEN_TOKEN_FILE=/path/to/tiger_openapi_token.properties  # Or specify a token file path

Configuration Options

Option	Description	Required	Default
tiger_id	Developer ID	Yes	-
private_key	RSA private key (PK1 and PK8 compatible)	Yes	-
account	Trading account	No	-
secret_key	Institutional account Secret Key (`WithSecretKey`; also via env var `TIGEROPEN_SECRET_KEY`)	No	-
license	License type (e.g. TBUS)	No	-
language	Language (zh_CN/zh_TW/en_US)	No	zh_CN
timeout	Request timeout	No	15s
token	TBHK license token (inline value)	No	-
token_file	Path to the token file (alternative to `token`; file is managed by the SDK)	No	`tiger_openapi_token.properties`
token_refresh_duration	Token refresh threshold (`WithTokenRefreshDuration`); background refresh starts automatically when > 0	No	0 (disabled)
token_check_interval	Background token refresh check interval (`WithTokenCheckInterval`)	No	5m

Auto-Detection

Device ID: Automatically detected from network interface MAC address
Dynamic domains: SDK fetches the latest server addresses from the domain garden (enabled by default)
Quote server: SDK resolves a dedicated quote server URL (LICENSE-QUOTE domain key)
Signature verification: Built-in Tiger public key for HTTP response signature verification

Token Auto-Refresh

TBHK license tokens have an expiry. Set the refresh threshold in config and NewHttpClient starts the background refresh automatically — no other setup required.

Basic Usage

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour), // refresh when token is older than 7 days
)
hc := client.NewHttpClient(cfg) // background refresh starts automatically

The default check interval is 5 minutes. Adjust it with WithTokenCheckInterval:

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenCheckInterval(1 * time.Hour), // check every hour instead
)

Post-Refresh Callback

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenWriter(func(token string) {
        // fired after the token is written
    }),
)
hc := client.NewHttpClient(cfg)
defer hc.Close() // stop the background refresh goroutine when done

Manual Refresh

// Fetch a new token only — does not update any state
newToken, err := hc.QueryToken()

// Fetch + update in-memory token (no file write)
err = hc.RefreshToken(nil)

Custom Token Loading

If tokens are stored outside the local file (e.g. a database or KV store), inject a custom loader via WithTokenLoader:

cfg, err := config.NewClientConfig(
    config.WithTokenRefreshDuration(7 * 24 * time.Hour),
    config.WithTokenLoader(func() (string, error) {
        // load token from a custom source (also called on initialization)
        return myStore.GetToken()
    }),
    config.WithTokenWriter(func(token string) {
        // write the refreshed token back to the custom source
        myStore.SaveToken(token)
    }),
)
hc := client.NewHttpClient(cfg)
defer hc.Close()

Lifecycle Management

NewHttpClient starts a background goroutine when TokenRefreshDuration > 0. Call Close() when the client is no longer needed to stop it and avoid goroutine leaks:

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

Configuration Parameters

Option	Description	Default
`WithTokenRefreshDuration(d)`	Trigger refresh when the token exceeds this age; `0` disables refresh	0 (disabled)
`WithTokenCheckInterval(d)`	Background check interval	5m
`WithTokenWriter(fn)`	Optional callback invoked after each token refresh	-
`WithTokenLoader(fn)`	Custom token loading function, replaces the default file-based load; also called on initialization (optional)	-

Quote Client

The SDK provides a dedicated quote HTTP client NewQuoteHttpClient that automatically uses the quote server URL:

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

Requests and Responses

All responses are strongly typed

Every method returns a concrete struct (or slice/pointer) defined in the model package — you don't have to call json.Unmarshal yourself:

briefs, _ := qc.GetRealTimeQuote(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)

Common return types:

Data shape	Return type
Multi-symbol quotes / positions / orders	`[]model.Brief` / `[]model.Position` / `[]model.Order`
Single aggregate object	`model.PrimeAsset` / `model.CapitalDistribution` / `*model.PreviewResult`
Place / modify / cancel order	`model.PlaceOrderResult` / `model.OrderIDResult`

Request parameter style (Go idioms)

Few required parameters (≤3) — positional arguments: GetRealTimeQuote(symbols) / GetKline(symbol, period) / GetCapitalFlow(symbol, market, period).
Many parameters or optional fields — Request struct: GetFinancialDaily(FinancialDailyRequest{...}) / GetFutureKline(FutureKlineRequest{...}) / MarketScanner(MarketScannerRequest{...}) / PlaceOrder(OrderRequest{...}).
Request struct json tags are snake_case to match the server wire format; response struct json tags are camelCase.