Market Data Subscription Push

Real-Time Market Data

The C++ SDK uses IPushClient to stream market data. Updates use Protobuf and invoke callbacks asynchronously.

connect() is asynchronous. The connection callback runs after the TLS handshake and authentication frame are sent, but it does not wait for server authentication. This SDK exposes no authentication-complete callback. Each subscription snippet below assumes the connection is usable; a returned request ID only means the request was queued, and the final outcome must be parsed from msg() in the subscription-result callback.

Initialize the Streaming Client

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

using namespace TIGER_API;

ClientConfig config(false, U("your_config_directory_path"));
auto push_client = IPushClient::create_push_client(config);

// Set connected/disconnected callbacks
push_client->set_connected_callback([]() {
    std::cout << "Connected" << std::endl;
});

push_client->set_disconnected_callback([]() {
    std::cout << "Disconnected" << std::endl;
});

// Set error callback
push_client->set_inner_error_callback([](std::string err) {
    std::cout << "Error: " << err << std::endl;
});

// Establish connection
push_client->connect();

Subscribe to Stock Quotes

unsigned int IPushClient::subscribe_quote(
    const std::vector<std::string> &symbols)

Description

Subscribes to real-time stock quote updates.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of symbols

Callback Setup

The Protobuf accessor latestprice() corresponds to the latestPrice quote field.

push_client->set_quote_changed_callback([](const tigeropen::push::pb::QuoteBasicData& data) {
    std::cout << "Symbol: " << data.symbol()
              << " Price: " << data.latestprice()
              << " Volume: " << data.volume()
              << std::endl;
});

Example

std::vector<std::string> symbols = {"AAPL", "TSLA"};
push_client->subscribe_quote(symbols);

Callback Data Example

Quote (BASIC):

{
    "symbol": "AAPL",
    "type": "BASIC",
    "timestamp": "1684766012120",
    "serverTimestamp": "1684766012129",
    "avgPrice": 174.1721,
    "latestPrice": 174.175,
    "latestPriceTimestamp": "1684766011918",
    "latestTime": "05-22 10:33:31 EDT",
    "preClose": 175.16,
    "volume": "12314802",
    "amount": 2144365591.41,
    "open": 173.98,
    "high": 174.71,
    "low": 173.45,
    "marketStatus": "Trading",
    "mi": {
        "p": 174.175,
        "a": 174.1721,
        "t": "1684765980000",
        "v": "57641",
        "o": 174.21,
        "h": 174.22,
        "l": 174.14
    }
}

Best Bid/Offer (BBO):

{
    "symbol": "AAPL",
    "type": "BBO",
    "timestamp": "1676992715509",
    "askPrice": 149.96,
    "askSize": "200",
    "askTimestamp": "1676992715367",
    "bidPrice": 149.94,
    "bidSize": "700",
    "bidTimestamp": "1676992715367"
}

The ordinary TradeTick callback returns decoded cond values; see Trade Tick Conditions. The full TickData callback returns raw one-character conditions; see Trade Tick Conditions.

Unsubscribe

unsigned int IPushClient::unsubscribe_quote(
    const std::vector<std::string> &symbols)

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of symbols

Subscribe to Futures Quotes

unsigned int IPushClient::subscribe_future_quote(
    const std::vector<std::string> &symbols)

Description

Subscribes to real-time futures quote updates. Futures and stock quotes use the same set_quote_changed_callback callback.

Limitation: The current C++ SDK exposes subscribe_future_quote but no matching futures-quote unsubscribe method. unsubscribe_quote sends the stock-quote data type and cannot substitute for it. Disconnect the client to stop this stream; doing so also ends every other subscription on that connection.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of futures contract codes, e.g., `{"CL2312"}`

Callback Data Example

{
    "symbol": "ESmain",
    "type": "BASIC",
    "timestamp": "1684766824130",
    "avgPrice": 4206.476,
    "latestPrice": 4202.5,
    "preClose": 4204.75,
    "volume": "557570",
    "open": 4189,
    "high": 4221.75,
    "low": 4186.5,
    "marketStatus": "Trading",
    "preSettlement": 4204.75,
    "minTick": 0.25
}

Subscribe to Option Quotes

unsigned int IPushClient::subscribe_option_quote(
    const std::vector<std::string> &symbols)

Description

Subscribes to real-time option quote updates.

Limitation: The current C++ SDK exposes subscribe_option_quote but no matching option-quote unsubscribe method. unsubscribe_quote sends the stock-quote data type and cannot substitute for it. Disconnect the client to stop this stream; doing so also ends every other subscription on that connection.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of option identifiers

Callback Data Example

{
    "symbol": "AAPL 20230317 150.0 CALL",
    "type": "BASIC",
    "timestamp": "1676994444927",
    "latestPrice": 4.83,
    "preClose": 6.21,
    "volume": "3181",
    "amount": 939117.01,
    "open": 4.85,
    "high": 5.6,
    "low": 4.64,
    "identifier": "AAPL  230317C00150000",
    "openInt": "82677"
}

Subscribe to Market Depth

unsigned int IPushClient::subscribe_quote_depth(
    const std::vector<std::string> &symbols)

Description

Subscribes to order-book updates. US market depth updates every 300ms, while Hong Kong market depth updates every 2s.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of symbols

Callback Setup

push_client->set_quote_depth_changed_callback([](const tigeropen::push::pb::QuoteDepthData& data) {
    std::cout << "Depth data received" << std::endl;
});

Callback Data Example

{
    "symbol": "AAPL",
    "timestamp": "1676993368405",
    "ask": {
        "price": [149.69, 149.70, 149.71],
        "volume": ["100", "200", "185"]
    },
    "bid": {
        "price": [149.68, 149.67, 149.66],
        "volume": ["84", "100", "100"]
    }
}

Unsubscribe

unsigned int IPushClient::unsubscribe_quote_depth(
    const std::vector<std::string> &symbols)

Subscribe to Bar Updates

unsigned int IPushClient::subscribe_kline(
    const std::vector<std::string> &symbols)

Description

Subscribes to candlestick bar (K-line) updates.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of symbols

Callback Setup

push_client->set_kline_changed_callback([](const tigeropen::push::pb::KlineData& data) {
    std::cout << "Kline data received" << std::endl;
});

Callback Data Example

{
    "symbol": "AAPL",
    "time": "1712584560000",
    "open": 168.9779,
    "high": 169.0015,
    "low": 168.9752,
    "close": 169.0,
    "avg": 168.778,
    "volume": "3664",
    "count": 114,
    "amount": 617820.6508,
    "serverTimestamp": "1712584569746"
}

Unsubscribe

unsigned int IPushClient::unsubscribe_kline(
    const std::vector<std::string> &symbols)

Subscribe to Trade Ticks

unsigned int IPushClient::subscribe_tick(
    const std::vector<std::string> &symbols)

Description

Subscribes to trade tick updates. Trade ticks are pushed every 200ms in snapshot mode, with the latest 50 records in each push.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of symbols

Callback Setup

// Using TradeTick object callback
push_client->set_tick_changed_callback([](const TradeTick& data) {
    std::cout << "Symbol: " << data.symbol << " ticks: " << data.ticks.size() << std::endl;
});

// Or using full Protobuf TickData callback
push_client->set_full_tick_changed_callback([](const tigeropen::push::pb::TickData& data) {
    std::cout << "Full tick data received" << std::endl;
});

Callback Data Example

{
    "symbol": "AAPL",
    "secType": "STK",
    "quoteLevel": "usQuoteBasic",
    "timestamp": 1676993925700,
    "ticks": [
        {
            "sn": 116202,
            "volume": 50,
            "tickType": "*",
            "price": 149.665,
            "time": 1676993924289,
            "cond": "US_REGULAR_SALE"
        }
    ]
}

Unsubscribe

unsigned int IPushClient::unsubscribe_tick(
    const std::vector<std::string> &symbols)

Subscribe to an Entire Market

unsigned int IPushClient::subscribe_market(const std::string &market)

Description

Subscribes to quote updates for an entire market.

Parameters

Parameter	Type	Required	Description
market	string	Yes	Market, e.g., "US", "HK"

Unsubscribe

unsigned int IPushClient::unsubscribe_market(const std::string &market)

Subscribe to Stock Rankings

unsigned int IPushClient::subscribe_stock_top(
    const std::string &market,
    const std::vector<std::string> &indicators = {})

Description

Subscribes to stock-ranking updates for US and Hong Kong stocks. The server runs the ranking push task every 30 seconds; ranking size is configurable and defaults to 10. During US pre-market and after-hours sessions, only changeRate and changeRate5Min are published. Outside all supported market sessions, no updates are sent. Use the order delivered by the server.

Parameters

Parameter	Type	Required	Description
market	string	Yes	Market code. Supported values: `"US"` and `"HK"`
indicators	std::vector of std::string	No	Ranking indicators. Pass an empty vector to subscribe to all supported indicators for the market. When unsubscribing, an empty vector cancels all indicators. See the supported values below

Supported indicators values

Value	Description
`changeRate`	Daily percentage gain ranking
`changeRate5Min`	Five-minute percentage gain ranking
`turnoverRate`	Turnover-rate ranking
`amount`	Daily trading-value ranking
`volume`	Daily trading-volume ranking
`amplitude`	Daily price-amplitude ranking

Indicator values are case-sensitive wire values. Do not pass Java enum constant names such as StockRankingIndicator.ChangeRate or aliases used by another SDK.

Return Value

Returns a locally generated subscription request ID as an unsigned int. Use it to correlate the subscription-result callback. The ID does not indicate that ranking data has already arrived.

Example

// Subscribe to daily gain, trading value, and amplitude rankings for US stocks.
const std::vector<std::string> indicators = {
    "changeRate", "amount", "amplitude"
};
const unsigned int request_id = push_client->subscribe_stock_top("US", indicators);

// Pass an empty vector to subscribe to every supported indicator.
// push_client->subscribe_stock_top("US", {});

// Unsubscribe from selected indicators; an empty vector cancels all indicators.
// push_client->unsubscribe_stock_top("US", indicators);

Callback Setup

push_client->set_stock_top_changed_callback([](const tigeropen::push::pb::StockTopData& data) {
    std::cout << "Stock top data received" << std::endl;
});

Callback Data Example

{
    "market": "US",
    "timestamp": "1687271010482",
    "topData": [
        {
            "targetName": "changeRate",
            "item": [
                {"symbol": "ICAD", "latestPrice": 1.63, "targetValue": 0.393162}
            ]
        },
        {
            "targetName": "volume",
            "item": [
                {"symbol": "TSLA", "latestPrice": 263.21, "targetValue": 40190416}
            ]
        }
    ]
}

Unsubscribe

unsigned int IPushClient::unsubscribe_stock_top(
    const std::string &market,
    const std::vector<std::string> &indicators = {})

Pass the same market and indicators used for subscription. Returns a request ID.

const unsigned int request_id = push_client->unsubscribe_stock_top("US", {"changeRate"});

Subscribe to Option Rankings

unsigned int IPushClient::subscribe_option_top(
    const std::string &market,
    const std::vector<std::string> &indicators = {})

Description

Subscribes to option-ranking updates.

Parameters

Parameter	Type	Required	Description
market	string	Yes	Market
indicators	std::vector of std::string	No	Ranking indicators

Callback Setup

push_client->set_option_top_changed_callback([](const tigeropen::push::pb::OptionTopData& data) {
    std::cout << "Option top data received" << std::endl;
});

Callback Data Example

{
    "market": "US",
    "timestamp": "1687277160445",
    "topData": [
        {
            "targetName": "volume",
            "item": [
                {
                    "symbol": "SPY",
                    "expiry": "20230620",
                    "strike": "435.0",
                    "right": "PUT",
                    "totalVolume": 212478
                }
            ]
        }
    ]
}

Unsubscribe

unsigned int IPushClient::unsubscribe_option_top(
    const std::string &market,
    const std::vector<std::string> &indicators = {})

Returns a request ID; the unsubscription callback confirms the final result.

const unsigned int request_id = push_client->unsubscribe_option_top("US");

Subscribe to Cryptocurrency Quotes

unsigned int IPushClient::subscribe_cc(
    const std::vector<std::string> &symbols)

Description

Subscribes to real-time cryptocurrency quote updates.

Parameters

Parameter	Type	Required	Description
symbols	std::vector of std::string	Yes	List of cryptocurrency symbols

Unsubscribe

unsigned int IPushClient::unsubscribe_cc(
    const std::vector<std::string> &symbols)

Get Subscribed Symbols

unsigned int IPushClient::query_subscribed_symbols()

Description

Returns all symbols in the current subscriptions.

Callback Setup

push_client->set_query_subscribed_symbols_changed_callback([](const tigeropen::push::pb::Response& resp) {
    std::cout << "Subscribed symbols: " << resp.DebugString() << std::endl;
});

push_client->query_subscribed_symbols();

Full Example

#include <iostream>
#include <thread>
#include <chrono>
#include "cpprest/json.h"
#include "tigerapi/push_client.h"
#include "tigerapi/client_config.h"

using namespace TIGER_API;

int main() {
    ClientConfig config(false, U("your_config_directory_path"));
    auto push_client = IPushClient::create_push_client(config);

    // Connection callbacks
    push_client->set_connected_callback([]() {
        std::cout << "Connected" << std::endl;
    });

    push_client->set_disconnected_callback([]() {
        std::cout << "Disconnected" << std::endl;
    });

    // code() is response type 112; business success is in the JSON in msg()
    push_client->set_subscribe_callback([](const tigeropen::push::pb::Response& resp) {
        try {
            const auto result = web::json::value::parse(
                utility::conversions::to_string_t(resp.msg()));
            const bool success = result.has_field(U("code"))
                && result.at(U("code")).as_integer() == 0;
            std::cout << (success ? "Subscribe succeeded: " : "Subscribe failed: ")
                      << resp.msg() << std::endl;
        } catch (const std::exception&) {
            // Some failures return plain text instead of the normal JSON result.
            std::cout << "Subscribe failed: " << resp.msg() << std::endl;
        }
    });

    // Quote change callback
    push_client->set_quote_changed_callback([](const tigeropen::push::pb::QuoteBasicData& data) {
        std::cout << "Symbol: " << data.symbol()
                  << " Price: " << data.latestprice()
                  << std::endl;
    });

    // Tick-by-tick trade callback
    push_client->set_tick_changed_callback([](const TradeTick& data) {
        std::cout << "Tick: " << data.symbol << " count: " << data.ticks.size() << std::endl;
    });

    // Connection is asynchronous; this SDK exposes no server-authentication completion callback
    push_client->connect();

    // Subscribe
    std::vector<std::string> symbols = {"AAPL", "TSLA"};
    push_client->subscribe_quote(symbols);
    push_client->subscribe_tick(symbols);

    // Wait for streaming updates
    std::this_thread::sleep_for(std::chrono::seconds(60));

    // Unsubscribe and disconnect
    push_client->unsubscribe_quote(symbols);
    push_client->unsubscribe_tick(symbols);
    push_client->disconnect();

    return 0;
}

Request IDs and Subscription Results

Every subscribe_*, unsubscribe_*, and query_subscribed_symbols method immediately returns an unsigned int request ID. Receive the response through set_subscribe_callback, set_unsubscribe_callback, or the query callback and correlate it with Response.id(). For subscription and unsubscription completions, outer Response.code() values 112/113 are response-type discriminators, not business results. Normally parse the JSON in Response.msg() and require its inner code == 0 for success. Exception paths can return plain text, so catch parse errors and log msg() directly. See Other Push Events.

Market-Data Callback Signatures

Set the Best-Bid/Offer Callback (`set_quote_bbo_changed_callback`)

void IPushClient::set_quote_bbo_changed_callback(
    const std::function<void(const tigeropen::push::pb::QuoteBBOData&)> &cb)

Description

Registers the best-bid/offer update callback. This setter does not initiate a subscription; BBO delivery depends on the corresponding market data subscription and account access.

Parameters

Parameter	Type	Required	Description
cb	std::function callback	Yes	Accepts `const tigeropen::push::pb::QuoteBBOData&` and returns `void`

Return

void. QuoteBBOData contains Protobuf fields including symbol, timestamp, askPrice, askSize, bidPrice, and bidSize.

Example

push_client->set_quote_bbo_changed_callback(
    [](const tigeropen::push::pb::QuoteBBOData& data) {
        std::cout << data.symbol() << " "
                  << data.bidprice() << " / " << data.askprice() << '\n';
    });

Permissions and Limits

The callback executes asynchronously and the reference is valid only during callback execution. The relevant real-time/BBO market data access is required.

Setter	Exact callback type
`set_quote_changed_callback`	`std::function<void(const tigeropen::push::pb::QuoteBasicData&)>`
`set_quote_bbo_changed_callback`	`std::function<void(const tigeropen::push::pb::QuoteBBOData&)>`
`set_quote_depth_changed_callback`	`std::function<void(const tigeropen::push::pb::QuoteDepthData&)>`
`set_kline_changed_callback`	`std::function<void(const tigeropen::push::pb::KlineData&)>`
`set_tick_changed_callback`	`std::function<void(const TradeTick&)>`
`set_full_tick_changed_callback`	`std::function<void(const tigeropen::push::pb::TickData&)>`
`set_stock_top_changed_callback`	`std::function<void(const tigeropen::push::pb::StockTopData&)>`
`set_option_top_changed_callback`	`std::function<void(const tigeropen::push::pb::OptionTopData&)>`

Callbacks execute asynchronously; const references are valid only during callback execution.

Real-Time Market Data

Initialize the Streaming Client

Subscribe to Stock Quotes

Unsubscribe

Subscribe to Futures Quotes

Subscribe to Option Quotes

Subscribe to Market Depth

Unsubscribe

Subscribe to Bar Updates

Unsubscribe

Subscribe to Trade Ticks

Unsubscribe

Subscribe to an Entire Market

Unsubscribe

Subscribe to Stock Rankings

Unsubscribe

Subscribe to Option Rankings

Unsubscribe

Subscribe to Cryptocurrency Quotes

Unsubscribe

Get Subscribed Symbols

Full Example

Request IDs and Subscription Results

Market-Data Callback Signatures

Set the Best-Bid/Offer Callback (set_quote_bbo_changed_callback)

Set the Best-Bid/Offer Callback (`set_quote_bbo_changed_callback`)