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. You hand it the package and tell it to use GoDark; it discovers every tool on its own and does the heavy lifting. You don't read an endpoint reference — the agent does.

The agent layer ships inside the GoDark SDK you receive during onboarding — 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. Get the SDK and build it

Your SDK arrives as an archive during onboarding (for example gdx-rust-sdk.zip or godark-cpp-sdk.tar.gz). Extract it and build it following the README.md inside — the agent layer (the godark CLI and godark-mcp server) is included and builds alongside the SDK:

tar -xzf godark-cpp-sdk.tar.gz      # or: unzip gdx-rust-sdk.zip
cd godark-cpp-sdk
# build per the bundled README (toolchain differs by language)

The tools and CLI are identical in every language; only the build step and the launch command differ:

The rest of this page applies to all of them.

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), or hand the agent the SKILL.md that ships in the archive. 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.