kraken-cli-main

Imported from x402agent/openclawd-main (kraken-cli-main/AGENTS.md). Install upstream with npx skills add x402agent/openclawd-main --skill kraken-cli-main. Copyright stays with the author.

Agent Integration Guide: kraken-cli

This is experimental software. Commands execute real financial transactions on the Kraken exchange. Test with kraken paper before using real funds. See DISCLAIMER.md for full terms.

Self-contained guide for integrating kraken-cli into AI agents, MCP clients, and automated pipelines.

Fast entry points:

• Runtime agent context: CONTEXT.md
• Full command contract: agents/tool-catalog.json
• Error routing contract: agents/error-catalog.json
• Workflow skills: skills/

Installation

Single binary, no runtime dependencies.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh | sh

Pre-built binaries for macOS (Apple Silicon, Intel) and Linux (x86_64, ARM64) are also available on the GitHub Releases page.

Verify: kraken --version

Authentication

Environment variables (recommended for agents)

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

# Futures (optional, separate credentials)
export KRAKEN_FUTURES_API_KEY="your-futures-key"
export KRAKEN_FUTURES_API_SECRET="your-futures-secret"

No config file needed. No interactive prompts. The CLI reads credentials from the environment.

Credential resolution order

1. Command-line flags (--api-key, --api-secret)
2. Environment variables (KRAKEN_API_KEY, KRAKEN_API_SECRET)
3. Config file (~/.config/kraken/config.toml)

Required permissions by command group

Invocation Pattern

Every command follows the same pattern:

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

Rules:

• Always pass -o json for structured output.
• Redirect stderr: 2>/dev/null or 2>debug.log.
• stdout contains only valid JSON (success) or a JSON error envelope (failure).
• Exit code 0 = success, non-zero = failure.

Basic examples

# Public data (no auth)
kraken ticker BTCUSD -o json
kraken orderbook BTCUSD --count 10 -o json
kraken ohlc BTCUSD --interval 60 -o json

# Private data
kraken balance -o json
kraken open-orders -o json

# Trading
kraken order buy BTCUSD 0.001 --type limit --price 50000 -o json
kraken order cancel TXID123 -o json

# Spot paper trading (no auth)
kraken paper init --balance 10000 -o json
kraken paper buy BTCUSD 0.01 -o json
kraken paper status -o json

# Futures paper trading (no auth)
kraken futures paper init --balance 10000 -o json
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json
kraken futures paper positions -o json

Asset Classes

The CLI supports six asset classes through the same command surface. Most commands default to crypto. For other asset classes, pass the --asset-class flag.

Crypto spot (default)

No flag needed. Covers 1,400+ pairs with margin up to 10x on major pairs.

kraken ticker BTCUSD -o json
kraken order buy BTCUSD 0.001 --type limit --price 50000 -o json
kraken order buy BTCUSD 0.001 --type limit --price 50000 --leverage 5 -o json

Tokenized U.S. stocks & ETFs (xStocks)

Requires --asset-class tokenized_asset. Stock symbols use the x suffix: AAPL becomes AAPLx, TSLA becomes TSLAx. 79 assets available with margin up to 3x on the top 10. Not available in the USA.

kraken ticker AAPLx/USD --asset-class tokenized_asset -o json
kraken order buy AAPLx/USD 0.1 --type limit --price 200 --asset-class tokenized_asset -o json
kraken order buy TSLAx/USD 0.5 --type limit --price 250 --asset-class tokenized_asset --leverage 3 -o json

To list all xStocks assets: kraken assets --asset-class tokenized_asset -o json

Forex

Requires --asset-class forex on market data commands. 11 fiat pairs including EUR/USD, GBP/USD, USD/JPY, AUD/USD.

kraken ticker EURUSD --asset-class forex -o json

Futures

Separate engine with its own credentials (KRAKEN_FUTURES_API_KEY, KRAKEN_FUTURES_API_SECRET). Covers crypto perpetuals, 5 forex perps (PF_EURUSD, PF_GBPUSD, PF_AUDUSD, PF_CHFUSD, PF_JPYUSD), 11 equity/index perps (PF_AAPLXUSD, PF_NVDAXUSD, PF_TSLAXUSD, PF_SPYXUSD, PF_QQQXUSD, PF_SPXUSD, and others), and fixed-date contracts. Leverage up to 50x.

kraken futures instruments -o json                                            # list all contracts
kraken futures order buy PF_XBTUSD 1 --type limit --price 50000 -o json      # crypto perp
kraken futures order buy PF_AAPLXUSD 10 --type limit --price 200 -o json     # equity perp
kraken futures order buy FI_XBTUSD_260327 1 --type limit --price 50000 -o json  # fixed-date

Earn / staking

kraken earn strategies --asset ETH -o json
kraken earn allocate <STRATEGY_ID> 1.0 -o json

Output Parsing

Success response

stdout contains the API response as JSON. Structure varies by command.

{"BTCUSD":{"a":["67234.10","1","1.000"],"b":["67234.00","1","1.000"]}}

Error response

On non-zero exit, stdout contains a JSON error envelope:

{"error": "auth", "message": "Authentication failed: EAPI:Invalid key"}

The error field is a stable category code. The message field is human-readable and not stable.

WebSocket streaming

WebSocket commands emit NDJSON (one JSON object per line):

kraken ws ticker BTC/USD -o json | while read -r line; do
  echo "$line" | jq -r '.data[0].last'
done

Error Handling

Route on the error field, not on message strings.

Error handling pattern

RESULT=$(kraken balance -o json 2>/dev/null)
EXIT=$?

if [ $EXIT -eq 0 ]; then
  echo "$RESULT" | jq .
else
  CATEGORY=$(echo "$RESULT" | jq -r '.error // "unknown"')
  case "$CATEGORY" in
    auth)       echo "Re-authenticate" ;;
    rate_limit)
      SUGGESTION=$(echo "$RESULT" | jq -r '.suggestion // "Wait and retry"')
      DOCS=$(echo "$RESULT" | jq -r '.docs_url // ""')
      echo "Rate limited. $SUGGESTION"
      echo "Docs: $DOCS"
      ;;
    network)    sleep 5; echo "Retry" ;;
    *)          echo "Failed: $CATEGORY" ;;
  esac
fi

For the full error catalog with backoff strategies and example envelopes, see agents/error-catalog.json.

Rate Limiting

The CLI does not pre-throttle or retry rate-limited requests. The Kraken API server enforces rate limits, and the CLI returns the error immediately with structured fields that agents should read:

• suggestion: specific guidance including tier limits, per-endpoint costs, and recommended alternatives
• docs_url: link to the relevant Kraken rate limit documentation
• retryable: true for all rate limit errors (the agent decides whether and when to retry)

Kraken rate limit systems

Kraken enforces multiple independent rate limit systems. The suggestion field in rate limit errors describes which system was triggered and its parameters. For full documentation:

• Spot REST counter: docs.kraken.com/api/docs/guides/spot-rest-ratelimits
• Spot trading engine (per-pair): docs.kraken.com/api/docs/guides/spot-ratelimits
• Futures cost-based budget: docs.kraken.com/api/docs/guides/futures-rate-limits

Agent recommendations

• Use WebSocket streaming instead of REST polling for real-time data (no rate limit cost).
• Batch order operations where possible (up to 15 per batch; lower per-order cost on both Spot and Futures).
• Let orders rest before cancelling; cancelling within 5 seconds costs +8 on the trading engine limiter.
• When a rate_limit error is returned, read the suggestion field and adapt your strategy accordingly.

Paper Trading

Two independent paper engines cover spot and futures. No API keys, no account, no real money. Both use live Kraken prices.

Spot Paper

kraken paper init --balance 10000 -o json   # Create paper account
kraken paper buy BTCUSD 0.01 -o json        # Market buy
kraken paper sell BTCUSD 0.005 --type limit --price 70000 -o json  # Limit sell
kraken paper status -o json                 # Check portfolio
kraken paper orders -o json                 # Check open orders
kraken paper history -o json                # Trade history
kraken paper reset -o json                  # Reset account

Switch between paper and live by changing the prefix: kraken paper buy vs kraken order buy.

A 0.26% taker fee is applied to all fills (Kraken Starter tier default). Limit orders fill at the limit price when the live market crosses the order price.

Futures Paper

Near-parity with live kraken futures order commands. Supports all 8 order types, leverage/margin tracking, position aggregation/netting, liquidation simulation, and funding rate accrual. Known differences: single-ID order-status, post-only orders are cancelled rather than queued, fills use the bid/ask snapshot with no depth-based slippage, and partial fills are not modeled.

kraken futures paper init --balance 10000 -o json                              # Create account
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json      # Market long
kraken futures paper sell PF_ETHUSD 5 --leverage 20 --type market -o json     # Market short
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type limit --price 50000 -o json  # Limit long
kraken futures paper sell PF_XBTUSD 1 --leverage 10 --type stop --stop-price 48000 --trigger-signal mark -o json  # Stop order
kraken futures paper positions -o json                                         # Open positions
kraken futures paper balance -o json                                           # Margin state
kraken futures paper fills -o json                                             # Fill history
kraken futures paper status -o json                                            # Account summary
kraken futures paper reset -o json                                             # Reset account

Switch between paper and live by replacing futures paper with futures order: kraken futures paper buy vs kraken futures order buy.

Spot paper and futures paper are fully independent. Resetting one does not affect the other.

Command Groups Overview

Total: 151 commands. For the full machine-readable catalog, see agents/tool-catalog.json.

kraken mcp is a runtime mode that starts an MCP server, not a tool-callable command. It is not included in the catalog.

Dangerous Commands

The catalog marks 34 commands as dangerous: true. These move real money, cancel real orders, or mutate account state. Gate every one with confirmation logic.

The authoritative source is the dangerous field in agents/tool-catalog.json.

Common dangerous command groups:

Agent Autonomy Levels

Traders can give agents increasing levels of control:

The CLI supports all levels today. The trader controls the boundary by choosing which API key permissions to grant and whether the agent passes --yes to skip prompts. See skills/kraken-autonomy-levels/SKILL.md for the full progression guide with safeguards at each level.

Dry-run support

Use --validate on order commands to validate without submitting:

kraken order buy BTCUSD 0.001 --type limit --price 50000 --validate -o json

Use paper trading for full lifecycle testing:

kraken paper buy BTCUSD 0.001 -o json                                 # spot
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json  # futures

Integration

Calling kraken-cli from agent code

import json, subprocess

def call_kraken(command_args: list[str]) -> dict:
    result = subprocess.run(
        ["kraken"] + command_args + ["-o", "json"],
        capture_output=True, text=True, timeout=30
    )
    output = json.loads(result.stdout) if result.stdout.strip() else {}
    if result.returncode != 0:
        return {"error": "subprocess", "exit_code": result.returncode, "response": output}
    return output

Discovering commands

Load agents/tool-catalog.json for the full command contract. Each entry includes the command template, parameter schemas, auth requirements, and a dangerous flag for safety gating.

import json

with open("agents/tool-catalog.json") as f:
    catalog = json.load(f)

# All 151 commands with full parameter schemas
commands = catalog["commands"]

# Filter to safe read-only commands
safe = [c for c in commands if not c.get("dangerous") and not c.get("auth_required")]

MCP (built-in server)

kraken-cli ships a built-in MCP server over stdio. No subprocess wrappers needed.

Security note:

• MCP is intended for local use on systems you control.
• All connected agents operate with the same configured Kraken account privileges.
• Do not expose or share this MCP server on network-accessible hosts.
• Always use https:// and wss:// endpoints.
• Current release posture is alpha, run with least-privilege API keys.

# Default mode: read-only services (market, account, paper)
kraken mcp

# Guarded mode: all services, dangerous calls require acknowledged=true
kraken mcp -s all

# Autonomous mode: all services, no per-call dangerous confirmation
kraken mcp -s all --allow-dangerous

# Start with specific services
kraken mcp -s market,trade,paper

Configure your MCP client:

{
  "mcpServers": {
    "kraken": {
      "command": "kraken",
      "args": ["mcp", "-s", "all"]
    }
  }
}

Service groups: market, account, trade, funding, earn, subaccount, futures, futures-paper, paper, auth, or all. Default exposed groups are market,account,paper.

Behavior:

• Streaming groups (websocket, futures-ws) are excluded in MCP v1 (REST-only tools).
• MCP tool execution uses the same command dispatch path as CLI, so error handling and rate-limit behavior is identical.
• utility (interactive setup/shell) is not available as an MCP service.
• Dangerous tools are annotated with destructive_hint: true and include [DANGEROUS: requires human confirmation] in the description.
• In guarded mode (default), dangerous calls must include acknowledged=true.
• In autonomous mode (--allow-dangerous), the per-call confirmation is disabled.
• auth set and auth reset are excluded from MCP registration because they rely on secret input or local credential deletion, both unsuitable for MCP's stateless tool-call model. Configure credentials via environment variables or config file instead.
• All tool execution runs with force=true (no interactive prompts).
• Tool names follow the pattern kraken_<command> with spaces and hyphens converted to underscores (e.g., kraken_server_time, kraken_order_buy).
• Input schemas are derived from clap argument metadata. Tool descriptions come from clap help text.
• Errors from tool execution are returned as MCP tool-execution errors, not as panics.

Environment Variables

Machine-Readable Resources