ccapi Documentation

ccapi is a high-performance, header-only C++ library designed for streaming market data and executing trades directly from cryptocurrency exchanges. It establishes direct connections between your server and the exchange server.

Key features:

• Ultra-fast: Optimized for high-speed trading.
• Multi-language support: Provides bindings for Python, Java, C#, Go, and JavaScript.
• Bloomberg-style API: The code structure closely follows the Bloomberg API pattern.
• Broad Exchange Support: Supports a wide range of exchanges for Market Data, Execution Management, and FIX API (e.g., Binance, Coinbase, Bybit, Kraken, OKX, etc.).

ccapi supports two modes of event handling:

1. Immediate Mode: When a Session is instantiated with an EventHandler argument, processEvent is invoked immediately upon receiving an event. This runs on the thread where the underlying boost::asio::io_context is running. If an EventDispatcher is also provided, the invocation runs in the threads provided by the dispatcher, preventing the io_context thread from being blocked.
2. Batching Mode: When a Session is instantiated without an EventHandler, events are collected in an internal Queue<Event>. You can retrieve them manually using: std::vector<Event> eventList = session.getEventQueue().purge();

When creating or cancelling orders on Hyperliquid, use the exchange's specific asset ID as the instrument string instead of a ticker symbol. For example, on mainnet, BTC is represented by ID 0.

Request request(Request::Operation::CREATE_ORDER, "hyperliquid", "0");  // Corresponds to https://app.hyperliquid.xyz/trade/BTC

The Javascript API is nearly identical to the C++ API. After building and installing the Javascript binding, use npm to install dependencies and node to run the entry point.

# Inside a concrete example directory
rm -rf node_modules # if rebuild from scratch
npm install
node index.js

ccapi allows fine-grained control over market data subscriptions using options passed to the Subscription constructor:

• Market Depth Size: Use MARKET_DEPTH_MAX=N to receive snapshots for the top N levels (e.g., "MARKET_DEPTH_MAX=10").
• Conflation: Use CONFLATE_INTERVAL_MILLISECONDS=N to receive events at periodic intervals. Combine with CONFLATE_GRACE_PERIOD_MILLISECONDS=N to handle late events.
• Order Book Updates: Use MARKET_DEPTH_RETURN_UPDATE=1 to receive incremental updates instead of full snapshots.
• Candlesticks: Use CANDLESTICK_INTERVAL_SECONDS=N for exchange-provided candlesticks.
• Correlation ID: Pass a unique string as the correlationId to match specific requests/subscriptions with returned data.

There are three ways to provide credentials, listed in order of increasing priority:

1. Environment Variables: Set variables like BYBIT_API_KEY and BYBIT_API_SECRET. Some exchanges require others like OKX_API_PASSPHRASE.
2. SessionConfigs: Pass a map of credentials to the SessionConfigs object.

   sessionConfigs.setCredential({
     {"BYBIT_API_KEY", ...},
     {"BYBIT_API_SECRET", ...}
   });

3. Request or Subscription: Pass credentials directly to the Request or Subscription constructor/object.

   Request request(Request::Operation::CREATE_ORDER, "bybit", "BTCUSDT", "", {
     {"BYBIT_API_KEY", ...},
     {"BYBIT_API_SECRET", ...}
   });

To build C++ examples, you must have CMake installed. Follow these steps to create a build directory, configure the project, and compile a specific target.

Note: The resulting executable will be located in example/build/src/<example-name>/<example-name>.

mkdir example/build
cd example/build
rm -rf * # if rebuild from scratch
cmake ..
cmake --build . --target <example-name>
# Run the executable located at:
# example/build/src/<example-name>/<example-name>

The C# API is nearly identical to the C++ API. To run examples, use dotnet run while providing the path to the ccapi library and ensuring the LD_LIBRARY_PATH environment variable is set so the runtime can find the native dependencies.

Troubleshooting:

• If you see error CS0246: The type or namespace name 'ccapi' could not be found, check your ccapi assembly references.
• If you see System.DllNotFoundException: Unable to load shared library 'ccapi_binding_csharp.so', ensure LD_LIBRARY_PATH includes the directory binding/build/csharp/packaging/1.0.0.

# Inside a concrete example directory
dotnet clean # if rebuild from scratch
env LD_LIBRARY_PATH="$LD_LIBRARY_PATH:../../../build/csharp/packaging/1.0.0" dotnet run --property:CcapiLibraryPath=../../../build/csharp/packaging/1.0.0/ccapi.dll -c Release

The Go API is nearly identical to the C++ API. Crucial Step: You must source the export_compiler_options.sh file before building, as it provides the environment variables required by the cgo tool to find C/C++ headers.

Troubleshooting: If you encounter errors stating that C/C++ header files are not found, verify that you successfully sourced export_compiler_options.sh.

# Inside a concrete example directory
go clean # if rebuild from scratch
source ../../../build/go/packaging/1.0.0/export_compiler_options.sh
go build .
./main