Bitculator Data API — C++ SDK

bitculator.com · API documentation · Get an API key GitHub (header-only — consume via CMake FetchContent)

The official C++ SDK for the Bitculator Data API. Header-only, C++17. Depends on libcurl and nlohmann/json.

Keep your API key server-side. It is a Bearer token with the data-api ability and is not meant for client-side embedding.

Install

Copy include/bitculator/ onto your include path, or use CMake:

find_package(CURL REQUIRED)
find_package(nlohmann_json 3 REQUIRED)
add_subdirectory(bitculator-cpp-sdk)          # provides the bitculator::bitculator target
target_link_libraries(your_app PRIVATE bitculator::bitculator)

Dependencies (Debian/Ubuntu): apt install libcurl4-openssl-dev nlohmann-json3-dev.

Quick start

#include <bitculator/bitculator.hpp>
#include <iostream>

int main() {
    bitculator::Client client(std::getenv("BITCULATOR_API_KEY"));

    // Single resource — the { "data": ... } envelope is unwrapped; results are nlohmann::json.
    auto bitcoin = client.coins().get("bitcoin");
    std::cout << bitcoin.value("price", "") << "\n"; // "63520.780763913"

    // A paginated list.
    auto page = client.coins().list(bitculator::Params().set("per_page", 50).set("sort", "-marketcap"));
    std::cout << page.data.size() << "\n";
}

Prices are decimal strings

Prices, rates, and supplies come back as strings (e.g. "63520.780763913") to preserve full precision. Read them as std::string — never parse them into a double, which silently loses precision.

Parameters

Query parameters are built fluently; keys mirror the API's names (snake_case):

auto p = bitculator::Params()
    .set("per_page", 50)
    .set("sort", "-marketcap")
    .set("ids", std::vector<std::string>{"bitcoin", "ethereum"}); // becomes CSV

Pagination

Paginated methods return a Page. Read one page, or auto-paginate with a callback:

// One page at a time.
auto page = client.exchanges().list(bitculator::Params().set("per_page", 100));
for (;;) {
    for (const auto& exchange : page.data) std::cout << exchange.value("name", "") << "\n";
    auto next = page.next_page();
    if (!next) break;
    page = std::move(*next);
}

// Or auto-paginate across every page (return false to stop early).
client.coins().list(bitculator::Params().set("sort", "-marketcap"))
    .auto_paging([](const bitculator::json& coin) {
        std::cout << coin.value("symbol", "") << "\n";
        return true;
    });

Errors

HTTP failures throw bitculator::ApiException (extends BitculatorError) carrying the { error: { code, message, details } } envelope.

try {
    client.coins().list(bitculator::Params().set("per_page", 9999)); // over the plan cap -> 422
} catch (const bitculator::ApiException& e) {
    if (e.is_validation())        std::cerr << e.code() << " " << e.details() << "\n";
    else if (e.is_rate_limited()) std::cerr << "retry after " << e.retry_after().value_or(0) << "\n";
    else                          std::cerr << e.status() << " " << e.what() << "\n";
}

is_auth (401) · is_permission (403) · is_not_found (404) · is_validation (422) · is_rate_limited (429) · is_server (5xx). Timeouts throw TimeoutError; network failures throw ConnectionError.

Quota

Every response carries X-Quota-* headers, surfaced on the client after each call:

client.coins().list();
if (auto q = client.quota()) { /* q->limit, q->remaining, q->reset, q->raw */ }

Configuration

bitculator::Client::Options options;
options.base_url = "https://bitculator.com"; // default
options.timeout_ms = 30000;                  // default
options.max_retries = 2;                     // auto-retry 429/5xx/network; 0 to disable
bitculator::Client client("your-api-key", options);

Resources

coins · prices · markets · exchanges · wallets · global_market · sentiment · indicators · liquidations · conversion · calculators · editorial · alarms · webhooks · meta

Full endpoint reference: https://bitculator.com/en/documentation/api/v1.

License

MIT