C++ SDK

Encrypted C++ client for the GoDark API. Headers under godark/.

Requirements: Linux x86_64, C++20 (GCC ≥ 13 recommended), CMake ≥ 3.25, and OpenSSL 3.3+ with HPKE headers for source builds. The examples bundle vendors the SDK archive and headers, but the consuming process still needs compatible OpenSSL runtime libraries. Status: Beta — clone the public examples repo to get started.

Get the SDK

Clone gdx-cpp-sdk-examples. The repo vendors a prebuilt libgodark.a plus headers under sdk/ so no private package registry is required:

git clone https://github.com/gq-godark/gdx-cpp-sdk-examples.git
cd gdx-cpp-sdk-examples
cp .env.example .env
# set GODARK_API_KEY_ID, GODARK_API_SECRET, GODARK_PASSPHRASE

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
./build/examples/quickstart

You can also point an LLM / coding agent at the cloned repo and ask it to build a strategy using your credentials in .env. See the repo README for system dependencies, examples, and packaging details.

Public Conan/vcpkg packages are not yet available; until then this repo is the supported distribution.

Quickstart

Set credentials, then place a limit order over encrypted WebSocket (GodarkClient). Subscribe to orders before placing so book confirmation can wait on private updates. Limit prices must stay near the oracle or the venue rejects — see Error Codes.

#include <chrono>
#include <cstdlib>
#include <iostream>
#include <thread>

#include <godark/godark.hpp>

int main() {
    godark::ClientConfig config;
    config.api_key_id = std::getenv("GODARK_API_KEY_ID");
    config.api_secret = std::getenv("GODARK_API_SECRET");
    config.passphrase = std::getenv("GODARK_PASSPHRASE");
    config.environment = godark::Environment::the configured host;
    if (const char* edge = std::getenv("GODARK_EDGE_URL"); edge && edge[0] != '\0') {
        config.base_url = edge;
    }

    godark::GodarkClient client(config);
    client.connect();
    client.subscribe({"orders"});

    const std::string symbol = "BTC-USDC-PERP";
    auto ack = client.place_order(
        symbol,
        godark::Side::SELL,
        godark::OrderType::LIMIT,
        "0.01",
        "68000");  // within ~10% of oracle
    std::cout << "placed " << ack.order_id << "\n";

    std::this_thread::sleep_for(std::chrono::milliseconds(500));
    auto cancel = client.cancel_order(ack.order_id, symbol);
    std::cout << "cancelled " << cancel.order_id << "\n";

    client.disconnect();
    return 0;
}

See WebSocket Trading and Place Order for request fields.

Clients

Configure via ClientConfig: api_key_id, api_secret, passphrase, environment, optional base_url. With that key triple, both clients mint POST /api/v1/auth/token (client_credentials) first. WebSocket login uses the returned access_token — the secret is never sent on the socket. A legacy opaque api_key (for example a custom host test-key-*) is still sent as-is for login. GodarkRestClient places / cancels / modifies with bearer + one-shot HPKE. GodarkClient uses a sealed HPKE WebSocket session for the same ops.

Public place / modify / mass-quote / batch-modify / TP-SL APIs take human decimal strings for prices and sizes (for example "0.01", std::optional<std::string>{"68000"}), validated against instrument price_decimals / quantity_decimals from GET /api/v1/instruments. There are no double / float / integer overloads — pass string literals (or env strings) at the API boundary. The same string form is sealed on the wire (PlaceOrderInput.price field 23, quantity field 24, and the same for modify / mass-quote / triggers / TP-SL / quote_notional / min_fill_size). WebSocket Place still accepts aon, min_fill_size, and expiry_time.

Environment::the configured host is the hosted default and Environment::the configured host selects the configured host. C++ expects a ws:// or wss:// edge URL, upgrades a trailing /ws, and otherwise appends /ws/v1. See Base URLs.

subscribe and unsubscribe wait for each channel ack and throw ConnectionError immediately when the edge rejects an unknown channel. get_order and get_order_by_client_id fill status from the decrypted open-order book, a terminal ack, or order history when the edge returns an encrypted pointer or 403/404. After a successful WebSocket place, a non-empty client_order_id is registered with POST /api/v1/orders/_register_coid using that place's header correlation id as a decimal u128. The call is not retried and a 400 is returned to the caller. The local id map is written only after HTTP 200. REST place does not register a client order id: the edge arms place correlations only on the WebSocket path. get_order_by_client_id reads the edge index. The REST client refreshes an access token that is near expiry or rejected as invalid, then retries the request once.

GodarkClient methods

Types and errors

Headers under godark/: Environment, Side, OrderType, TimeInForce, OrderStatus, OrderAck, OrderUpdate, PositionUpdate. Errors: AuthenticationError, SessionError, OrderError, EncryptionError, TimeoutError, ConnectionError.

The HPKE login conn_id is an unsigned 64-bit integer (std::uint64_t).

Environment variables: OS GODARK_*, then OS GDX_*, then .env GODARK_*, then .env GDX_*. The process environment always wins over .env. Quickstart snippets use the canonical GODARK_* names.

Bundled examples

Runnable samples in the examples repo: quickstart (connect → subscribe → place → cancel) and full_trader_example (modify, mass quote, batch cancel) — ./build/examples/quickstart, ./build/examples/full_trader_example.

See also

• SDKs overview
• Programmatic Access
• Agent Access

Shared trading fields

Prices, sizes, quote notional, trigger, take-profit, and stop-loss are decimal strings.

Place options (names follow each language): reduce_only, post_only, stp_mode (UNSPECIFIED, CANCEL_RESTING, CANCEL_AGGRESSOR, CANCEL_BOTH), quote_notional, peg_offset_bps, trigger_price, take_profit_price, stop_loss_price, slippage_bps, client_order_id.

confirmation: ack returns on the sequencer acknowledgement. book waits for a terminal private order update until the place timeout.

Time in force: GTC, IOC, FOK, GTD. Order types: MARKET, LIMIT, PEG, STOP_MARKET, STOP_LIMIT. Side: BUY, SELL.

Mass quote: 1 to 20 legs. Each leg has side, price, quantity, optional cancel_order_id, time_in_force, expiry_time. post_only omitted uses the venue default.

Batch modify legs: order_id plus at least one of new_price, new_quantity.

WebSocket implements cancel-all, close-all, reverse, and TP/SL amend or cancel. REST implements one-shot encrypted place, cancel, modify, mass quote, batch cancel, batch modify, plus snapshots. REST does not implement cancel-all, close-all, reverse, or TP/SL amend.

A WebSocket place that sets client_order_id registers it after the ack. REST leaves that id unregistered.

Errors: authentication, session, connection, encryption, timeout, and order rejection with a numeric code and symbolic name. See Error Codes.

C++ reference

GodarkClient(ClientConfig) and GodarkRestClient(Config). Config fields: api_key_id, api_secret, passphrase, api_key, environment, base_url or rest_base_url, account, hpke_static_public_key_hex, auto_reconnect, stream_buffer_size, transport, symbol_map.

TransportConfig: tls_skip_verify, extra_headers, timeouts, heartbeat_interval_sec, stale_timeout_sec, missed_heartbeat_limit, use_docs_wire.

PlaceOrderOptions: reduce_only, post_only, stp_mode, peg_offset_bps, trigger_price, take_profit_price, stop_loss_price, slippage_bps, quote_notional.

Socket: connect, disconnect, logout, place_order, cancel_order, modify_order, mass_quote, update_leverage, cancel_all_orders, close_all, reverse_position, amend_tpsl, cancel_tpsl, batch_cancel, batch_modify, subscribe, unsubscribe, plus try_recv_* and on_* callbacks for the same streams as the other SDKs except account margin.

REST: snapshots, leverage get and set, order lookup, cancel by client id, get_me, get_balance, funding, open interest, volume, mass quote, and batch commands. There is no socket cancel-by-client-id.