Kraken CLI

Trade on Kraken from your terminal, or let your AI agent trade for you. One install covers crypto, tokenized U.S. stocks and ETFs (for non-U.S. customers), forex, and futures. Every command can answer in JSON. A built-in MCP server connects the CLI to Claude, Cursor, Codex and other agents, and paper trading runs on live prices with no account.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh | sh
source "$HOME/.cargo/env"   # puts kraken on your PATH in this terminal
kraken ticker BTCUSD        # live price, no account needed

With kraken-cli you can:

• Trade 1,400+ crypto pairs, 170+ tokenized U.S. stocks and ETFs (xStocks), 12 forex pairs and 200+ futures contracts. What you can trade
• Practice on paper first. Paper orders fill at live prices and need no Kraken account, and the basic order commands are the same as live. Paper trading
• Connect Claude, Cursor, Codex, Gemini and other MCP clients through kraken-mcp, which serves up to 152 MCP tools. On clients that support MCP elicitation, calls that move money ask you first; the kraken CLI itself places orders without a prompt. MCP server
• Script it: every command takes -o json, and a failure comes back as JSON with a stable error field and a non-zero exit code. For AI agents
• Record live market data and replay it into paper sessions, then score a strategy against pass criteria you fixed before the first run. Workspaces, sessions, and research
• Start from 59 agent skills for DCA, grid trading, rebalancing, futures risk and more. Agent skills

Paste one of these prompts into Claude Code, Codex, Cursor, or another AI coding agent. No agent yet? Install Claude Code first.

Install kraken-cli (https://github.com/krakenfx/kraken-cli) and tell me how to sign in with OAuth.

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

With kraken-cli, watch ETH, SOL, and BTC for 30 seconds. What are the pros and cons of buying each right now?

With kraken-cli, 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 with kraken-cli and show me your P&L.

With kraken-cli futures paper trading, open a 10x leveraged long on BTC with $5,000 collateral. Set a trailing stop at 3%.

If kraken-cli is useful to you, star the repo so other traders and agent builders can find it. To hear about new releases, choose Watch > Custom > Releases on the repo page.

• Installation
• Quick start
• Sign in with OAuth
• API keys & configuration
• What you can trade
• Paper trading
• For AI agents
• Output and errors
• MCP server
• Workspaces, sessions, and research
• Commands
• Examples
• Agent skills
• Troubleshooting
• Star history
• Development
• Contributing
• License & disclaimer

One install, no runtime dependencies. It puts three binaries on your PATH: kraken, kraken-mcp (the MCP server) and kraken-shell (an interactive shell).

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

The installer detects your OS and architecture, downloads the right build, and installs it. macOS (Apple Silicon and Intel) and Linux (x86_64 and ARM64) are supported. On Windows, use WSL. AI agents: ask your human before you run the installer on their machine.

Open a new terminal (or run source "$HOME/.cargo/env"), then check that it works:

kraken status && kraken ticker BTCUSD

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

Releases are signed with minisign. Every release archive, its .sha256 file, the installer script and SHA256SUMS.txt on the Releases page has a matching .minisig signature file.

Download the archive and its .minisig into the same folder, then check it against the public key:

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

Public key:

RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd

Install minisign with brew install minisign (macOS) or apt install minisign (Linux). To check the installer before you run it:

curl -LO https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh
curl -LO https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh.minisig
minisign -Vm kraken-cli-installer.sh -P RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd && sh kraken-cli-installer.sh

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

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

Steps 1 and 2 need no account. To trade real money you need a verified Kraken account with funds in it; you can create one on kraken.com.

Public market data needs no credentials, so nothing here can touch an account.

kraken ticker BTCUSD
kraken orderbook BTCUSD --count 10
kraken ohlc BTCUSD --interval 60

Output is a table. Add -o json to any command for JSON. REST commands accept BTCUSD, BTC/USD or XBTUSD; the examples for streaming commands (ws, record, session) use BTC/USD.

kraken workspace create sandbox --capital 10000 --mode paper
export KRAKEN_WORKSPACE=sandbox
kraken paper buy BTCUSD 0.01
kraken workspace status
unset KRAKEN_WORKSPACE

Paper orders fill at live prices with simulated money. paper buy may log a warning that no session is recording; you can ignore it here.

While KRAKEN_WORKSPACE names a paper workspace, kraken order buy and kraken balance act on the simulated account as well. The last line unsets it so the next steps reach your real account. Paper trading covers the rest.

kraken auth login
kraken auth test

kraken auth login opens Kraken's sign-in page in your browser. Sign in, approve access, and the CLI saves a Spot API key for you. The key covers spot crypto, xStocks and forex, can't withdraw funds, and expires after 90 days. Run it yourself in an interactive terminal: it refuses to run from a script, a CI job or an AI agent's shell. kraken auth test checks the saved key against your account. Sign in with OAuth covers each step.

• Trading futures? The sign-in key is Spot only. Create a Futures key and set KRAKEN_FUTURES_API_KEY and KRAKEN_FUTURES_API_SECRET, or add it to config.toml (see API keys & configuration).
• Prefer a key you created yourself? Run kraken setup in a terminal, or store it with kraken auth set.
• Using an AI agent? Sign in in your own terminal, and the agent uses the stored key. Never paste an API key into an AI chat.

kraken balance
kraken open-orders

Balance empty? Fund the account on kraken.com, or list your deposit options with kraken deposit methods USD.

kraken ticker BTCUSD                                                # check the price
kraken order buy BTCUSD 20 --type market --oflags viqc --validate  # $20 of BTC, checked only

--validate asks Kraken to check the order without placing it, so nothing trades. --oflags viqc makes the volume a quote-currency amount, here 20 USD. Leave the flag off and 20 means 20 BTC. Kraken accepts viqc on market buys only. For a limit order, give the volume in BTC and a price:

kraken order buy BTCUSD 0.0005 --type limit --price 75000 --validate

kraken order buy defaults to --type limit, which needs --price. To see the smallest order a pair accepts, run kraken pairs --pair BTCUSD -o json and read ordermin (volume) and costmin (cost in the quote currency).

Drop --validate. This places a real order with real money, and there is no confirmation prompt: it goes to Kraken when you press Enter. Check that echo $KRAKEN_WORKSPACE prints nothing first, so the order reaches your real account:

kraken order buy BTCUSD 20 --type market --oflags viqc

The receipt starts with Mode [LIVE] Real Money and shows the order ID, which is Kraken's transaction ID. With -o json, check that mode is "live" and read order_id. Then check it:

kraken query-orders <ORDER_ID>     # status "closed" means it filled
kraken balance

A limit order that hasn't filled stays open; cancel it with kraken order cancel <ORDER_ID>.

Futures orders use kraken futures order buy and sell with your Futures key. They have no --validate, so rehearse them with futures paper trading first. Sizes are in contracts: one PF_XBTUSD contract is 1 BTC.

kraken auth login signs you in with OAuth. You approve access on Kraken's own sign-in page, and the CLI creates and saves a restricted Spot API key for you. You skip the API settings page and the copy and paste.

kraken auth login

• It can query balances, place, amend and cancel orders, read trades and ledger entries, use deposits and Earn, request exports, and open authenticated WebSocket streams.
• It has no withdrawal rights.
• It covers Spot only: spot crypto, xStocks and forex. Futures commands still use their own key (see API keys & configuration).
• It expires after 90 days. --valid-for sets a shorter life, from 1 minute up to 90 days.

kraken auth login --read-only --valid-for 30d

You have 5 minutes to approve in the browser. After that the command stops with a timeout error, and you run it again.

Forward the three callback ports, then ask the CLI to print the sign-in URL and open it on your own machine. The listener takes the first free port of the three, so forward all of them.

# On your own machine: connect with the callback ports forwarded.
ssh -L 27461:localhost:27461 -L 27462:localhost:27462 -L 27463:localhost:27463 <host>

# On the remote machine: print the sign-in URL, then open it on your own machine.
kraken auth login --no-browser

kraken auth show              # which key is in use, and whether a flag or env var overrides it (alias: auth status)
kraken auth test              # checks the key in use against your account
kraken auth switch sign-in    # signs requests with the OAuth sign-in key
kraken auth switch api-key    # signs requests with the key from `kraken auth set` or `kraken setup`
kraken auth reset             # deletes every stored key from config.toml; revokes nothing on Kraken

Your config can hold a sign-in key and an API key at the same time. Credential resolution explains which one signs.

auth reset deletes every stored key from config.toml: the API key, the sign-in key, and the Futures key. It revokes nothing on Kraken, so the sign-in key keeps working until it expires. To revoke it at once, delete it where you manage API keys on kraken.com. An older release ignores the sign-in key and can drop it from config.toml, so delete the key in the Kraken UI before you downgrade.

OAuth sign-in is for a person at a terminal. kraken auth login refuses to run without one, the catalog marks it dangerous, and the MCP server does not serve it. An agent can't start it and should never try.

A person signs in once, and the agent reuses the key:

1. A person runs kraken auth login once, in their own terminal.
2. The agent calls commands as usual, for example kraken balance -o json 2>/dev/null. The CLI signs with the stored OAuth key.
3. A key from a flag or an environment variable wins over the stored key.
4. When the sign-in key expires, calls that need a key return an auth error envelope. The CLI does not fall back to another stored key. Tell the person to run kraken auth login again.

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

The easiest way to get a key is OAuth sign-in. Create one by hand when you need a Futures key, specific permissions, or credentials for automation.

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

Futures (only for kraken futures commands): sign in to Kraken Futures, then go to Settings > Create Key. Full guide: How to create a Futures API key.

Grant the minimum permissions your workflow needs:

• Read-only monitoring: "Query Funds" and "Query Open Orders & Trades" cover balances and open orders. Add "Query Closed Orders & Trades" for trade history and "Query Ledger Entries" for ledgers.
• Trading: add the permissions to create, modify, cancel and close orders.
• Leave withdrawal permission off unless a script needs to withdraw.

kraken setup is an interactive wizard. It asks for your Spot key and, optionally, a Futures key. Run it in a normal terminal, because it reads your input.

kraken auth set stores a key without asking you to type it. It always needs a Spot key and its secret. Pass the secret on stdin or from a file so it stays out of your shell history and process list, and add the Futures flags to store a Futures key in the same call:

kraken auth set --api-key <YOUR_KEY> --api-secret-stdin
kraken auth set --api-key <YOUR_KEY> --api-secret-file ~/kraken-secret.txt \
  --futures-api-key <FUTURES_KEY> --futures-api-secret-file ~/kraken-futures-secret.txt

Delete the secret files once the keys are stored. kraken setup and kraken auth set write the same API key slot. If a working sign-in key is already active, the CLI asks which key to use in a terminal and keeps the active key in a script. To add only a Futures key and keep your sign-in key, use the Futures environment variables or the config.toml fields below.

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

Set them in the environment that the agent or script starts from. A secrets manager keeps the secret out of your shell history, for example export KRAKEN_API_SECRET="$(op read 'op://Private/Kraken/secret')" with the 1Password CLI. An agent that is already running won't see variables you export afterwards. Never paste API keys into an AI chat.

Credentials live in ~/.config/kraken/config.toml (Linux) or ~/Library/Application Support/kraken/config.toml (macOS):

[auth]
api_key = "your-api-key"
api_secret = "your-api-secret"
futures_api_key = "your-futures-key"         # optional
futures_api_secret = "your-futures-secret"   # optional

Highest precedence first:

1. Command-line flags (--api-key, --api-secret). Spot and Futures commands share this pair.
2. Environment variables: KRAKEN_API_KEY and KRAKEN_API_SECRET for Spot, KRAKEN_FUTURES_API_KEY and KRAKEN_FUTURES_API_SECRET for Futures.
3. The stored key in config.toml. For Spot that is the active one of the API key (from kraken auth set or kraken setup) and the OAuth sign-in key (from kraken auth login).

Which stored Spot key is active:

The CLI changes the active key only when you choose one, or when you store a new key while the active one is expired or missing. It never falls back to the other key: an expired sign-in key stays active and fails with an auth error until you sign in again or run kraken auth switch api-key. kraken auth show tells you which key is in use.

• The 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 keep secrets out of process listings.
• For automation, prefer environment variables over command-line flags.

Spot crypto, xStocks and forex share kraken order (add --asset-class tokenized_asset for xStocks; forex pairs such as EURUSD need no asset class to trade). Futures use kraken futures order with a separate Futures API key, and Earn has its own kraken earn commands. The spot and xStocks examples below use --validate, so Kraken checks them without placing them.

Futures sizes are in contracts: one PF_XBTUSD contract is 1 BTC, and FI_ contracts are 1 USD each. Fixed-date symbols end in their expiry date (YYMMDD). kraken futures instruments lists the contracts that are trading now. Futures orders have no --validate, so rehearse them with futures paper trading.

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

Paper trading tests trading logic against live Kraken prices with simulated money. It needs no API key and no Kraken account. Spot and futures each have their own paper engine.

There are two ways to place a spot paper order:

• kraken paper buy and kraken paper sell always simulate.
• Inside a paper workspace (KRAKEN_WORKSPACE or --workspace), the live verbs kraken order buy, balance, open-orders and trades-history act on the simulated account too. A strategy that sticks to these verbs, with --type and --price, runs unchanged once you promote it to live (see Strategy workspaces in the full command reference). Inside a workspace, order buy and sell refuse --cl-ord-id, --oflags and most other advanced flags.

paper buy defaults to a market order and order buy to a limit order, so pass --type when you switch. Paper supports market and limit orders, a configurable flat slippage model, and no partial fills.

Agent pattern:

kraken workspace create sandbox --capital 10000 --mode paper -o json
export KRAKEN_WORKSPACE=sandbox
kraken paper buy BTCUSD 0.01 -o json
kraken paper sell BTCUSD 0.005 --type limit --price 90000 -o json
kraken workspace status -o json
kraken workspace reset --yes -o json   # dangerous: only when your human asks for a reset
unset KRAKEN_WORKSPACE

Human pattern:

kraken workspace create sandbox-eur --capital 5000 --currency EUR --mode paper
export KRAKEN_WORKSPACE=sandbox-eur
kraken paper buy BTCEUR 0.01
kraken paper balance
kraken paper status
kraken paper orders
kraken paper history
kraken workspace reset
unset KRAKEN_WORKSPACE

Prices come from the public Kraken Ticker API (no auth needed). By default a 0.26% taker fee applies to every fill; set another rate with --fee-rate. Optional slippage simulation applies a flat rate to market orders: buys fill at ask * (1 + slippage_rate), sells at bid * (1 - slippage_rate). Default slippage is 0.0 (no simulation). A limit order always rests when placed, even when the market is already through its price. The next paper buy, sell, orders, cancel, cancel-all, history or status checks it against the live price, and once the market has crossed the limit it fills at the limit price, not at the better market price.

In table mode, paper buy, sell, cancel, cancel-all and status lead with a [PAPER] Simulated Trading row, and paper orders and history put [PAPER] in their first column header. Their JSON carries "mode": "paper", as does the JSON of paper balance and paper init. paper init shows a plain Mode row; the paper balance table and all paper reset output carry no marker.

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. --type defaults to limit, and the fee rate to 0.05% (--fee-rate 0.0005). Known differences: order-status accepts a single ID (live accepts multiple), post-only orders are cancelled rather than simulating maker queue priority, and fills use the bid/ask snapshot with no depth-based slippage. Only IOC orders fill partially: they take the book depth available at the limit price and cancel the rest.

The live commands differ in more than the prefix. futures paper buy/sell become futures order buy/sell, which take no --leverage (set it with futures set-leverage), and futures paper orders becomes futures open-orders. edit-order, cancel, cancel-all, batch-order, order-status, positions, fills, leverage and set-leverage keep their names under futures. init, reset, balance and status are paper-only; futures accounts shows the live wallet. Live futures history is public trade history; your own past orders and fills are in futures history-orders and futures history-executions.

Futures paper state is global, not per workspace. Run it with no workspace selected (unset KRAKEN_WORKSPACE if an earlier example exported it): inside a workspace only balance, status, orders, order-status, positions and fills run; history, leverage and every mutation are refused.

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

futures paper buy and sell also take --stop-price, --trigger-signal mark|index|last, --client-order-id, --reduce-only, --trailing-stop-max-deviation and --trailing-stop-deviation-unit percent|quote_currency, the same as the live order commands.

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.

If you're an AI agent or building one, read AGENTS.md first: it is the full integration contract. CONTEXT.md is a shorter version for tool-use prompts.

• A person is with you: ask them to open a new terminal window and run kraken auth login there. Never start it yourself. It needs an interactive terminal, and the catalog marks it dangerous. Then confirm with kraken auth test -o json (exit code 0 means the key works) and run kraken auth show -o json: active_spot_source names the key that signs, overridden is true when a flag or environment variable wins over the stored key, and sign_in_key carries valid_until and expired. See Using OAuth with AI agents.
• Running unattended (CI, a server): the operator sets KRAKEN_API_KEY and KRAKEN_API_SECRET in the environment the agent starts from. Flags and environment variables take priority over stored keys.
• Never ask for, accept, or paste API keys in a chat.

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

• stdout carries one JSON document on success, or a JSON error envelope on failure. Streaming commands such as kraken ws ticker write JSONL: one JSON object per line.
• Exit code 0 means success, 1 a runtime or API failure, and 2 a usage error such as a bad flag or a missing argument.
• stderr carries diagnostics only: structured JSON logs (warnings and errors by default, more with -v or RUST_LOG). Real-account orders and cancels, and commands in a live workspace, also print a plain-text live: banner there (not for --validate orders). Never parse stderr for data; read the mode field in the JSON to tell paper from live. For orders, capture stderr to a file instead of discarding it, so you can show your human any banner or warning.

1. The CLI places orders without a confirmation prompt. Before any command the catalog marks dangerous, confirm the pair, side, size and estimated cost with your human.
2. Run the order with --validate first. A validated order places nothing, so on the CLI it needs no approval (over MCP it is gated like the real order); confirm with your human between the validation and the real order.
3. Check where it goes. KRAKEN_WORKSPACE or --workspace decides, and the receipt's mode field says paper or live.
4. Give every order a new --cl-ord-id, such as a fresh UUID, and never reuse one. After a network error or an envelope with "verify_first": true, look the order up with kraken open-orders --cl-ord-id <ID> -o json and then closed-orders before you resubmit. For futures orders, withdrawals, transfers and Earn, use the lookups in the network row of the error table. (Inside a workspace, order buy and sell refuse --cl-ord-id and most other advanced flags.)
5. Over MCP, set acknowledged=true only after your human approved that exact call.
6. Call feedback only when your human asks, and never put secrets or personal data in it.

• balance is keyed by asset code (BTC, USD, ETH), and on the real account its values are JSON numbers. Outside a workspace the result has no mode field, so confirm that KRAKEN_WORKSPACE is unset and no --workspace flag is passed before you call it real money. Inside a workspace it returns {"workspace": ..., "mode": ..., "balances": {"USD": {"total", "reserved", "available"}}} instead.
• Market data is keyed by the pair name Kraken returns: XXBTZUSD when you ask for BTCUSD, BTC/USD when you ask for BTC/USD. Read it with .[].
• An order receipt carries mode, status and order_id (Kraken's transaction ID). kraken query-orders <ID> -o json returns an object keyed by order ID, so read it with .[]. Each order carries status (open, closed, canceled, ...), volume, volume_executed, cost, fee, and price (the average fill price).
• Workspace amounts are decimal strings, unlike the real-account balance values: backing, and the total, reserved and available of a workspace balance. Convert them with tonumber in jq before you compare them.

To buy a dollar amount, make the volume a quote-currency amount with --oflags viqc (market buys only):

kraken order buy BTCUSD 25 --type market --oflags viqc --validate -o json 2>/dev/null
# after your human confirms; use a new client order ID for every order:
CLID=$(uuidgen | tr 'A-Z' 'a-z')
kraken order buy BTCUSD 25 --type market --oflags viqc --cl-ord-id "$CLID" -o json 2>>kraken-order.log
kraken query-orders <ORDER_ID> -o json 2>/dev/null

Every request/response command returns one JSON document on stdout.

kraken ticker BTCUSD -o json
# {"XXBTZUSD":{"ask_price":81401.4,"bid_price":81401.3,"last_price":81401.3,"volume_24h":1371.77,...}}

Results are keyed by the pair name Kraken returns (XXBTZUSD here), with named fields and numeric values. WebSocket and other streaming commands emit JSONL (one JSON object per line).

Human-readable tables. This is the default when -o is not specified.

┌──────────┬─────────┬─────────┬─────────┬───────────────┬────────────┬───────────┐
│ Pair     ┆ Ask     ┆ Bid     ┆ Last    ┆ Volume (24h)  ┆ High (24h) ┆ Low (24h) │
╞══════════╪═════════╪═════════╪═════════╪═══════════════╪════════════╪═══════════╡
│ XXBTZUSD ┆ 79707.1 ┆ 79707.0 ┆ 79707.0 ┆ 1996.38136702 ┆ 81709.1    ┆ 79614.8   │
└──────────┴─────────┴─────────┴─────────┴───────────────┴────────────┴───────────┘

With -o json, a failure prints a JSON envelope on stdout with a stable error category and exits 1:

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

In table mode, the default, the error is a plain Error: ... line on stderr. Argument and usage errors exit 2, and with -o json they also put a validation envelope on stdout.

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

A futures ws reconnect counts as failed unless the new connection stays up for 30 seconds.

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

kraken balance -o json -v 2>/dev/null | jq .   # result on stdout; logs (JSON) on stderr
kraken balance -v --log-format pretty           # human-readable logs instead
export KRAKEN_LOG_FORMAT=pretty                 # ...or via env (e.g. a dev shell profile)

kraken balance -v                                  # kraken-cli at debug, dependencies at warn
RUST_LOG=warn,kraken=debug kraken balance          # same, explicit
RUST_LOG=kraken_rest=trace kraken ticker BTCUSD   # HTTP request/response detail

kraken-mcp is a built-in Model Context Protocol server over stdio, so MCP clients can call Kraken as tools without a subprocess wrapper. Tool calls run through the same command path as CLI commands and inherit the same error handling and rate-limit behavior.

kraken-mcp                                          # default: market, account, paper, workspace, feedback
kraken-mcp -s market,account,paper,workspace,trade  # adds live spot trading
kraken-mcp -s all                                   # all services; dangerous calls need approval (see below)
kraken-mcp -s all --allow-dangerous                 # DANGER: no approval step; an agent can trade, withdraw and transfer

-s all serves all 152 MCP tools; the default services serve the subset in their groups.

kraken-mcp signs with KRAKEN_API_KEY and KRAKEN_API_SECRET (and KRAKEN_FUTURES_API_KEY and KRAKEN_FUTURES_API_SECRET for futures) when they are set in the server's environment. Otherwise it signs with the active stored key, including the OAuth sign-in key from kraken auth login, and reads that key again on every call that can sign. When a stored sign-in key expires, calls that need a key fail with an auth error, and a person runs kraken auth login again. The auth login, auth set, auth switch, and auth reset commands are not served over MCP.

Dangerous tools carry the destructive_hint annotation and include [DANGEROUS: requires human confirmation] in the description. Unless you pass --allow-dangerous, the server runs in guarded mode, whichever services you load:

• On a client that supports MCP elicitation, the server puts each dangerous call to you and runs it only if you approve. A prompt that gets no answer within 300 seconds fails closed.
• Inside a paper workspace, order buy, order sell, order cancel and order cancel-all fill on the simulator, so they drop both markers and run without approval. Every other dangerous tool stays gated there.
• workspace create with mode: live also asks for approval, because it allocates real money.

Install kraken-cli with the one-liner first, because the plugin starts the kraken-mcp binary that the installer puts on your PATH. Then install the plugin, which adds the MCP server and the agent skills. Its server runs market,paper,feedback, with no account access, so balances and live orders go through the kraken CLI unless you widen -s:

/plugin marketplace add krakenfx/kraken-cli
/plugin install kraken-cli@kraken

Or add only the MCP server. The full path works even before kraken-mcp is on your PATH:

claude mcp add kraken -- "$HOME/.cargo/bin/kraken-mcp" -s market,paper,feedback

If you set CARGO_HOME, use $CARGO_HOME/bin/kraken-mcp instead.

If you installed kraken-cli while Claude Code was running, quit Claude Code and start it again from a new terminal window.

Claude Desktop, Cursor, Windsurf, Gemini CLI and other clients that read mcpServers JSON take this entry:

{
  "mcpServers": {
    "kraken": {
      "command": "kraken-mcp",
      "args": ["-s", "market,paper,feedback"]
    }
  }
}

VS Code takes the same entry under a top-level "servers" key in .vscode/mcp.json. Codex reads TOML in ~/.codex/config.toml:

[mcp_servers.kraken]
command = "kraken-mcp"
args = ["-s", "market,paper,feedback"]

This set starts market data, paper trading, and the feedback tool, which uploads text, or a local file it names, to Kraken with no approval step (see Service groups). It needs no credentials. Add account to read your balances and orders, and workspace for paper workspaces. For live trading, use market,account,paper,workspace,trade with a least-privilege API key. If the client shows "Failed to connect", set command to the full path that command -v kraken-mcp prints.

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

Default: market,account,paper,workspace,feedback. The feedback tool calls the same upload path as kraken feedback. It sends the text you give it (at most 8192 bytes after trimming), the feedback type, the optional --llm-model value, the CLI version, the OS and architecture, the detected agent client, a stable install ID, a random event ID and a timestamp to https://cli-feedback.kraken.com/v1/feedback over HTTPS. Do not put secrets or personal data in it. Over MCP the tool also accepts input_file: it reads that local file and uploads its contents, with no approval step, so a model could upload any file it can name, including the config file that holds your stored keys. A failed upload fails the command and is not retried. Drop feedback from -s to turn the tool off, especially for an agent that reads untrusted input. The streaming groups (websocket, futures-ws) and utility (the setup wizard) are not served over MCP.

Beyond single orders, the CLI runs a research loop on paper:

1. A workspace gives a strategy its own capital and ledger.
2. A session records an evaluation window.
3. A tape preserves replayable market data.
4. A lab experiment seals the hypothesis and pass criteria before the first run.

# Create a paper workspace with its own $10,000.
kraken workspace create momentum --capital 10000 --mode paper -o json
export KRAKEN_WORKSPACE=momentum

# Record in one terminal.
kraken session start --symbols BTC/USD --channels ticker,trade \
  --label baseline --to jsonl -o json

# Trade in another terminal and preserve the rationale.
export KRAKEN_WORKSPACE=momentum
kraken paper buy BTC/USD 0.01 -o json
kraken session note --kind buy --symbol BTC/USD \
  --reason "breakout held above the prior high" -o json
kraken session stop -o json

# Review the closed window.
kraken session show --session baseline -o json
kraken explain pnl --session baseline -o json
kraken workspace report momentum -o json

For repeatable experiments, freeze the plan before the first session. A replay leg names a finalized tape: replay:session:s1 is the baseline session above, the first one in this workspace (kraken session list shows each ordinal).

kraken lab new breakout-v1 \
  --hypothesis "a confirmed breakout produces positive net return" \
  --min-return-pct 0 --max-drawdown-pct 2 --min-fills 1 \
  --session live:5m --session replay:session:s1 -o json

kraken lab next breakout-v1 -o json
kraken lab compare breakout-v1 -o json

--session live:5m plans a 5-minute session on live prices inside the paper workspace; it places no real orders. When you are done, run unset KRAKEN_WORKSPACE so later commands reach your real account again.

The command tables below cover each surface. Machine-readable contracts live in agents/tool-catalog.json.

The published catalog contains 188 commands across 15 groups; 152 of them are callable as MCP tools, and the rest say why they are not. Parameter schemas live in agents/tool-catalog.json. Long-running streams are in the catalog too, with reach: stream, and are documented below. They stay CLI-only.

43 commands are marked dangerous: orders and cancels (including the ws order methods), withdrawals, transfers, staking, futures leverage/PnL/subaccount settings, export retrieval and deletion, subaccount creation, paper and workspace resets, workspace promotion, browser sign-in, and switching or resetting the stored key. The CLI places orders without a confirmation prompt; only some destructive commands, such as cancel-all and the resets, ask first (skip the question with --yes). The MCP server gates the ones it serves (see Approval for dangerous calls). The authoritative list is the dangerous field in agents/tool-catalog.json.

$ kraken order buy BTC/USD 0.01 --type limit --price 60000     # paper workspace
┌───────────┬───────────────────────────┐
│ Mode      ┆ [PAPER] Simulated Trading │   ← simulated, no money moved
│ Session   ┆ none                      │   ← the recording session, if any
│ Workspace ┆ sandbox                   │
│ Action    ┆ Limit buy order placed    │
│ Order ID  ┆ PAPER-00003               │   ← a minted id
│ …         ┆ …                         │
└───────────┴───────────────────────────┘

$ kraken order buy BTC/USD 0.01 --type limit --price 60000     # live workspace
live: this goes to the real Kraken account                        ← stderr
workspace 'prod' is an allocation ledger over that account, not a separate balance
┌─────────────┬──────────────────────────────────────────────┐
│ Mode        ┆ [LIVE] Real Money                            │   ← a REAL order at Kraken
│ Workspace   ┆ prod                                         │
│ Scope       ┆ REAL orders — allocation of the real account │
│ Action      ┆ Limit buy order placed                       │
│ Order ID    ┆ OQABCD-1EFGH-2IJKLM                          │   ← a venue txid
│ …           ┆ …                                            │
│ Backing     ┆ backed                                       │   ← what backs it
│ Account     ┆ 5000 USD                                     │
│ Unallocated ┆ 4000 USD                                     │
│ Spendable   ┆ 400 USD                                      │
└─────────────┴──────────────────────────────────────────────┘

kraken workspace balance -o json | jq '.backing'
# { "status": "backed", "asset": "BTC", "allocation": "0.1",
#   "account": "1", "allocated_elsewhere": "0.15",
#   "unallocated": "0.75", "spendable": "0.0975" }

The guided walkthroughs in examples/ cover the bigger features: the playground, paper workspaces, market recording, session replay with P&L explain, the autoresearch lab, and driving all of it with agent skills. None of them need a Kraken account, because all their trading happens in paper workspaces. The one-liners below use jq (brew install jq or apt install jq).

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

if kraken ticker BTCUSD -o json | jq -e '.[].ask_price < 75000' >/dev/null; then
  kraken order buy BTCUSD 20 --type market --oflags viqc --validate -o json   # $20 of BTC
fi

if kraken balance -o json | jq -e '(.BTC // 0) > 0.001' >/dev/null; then
  kraken order sell BTCUSD 0.001 --type market --validate -o json
fi

balance is keyed by asset code (BTC, USD, ETH). BTC you hold in Earn appears under Kraken's raw code with a suffix, such as XBT.F, so add it to BTC when you report total BTC.

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

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

kraken order cancel-after 60

This has no --validate. It arms Kraken's dead man's switch: unless you call it again within 60 seconds, Kraken cancels all your open orders. Each call restarts the countdown, so a script keeps it alive by re-running it well inside the timeout, for example every 15 to 30 seconds. kraken order cancel-after 0 turns it off. It needs API credentials and runs only with no workspace selected.

Ships with 59 agent skills: SKILL.md packages that walk an agent through a workflow from start to finish. A few to start with:

The full list is in the Skills Index. The Claude Code plugin installs the skills along with the MCP server.

command not found: kraken after install

The installer puts the binaries in ~/.cargo/bin (or $CARGO_HOME/bin). Open a new terminal, or restart your agent. To run it right now, use the full path: ~/.cargo/bin/kraken --version (or $CARGO_HOME/bin/kraken --version).

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

This only affects binaries downloaded with a web browser. The one-liner install is not affected. In the folder where you unpacked the download, remove the quarantine flag:

xattr -d com.apple.quarantine kraken kraken-mcp kraken-shell

"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.). If you signed in with OAuth, run kraken auth show to see which key is in use. A flag or an environment variable overrides the stored key.

Futures commands fail after OAuth sign-in

The sign-in key covers Spot only. Create a Futures key (see Getting API keys), then set KRAKEN_FUTURES_API_KEY and KRAKEN_FUTURES_API_SECRET, or add futures_api_key and futures_api_secret to config.toml. kraken setup and kraken auth set can store it too, but both also need a Spot API key.

An order went to the paper account

KRAKEN_WORKSPACE is still set from a paper example, so kraken order buy and kraken balance act on that workspace. Run unset KRAKEN_WORKSPACE, or check the Mode row (mode in JSON) before you trade.

kraken auth login needs a terminal

Run it yourself in a terminal window. It refuses to run from a script or an agent.

Browser sign-in times out

You have 5 minutes to approve in the browser. An unfinished sign-in ends with a timeout error. Run kraken auth login again and approve access in time. Over SSH, forward the callback ports and use --no-browser (see Signing in over SSH).

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.

"Failed to connect" or "No tools found" in MCP client

The client cannot find kraken-mcp on its PATH. Quit the client and start it again from a new terminal window, or set command to the absolute path that command -v kraken-mcp prints in a new terminal. Most clients start the server without a shell, so ~ and $CARGO_HOME stay unexpanded. If kraken-mcp is missing, run the one-liner again: older releases installed kraken only. Run ~/.cargo/bin/kraken-mcp -s market (or the $CARGO_HOME path) in a terminal to confirm the server starts; it prints one server_start line, then waits for a client. Stop it with Ctrl-C. Check that your client configuration matches the format in the MCP server section.

Spot paper trading state errors

Workspace '<NAME>' not found means the paper account was never created: run kraken paper init (or kraken workspace create <NAME> --mode paper --capital 10000). To start an existing account over, run kraken paper reset --yes, after stopping any recording session with kraken session stop. A malformed log line error means the journal itself is damaged, and reset cannot read it either: move that workspace's journal.jsonl aside (in ~/Library/Application Support/kraken/workspaces/<NAME>/ on macOS, ~/.config/kraken/workspaces/<NAME>/ on Linux), then run kraken paper reset --yes.

Futures paper trading state errors

Run kraken futures paper reset with no workspace selected. If the state file itself cannot be read (for example, open orders saved by 0.4.1), reset fails too: delete futures_state.json from the paper/ folder of your config directory (~/Library/Application Support/kraken/paper/ on macOS, ~/.config/kraken/paper/ on Linux) and run kraken futures paper init. Spot and futures paper states are independent.

The chart tracks stars on krakenfx/kraken-cli over time.

cargo build                                            # dev build
cargo test                                             # run tests
cargo clippy --workspace --all-targets -- -D warnings  # lint
just ready                                             # the full local gate (see CONTRIBUTING.md)

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

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.