Merge pull request #535 from crypto-chassis/develop

Release

Author: cryptochassis

README.md

@@ -1,5 +1,6 @@
 # Notice
-* New release has about 20% reduction in cpu usage.
+* Small breaking change: renamed `toStringPretty` to `toPrettyString`.
+* Added FIX API support for binance.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -48,6 +49,7 @@
       * [Thread safety](#thread-safety)
       * [Enable library logging](#enable-library-logging)
       * [Set timer](#set-timer)
+      * [Heartbeat](#heartbeat)
   * [Performance Tuning](#performance-tuning)
   * [Known Issues and Workarounds](#known-issues-and-workarounds)
 
@@ -56,11 +58,6 @@
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 
-
-
-
-
-
 # ccapi
 * A header-only C++ library for streaming market data and executing trades directly from cryptocurrency exchanges (i.e. the connections are between your server and the exchange server without anything in-between).
 * Bindings for other languages such as Python, Java, C#, Go, and Javascript are provided.
@@ -69,7 +66,7 @@
 * Supported exchanges:
   * Market Data: ascendex, [binance](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), [binance-usds-futures](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), [binance-coin-futures](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), bitfinex, bitget, bitget-futures, bitmart, bitmex, bitstamp, [bybit](https://www.bybit.com/invite?ref=XNYP2K), coinbase, [cryptocom](https://crypto.com/exch/tqj4b8x48w), deribit, erisx (Cboe Digital), [gateio](https://www.gate.com/signup/VLUQXVFWAW?ref_type=103), [gateio-perpetual-futures](https://www.gate.com/signup/VLUQXVFWAW?ref_type=103), gemini, huobi, huobi-usdt-swap, huobi-coin-swap, kraken, kraken-futures, kucoin, kucoin-futures, mexc, mexc-futures, [okx](https://www.okx.com/join/47636709), whitebit.
   * Execution Management: ascendex, [binance](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), [binance-usds-futures](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), [binance-coin-futures](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), bitfinex, bitget, bitget-futures, bitmart, bitmex, bitstamp, [bybit](https://www.bybit.com/invite?ref=XNYP2K), coinbase, [cryptocom](https://crypto.com/exch/tqj4b8x48w), deribit, erisx (Cboe Digital), [gateio](https://www.gate.com/signup/VLUQXVFWAW?ref_type=103), [gateio-perpetual-futures](https://www.gate.com/signup/VLUQXVFWAW?ref_type=103), gemini, huobi, huobi-usdt-swap, huobi-coin-swap, kraken, kraken-futures, kucoin, kucoin-futures, mexc, [okx](https://www.okx.com/join/47636709).
-  * FIX: coinbase, gemini.
+  * FIX: [binance](https://www.marketwebb.net/activity/referral-entry/CPA?ref=CPA_00WFM0HU96), coinbase, gemini.
 * Join us on Discord https://discord.gg/b5EKcp9s8T and Medium https://cryptochassis.medium.com.
 
 ## Branches
@@ -232,7 +229,7 @@ Logger* Logger::logger = nullptr;  // This line is needed.
 class MyEventHandler : public EventHandler {
  public:
   void processEvent(const Event& event, Session* sessionPtr) override {
-    std::cout << "Received an event:\n" + event.toStringPretty(2, 2) << std::endl;
+    std::cout << "Received an event:\n" + event.toPrettyString(2, 2) << std::endl;
   }
 };
 
@@ -311,7 +308,7 @@ class MyEventHandler : public EventHandler {
  public:
   void processEvent(const Event& event, Session* sessionPtr) override {
     if (event.getType() == Event::Type::SUBSCRIPTION_STATUS) {
-      std::cout << "Received an event of type SUBSCRIPTION_STATUS:\n" + event.toStringPretty(2, 2) << std::endl;
+      std::cout << "Received an event of type SUBSCRIPTION_STATUS:\n" + event.toPrettyString(2, 2) << std::endl;
     } else if (event.getType() == Event::Type::SUBSCRIPTION_DATA) {
       for (const auto& message : event.getMessageList()) {
         std::cout << std::string("Best bid and ask at ") + UtilTime::getISOTimestamp(message.getTime()) + " are:" << std::endl;
@@ -505,7 +502,7 @@ Logger* Logger::logger = nullptr;  // This line is needed.
 class MyEventHandler : public EventHandler {
  public:
   void processEvent(const Event& event, Session* sessionPtr) override {
-    std::cout << "Received an event:\n" + event.toStringPretty(2, 2) << std::endl;
+    std::cout << "Received an event:\n" + event.toPrettyString(2, 2) << std::endl;
   }
 };
 
@@ -605,7 +602,7 @@ class MyEventHandler : public EventHandler {
  public:
   void processEvent(const Event& event, Session* sessionPtr) override {
     if (event.getType() == Event::Type::SUBSCRIPTION_STATUS) {
-      std::cout << "Received an event of type SUBSCRIPTION_STATUS:\n" + event.toStringPretty(2, 2) << std::endl;
+      std::cout << "Received an event of type SUBSCRIPTION_STATUS:\n" + event.toPrettyString(2, 2) << std::endl;
       auto message = event.getMessageList().at(0);
       if (message.getType() == Message::Type::SUBSCRIPTION_STARTED) {
         Request request(Request::Operation::CREATE_ORDER, "okx", "BTC-USDT");
@@ -618,7 +615,7 @@ class MyEventHandler : public EventHandler {
         sessionPtr->sendRequest(request);
       }
     } else if (event.getType() == Event::Type::SUBSCRIPTION_DATA) {
-      std::cout << "Received an event of type SUBSCRIPTION_DATA:\n" + event.toStringPretty(2, 2) << std::endl;
+      std::cout << "Received an event of type SUBSCRIPTION_DATA:\n" + event.toPrettyString(2, 2) << std::endl;
     }
   }
 };
@@ -843,61 +840,66 @@ For a specific exchange and instrument, submit a simple limit order.
 [C++](example/src/fix_simple/main.cpp) / [Python](binding/python/example/fix_simple/main.py) / [Java](binding/java/example/fix_simple/Main.java) / [C#](binding/csharp/example/fix_simple/MainProgram.cs) / [Go](binding/go/example/fix_simple/main.go) / [Javascript](binding/javascript/example/fix_simple/index.js)
 ```
 #include "ccapi_cpp/ccapi_session.h"
+
 namespace ccapi {
 
 Logger* Logger::logger = nullptr;  // This line is needed.
+
 class MyEventHandler : public EventHandler {
  public:
+  MyEventHandler(const std::string& fixSubscriptionCorrelationId) : fixSubscriptionCorrelationId(fixSubscriptionCorrelationId) {}
+
   void processEvent(const Event& event, Session* sessionPtr) override {
-    if (event.getType() == Event::Type::AUTHORIZATION_STATUS) {
-      std::cout << "Received an event of type AUTHORIZATION_STATUS:\n" + event.toStringPretty(2, 2) << std::endl;
-      auto message = event.getMessageList().at(0);
-      if (message.getType() == Message::Type::AUTHORIZATION_SUCCESS) {
-        Request request(Request::Operation::FIX, "okx", "", "same correlation id for subscription and request");
-        request.appendParamFix({
+    std::cout << "Received an event:\n" + event.toPrettyString(2, 2) << std::endl;
+    if (!willSendRequest) {
+      sessionPtr->setTimer("id", 1000, nullptr, [this, sessionPtr]() {
+        Request request(Request::Operation::FIX, "binance");
+        request.appendFixParam({
             {35, "D"},
-            {11, "6d4eb0fb-2229-469f-873e-557dd78ac11e"},
-            {55, "BTC-USDT"},
+            {11, request.generateNextClientOrderId()},
+            {55, "BTCUSDT"},
             {54, "1"},
-            {44, "20000"},
-            {38, "0.001"},
+            {44, "100000"},
+            {38, "0.0001"},
             {40, "2"},
             {59, "1"},
         });
-        sessionPtr->sendRequestByFix(request);
-      }
-    } else if (event.getType() == Event::Type::FIX) {
-      std::cout << "Received an event of type FIX:\n" + event.toStringPretty(2, 2) << std::endl;
+        sessionPtr->sendRequestByFix(this->fixSubscriptionCorrelationId, request);
+      });
+      willSendRequest = true;
     }
   }
+
+ private:
+  std::string fixSubscriptionCorrelationId;
+  bool willSendRequest{};
 };
 
 } /* namespace ccapi */
+
 using ::ccapi::MyEventHandler;
 using ::ccapi::Session;
 using ::ccapi::SessionConfigs;
 using ::ccapi::SessionOptions;
 using ::ccapi::Subscription;
 using ::ccapi::UtilSystem;
+
 int main(int argc, char** argv) {
-  if (UtilSystem::getEnvAsString("OKX_API_KEY").empty()) {
-    std::cerr << "Please set environment variable OKX_API_KEY" << std::endl;
+  if (UtilSystem::getEnvAsString("BINANCE_FIX_API_KEY").empty()) {
+    std::cerr << "Please set environment variable BINANCE_FIX_API_KEY" << std::endl;
     return EXIT_FAILURE;
   }
-  if (UtilSystem::getEnvAsString("OKX_API_SECRET").empty()) {
-    std::cerr << "Please set environment variable OKX_API_SECRET" << std::endl;
-    return EXIT_FAILURE;
-  }
-  if (UtilSystem::getEnvAsString("OKX_API_PASSPHRASE").empty()) {
-    std::cerr << "Please set environment variable OKX_API_PASSPHRASE" << std::endl;
+  if (UtilSystem::getEnvAsString("BINANCE_FIX_API_PRIVATE_KEY_PATH").empty()) {
+    std::cerr << "Please set environment variable BINANCE_FIX_API_PRIVATE_KEY_PATH" << std::endl;
     return EXIT_FAILURE;
   }
   SessionOptions sessionOptions;
   SessionConfigs sessionConfigs;
-  MyEventHandler eventHandler;
+  std::string fixSubscriptionCorrelationId("any");
+  MyEventHandler eventHandler(fixSubscriptionCorrelationId);
   Session session(sessionOptions, sessionConfigs, &eventHandler);
-  Subscription subscription("okx", "", "FIX", "", "same correlation id for subscription and request");
-  session.subscribeByFix(subscription);
+  Subscription subscription("binance", "", "FIX", "", fixSubscriptionCorrelationId);
+  session.subscribe(subscription);
   std::this_thread::sleep_for(std::chrono::seconds(10));
   session.stop();
   std::cout << "Bye" << std::endl;
@@ -906,56 +908,97 @@ int main(int argc, char** argv) {
 ```
 **Output:**
 ```console
-Received an event of type AUTHORIZATION_STATUS:
+Received an event:
+  Event [
+    type = SESSION_STATUS,
+    messageList = [
+      Message [
+        type = SESSION_CONNECTION_UP,
+        recapType = UNKNOWN,
+        time = 1970-01-01T00:00:00.000000000Z,
+        timeReceived = 2025-08-08T18:50:06.816550779Z,
+        elementList = [
+          Element [
+            tagValueList = [
+
+            ],
+            nameValueMap = {
+              CONNECTION_ID = IF8j4HbdLP0,
+              CONNECTION_URL = tcp+tls://fix-oe.binance.com:9000
+            }
+          ]
+        ],
+        correlationIdList = [ any ],
+      ]
+    ]
+  ]
+Received an event:
   Event [
     type = AUTHORIZATION_STATUS,
     messageList = [
       Message [
         type = AUTHORIZATION_SUCCESS,
         recapType = UNKNOWN,
         time = 1970-01-01T00:00:00.000000000Z,
-        timeReceived = 2021-05-25T05:05:15.892366000Z,
+        timeReceived = 2025-08-08T18:50:06.819417404Z,
         elementList = [
           Element [
-            tagValueMap = {
-              96 = 0srtt0WetUTYHiTpvyWnC+XKKHCzQQIJ/8G9lE4KVxM=,
-              98 = 0,
-              108 = 15,
-              554 = 26abh7of52i
+            tagValueList = [
+              (35, "A"),
+              (98, "0"),
+              (108, "60"),
+              (25037, "e9ed8253-8f49-4a1b-bba9-718ff73991e5")
+            ],
+            nameValueMap = {
+
             }
           ]
         ],
-        correlationIdList = [ same correlation id for subscription and request ]
+        correlationIdList = [ any ],
       ]
     ]
   ]
-Received an event of type FIX:
+Received an event:
   Event [
     type = FIX,
     messageList = [
       Message [
         type = FIX,
         recapType = UNKNOWN,
         time = 1970-01-01T00:00:00.000000000Z,
-        timeReceived = 2021-05-25T05:05:15.984090000Z,
+        timeReceived = 2025-08-08T18:50:07.820112736Z,
         elementList = [
           Element [
-            tagValueMap = {
-              11 = 6d4eb0fb-2229-469f-873e-557dd78ac11e,
-              17 = b7caec79-1bc8-460e-af28-6489cf12f45e,
-              20 = 0,
-              37 = 458acfe5-bdea-46d2-aa87-933cda84163f,
-              38 = 0.001,
-              39 = 0,
-              44 = 20000,
-              54 = 1,
-              55 = BTC-USDT,
-              60 = 20210525-05:05:16.008,
-              150 = 0
+            tagValueList = [
+              (35, "8"),
+              (17, "100146443390"),
+              (11, "x-XHKUG2CH-1754679007000"),
+              (37, "47156106695"),
+              (38, "0.00010000"),
+              (40, "2"),
+              (54, "1"),
+              (55, "BTCUSDT"),
+              (44, "100000.00000000"),
+              (59, "1"),
+              (60, "20250808-18:50:07.819027"),
+              (25018, "20250808-18:50:07.819027"),
+              (25001, "3"),
+              (150, "0"),
+              (14, "0.00000000"),
+              (151, "0.00010000"),
+              (25017, "0.00000000"),
+              (1057, "Y"),
+              (32, "0.00000000"),
+              (39, "0"),
+              (636, "Y"),
+              (25023, "20250808-18:50:07.819027")
+            ],
+            nameValueMap = {
+
             }
           ]
         ],
-        correlationIdList = [ same correlation id for subscription and request ]
+        correlationIdList = [ any ],
       ]
     ]
   ]
@@ -976,7 +1019,7 @@ std::vector<Event> eventList = session.getEventQueue().purge();
 An example can be found [here](example/src/market_data_advanced_subscription/main.cpp).
 
 #### Thread safety
-* The following methods are implemented to be thread-safe: `Session::sendRequest`, `Session::subscribe`, `Session::sendRequestByFix`, `Session::subscribeByFix`, `Session::setTimer`, all public methods in `Queue`.
+* The following methods are implemented to be thread-safe: `Session::sendRequest`, `Session::subscribe`, `Session::sendRequestByFix`, `Session::setTimer`, all public methods in `Queue`.
 * If you choose to inject an external `boost::asio::io_context` to `ServiceContext`, the `boost::asio::io_context` has to run on a single thread to ensure thread safety.
 
 #### Enable library logging
@@ -1007,7 +1050,7 @@ Logger* Logger::logger = &myLogger;
 
 #### Set timer
 
-[C++](example/src/utility_set_timer/main.cpp)
+[C++](example/src/set_timer/main.cpp)
 
 To perform an asynchronous wait, use the utility method `setTimer` in class `Session`. The handlers are invoked in the same threads as the `processEvent` method in the `EventHandler` class. The `id` of the timer should be unique. `delayMilliseconds` can be 0.
 ```
@@ -1019,6 +1062,16 @@ sessionPtr->setTimer(
     []() { std::cout << std::string("Timer success handler is triggered at ") + UtilTime::getISOTimestamp(UtilTime::now()) << std::endl; });
 ```
 
+#### Heartbeat
+
+[C++](example/src/heartbeat/main.cpp)
+
+To receive heartbeat events, instantiate a `Subscription` object with field `HEARTBEAT` and subscribe it.
+```
+Subscription subscription("", "", "HEARTBEAT", "HEARTBEAT_INTERVAL_MILLISECONDS=1000");
+session.subscribe(subscription);
+```
+
 ## Performance Tuning
 * Turn on compiler optimization flags (e.g. `cmake -DCMAKE_BUILD_TYPE=Release ...`).
 * Enable link time optimization (e.g. in CMakeLists.txt `set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)` before a target is created). Note that link time optimization is only applicable to static linking.

binding/java/example/execution_management_simple_request/Main.java

@@ -10,7 +10,7 @@ public class Main {
   static class MyEventHandler extends EventHandler {
     @Override
     public void processEvent(Event event, Session session) {
-      System.out.println(String.format("Received an event:\n%s", event.toStringPretty(2, 2)));
+      System.out.println(String.format("Received an event:\n%s", event.toPrettyString(2, 2)));
           }
   }
   public static void main(String[] args) {

binding/java/example/execution_management_simple_subscription/Main.java

@@ -14,7 +14,7 @@ static class MyEventHandler extends EventHandler {
     @Override
     public void processEvent(Event event, Session session) {
       if (event.getType() == Event.Type.SUBSCRIPTION_STATUS) {
-        System.out.println(String.format("Received an event of type SUBSCRIPTION_STATUS:\n%s", event.toStringPretty(2, 2)));
+        System.out.println(String.format("Received an event of type SUBSCRIPTION_STATUS:\n%s", event.toPrettyString(2, 2)));
         var message = event.getMessageList().get(0);
         if (message.getType() == Message.Type.SUBSCRIPTION_STARTED) {
           var request = new Request(Request.Operation.CREATE_ORDER, "okx", "BTC-USDT");
@@ -26,7 +26,7 @@ public void processEvent(Event event, Session session) {
           session.sendRequest(request);
         }
       } else if (event.getType() == Event.Type.SUBSCRIPTION_DATA) {
-        System.out.println(String.format("Received an event of type SUBSCRIPTION_DATA:\n%s", event.toStringPretty(2, 2)));
+        System.out.println(String.format("Received an event of type SUBSCRIPTION_DATA:\n%s", event.toPrettyString(2, 2)));
       }
           }
   }

binding/java/example/fix_simple/Main.java

@@ -15,7 +15,7 @@ static class MyEventHandler extends EventHandler {
     @Override
     public void processEvent(Event event, Session session) {
       if (event.getType() == Event.Type.AUTHORIZATION_STATUS) {
-        System.out.println(String.format("Received an event of type AUTHORIZATION_STATUS:\n%s", event.toStringPretty(2, 2)));
+        System.out.println(String.format("Received an event of type AUTHORIZATION_STATUS:\n%s", event.toPrettyString(2, 2)));
         var message = event.getMessageList().get(0);
         if (message.getType() == Message.Type.AUTHORIZATION_SUCCESS) {
           var request = new Request(Request.Operation.FIX, "coinbase", "", "same correlation id for subscription and request");
@@ -28,11 +28,11 @@ public void processEvent(Event event, Session session) {
           param.add(new PairIntString(38, "0.001"));
           param.add(new PairIntString(40, "2"));
           param.add(new PairIntString(59, "1"));
-          request.appendParamFix(param);
+          request.appendFixParam(param);
           session.sendRequestByFix(request);
         }
       } else if (event.getType() == Event.Type.FIX) {
-        System.out.println(String.format("Received an event of type FIX:\n%s", event.toStringPretty(2, 2)));
+        System.out.println(String.format("Received an event of type FIX:\n%s", event.toPrettyString(2, 2)));
       }
           }
   }
@@ -55,7 +55,7 @@ public static void main(String[] args) {
     var config = new SessionConfigs();
     var session = new Session(option, config, eventHandler);
     var subscription = new Subscription("coinbase", "", "FIX", "", "same correlation id for subscription and request");
-    session.subscribeByFix(subscription);
+    session.subscribe(subscription);
     try {
       Thread.sleep(10000);
     } catch (InterruptedException e) {

binding/java/example/market_data_simple_request/Main.java

@@ -10,7 +10,7 @@ public class Main {
   static class MyEventHandler extends EventHandler {
     @Override
     public void processEvent(Event event, Session session) {
-      System.out.println(String.format("Received an event:\n%s", event.toStringPretty(2, 2)));
+      System.out.println(String.format("Received an event:\n%s", event.toPrettyString(2, 2)));
           }
   }
   public static void main(String[] args) {