Client Lifecycle

Create `QuoteClient` and `TradeClient`

explicit QuoteClient(const ClientConfig &cf, bool is_grab_permission = true)
explicit TradeClient(const ClientConfig &cf)

Description

Creates a quote or trading HTTP client. The current QuoteClient implementation always calls grab_quote_permission() and does not read is_grab_permission; although the parameter has a default, this release cannot use it to disable claiming.

Parameters

Parameter	Type	Required	Description
cf	const ClientConfig&	Yes	Configured developer credentials; trading also requires an account
is_grab_permission	bool	No	Header default `true`; ignored by the current implementation

Return

Constructs QuoteClient or TradeClient. They cannot be copied or moved because inherited TigerClient copy/move operations are deleted.

Example

TIGER_API::ClientConfig config(false, U("your_config_directory_path"));
TIGER_API::QuoteClient quote_client(config);
TIGER_API::TradeClient trade_client(config);

Permissions and Limits

Trading methods require account permission; quote methods require relevant market data access. See quote_client.h, trade_client.h, and quote_client.cpp.

Create a Push Client

static std::shared_ptr<IPushClient> IPushClient::create_push_client(
    const ClientConfig &client_config)

Description

Creates an asynchronous push client from a configuration copy. Keep the returned shared pointer alive for all asynchronous callbacks.

Parameters

Parameter	Type	Required	Description
client_config	const ClientConfig&	Yes	Validated developer, account, and socket configuration

Return

std::shared_ptr<IPushClient>. Object creation does not mean the network connection is established.

Security warning: Push uses TCP/TLS. When ClientConfig.socket_ca_certs is empty, this SDK disables server-certificate verification. When a CA file is configured, it verifies the certificate chain but still does not match the certificate hostname, so server authentication remains incomplete. Using an official endpoint or trusted network does not compensate for missing hostname verification; the SDK must verify both the certificate chain and target hostname.

Example

#include "tigerapi/client_config.h"
#include "tigerapi/push_client.h"

int main() {
    TIGER_API::ClientConfig config(false, U("your_config_directory_path"));
    auto client = TIGER_API::IPushClient::create_push_client(config);
    client->connect();
    client->disconnect();
}

Permissions and Limits

A valid token, socket endpoint, and certificate configuration are required. Keep the shared pointer alive until callbacks finish.

Get Client Configuration

const ClientConfig& IPushClient::get_client_config() const

Description

Returns a read-only reference to the client's configuration. The reference does not outlive the client.

Parameters

None.

Return

const ClientConfig&; it must not be used to mutate client configuration.

Example

const TIGER_API::ClientConfig& active_config = client->get_client_config();
utility::ucout << active_config.account << std::endl;

Permissions and Limits

The returned reference becomes invalid when the client is destroyed.

Connect

void IPushClient::connect()

Description

Starts the worker thread and connects asynchronously. Observe the result through set_connected_callback, set_inner_error_callback, or set_error_callback; there is no synchronous result. set_connected_callback runs immediately after the TLS handshake and authentication frame are sent, without waiting for the server's authentication response. The public API has no separate authentication-complete callback, so this event does not prove authentication succeeded.

Parameters

None.

Return

void. Method return does not indicate handshake success.

Example

client->set_connected_callback([]() { std::cout << "connected\n"; });
client->connect();

The client automatically reconnects after an unintentional disconnect, but it does not retain or restore subscriptions. Reissue required subscriptions when set_connected_callback runs after reconnecting, and confirm their business results through the subscription-result callback. Messages missed while disconnected are not replayed.

Permissions and Limits

Do not call connect() concurrently or repeatedly to create multiple worker threads.

Disconnect

void IPushClient::disconnect()

Description

Posts an asynchronous disconnect operation to the worker thread. Observe completion through set_disconnected_callback; method return does not mean the network connection has already closed.

Parameters

None.

Return

void.

Example

client->set_disconnected_callback([]() { std::cout << "disconnected\n"; });
client->disconnect();

Permissions and Limits

Unsubscribe data no longer needed before disconnecting. Callbacks may execute on the worker thread.

Refresh the Access Token

utility::string_t TigerClient::refresh_token()

Description

Fetches a new token and, on success, persists it and updates the thread-safe configuration. Returns an empty string on failure. query_token() is the retained deprecated alias.

Parameters

None.

Return

utility::string_t new token, or an empty string on failure.

Example

TIGER_API::QuoteClient client(config);
const utility::string_t token = client.refresh_token();
if (token.empty()) {
    std::cerr << "token refresh failed\n";
}

Permissions and Limits

Valid developer credentials and a writable token persistence path are required. Never log the complete token.

Refresh-Token Compatibility Alias

utility::string_t TigerClient::query_token()

Description

Deprecated compatibility alias for refresh_token(). New code should call refresh_token().

Parameters

None.

Return

utility::string_t new token, or an empty string on failure.

Example

const utility::string_t token = client.query_token(); // Compatibility only.

Permissions and Limits

Identical to refresh_token(). Do not introduce new dependencies on this alias.

Start Automatic Token Refresh

bool TigerClient::start_token_refresh(int interval_seconds)

Description

Starts background refresh at a positive interval in seconds. Returns false if a refresh thread is already running. The client is noncopyable and nonmovable and must remain alive.

Parameters

Parameter	Type	Required	Description
interval_seconds	int	Yes	Positive refresh interval in seconds

Return

bool: true when started, false when a refresh thread already runs.

Example

if (!client.start_token_refresh(3600)) {
    std::cerr << "refresh thread already running\n";
}

Permissions and Limits

Only one refresh thread may run per client. The client must outlive it.

Stop Automatic Token Refresh

void TigerClient::stop_token_refresh()

Description

Signals the background thread and waits for it to exit. Destruction cleans up the thread, but explicit shutdown is recommended.

Parameters

None.

Return

void.

Example

client.stop_token_refresh();

Permissions and Limits

Safe to call when no refresh thread is running; a waiting thread is awakened and exits.

Permissions and Limits

HTTP clients require valid developer credentials. Push clients additionally require socket configuration, certificates, and the applicable data access. Do not copy a ClientConfig while its refresh thread is running, and do not call connect() concurrently to create multiple worker threads.

Construct and Configure `ClientConfig`

ClientConfig(bool sandbox_debug = false)
ClientConfig(utility::string_t tiger_id, utility::string_t private_key, utility::string_t account)
ClientConfig(utility::string_t tiger_id, utility::string_t private_key, utility::string_t account,
             bool sandbox_debug = false, utility::string_t lang = U("en_US"))
ClientConfig(bool sandbox_debug, const utility::string_t props_path)
ClientConfig(const ClientConfig& other)

Description

Creates configuration from defaults, explicit credentials, or a properties path. Copy construction copies configuration and the current token but not the refresh thread; assignment and movement are deleted.

Parameters

Parameter	Type	Required	Description
sandbox_debug	bool	No	SDK default `false`
tiger_id	utility::string_t	Conditional	Required by explicit-credential constructors
private_key	utility::string_t	Conditional	RSA private key; never log it
account	utility::string_t	Conditional	Trading account; quote-only use may configure it later
lang	utility::string_t	No	SDK default `U("en_US")`
props_path	const utility::string_t	Conditional	Properties file directory/path
other	const ClientConfig&	Conditional	Configuration to copy; its refresh thread must not be running

Return

Constructs ClientConfig. Defaults include charset = U("UTF-8"), sign_type = U("RSA"), use_full_tick = false, and 10,000 ms send/receive intervals.

Example

TIGER_API::ClientConfig config(
    U("tiger-id"), U("-----BEGIN PRIVATE KEY-----..."), U("account"),
    false, U("en_US"));

Permissions and Limits

Credentials must be valid. Do not copy a configuration while auto-refresh runs. Source: client_config.h.

Validate `ClientConfig`

void ClientConfig::check() const
void ClientConfig::check_account() const

Description

check() validates configuration needed for client requests. check_account() additionally validates the trading account.

Parameters

None.

Return

void; invalid configuration raises an SDK exception and does not return JSON.

Example

config.check();
config.check_account();

Permissions and Limits

Validation is local and does not verify remote access.

Access `ClientConfig` Endpoints

void ClientConfig::set_server_url(const utility::string_t& url)
void ClientConfig::set_socket_url(const utility::string_t& url)
void ClientConfig::set_socket_port(const utility::string_t& port)
void ClientConfig::set_server_public_key(const utility::string_t& key)
const utility::string_t& ClientConfig::get_server_url() const
const utility::string_t& ClientConfig::get_server_pub_key() const
const utility::string_t& ClientConfig::get_socket_url() const
const utility::string_t& ClientConfig::get_socket_port() const

Description

Sets or reads HTTP, socket, and server-public-key configuration.

Parameters

Parameter	Type	Required	Description
url	const utility::string_t&	Yes	Complete HTTP or socket host URL
port	const utility::string_t&	Yes	Socket port string
key	const utility::string_t&	Yes	Server RSA public key

Return

Setters return void; getters return const references to stored strings.

Example

config.set_server_url(U("https://openapi.tigerfintech.com/gateway"));
const auto& server_url = config.get_server_url();

Permissions and Limits

Override defaults only with official environment endpoints. Getter references must not outlive the configuration.

Manage `ClientConfig` Tokens

void ClientConfig::set_token(const utility::string_t& token)
utility::string_t ClientConfig::get_token() const
bool ClientConfig::start_token_refresh(int interval_seconds,
    std::function<utility::string_t()> fetch_fn)
void ClientConfig::stop_token_refresh()

Description

Sets/reads the token thread-safely or manages background refresh with an application-provided fetch function. Prefer TigerClient::start_token_refresh(int) when using the SDK refresh request.

Parameters

Parameter	Type	Required	Description
token	const utility::string_t&	Yes	New token; never log it
interval_seconds	int	Yes	Positive refresh interval in seconds
fetch_fn	std::function callback	Yes	Takes no arguments and returns a new `utility::string_t` token

Return

get_token() returns a token copy. start_token_refresh returns true when started and false when a thread already runs. Other methods return void.

Example

config.set_token(U("redacted-token"));
const utility::string_t token_copy = config.get_token();
const bool started = config.start_token_refresh(3600, []() {
    return utility::string_t{}; // Replace with secure application token retrieval.
});
config.stop_token_refresh();

Permissions and Limits

Only one refresh thread may run per configuration. Objects captured by fetch_fn must remain alive.

Detect the US Site

bool ClientConfig::is_us()

Description

Determines from current configuration whether the US site is selected.

Parameters

None.

Return

bool.

Example

if (config.is_us()) {
    std::cout << "US environment\n";
}

Permissions and Limits

The result is local and does not perform network discovery.

`TigerClient` Documentation Scope

User-facing lifecycle APIs include concrete QuoteClient/TradeClient construction, public client_config, refresh_token(), deprecated alias query_token(), start_token_refresh(int), and stop_token_refresh(). TigerClient(const ClientConfig&) is a base-class construction detail; instantiate a concrete client instead.

The following public methods are low-level utilities rather than user-facing business APIs: post, get, and send_request handle signing and HTTP dispatch for QuoteClient and TradeClient; identifiers_to_options converts option identifiers. Prefer the typed client methods because these utilities do not provide a stable business parameter, permission, or response contract. See tiger_client.h.

See client_config.h and push_client.h for the related declarations.

Create QuoteClient and TradeClient

Create a Push Client

Get Client Configuration

Connect

Disconnect

Refresh the Access Token

Refresh-Token Compatibility Alias

Start Automatic Token Refresh

Stop Automatic Token Refresh

Construct and Configure ClientConfig

Validate ClientConfig

Access ClientConfig Endpoints

Manage ClientConfig Tokens

Detect the US Site

TigerClient Documentation Scope

Create `QuoteClient` and `TradeClient`

Construct and Configure `ClientConfig`

Validate `ClientConfig`

Access `ClientConfig` Endpoints

Manage `ClientConfig` Tokens

`TigerClient` Documentation Scope