Skip to content

About

openapi c++ sdk

Resources

Stars

7 stars

Watchers

5 watching

Forks

Repository files navigation

Tiger OpenAPI C++ SDK

Version License

Tiger OpenAPI C++ SDK 是老虎证券开放平台的官方 C++ 客户端,提供交易、行情、长连接推送等功能。

English | 中文

主要特性

  • 🚀 完整的交易接口支持(下单、撤单、查询持仓等)
  • 📊 实时行情数据获取(K线、报价、逐笔成交等)
  • 📰 资讯查询(个股新闻、市场要闻)
  • 🔌 WebSocket 长连接推送(持仓、订单、行情实时推送)
  • 🌐 跨平台支持(macOS、Linux、Windows)
  • 🛡️ 类型安全的 C++ API 设计
  • 📦 支持静态库和动态库编译

环境要求

平台 编译器 CMake 依赖管理
macOS Clang (Xcode) 3.15+ Homebrew + 源码
Linux GCC/G++ 3.15+ apt + 源码
Windows MSVC 2019/2022 3.15+ vcpkg

核心依赖

  • Boost 1.86.0(system, thread, log, program_options, chrono, filesystem)
  • OpenSSL 1.0.1+(推荐 3.x)
  • cpprestsdk 最新版(HTTP 客户端)
  • Protobuf 5.28.3
  • Abseil 20240722.0(固定的 C++14 兼容版本,Protobuf 运行时依赖)
  • C++ 标准: C++14(最低构建基线,支持 C++17 用户项目直接编译和链接)

快速开始

一键构建(推荐)

macOS/Linux

# 赋予执行权限(仅首次)
chmod +x scripts/build_linux_mac.sh

# 默认构建(Debug 模式,自动安装依赖并运行 demo)
./scripts/build_linux_mac.sh

# Release 模式构建
BUILD_TYPE=Release ./scripts/build_linux_mac.sh

# 仅构建 SDK,跳过 demo
SKIP_DEMO=1 ./scripts/build_linux_mac.sh

脚本会自动完成:

  1. 安装系统依赖(Homebrew/apt)
  2. 编译 Boost、cpprestsdk、Abseil 20240722.0、Protobuf
  3. 构建 SDK(Debug + Release)
  4. 构建并运行 demo

Windows

# 在 Developer PowerShell 中构建 SDK(x64 Release MD)
msbuild openapi-cpp-sdk.vcxproj /t:Rebuild /p:Configuration=Release-MD /p:Platform=x64 /m /nr:false

# 构建 demo
msbuild demo\openapi_cpp_test\openapi_cpp_test.vcxproj /t:Rebuild /p:Configuration=Release-MD /p:Platform=x64 /m /nr:false

# 重新生成 Windows 8 个预编译 zip 包
powershell -ExecutionPolicy Bypass -File scripts\package_windows.ps1

使用预编译库

如果不想从源码编译,可以直接使用 output/ 目录下的预编译库:

output/
├── Mac/
│   ├── Debug.zip      # macOS Debug 静态库 + 头文件
│   └── Release.zip    # macOS Release 静态库 + 头文件
├── Linux/
│   ├── Debug.zip
│   └── Release.zip
└── Windows/
    ├── readme.md
    ├── x64/
    │   ├── Debug-MD.zip
    │   ├── Debug-MT.zip
    │   ├── Release-MD.zip
    │   └── Release-MT.zip
    └── Win32/
        ├── Debug-MD.zip
        ├── Debug-MT.zip
        ├── Release-MD.zip
        └── Release-MT.zip

手动编译

macOS

1. 安装基础工具

brew install cmake wget automake libtool pkg-config openssl@3

# 一键构建脚本会从源码构建 Protobuf v5.28.3 和固定的 Abseil 20240722.0,
# 不要另外安装或使用 Homebrew 最新版 Abseil。

2. 安装 Boost

cd /usr/local
wget https://archives.boost.io/release/1.86.0/source/boost_1_86_0.tar.bz2
tar --bzip2 -xf boost_1_86_0.tar.bz2
cd boost_1_86_0
./bootstrap.sh
./b2 headers
./b2 -j $(sysctl -n hw.ncpu)

3. 编译 cpprestsdk

cd /tmp
git clone https://github.com/microsoft/cpprestsdk.git
cd cpprestsdk
git submodule update --init
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_INSTALL_PREFIX=/usr/local/opt/cpprestsdk \
    -DBUILD_SHARED_LIBS=ON \
    -DBUILD_SAMPLES=OFF \
    -DBUILD_TESTS=OFF \
    -DBOOST_ROOT=/usr/local/boost_1_86_0 \
    -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3) \
    -DCMAKE_CXX_FLAGS="-Wno-error=null-pointer-subtraction -w"
cmake --build build -- -j $(sysctl -n hw.ncpu)
sudo cmake --install build

4. 编译 Abseil

cd /tmp
git clone --depth 1 --branch 20240722.0 https://github.com/abseil/abseil-cpp.git
cd abseil-cpp
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_STANDARD=14 \
    -DCMAKE_INSTALL_PREFIX=/usr/local/opt/abseil-20240722.0 \
    -DABSL_BUILD_TESTING=OFF \
    -DABSL_PROPAGATE_CXX_STD=ON \
    -DBUILD_SHARED_LIBS=ON
cmake --build build -- -j $(sysctl -n hw.ncpu)
sudo cmake --install build

5. 编译 Protobuf

cd /tmp
curl -sL https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protobuf-28.3.tar.gz -o protobuf-28.3.tar.gz
tar xzf protobuf-28.3.tar.gz
cd protobuf-28.3
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local/opt/protobuf-v5.28.3 \
    -DCMAKE_CXX_STANDARD=14 \
    -Dprotobuf_BUILD_TESTS=OFF \
    -Dprotobuf_ABSL_PROVIDER=package \
    -Dabsl_DIR=/usr/local/opt/abseil-20240722.0/lib/cmake/absl \
    -DCMAKE_PREFIX_PATH=/usr/local/opt/abseil-20240722.0
cmake --build build -- -j $(sysctl -n hw.ncpu)
sudo cmake --install build

6. 构建 SDK

cd <project_root>

cmake -S . -B build/Debug \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_INSTALL_PREFIX=/usr/local/opt/tigerapi/Debug \
    -DBOOST_ROOT=/usr/local/boost_1_86_0 \
    -DCMAKE_PREFIX_PATH="/usr/local/opt/cpprestsdk;/usr/local/opt/abseil-20240722.0;/usr/local/opt/protobuf-v5.28.3" \
    -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3)
cmake --build build/Debug -- -j $(sysctl -n hw.ncpu)
sudo cmake --install build/Debug

7. 构建 Demo

cd demo
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Debug \
    -DBOOST_ROOT=/usr/local/boost_1_86_0 \
    -DTIGERAPI_INCLUDE_DIR=/usr/local/opt/tigerapi/Debug/include \
    -DTIGERAPI_LIBRARY=/usr/local/opt/tigerapi/Debug/lib/libtigerapi.a \
    -DCPPREST_INCLUDE_DIR=/usr/local/opt/cpprestsdk/include \
    -DCPPREST_LIBRARY=/usr/local/opt/cpprestsdk/lib/libcpprest.dylib \
    -DProtobuf_INCLUDE_DIR=/usr/local/opt/protobuf-v5.28.3/include \
    -DProtobuf_LIBRARY=/usr/local/opt/protobuf-v5.28.3/lib/libprotobuf.dylib \
    -DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3)
cmake --build build -- -j $(sysctl -n hw.ncpu)

# 运行 demo(需要设置动态库路径)
export DYLD_LIBRARY_PATH="/usr/local/opt/cpprestsdk/lib:/usr/local/opt/protobuf-v5.28.3/lib:$DYLD_LIBRARY_PATH"
./build/openapi_cpp_test

Linux (Ubuntu)

1. 安装系统依赖

sudo apt-get update
sudo apt-get install -y git wget bzip2 unzip gcc g++ libtool automake autoconf \
    build-essential cmake libssl-dev libabsl-dev zlib1g-dev pkg-config

2-6. 编译步骤

与 macOS 类似,主要区别:

  • 去掉 OPENSSL_ROOT_DIR 参数(Linux 上 OpenSSL 在系统路径)
  • 使用 LD_LIBRARY_PATH 代替 DYLD_LIBRARY_PATH
export LD_LIBRARY_PATH="/usr/local/opt/cpprestsdk/lib:/usr/local/opt/protobuf-v5.28.3/lib:$LD_LIBRARY_PATH"

Windows

Windows 平台提供两种编译方式:

方式一:使用 Visual Studio(推荐)

  1. 前置要求

    • Visual Studio 2019 或 2022
    • 安装"使用 C++ 的桌面开发"工作负载
  2. 准备依赖

    项目使用 vcpkg 管理依赖,支持两种方式:

    自动安装(推荐):

    # vcpkg 会根据 vcpkg.json 自动安装依赖
    # 首次打开解决方案时自动触发

    手动安装:

    git clone https://github.com/microsoft/vcpkg .vcpkg
    .\.vcpkg\bootstrap-vcpkg.bat -disableMetrics
     .\.vcpkg\vcpkg install --triplet x64-windows
  3. 打开并编译

    • 双击打开 openapi-cpp-sdk.sln
    • 选择配置(推荐 Release-MD|x64)
    • 右键解决方案 → 生成解决方案
  4. 配置说明

    解决方案提供 8 种配置组合:

    配置 平台 运行时库 说明
    Debug-MD x64/Win32 /MDd Debug + 动态运行时
    Debug-MT x64/Win32 /MTd Debug + 静态运行时
    Release-MD x64/Win32 /MD Release + 动态运行时(推荐)
    Release-MT x64/Win32 /MT Release + 静态运行时
  5. 编译产物

    output/Windows/
    ├── x64/
    │   ├── Release-MD/
    │   │   ├── openapi-cpp-sdk.dll
    │   │   ├── openapi-cpp-sdk.lib
    │   │   └── openapi_cpp_test.exe
    │   └── Release-MT/
    └── Win32/
        └── ...
    
  6. 依赖路径配置

    工程文件已配置好依赖路径:

    • Boost: .deps/boost/boost_1_86_0(可通过环境变量 BOOST_ROOT 覆盖)
    • vcpkg 依赖: vcpkg_installed/x64-windows/(自动管理)
    • SDK 头文件: include/

方式二:使用 CMake 命令行

推荐使用仓库脚本统一准备依赖并调用 CMake。Windows 下默认使用 vcpkg 安装树中的 Protobuf 5.28.3、Abseil、OpenSSL 和 cpprestsdk,避免与生成代码版本不一致;同时保留 Protobuf 源码安装路径,便于和 macOS/Linux 的 CMake 构建方式保持一致。

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force

# 构建 SDK + demo(x64 Release MD)
.\scripts\build_windows.ps1 -Triplet x64-windows -BuildType Release -Runtime MD

# 仅构建 SDK
.\scripts\build_windows.ps1 -Triplet x64-windows -BuildType Release -Runtime MD -SkipDemo

# 使用 Protobuf 源码安装路径(默认是 vcpkg)
.\scripts\build_windows.ps1 -Triplet x64-windows -BuildType Release -Runtime MD -ProtobufProvider Source

# 重新生成 output/Windows/{Win32,x64} 下 8 个 zip 包
.\scripts\package_windows.bat

# 仅重新压缩已有输出目录,不重新编译
.\scripts\package_windows.bat -SkipBuild

如果需要手动执行 CMake,可参考以下命令。

  1. 安装 vcpkg
git clone https://github.com/microsoft/vcpkg .vcpkg
.\.vcpkg\bootstrap-vcpkg.bat -disableMetrics
  1. 安装依赖
.\.vcpkg\vcpkg install --triplet x64-windows
  1. 构建 SDK
$env:VCPKG_ROOT = "$PWD\.vcpkg"
$toolchain = "$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake"

cmake -S . -B build\windows -A x64 `
    -DCMAKE_BUILD_TYPE=Release `
    -DCMAKE_TOOLCHAIN_FILE=$toolchain `
    -DVCPKG_TARGET_TRIPLET=x64-windows `
    -DCMAKE_PREFIX_PATH="$PWD\.deps\install\x64-windows\boost-1.86.0;$PWD\vcpkg_installed\x64-windows" `
    -DBOOST_ROOT="$PWD\.deps\install\x64-windows\boost-1.86.0" `
    -DProtobuf_DIR="$PWD\vcpkg_installed\x64-windows\share\protobuf" `
    -DCMAKE_INSTALL_PREFIX=output\Windows\x64\Release-MD

cmake --build build\windows --config Release
cmake --install build\windows --config Release
  1. 构建 Demo
cmake -S demo -B demo\build\windows -A x64 `
    -DCMAKE_BUILD_TYPE=Release `
    -DCMAKE_TOOLCHAIN_FILE=$toolchain `
    -DVCPKG_TARGET_TRIPLET=x64-windows `
    -DCMAKE_PREFIX_PATH="$PWD\.deps\install\x64-windows\boost-1.86.0;$PWD\vcpkg_installed\x64-windows;output\Windows\x64\Release-MD" `
    -DTIGERAPI_INCLUDE_DIR=output\Windows\x64\Release-MD\include `
    -DTIGERAPI_LIBRARY=output\Windows\x64\Release-MD\lib\tigerapi.lib `
    -DProtobuf_DIR="$PWD\vcpkg_installed\x64-windows\share\protobuf"

cmake --build demo\build\windows --config Release --target openapi_cpp_test

使用示例

HTTP 行情接口

#include "tigerapi/quote_client.h"

TigerClient client;
client.init("your_tiger_id", "your_private_key", "your_account");

// 获取 K 线数据
std::vector<std::string> symbols = {"AAPL", "TSLA"};
ResponseModel response = client.grab_quote_kline(symbols, "day", "2024-01-01", "2024-12-31");

逐笔成交 cond 字段说明

trade_tick 接口和 push 层返回的 cond 字段已由 SDK 转换为可读字符串,含义如下:

美股(US)

值 含义
US_REGULAR_SALE 常规交易(Regular Sale)
US_BUNCHED_TRADE 批量交易(Bunched Trade)
US_CASH_TRADE 现金交易(Cash Trade)
US_INTERMARKET_SWEEP 跨市场交易(Intermarket Sweep)
US_BUNCHED_SOLD_TRADE 批量卖出(Bunched Sold Trade)
US_PRICE_VARIATION_TRADE 离价交易(Price Variation Trade)
US_ODD_LOT_TRADE 碎股交易(Odd Lot Trade)
US_RULE_127_OR_155_TRADE 纽交所第 127/155 条交易
US_SOLD_LAST 延迟交易(Sold Last)
US_MARKET_CENTER_CLOSE_PRICE 中央收市价(Market Center Close Price)
US_NEXT_DAY_TRADE 隔日交易(Next Day Trade)
US_MARKET_CENTER_OPENING_TRADE 中央开盘价交易(Market Center Opening Trade)
US_PRIOR_REFERENCE_PRICE 前参考价(Prior Reference Price)
US_MARKET_CENTER_OPEN_PRICE 中央开盘价(Market Center Open Price)
US_SELLER 卖方(Seller)
US_FORM_T 盘前盘后交易(Form T)
US_EXTENDED_TRADING_HOURS 延长交易时段(Extended Trading Hours)
US_CONTINGENT_TRADE 合单交易(Contingent Trade)
US_AVERAGE_PRICE_TRADE 均价交易(Average Price Trade)
US_CROSS_TRADE 跨市场交易(Cross Trade)
US_SOLD_OUT_OF_SEQUENCE 场外售出(Sold Out of Sequence)
US_DERIVATIVELY_PRICED 衍生工具定价(Derivatively Priced)
US_QUALIFIED_CONTINGENT_TRADE 合单交易(Qualified Contingent Trade)

港股(HK)

值 含义
HK_AUTOMATCH_NORMAL 自动对盘(Automatch Normal)
HK_ODD_LOT_TRADE 碎股交易(Odd Lot Trade)
HK_AUCTION_TRADE 竞价交易(Auction Trade)
HK_OVERSEAS_TRADE 场外交易(Overseas Trade)
HK_LATE_TRADE_OFF_EXCHG 场外延迟交易(Late Trade Off Exchange)
HK_NON_DIRECT_OFF_EXCHG_TRADE 非自动对盘(Non-Direct Off Exchange Trade)
HK_DIRECT_OFF_EXCHG_TRADE 同券商自动对盘(Direct Off Exchange Trade)
HK_AUTOMATIC_INTERNALIZED 自动内部化(Automatic Internalized)

WebSocket 长连接推送

#include "tigerapi/push_client.h"

// 创建推送客户端
PushClient push_client(tiger_id, private_key, "your_language");

// 订阅持仓推送
push_client.subscribe_position();

// 订阅行情推送
push_client.subscribe_quote({"AAPL", "TSLA"});

// 连接并接收推送
push_client.connect();

更多示例请参考 demo/openapi_cpp_test/openapi_cpp_test.cpp。

夜盘资产口径 AssetQuoteType

查询和订阅资产 / 持仓时,可以指定服务端用哪个行情口径给资产估值:

值 含义
AssetQuoteType::ETH 盘前盘后(默认,不传即为此值)
AssetQuoteType::RTH 常规交易时段
AssetQuoteType::OVERNIGHT 夜盘时段

仅美股有夜盘时段。 其他市场传 OVERNIGHT 无实际意义。

拉取侧——以下方法各有一个末位参数为 AssetQuoteType 的重载:

TradeClient trade_client(client_config);

// 按夜盘口径查持仓
value positions = trade_client.get_positions(account, AssetQuoteType::OVERNIGHT);
vector<Position> list = trade_client.get_position_list(account, AssetQuoteType::OVERNIGHT);

// 按夜盘口径查资产
value prime = trade_client.get_prime_asset(account, U("USD"), AssetQuoteType::OVERNIGHT);
PortfolioAccount portfolio = trade_client.get_prime_portfolio(account, U("USD"), AssetQuoteType::OVERNIGHT);
value asset = trade_client.get_asset(account, value::array(), true, false, AssetQuoteType::OVERNIGHT);
value aggregate = trade_client.get_aggregate_assets(account, U(""), U("USD"), AssetQuoteType::OVERNIGHT);

订阅侧——subscribe_asset / subscribe_position 各有一个带口径的重载:

push_client->subscribe_asset(account, AssetQuoteType::OVERNIGHT);
push_client->subscribe_position(account, AssetQuoteType::OVERNIGHT);

不带口径的原有重载全部保留,行为与之前版本完全一致(服务端按 ETH 处理),老代码无需改动。

查询资讯

SDK 提供两个资讯查询接口(NewsClient),均为 HTTP 请求,与交易接口共用同一主网关(POST /gateway,method + biz_content,签名方式与其他 HTTP 接口一致):

接口 method 说明
个股新闻 news_stock_list 查询单只股票的资讯列表,按 page_count / page_size 翻页
市场要闻 news_highlight_list 查询市场要闻列表,按 last_id 游标翻页

个股新闻

#include "tigerapi/news_client.h"

ClientConfig config(U("your_tiger_id"), U("your_private_key"), U("your_account"));
NewsClient news_client(config);

// 查询 AAPL 个股新闻:第 1 页、每页 20 条、中文内容
NewsPage page = news_client.get_stock_news(U("AAPL"), U("zh_CN"), 1, 20);
for (const NewsItem &item : page.items) {
    ucout << item.title << U(" — ") << item.url << endl;
}

参数说明:

参数 必填 说明
symbol 是 股票代码,仅支持单只(该接口不支持批量查询)
lang 否 语言枚举:zh_CN / zh_TW / en_US
page_count 否 页码,0(缺省)= 不发送,服务端默认 1;显式传值须 >= 1(越界由服务端校验报错)
page_size 否 每页条数,0(缺省)= 不发送,服务端默认 20;显式传值须 1–50(闭区间)

市场要闻

#include "tigerapi/news_client.h"

NewsClient news_client(config);

// 从最新一条开始拉取要闻
NewsPage page = news_client.get_market_news(U("zh_CN"));

// 下一页:把本页最后一条的 id 作为 last_id 传回
if (!page.items.empty()) {
    utility::string_t next_last_id = page.items.back().id;
    NewsPage next = news_client.get_market_news(U("zh_CN"), next_last_id);
}

参数说明:

参数 必填 说明
lang 否 同上
last_id 否 游标。不传从最新开始;下一页传本页 items 最后一条的 id。该接口仅有这一种翻页方式(无 page_count / page_size 参数)

响应结构

两个接口的返回值都是 NewsPage(响应 data 字段的驼峰解析结果),字段一一对应:

字段 类型 说明
items vector<NewsItem> 当前页资讯列表
page_count int 当前页码(要闻接口恒为 1)
page_size int 每页条数
total_page int 总页数
total_size int 总条数

NewsItem:

字段 类型 说明
id utility::string_t 资讯 ID(要闻接口游标翻页的 last_id 取值来源)
title utility::string_t 标题
summary utility::string_t 摘要
pub_timestamp long long 发布时间戳(秒级)
url utility::string_t 原文链接

项目结构

openapi-cpp-sdk/
├── include/                    # 头文件
│   ├── tigerapi/              # SDK 公共头文件
│   ├── cpprest/               # cpprestsdk 头文件
│   ├── google/protobuf/       # Protobuf 5.28.3 头文件
│   └── openapi_pb/            # Protobuf 生成的消息定义
├── src/                       # SDK 源码实现
├── demo/                      # 示例代码
│   └── openapi_cpp_test/
├── scripts/                   # 构建脚本
│   ├── build_linux_mac.sh    # macOS/Linux 一键构建
│   └── build_windows.ps1     # Windows CMake 构建脚本
├── output/                    # 编译产物
│   ├── Mac/
│   ├── Linux/
│   └── Windows/
└── CMakeLists.txt            # CMake 配置

常见问题

macOS

Q: 找不到 OpenSSL

# 指定 OpenSSL 路径
-DOPENSSL_ROOT_DIR=$(brew --prefix openssl@3)

Q: 架构不匹配(arm64 vs x86_64)

修改 CMakeLists.txt 和 demo/CMakeLists.txt 中的架构参数:

# ARM Mac(默认)
set(CMAKE_CXX_FLAGS "-arch arm64 -std=c++14 ...")

# Intel Mac
set(CMAKE_CXX_FLAGS "-arch x86_64 -std=c++14 ...")

Q: 运行时找不到动态库

export DYLD_LIBRARY_PATH="/usr/local/opt/cpprestsdk/lib:/usr/local/opt/protobuf-v5.28.3/lib:$DYLD_LIBRARY_PATH"

Linux

Q: 运行时找不到 .so 文件

export LD_LIBRARY_PATH="/usr/local/opt/cpprestsdk/lib:/usr/local/opt/protobuf-v5.28.3/lib:$LD_LIBRARY_PATH"

Windows

Q: vcpkg bootstrap 失败

确保安装了 Visual Studio "使用 C++ 的桌面开发"工作负载。

Q: 运行时库不匹配(MT vs MD)

确保 SDK 和 demo 使用相同的 -DCMAKE_MSVC_RUNTIME_LIBRARY 设置。

所有平台

Q: Protobuf 版本冲突

确保使用 Protobuf 5.28.3 和固定的 Abseil 20240722.0,以保持 C++14 支持。Windows 工程已通过 PROTOBUF_USE_DLLS 与 vcpkg DLL 版本保持一致。

Q: 编译警告被当作错误

# 添加编译参数关闭警告
-DCMAKE_CXX_FLAGS="-w"

更新日志

查看 CHANGELOG.md 了解版本更新历史。

许可证

Apache License 2.0

相关链接

技术支持

如有问题,请通过以下方式联系:

About

openapi c++ sdk

Resources

Stars

7 stars

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages