Java SDK

Encrypted Java client for the GoDark API. Distributed as a shaded godark-*-all.jar (not published to Maven Central yet).

Requirements: JDK 17+
Status: Beta — clone the public examples repo to get started.

Get the SDK

Clone gdx-java-sdk-examples. The repo vendors a shaded godark-*-all.jar under sdk/lib/ so no private Maven registry is required:

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

cd examples
./gradlew --no-daemon runQuickstart
./gradlew --no-daemon runFullTraderExample

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

Public Maven Central release is 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.

import godark.Environment;
import godark.GodarkClient;
import godark.Types;

public class Quickstart {
  public static void main(String[] args) throws Exception {
    GodarkClient.Builder b =
        GodarkClient.builder()
            .baseUrl(yourOrigin)
            .apiKeyId(System.getenv("GODARK_API_KEY_ID"))
            .apiSecret(System.getenv("GODARK_API_SECRET"))
            .passphrase(System.getenv("GODARK_PASSPHRASE"));
    String edge = System.getenv("GODARK_EDGE_URL");
    if (edge != null && !edge.isBlank()) {
      b.baseUrl(edge);
    }

    GodarkClient client = b.build();
    try {
      client.connect();
      client.subscribe("orders");
      Types.OrderAck ack =
          client.placeOrder(
              "BTC-USDC-PERP",
              "SELL",
              "LIMIT",
              "0.01",
              "68000", // within ~10% of oracle
              "GTC",
              false,
              null,
              null);
      System.out.println("placed " + ack.orderId());
      Thread.sleep(500);
      Types.OrderAck cancel = client.cancelOrder(ack.orderId(), "BTC-USDC-PERP");
      System.out.println("cancelled " + cancel.orderId());
    } finally {
      client.disconnect();
    }
  }
}

See WebSocket Trading and Place Order for request fields.

Clients

Build GodarkClient with GodarkClient.builder(): .apiKeyId(), .apiSecret(), .passphrase(), .environment(). With a key id + secret + passphrase, connect() mints POST /api/v1/auth/token (client_credentials) and logs in with the returned access_token — the raw key triple is never sent on the socket. Legacy opaque apiKey is still sent as-is for local test-key-*. 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 prices and sizes are decimal strings only — numbers (double / Double / long sizing) are not accepted. The SDK normalizes validated strings to each instrument’s price_decimals / quantity_decimals (from GET /api/v1/instruments) on the sealed protobuf wire (PlaceOrderInput.price field 23, quantity field 24) via Decimals.normalizeDecimal.

the default environment preset is the hosted default and an alternate environment preset selects the configured host. Java accepts ws(s) or http(s) edge URLs, rewrites HTTP schemes for WebSocket use, upgrades a trailing /ws, and otherwise appends /ws/v1. See Base URLs.

GodarkClient methods

Types and errors

Public API lives in the godark package: Environment, Enums, Types, Proto, and exception types (GodarkException, SessionException, OrderRejectedException, EncryptionException, etc.). See Error Codes.

The protobuf conn_id is an unsigned 64-bit wire value represented by Java long.

Environment variables: OS GODARK_*, then OS GDX_*, then .env GODARK_*, then .env GDX_*. The process environment always wins over .env. Gradle samples load examples/.env only for keys not already exported. The snippet uses System.getenv with canonical GODARK_* names; runQuickstart also reads examples/.env.

Bundled examples

Gradle tasks under the examples group in the examples repo:

./gradlew tasks --group=examples
./gradlew --no-daemon runQuickstart

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.

Java reference

GodarkClient.Builder and GodarkRestClient.Builder. Builder methods: apiKey, apiKeyId, apiSecret, passphrase, baseUrl or restBaseUrl, environment, account, hpkeStaticPublicKeyHex, symbolMap, transport, autoReconnect, streamBufferSize, placeOrderTerminalTimeout.

Checked GodarkException hierarchy: AuthenticationException, SessionException, ConnectionException, EncryptionException, CommandTimeoutException, RestEnvelopeException, OrderRejectedException.

Socket: connect, logout, disconnect, placeOrder, getOrderByClientOrderId, cancelOrderByClientId, cancelOrder, modifyOrder, massQuote, updateLeverage, cancelAllOrders, closeAll, reversePosition, amendTpsl, cancelTpsl, batchCancel, batchModify, subscribe, unsubscribe, poll*Update, and listener setters.

REST placeOrder rejects a non-blank client order id. REST provides snapshots, leverage, order lookup, funding, open interest, volume, mass quote, batch commands, and awaitTerminalStatus. It does not provide profile or balance reads.

PlaceOrderOptions.defaults() matches the shared field list. Side and order type on most calls are strings. STP uses the protobuf enum.