Kraken CLI

The first AI-native CLI for trading crypto, stocks, forex, and derivatives.

Full Kraken API access. Built-in MCP server. Live and paper trading. Single binary.

Works with Cursor, Claude, Codex, Copilot, Gemini, Goose, and OpenClaw.

Try these with your AI agent:

"Install kraken-cli (https://github.com/krakenfx/kraken-cli) and build me a morning market brief."

"Watch ETH, SOL, and BTC for 30 seconds. What are the pros and cons of buying each right now?"

"Look up AAPLx, TSLAx, and SPYx on xStocks. Summarize how each is performing today."

"You are a Wall Street veteran with 20 years of experience. You have 1 minute. Paper trade BTC and show me your P&L."

"Open a 10x leveraged long on BTC futures paper with $5,000 collateral. Set a trailing stop at 3%."

[!CAUTION]
Experimental software. Interacts with the live Kraken exchange and can execute real financial transactions. Read DISCLAIMER.md before using with real funds or AI agents.

Contents

• Installation
• What You Can Trade
• Quick Start
• MCP Server
• Paper Trading
• Commands
• API Keys & Configuration
• Verifying Binaries
• Contributing
• License & Disclaimer

Installation

Single binary, no runtime dependencies.

One-liner

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

Detects your OS and architecture, downloads the right binary, and installs it. macOS (Apple Silicon and Intel) and Linux (x86_64 and ARM64) are supported. Windows: use WSL.

Verify it works:

kraken status && kraken ticker BTCUSD

Pre-built binaries are also available on the GitHub Releases page.

Requires Rust.

cargo install --git https://github.com/krakenfx/kraken-cli

Or clone and build:

git clone https://github.com/krakenfx/kraken-cli.git
cd kraken-cli
cargo install --path .

What You Can Trade

One binary covers six asset classes. All trading commands work across asset classes using the same interface; pass --asset-class where needed.

xStocks are not available in the USA. Availability for all products varies by jurisdiction.

For AI Agents

If you're an AI agent or building one, start here:

Core invocation pattern:

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

• stdout is always valid JSON on success, or a JSON error envelope on failure.
• Exit code 0 means success. Non-zero means failure.
• stderr carries diagnostics only (enabled with -v). Never parse stderr for data.

Most CLIs are built for humans at a terminal. This one is built for LLM-based agents, MCP tool servers, and automated pipelines that need to call Kraken reliably without custom API clients.

• Structured output by default. Every command supports -o json. No screen-scraping, no regex on table borders.
• Consistent error envelopes. Errors are JSON objects with a stable error field (auth, rate_limit, validation, api, network). Agents route on error without parsing human sentences.
• Predictable exit codes. Success is 0, failure is non-zero. Combined with JSON errors on stdout, agents detect and classify failures programmatically.
• Paper trading for safe iteration. Test strategies against live prices with kraken paper (spot) and kraken futures paper (perpetual futures) commands. No API keys, no real money, same interface as live trading.
• Full API surface. 151 commands covering Spot, Futures, xStocks, Forex, Funding, Earn, Subaccounts, WebSocket streaming, and paper trading for both spot and futures.
• Built-in MCP server. Native Model Context Protocol support over stdio. No subprocess wrappers needed.
• Rate-limit aware. No client-side throttling. When the Kraken API rejects a request due to rate limits, the CLI returns an enriched error with suggestion, retryable, and docs_url fields so agents can read the documentation and adapt their strategy.

Humans benefit from the same design: --output table renders clean tables, kraken shell provides a REPL, and kraken setup walks through configuration.

Verifying Binaries

Release binaries are signed with minisign. Every artifact on the Releases page has a corresponding .minisig signature file.

Public key:

RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd

Verify a downloaded binary:

minisign -Vm kraken-cli-aarch64-apple-darwin.tar.gz -P RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd

Install minisign: brew install minisign (macOS) or apt install minisign (Linux).

Quick Start

Public market data requires no credentials:

kraken ticker BTCUSD -o json
kraken orderbook BTCUSD --count 10 -o json
kraken trades BTCUSD --count 20 -o json
kraken ohlc BTCUSD --interval 60 -o json

With authentication:

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

kraken balance -o json
kraken open-orders -o json
kraken order buy BTCUSD 0.001 --type limit --price 50000 -o json

For humans (table output, interactive setup):

kraken setup
kraken ticker BTCUSD
kraken balance
kraken shell

API Keys & Configuration

Authenticated commands (trading, balances, order management) require a Kraken API key pair. Public market data and paper trading work without credentials.

Getting API keys

Spot (covers trading, balances, funding, earn, subaccounts): Settings > API on kraken.com. Full guide: How to create a spot API key.

Futures (only for kraken futures commands): Settings > Create Key on the Futures interface. Full guide: How to create a Futures API key.

Grant the minimum permissions your workflow needs. For read-only monitoring, "Query Funds" and "Query Open Orders & Trades" are sufficient.

Environment variables (recommended for agents)

export KRAKEN_API_KEY="your-key"
export KRAKEN_API_SECRET="your-secret"
export KRAKEN_FUTURES_API_KEY="your-futures-key"       # optional
export KRAKEN_FUTURES_API_SECRET="your-futures-secret"  # optional

Config file (for humans)

Store credentials in ~/.config/kraken/config.toml:

[auth]
api_key = "your-api-key"
api_secret = "your-api-secret"

[settings]
default_pair = "BTCUSD"
output = "table"

Or use the interactive wizard: kraken setup.

Credential resolution

Highest precedence first:

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

Security

• Config file is created with 0600 permissions (owner read/write only)
• Secrets are never logged, printed, or included in error messages
• Use --api-secret-stdin or --api-secret-file instead of --api-secret to avoid secrets in process listings
• For automation, prefer environment variables over command-line flags

Resolution: CLI flag > environment variable > default. Only https:// and wss:// schemes are accepted.

MCP Server

kraken-cli includes a built-in Model Context Protocol server over stdio. No subprocess wrappers needed.

MCP tool calls run through the same command path as CLI commands and inherit the same error handling and rate-limit behavior.

[!WARNING]
MCP is local-first and designed for your own machine. Any agent connected to this MCP server uses the same configured Kraken account and API key permissions. Do not expose, tunnel, or share this server outside systems you control. Always use https:// and wss:// endpoints. Treat this integration as alpha and use least-privilege API keys.

kraken mcp                           # read-only (market, account, paper)
kraken mcp -s all                    # all services, dangerous calls require acknowledged=true
kraken mcp -s all --allow-dangerous  # all services, no per-call confirmation
kraken mcp -s market,trade,paper     # specific services

Configure your MCP client (Claude Desktop, ChatGPT, Codex, Gemini CLI, Cursor, VS Code, Windsurf, etc.):

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

Gemini CLI users can install directly: gemini extensions install https://github.com/krakenfx/kraken-cli

Service groups

Default: market,account,paper. Streaming groups (websocket, futures-ws) are excluded in MCP v1.

Dangerous tools carry the destructive_hint annotation and include [DANGEROUS: requires human confirmation] in the description. In guarded mode (default), dangerous calls must include acknowledged=true. In autonomous mode (--allow-dangerous), this requirement is disabled.

JSON (-o json)

The primary output format. Every command returns valid JSON on stdout.

kraken ticker BTCUSD -o json
# {"BTCUSD":{"a":["67234.10","1","1.000"],"b":["67234.00","1","1.000"],...}}

WebSocket commands emit NDJSON (one JSON object per line) for streaming.

Table (-o table)

Human-readable tables. Default when -o is not specified.

┌──────────┬──────────┬──────────┬──────────┬────────────┐
│ Pair     │ Ask      │ Bid      │ Last     │ Volume ... │
├──────────┼──────────┼──────────┼──────────┼────────────┤
│ BTCUSD   │ 67234.10 │ 67234.00 │ 67234.10 │ 1234.56    │
└──────────┴──────────┴──────────┴──────────┴────────────┘

Error envelopes

On failure, stdout contains a JSON envelope with a stable error category:

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

Route on error, not on message. The message field is human-readable and not stable.

Full error catalog with envelopes and backoff strategies: agents/error-catalog.json.

Verbose (-v)

Request/response diagnostics go to stderr, keeping stdout clean:

kraken balance -o json -v 2>/dev/null | jq .

Commands

151 commands across 13 groups. For machine-readable parameter schemas, load agents/tool-catalog.json.

34 commands are marked dangerous (orders, withdrawals, transfers, cancel-all, staking). The authoritative list is the dangerous field in agents/tool-catalog.json.

Market Data (Public)

Account Data (Private)

Trading

Funding

Earn

Subaccounts

Futures: Public Market Data

Futures: Trading (Private)

Futures: Account Data (Private)

Futures: Paper Trading (No Auth)

Futures WebSocket Streaming

WebSocket (Streaming and Request/Response)

Utility

Paper Trading

Paper trading provides a safe sandbox for testing trading logic against live Kraken prices. No API keys, no account, no real money. Two independent paper engines cover spot and futures.

Spot Paper Trading

The command interface has near-parity with live spot trading. Switch between paper and live by changing the prefix: kraken paper buy vs kraken order buy. Known differences: paper supports market and limit order types only; slippage and partial fills are not modeled.

Agent pattern:

kraken paper init --balance 10000 -o json
kraken paper buy BTCUSD 0.01 -o json
kraken paper sell BTCUSD 0.005 --type limit --price 70000 -o json
kraken paper status -o json
kraken paper reset -o json

Human pattern:

kraken paper init --balance 5000 --currency EUR
kraken paper buy BTCUSD 0.01
kraken paper balance
kraken paper status
kraken paper orders
kraken paper history
kraken paper reset

Prices come from the public Kraken Ticker API (no auth needed). A 0.26% taker fee (Kraken Starter tier default) is applied to all fills. Limit orders fill at the limit price when the live market crosses the order price.

All output is labeled [PAPER] in table mode and includes "mode": "paper" in JSON mode.

Futures Paper Trading

Near-parity with live kraken futures order commands. Supports all 8 order types (market, limit, post, stop, take-profit, ioc, trailing-stop, fok), leverage and margin tracking, position aggregation/netting, liquidation simulation, and funding rate accrual. Known differences: order-status accepts a single ID (live accepts multiple), post-only orders are cancelled rather than simulating maker queue priority, fills use the bid/ask snapshot with no depth-based slippage, and partial fills are not modeled. Switch between paper and live by replacing futures paper with futures order.

Successful JSON responses include "mode": "futures_paper". Most table views are labeled [FUTURES PAPER] or [FP].

Agent pattern:

kraken futures paper init --balance 10000 -o json
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json
kraken futures paper sell PF_ETHUSD 5 --leverage 20 --type market -o json
kraken futures paper positions -o json
kraken futures paper status -o json
kraken futures paper reset -o json

Human pattern:

kraken futures paper init --balance 10000 --currency USD
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market
kraken futures paper sell PF_XBTUSD 1 --leverage 10 --type limit --price 70000
kraken futures paper positions
kraken futures paper balance
kraken futures paper fills
kraken futures paper history
kraken futures paper reset

Prices come from the public Kraken Futures Ticker API (no auth needed). Taker fees are simulated. Positions track leverage, margin, and liquidation prices. Funding rates are accrued based on the public funding rate API. Spot paper and futures paper are fully independent: resetting one does not affect the other.

Examples

Conditional order based on live price

PRICE=$(kraken ticker BTCUSD -o json | jq -r '.[].c[0]')
kraken order buy BTCUSD 0.001 --type limit --price "$PRICE" -o json

Portfolio rebalance check

BTC=$(kraken balance -o json | jq -r '.BTC // "0"')

if [ "$(echo "$BTC > 0.001" | bc)" -eq 1 ]; then
  kraken order sell BTCUSD 0.001 --type market -o json
fi

Real-time price stream

kraken ws ticker BTC/USD -o json | while read -r line; do
  LAST=$(echo "$line" | jq -r '.data[0].last // empty')
  [ -n "$LAST" ] && echo "BTC: $LAST"
done

Stream multiple tickers

kraken ws ticker BTC/USD ETH/USD SOL/USD -o json

Dead man's switch

kraken order cancel-after 60

Cancels all open orders if the CLI does not reset the timer within 60 seconds.

Agent Skills

Ships with 50 agent skills covering trading strategies, market analysis, and portfolio management. See the full Skills Index.

macOS blocks the binary ("Apple could not verify")

xattr -d com.apple.quarantine /usr/local/bin/kraken

"EAPI:Invalid key" or authentication errors

Check that KRAKEN_API_KEY and KRAKEN_API_SECRET are set correctly. Keys are case-sensitive. Verify the API key has the required permissions for the command (Query Funds for balance, Modify Orders for order buy, etc.).

Rate limit errors

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 a suggestion field containing tier-specific limits and a docs_url pointing to the relevant Kraken documentation. Read the suggestion and adjust request frequency. For sustained high-frequency use, prefer WebSocket streaming over REST polling.

"No tools found" in MCP client

Verify kraken is on your PATH. Run kraken mcp -s market in a terminal to confirm the server starts. Check that your client configuration matches the JSON format in the MCP Server section.

Spot paper trading state errors

Run kraken paper reset to clear and reinitialize.

Futures paper trading state errors

Run kraken futures paper reset to clear and reinitialize. Spot and futures paper states are independent.

src/
  main.rs          -- CLI entry point, clap parsing, exit codes
  lib.rs           -- AppContext, shared dispatcher, module re-exports
  auth.rs          -- HMAC-SHA512 signing (Spot + Futures), nonce management
  config.rs        -- Config file I/O, credential resolution, secret wrappers
  client.rs        -- HTTP clients with transient-error retry and enriched rate-limit errors
  errors.rs        -- Unified error types with category-based JSON envelopes
  paper.rs         -- Spot paper trading state engine (local simulation)
  futures_paper.rs -- Futures paper trading engine (leverage, margin, liquidation, funding)
  shell.rs         -- Interactive REPL with rustyline
  telemetry.rs     -- Agent client identification, instance tracking, user-agent
  commands/        -- One module per command group
    mod.rs         -- Module re-exports
    helpers.rs     -- Shared utilities (JSON extraction, output formatting)
    market.rs      -- Public market data
    account.rs     -- Private account data
    trade.rs       -- Spot trading
    funding.rs     -- Deposits, withdrawals, wallet transfers
    earn.rs        -- Staking/earn
    subaccount.rs  -- Subaccount management
    futures.rs        -- Futures trading and market data
    futures_paper.rs  -- Futures paper trading commands
    futures_ws.rs     -- Futures WebSocket v1 streaming
    websocket.rs      -- Spot WebSocket v2 streaming
    paper.rs          -- Spot paper trading commands
    auth.rs        -- Credential management commands
    utility.rs     -- Setup wizard
  mcp/             -- Built-in MCP server
    mod.rs         -- Service group parsing, streaming exclusion filters
    server.rs      -- ServerHandler impl, tool dispatch, env-based URL resolution
    registry.rs    -- Tool registry built from clap tree + tool-catalog.json
    schema.rs      -- JSON Schema generation from clap argument metadata
  output/          -- Rendering layer
    mod.rs         -- Format dispatch, CommandOutput type
    table.rs       -- Human-readable table output
    json.rs        -- JSON output and NDJSON streaming

Development

cargo build                    # dev build
cargo test                     # run tests
cargo clippy -- -D warnings    # lint

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for guidelines.

License & Disclaimer

MIT. See LICENSE.

This is experimental software. Commands interact with the live Kraken exchange and can result in real financial transactions. Orders, withdrawals, and transfers are irreversible once processed. The authors accept no liability for financial losses. See DISCLAIMER.md for full terms.