Agent Access

Let an AI agent — Cursor, Claude Desktop, Codex, Continue, a CI job, or your own script — trade on GoDark the way a person uses the web app: check a balance, read the book, place an order, watch the fills. Clone a public SDK examples repo, add your API credentials, and point the agent at that checkout; it can read the SDK, run the samples, and build a strategy. You don't read an endpoint reference — the agent does.

The agent layer ships inside the GoDark SDK bundled in each examples repo — same package, nothing extra to obtain. Underneath, the MCP server and the CLI both call the same SDK: one implementation of the crypto, session, and protobuf logic, reached two ways.

What you get

• MCP server — exposes GoDark as native tools any MCP-compatible agent can call (balance, positions, quotes, place/cancel/modify orders). This is the standard interface coding agents speak.
• godark CLI — the same actions as shell commands with --json output and --dry-run, for bash, cron, or GitHub Actions. Deterministic exit codes: 0 on success, non-zero with a structured error otherwise.
• SKILL.md — a single file that teaches the agent what exists, so it never has to guess or read docs.

Read tools (balance, positions, quotes) are available by default. Write tools (place, cancel, modify) are opt-in — the operator enables them explicitly.

1. Clone an examples repo and build it

Pick a language and clone its public examples repo. Each repo vendors the SDK under sdk/ — no private package registry required. Follow the repo README.md to install deps and run samples; the agent layer (the godark CLI and godark-mcp server, when present) builds alongside the SDK:

git clone https://github.com/gq-godark/gdx-python-sdk-examples.git   # or any language above
cd gdx-python-sdk-examples
cp .env.example .env   # Java: examples/.env.example → examples/.env
# set GODARK_API_KEY_ID, GODARK_API_SECRET, GODARK_PASSPHRASE
# then build / run per the repo README

Two ways to use an agent with the checkout:

1. Point the agent at the repo — open the clone in Cursor (or similar) and ask it to build a strategy from the vendored SDK + examples.
2. MCP / CLI — if your SDK build produces godark-mcp / godark, register the MCP server below.

When using MCP, launch commands by language:

The rest of this page applies to all of them. See SDKs for language-specific clone and setup commands.

2. Set your credentials

Create credentials once (frontend → fund via faucet → Settings → API Key Management → Create API Key), then pass them as environment variables — never commit them to a config file:

export GODARK_API_KEY_ID="gdk_your_key_id"
export GODARK_API_SECRET="your_api_secret"
export GODARK_PASSPHRASE="your_passphrase"

# Allow the agent to place/cancel/modify orders (omit for read-only)
export GODARK_WRITE_ENABLED=1

These can also live in a .env next to the SDK (cp .env.example .env); the OS environment always wins. See Authentication for how the key pair and passphrase work.

3. Register the MCP server with your agent

Add GoDark to your agent's MCP config. The block below is the cross-tool standard — the same format Cursor (.cursor/mcp.json), Claude Desktop, Codex, and most coding agents read. Point it at the launch command for your SDK from the table above:

{
  "mcpServers": {
    "godark-trading": {
      "type": "stdio",
      "command": "godark-mcp",
      "env": {
        "GODARK_API_KEY_ID": "${env:GODARK_API_KEY_ID}",
        "GODARK_API_SECRET": "${env:GODARK_API_SECRET}",
        "GODARK_PASSPHRASE": "${env:GODARK_PASSPHRASE}",
        "GODARK_WRITE_ENABLED": "1"
      }
    }
  }
}

That's the whole setup. Your agent now has the GoDark tools — no code to write. (For the Python SDK, set "command": "python" and "args": ["-m", "godark_mcp.server"].)

Let the agent discover the rest

This is the point of the agent layer: you don't explain GoDark to your agent — the package does. Enable the MCP server (above), point the agent at the cloned examples repo, or hand it the SKILL.md that ships with the SDK. Either way it reads the full tool catalog — every tool, its parameters, and the response schema — then drives them on your behalf:

---
name: godark-trading
description: Trade on the GoDark dark pool. Use for checking balance, positions,
  quotes, leverage, and placing/cancelling/modifying orders.
---

# GoDark Trading

Run `godark_doctor` first to verify connectivity. Always check balance before trading.

Read tools: godark_doctor, godark_get_me, godark_get_balance, godark_get_leverage,
godark_get_positions, godark_get_order, godark_get_quote
Write tools (require GODARK_WRITE_ENABLED=1): godark_place_order (supports dry_run),
godark_cancel_order, godark_modify_order

Symbols: BTC-USDC-PERP, ETH-USDC-PERP, SOL-USDC-PERP
All tools return {ok: bool, data?: {...}, error?: {code, message}}.

You give the agent one config (or one file) and tell it to use GoDark; it reads, understands, and trades.

Tools the agent can call

Every tool — and its matching CLI command — returns the same envelope: {ok, data?, error?: {code, message}}. The agent parses it once.

Write tools only appear when GODARK_WRITE_ENABLED=1, so a read-only agent can explore safely.

CLI usage (scripts and CI)

The same actions are available as the godark command. Every command takes --json for machine-readable output:

godark doctor --json                 # verify auth + connectivity
godark balance --json                # shielded pool balance
godark leverage --json               # per-symbol leverage
godark quote BTC-USDC-PERP --json    # best bid/ask (symbol is positional)

# Preview an order without sending it
godark order place --symbol BTC-USDC-PERP --side buy --qty 0.01 \
  --type LIMIT --price 100000 --tif GTC --dry-run --json

# Send it
godark order place --symbol BTC-USDC-PERP --side buy --qty 0.01 \
  --type LIMIT --price 100000 --tif GTC --json

godark order get <order-id> --json
godark order cancel <order-id> --json
godark order modify <order-id> --price 99500 --json

In CI, a job can run the --dry-run form on a pull request and the real order on merge — exit code 0 is success, non-zero is a rejection with a structured reason (insufficient margin, symbol not found, rate limit).

Recommended agent flow

1. godark_doctor — confirm everything is connected
2. godark_get_balance — check available margin
3. godark_get_quote — read the current market
4. godark_place_order with dry_run: true — preview the order
5. godark_place_order with dry_run: false — submit
6. godark_get_order — track the fill
7. godark_get_positions — monitor exposure

For the REST/WebSocket details these tools call underneath, see Programmatic Access.