SDKs
Official GoDark client libraries for programmatic trading. Each SDK implements the same public API documented in REST API and WebSocket API. Trading clients authenticate, run a Noise XK handshake, and send AES-GCM encrypted order payloads over WebSocket — see Authentication and Encryption & Transport. REST base URLs remain for auth and account APIs.
Get started
Clone a language examples repo locally. Each repo vendors the SDK (source, wheel, JAR, or static library) so you do not need a private package registry. Add your API key, secret, and passphrase, then run the samples — or point an LLM / coding agent at the cloned repo to build a strategy.
| Language | Examples repo | Clone |
|---|---|---|
| Python | gdx-python-sdk-examples | git clone https://github.com/gq-godark/gdx-python-sdk-examples.git |
| Rust | gdx-rust-sdk-examples | git clone https://github.com/gq-godark/gdx-rust-sdk-examples.git |
| JavaScript / TypeScript | gdx-js-sdk-examples | git clone https://github.com/gq-godark/gdx-js-sdk-examples.git |
| C++ | gdx-cpp-sdk-examples | git clone https://github.com/gq-godark/gdx-cpp-sdk-examples.git |
| Go | gdx-go-sdk-examples | git clone https://github.com/gq-godark/gdx-go-sdk-examples.git |
| Java | gdx-java-sdk-examples | git clone https://github.com/gq-godark/gdx-java-sdk-examples.git |
Public package registries (PyPI, npm, crates.io, pkg.go.dev, Maven Central) may be announced later. Until then, the examples repos are the supported way to get the SDKs.
Languages
| Language | Package | Requirements | Status |
|---|---|---|---|
| Python | godark | Python 3.10+ | Beta |
| Rust | godark | Rust 2021, tokio | Beta |
| JavaScript / TypeScript | @godark/sdk | Node.js 18+ | Beta |
| C++ | godark headers | C++20 | Beta |
| Go | github.com/gq-godark/gdx-go-sdk | Go 1.22+ | Beta |
| Java | vendored godark-*-all.jar | JDK 17+ | Beta |
Choose a client
| Client | Transport | Best for |
|---|---|---|
GodarkClient | WebSocket (/ws/v1) | Encrypted trading: place / cancel / modify, mass quote, batch cancel, order + position streams |
MarketDataClient | WebSocket (/ws/gomarket) | External venue reference data — not GoDark's internal order book |
GodarkClient handles WS login, Noise XK session setup, and order encryption automatically. GodarkRestClient may still be exported for residual HTTP helpers (identity / balance); encrypted order place / cancel / modify is WebSocket-only.
Environment variables
Copy .env.example to .env in the cloned examples repo (Java: examples/.env). Required for public testnet:
| Variable | Required | Description |
|---|---|---|
GODARK_API_KEY_ID | Yes | API key id from API Key Management (client_id) |
GODARK_API_SECRET | Yes | API secret (client_secret) |
GODARK_PASSPHRASE | Yes | Passphrase for API key-pair auth |
GODARK_EDGE_URL | No | Override edge / WebSocket origin (testnet preset is the default) |
Resolution order for each setting: OS GODARK_*, then OS GDX_*, then .env GODARK_*, then .env GDX_*. The process environment always wins over .env in every language, including Java (examples/.env is only used when neither OS alias is set). Language pages use the same order; quickstart snippets show the canonical GODARK_* names.
Create a testnet key: app.godark-dex.com → fund via faucet → Settings → API Key Management → Create API Key.
Network endpoints
| Network | REST | WebSocket |
|---|---|---|
| Mainnet | https://api.godarkdex.com/api/v1 | wss://api.godarkdex.com/ws/v1 |
| Testnet | https://api.godark-dex.com/api/v1 | wss://api.godark-dex.com/ws/v1 |
| Localnet | http://127.0.0.1:4000/api/v1 | ws://127.0.0.1:4000/ws/v1 |
GODARK_EDGE_URL is a WebSocket origin: wss://api.godark-dex.com or wss://…/ws/v1. Helpers append /ws/v1 if missing. They do not strip /api/v1 or rewrite https → wss. REST column URLs are for auth and account APIs, not GodarkClient input.
WebSocket trading flow
Every SDK follows the same sequence for encrypted orders:
- Connect to
/ws/v1withGODARK_API_KEY_ID,GODARK_API_SECRET, andGODARK_PASSPHRASE - The SDK sends WebSocket
loginwith that key pair, then runs a Noise XK handshake and derives the AES-256-GCM session key - Subscribe to
orders(book confirmation waits on private order updates) place_order/cancel_order/modify_order(and mass quote / batch cancel) over the multiplexed socket
See WebSocket Trading. Limit prices must stay near the oracle or the venue rejects — see Error Codes.
Error handling
All SDKs expose typed exceptions. WebSocket rejects carry a numeric error_code and a symbolic name — see Error Codes. Names below are the Python/C++/Go/JS/Rust spellings; Java uses GodarkException, SessionException, OrderRejectedException, and similar.
| Error | Typical cause |
|---|---|
AuthenticationError | Invalid credentials or failed WS login |
SessionError | Noise XK handshake or session setup failure |
EncryptionError | Encrypt/decrypt or framing error |
OrderError | Venue risk rejection or trading error (symbolic error_code when present) |
TimeoutError | Await/poll exceeded deadline |
ConnectionError | Network or WebSocket disconnect |
Related documentation
- Programmatic Access — getting started with the API
- Agent Access — MCP server and CLI for coding agents
- Trading Concepts — order types, TIF, execution attributes (read before placing orders)
- Rules & Limits — rate limits and trade protection