kraken-cli CLAUDE.md

CLAUDE.md

This is experimental software. Commands execute real financial transactions. Test with kraken paper (spot) or kraken futures paper (futures) before real funds. See DISCLAIMER.md.

Integration guidance for Claude Code, Claude Desktop, and other Anthropic-powered agents interacting with kraken-cli.

Fast entry points:

• Runtime context: CONTEXT.md
• Full command contract: agents/tool-catalog.json

What is kraken-cli?

A command-line interface for trading crypto, stocks, forex, and derivatives on Kraken. Every command returns structured JSON. Designed for AI agents and automated pipelines.

Invocation

Call kraken as a subprocess. Always use -o json and redirect stderr:

kraken <command> [args...] -o json 2>/dev/null

Authentication

Set environment variables before invoking:

export KRAKEN_API_KEY="your-key"
export KRAKEN_API_SECRET="your-secret"

Public market data commands (ticker, orderbook, ohlc, trades, spreads, status) require no credentials.

Key Conventions

• stdout is valid JSON on success (exit 0), or a JSON error envelope on runtime failure (exit 1).
• The error field in error envelopes is a stable category code: api, auth, network, rate_limit, validation, config, websocket, io, timeout, parse.
• WebSocket commands emit JSONL (one JSON object per line).
• Paper trading commands (kraken paper ... for spot, kraken futures paper ... for futures) use live prices but no real money. No auth needed.
• Exit code 0 = success, 1 = runtime failure (JSON envelope on stdout), 2 = argument/usage error from the parser. With -o json, exit 2 puts a {"error":"validation"} envelope on stdout (stderr stays empty); without it, clap's usage text goes to stderr. Validate argument values against the values arrays in agents/tool-catalog.json before invoking.

Safety Rules

1. Never execute any command marked dangerous without explicit user confirmation. The dangerous field in agents/tool-catalog.json is the authoritative list (41 commands). Four of them (order buy/sell/cancel/cancel-all) also carry paper_safe: true: inside a paper workspace they execute simulated fills and need no confirmation.
2. Use --validate flag to dry-run order commands before submitting.
3. Use kraken paper (spot) or kraken futures paper (futures) commands for testing strategies safely.
4. Gate all order placement, cancellation, withdrawal, transfer, and staking operations behind user approval.
5. Never log or display API secrets.