Docs
中文

Market Data Subscription Push

Real-Time Market Data

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

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

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList of symbols

Callback Setup

Register the quote-update callback with set_quote_changed_callback:

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"
}

Unsubscribe from Stock Quotes

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

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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.

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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.

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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.

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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 from Market Depth

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

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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 from Bar Updates

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 tick-by-tick trade updates.

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList 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 from Trade Ticks

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

ParameterTypeRequiredDescription
marketstringYesMarket, e.g., "US", "HK"

Unsubscribe from an Entire Market

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. During regular trading hours, the server sends an update about every 30 seconds. During US pre-market and after-hours sessions, only changeRate and changeRate5Min are published. Outside all supported market sessions, no updates are sent. Each subscribed indicator contains up to 30 ranked symbols; use the order delivered by the server.

Parameters

ParameterTypeRequiredDescription
marketstringYesMarket code. Supported values: "US" and "HK"
indicatorsstd::vector of std::stringNoRanking 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

ValueDescription
changeRateDaily percentage gain ranking
changeRate5MinFive-minute percentage gain ranking
turnoverRateTurnover-rate ranking
amountDaily trading-value ranking
volumeDaily trading-volume ranking
amplitudeDaily 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}
            ]
        }
    ]
}

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

ParameterTypeRequiredDescription
marketstringYesMarket
indicatorsstd::vector of std::stringNoRanking 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
                }
            ]
        }
    ]
}

Subscribe to Cryptocurrency Quotes

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

Description

Subscribes to real-time cryptocurrency quote updates.

Parameters

ParameterTypeRequiredDescription
symbolsstd::vector of std::stringYesList of cryptocurrency symbols

Unsubscribe from Cryptocurrency Quotes

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 "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;
    });

    // Subscribe success/failure callback
    push_client->set_subscribe_callback([](const tigeropen::push::pb::Response& resp) {
        std::cout << "Subscribe result: " << resp.DebugString() << 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;
    });

    // Connect
    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 final result through set_subscribe_callback, set_unsubscribe_callback, or the query callback and correlate it with Response.id(); Response.code() and Response.msg() contain the server result. 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 quote subscription and account entitlement.

Parameters

ParameterTypeRequiredDescription
cbstd::function callbackYesAccepts const tigeropen::push::pb::QuoteBBOData& and returns void

Return

void. The generated QuoteBBOData.pb.h model contains Protobuf fields including symbol, timestamp, askPrice, askSize, bidPrice, and bidSize; the current generated header is authoritative.

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 entitlement is required. See include/tigerapi/push_client.h and include/openapi_pb/pb_source/QuoteBBOData.pb.h.

SetterExact callback type
set_quote_changed_callbackstd::function<void(const tigeropen::push::pb::QuoteBasicData&)>
set_quote_bbo_changed_callbackstd::function<void(const tigeropen::push::pb::QuoteBBOData&)>
set_quote_depth_changed_callbackstd::function<void(const tigeropen::push::pb::QuoteDepthData&)>
set_kline_changed_callbackstd::function<void(const tigeropen::push::pb::KlineData&)>
set_tick_changed_callbackstd::function<void(const TradeTick&)>
set_full_tick_changed_callbackstd::function<void(const tigeropen::push::pb::TickData&)>
set_stock_top_changed_callbackstd::function<void(const tigeropen::push::pb::StockTopData&)>
set_option_top_changed_callbackstd::function<void(const tigeropen::push::pb::OptionTopData&)>

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

Unsubscribe from Stock Rankings

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"});

Unsubscribe from Option Rankings

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");

Updated 7 days ago

Did this page help you?