Skip to content
Back to search

kraken

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/krakenfx--kraken-cli/badge.svg)](/listings/krakenfx--kraken-cli)

HTML

<a href="/listings/krakenfx--kraken-cli"><img src="/api/listings/krakenfx--kraken-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

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 build, 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

> [!NOTE] `command not found: kraken` right after install? The installer puts > the binaries in `~/.cargo/bin` (or `$CARGO_HOME/bin` if you set it) and adds > that folder to your PATH for new terminals only. > > - Terminal: open a new window, or run `source "$HOME/.cargo/env"` > (`$CARGO_HOME/env` if you set it, `env.fish` for fish). > - Claude Code, Codex, or another agent you start in a terminal: quit it, open > a new terminal window, and start it there. The old window keeps the old > PATH. > - Cursor, VS Code, or another desktop app: quit it and open it again. > - Until then, use the full path `~/.cargo/bin/kraken` (or > `$CARGO_HOME/bin/kraken`).

Pre-built binaries are also available on the [GitHub Releases](https://github.com/krakenfx/kraken-cli/releases) page.

<details> <summary>Build from source</summary>

Requires [Rust](https://rustup.rs/) 1.97 or later. If cargo says a newer rustc is required, run `rustup update`.

A source build is DuckDB-free by default, because the bundled DuckDB C++ build dominates compile time and only `kraken record --to duckdb` needs it. Pass `--features record-duckdb` to any command below to include it; the released binaries already carry it.

Both commands install all three binaries: `kraken`, `kraken-mcp` and `kraken-shell`.

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

Or clone and build:

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

If an earlier source install added `kraken-mcp` or `kraken-shell`, cargo stops with "binary already exists". Run `cargo uninstall kraken-mcp kraken-shell` first, or add `--force`.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "kraken",
  3. "owner": { "name": "Kraken", "email": "support@kraken.com" },
  4. "metadata": { "description": "Official Kraken plugins for AI agents." },
  5. "plugins": [
  6. {
  7. "name": "kraken-cli",
  8. "source": "./",
  9. "description": "Market data, paper trading and Kraken trading tools for agents, backed by kraken-cli."
  10. }
  11. ]
  12. }
README.md · README · 1,989 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Kraken CLI
  2. [![GitHub stars](https://img.shields.io/github/stars/krakenfx/kraken-cli?style=social)](https://github.com/krakenfx/kraken-cli)
  3. [![version](https://img.shields.io/github/v/release/krakenfx/kraken-cli?color=blue)](https://github.com/krakenfx/kraken-cli/releases)
  4. [![downloads](https://img.shields.io/github/downloads/krakenfx/kraken-cli/total?color=blue)](https://github.com/krakenfx/kraken-cli/releases)
  5. [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  6. [![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)](#installation)
  7. Trade on Kraken from your terminal, or let your AI agent trade for you. One
  8. install covers crypto, tokenized U.S. stocks and ETFs (for non-U.S. customers),
  9. forex, and futures. Every command can answer in JSON. A built-in MCP server
  10. connects the CLI to Claude, Cursor, Codex and other agents, and paper trading
  11. runs on live prices with no account.
  12. ```bash
  13. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh | sh
  14. source "$HOME/.cargo/env" # puts kraken on your PATH in this terminal
  15. kraken ticker BTCUSD # live price, no account needed
  16. ```
  17. <!-- prettier-ignore -->
  18. > [!TIP]
  19. > **New: sign in with OAuth.** You no longer have to fumble around for API
  20. > keys. `kraken auth login` opens Kraken in your browser, you approve, and the
  21. > CLI saves a restricted Spot API key for you. The key can't withdraw funds,
  22. > and it expires on its own. [See how it works](#sign-in-with-oauth).
  23. With kraken-cli you can:
  24. - Trade 1,400+ crypto pairs, 170+ tokenized U.S. stocks and ETFs (xStocks), 12
  25. forex pairs and 200+ futures contracts.
  26. [What you can trade](#what-you-can-trade)
  27. - Practice on paper first. Paper orders fill at live prices and need no Kraken
  28. account, and the basic order commands are the same as live.
  29. [Paper trading](#paper-trading)
  30. - Connect Claude, Cursor, Codex, Gemini and other MCP clients through
  31. `kraken-mcp`, which serves up to 152 MCP tools. On clients that support MCP
  32. elicitation, calls that move money ask you first; the `kraken` CLI itself
  33. places orders without a prompt. [MCP server](#mcp-server)
  34. - Script it: every command takes `-o json`, and a failure comes back as JSON
  35. with a stable `error` field and a non-zero exit code.
  36. [For AI agents](#for-ai-agents)
  37. - Record live market data and replay it into paper sessions, then score a
  38. strategy against pass criteria you fixed before the first run.
  39. [Workspaces, sessions, and research](#workspaces-sessions-and-research)
  40. - Start from 59 agent skills for DCA, grid trading, rebalancing, futures risk
  41. and more. [Agent skills](#agent-skills)
  42. | You are | Start here |
  43. | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  44. | A person at a terminal | [Install](#installation), then follow the [Quick start](#quick-start) from sign-in to your first order. |
  45. | An AI agent, or building one | Read [For AI agents](#for-ai-agents) and [AGENTS.md](AGENTS.md). Ask your human to open a new terminal and run `kraken auth login` there, then call `kraken <command> -o json 2>/dev/null`. Orders trade real money with no confirmation prompt, so follow the [rules for trading real money](#rules-for-trading-real-money). |
  46. | Just looking around | Market data and paper trading need no account. Try steps 1 and 2 of the [Quick start](#quick-start). |
  47. Paste one of these prompts into Claude Code, Codex, Cursor, or another AI coding
  48. agent. No agent yet? Install [Claude Code](https://claude.com/claude-code)
  49. first.
  50. ```text
  51. Install kraken-cli (https://github.com/krakenfx/kraken-cli) and tell me how to sign in with OAuth.
  52. ```
  53. ```text
  54. Install kraken-cli (https://github.com/krakenfx/kraken-cli) and build me a morning market brief.
  55. ```
  56. ```text
  57. With kraken-cli, watch ETH, SOL, and BTC for 30 seconds. What are the pros and cons of buying each right now?
  58. ```
  59. ```text
  60. With kraken-cli, look up AAPLx, TSLAx, and SPYx on xStocks. Summarize how each is performing today.
  61. ```
  62. ```text
  63. 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.
  64. ```
  65. ```text
  66. With kraken-cli futures paper trading, open a 10x leveraged long on BTC with $5,000 collateral. Set a trailing stop at 3%.
  67. ```
  68. If kraken-cli is useful to you,
  69. [star the repo](https://github.com/krakenfx/kraken-cli) so other traders and
  70. agent builders can find it. To hear about new releases, choose **Watch >
  71. Custom > Releases** on the repo page.
  72. <!-- prettier-ignore -->
  73. > [!CAUTION]
  74. > Experimental software. It interacts with the live Kraken exchange and can
  75. > execute real financial transactions. Read [DISCLAIMER.md](DISCLAIMER.md)
  76. > before using it with real funds or AI agents.
  77. ## Contents
  78. - [Installation](#installation)
  79. - [Quick start](#quick-start)
  80. - [Sign in with OAuth](#sign-in-with-oauth)
  81. - [API keys & configuration](#api-keys--configuration)
  82. - [What you can trade](#what-you-can-trade)
  83. - [Paper trading](#paper-trading)
  84. - [For AI agents](#for-ai-agents)
  85. - [Output and errors](#output-and-errors)
  86. - [MCP server](#mcp-server)
  87. - [Workspaces, sessions, and research](#workspaces-sessions-and-research)
  88. - [Commands](#commands)
  89. - [Examples](#examples)
  90. - [Agent skills](#agent-skills)
  91. - [Troubleshooting](#troubleshooting)
  92. - [Star history](#star-history)
  93. - [Development](#development)
  94. - [Contributing](#contributing)
  95. - [License & disclaimer](#license--disclaimer)
  96. ## Installation
  97. One install, no runtime dependencies. It puts three binaries on your PATH:
  98. `kraken`, `kraken-mcp` (the MCP server) and `kraken-shell` (an interactive
  99. shell).
  100. ### One-liner
  101. ```bash
  102. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh | sh
  103. ```
  104. The installer detects your OS and architecture, downloads the right build, and
  105. installs it. macOS (Apple Silicon and Intel) and Linux (x86_64 and ARM64) are
  106. supported. On Windows, use WSL. AI agents: ask your human before you run the
  107. installer on their machine.
  108. Open a new terminal (or run `source "$HOME/.cargo/env"`), then check that it
  109. works:
  110. ```bash
  111. kraken status && kraken ticker BTCUSD
  112. ```
  113. <!-- prettier-ignore -->
  114. > [!NOTE]
  115. > `command not found: kraken` right after install? The installer puts the
  116. > binaries in `~/.cargo/bin` (or `$CARGO_HOME/bin` if you set it) and adds that
  117. > folder to your PATH for new terminals only.
  118. >
  119. > - AI agent in the middle of a task: call `~/.cargo/bin/kraken` (or
  120. > `$CARGO_HOME/bin/kraken`) by its full path for the rest of the session.
  121. > - Terminal: open a new window, or run `source "$HOME/.cargo/env"`
  122. > (`$CARGO_HOME/env` if you set it, `env.fish` for fish).
  123. > - Claude Code, Codex, or another agent you start in a terminal: quit it, open
  124. > a new terminal window, and start it there. The old window keeps the old
  125. > PATH.
  126. > - Cursor, VS Code, Claude Desktop, or another desktop app: quit it and open
  127. > it again. If it still can't find `kraken`, use the full path that
  128. > `command -v kraken` prints in a new terminal.
  129. Pre-built binaries are also on the
  130. [GitHub Releases](https://github.com/krakenfx/kraken-cli/releases) page.
  131. ### Verifying binaries
  132. Releases are signed with [minisign](https://jedisct1.github.io/minisign/). Every
  133. release archive, its `.sha256` file, the installer script and `SHA256SUMS.txt`
  134. on the [Releases](https://github.com/krakenfx/kraken-cli/releases) page has a
  135. matching `.minisig` signature file.
  136. Download the archive and its `.minisig` into the same folder, then check it
  137. against the public key:
  138. ```bash
  139. minisign -Vm kraken-cli-aarch64-apple-darwin.tar.gz -P RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd
  140. ```
  141. Public key:
  142. ```text
  143. RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd
  144. ```
  145. Install minisign with `brew install minisign` (macOS) or `apt install minisign`
  146. (Linux). To check the installer before you run it:
  147. ```bash
  148. curl -LO https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh
  149. curl -LO https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh.minisig
  150. minisign -Vm kraken-cli-installer.sh -P RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd && sh kraken-cli-installer.sh
  151. ```
  152. <details>
  153. <summary>Build from source</summary>
  154. Requires [Rust](https://rustup.rs/) 1.97 or later. If cargo says a newer rustc
  155. is required, run `rustup update`. A clone pins its toolchain in
  156. `rust-toolchain.toml`, so rustup may download that version on the first build.
  157. A source build is DuckDB-free by default, because the bundled DuckDB C++ build
  158. dominates compile time and only DuckDB tapes need it: writing one
  159. (`kraken record --to duckdb`) or reading one, such as a 0.4.x tape. Pass
  160. `--features record-duckdb` to any command below to include it; the released
  161. binaries already carry it.
  162. Both commands install all three binaries: `kraken`, `kraken-mcp` and
  163. `kraken-shell`.
  164. ```bash
  165. cargo install --locked --git https://github.com/krakenfx/kraken-cli kraken-cli
  166. ```
  167. Or clone and build:
  168. ```bash
  169. git clone https://github.com/krakenfx/kraken-cli.git
  170. cd kraken-cli
  171. cargo install --locked --path crates/kraken-cli
  172. ```
  173. If an earlier source install added `kraken-mcp` or `kraken-shell`, cargo stops
  174. with "binary already exists". Run `cargo uninstall kraken-mcp kraken-shell`
  175. first, or add `--force`.
  176. </details>
  177. ## Quick start
  178. Steps 1 and 2 need no account. To trade real money you need a verified Kraken
  179. account with funds in it; you can
  180. [create one on kraken.com](https://www.kraken.com/sign-up).
  181. ### 1. Look at the market
  182. Public market data needs no credentials, so nothing here can touch an account.
  183. ```bash
  184. kraken ticker BTCUSD
  185. kraken orderbook BTCUSD --count 10
  186. kraken ohlc BTCUSD --interval 60
  187. ```
  188. Output is a table. Add `-o json` to any command for JSON. REST commands accept
  189. `BTCUSD`, `BTC/USD` or `XBTUSD`; the examples for streaming commands (`ws`,
  190. `record`, `session`) use `BTC/USD`.
  191. ### 2. Practice with paper trading
  192. ```bash
  193. kraken workspace create sandbox --capital 10000 --mode paper
  194. export KRAKEN_WORKSPACE=sandbox
  195. kraken paper buy BTCUSD 0.01
  196. kraken workspace status
  197. unset KRAKEN_WORKSPACE
  198. ```
  199. Paper orders fill at live prices with simulated money. `paper buy` may log a
  200. warning that no session is recording; you can ignore it here.
  201. While `KRAKEN_WORKSPACE` names a paper workspace, `kraken order buy` and
  202. `kraken balance` act on the simulated account as well. The last line unsets it
  203. so the next steps reach your real account. [Paper trading](#paper-trading)
  204. covers the rest.
  205. ### 3. Sign in
  206. ```bash
  207. kraken auth login
  208. kraken auth test
  209. ```
  210. `kraken auth login` opens Kraken's sign-in page in your browser. Sign in,
  211. approve access, and the CLI saves a Spot API key for you. The key covers spot
  212. crypto, xStocks and forex, can't withdraw funds, and expires after 90 days. Run
  213. it yourself in an interactive terminal: it refuses to run from a script, a CI
  214. job or an AI agent's shell. `kraken auth test` checks the saved key against your
  215. account. [Sign in with OAuth](#sign-in-with-oauth) covers each step.
  216. - Trading futures? The sign-in key is Spot only. Create a Futures key and set
  217. `KRAKEN_FUTURES_API_KEY` and `KRAKEN_FUTURES_API_SECRET`, or add it to
  218. `config.toml` (see [API keys & configuration](#api-keys--configuration)).
  219. - Prefer a key you created yourself? Run `kraken setup` in a terminal, or store
  220. it with [`kraken auth set`](#store-a-key-you-created).
  221. - Using an AI agent? Sign in in your own terminal, and the agent uses the stored
  222. key. Never paste an API key into an AI chat.
  223. ### 4. Check your account
  224. ```bash
  225. kraken balance
  226. kraken open-orders
  227. ```
  228. Balance empty? Fund the account on kraken.com, or list your deposit options with
  229. `kraken deposit methods USD`.
  230. ### 5. Preview an order
  231. ```bash
  232. kraken ticker BTCUSD # check the price
  233. kraken order buy BTCUSD 20 --type market --oflags viqc --validate # $20 of BTC, checked only
  234. ```
  235. `--validate` asks Kraken to check the order without placing it, so nothing
  236. trades. `--oflags viqc` makes the volume a quote-currency amount, here 20 USD.
  237. Leave the flag off and `20` means 20 BTC. Kraken accepts `viqc` on market buys
  238. only. For a limit order, give the volume in BTC and a price:
  239. ```bash
  240. kraken order buy BTCUSD 0.0005 --type limit --price 75000 --validate
  241. ```
  242. `kraken order buy` defaults to `--type limit`, which needs `--price`. To see the
  243. smallest order a pair accepts, run `kraken pairs --pair BTCUSD -o json` and read
  244. `ordermin` (volume) and `costmin` (cost in the quote currency).
  245. ### 6. Place your first order
  246. Drop `--validate`. This places a real order with real money, and there is no
  247. confirmation prompt: it goes to Kraken when you press Enter. Check that
  248. `echo $KRAKEN_WORKSPACE` prints nothing first, so the order reaches your real
  249. account:
  250. ```bash
  251. kraken order buy BTCUSD 20 --type market --oflags viqc
  252. ```
  253. The receipt starts with `Mode [LIVE] Real Money` and shows the order ID, which
  254. is Kraken's transaction ID. With `-o json`, check that `mode` is `"live"` and
  255. read `order_id`. Then check it:
  256. ```bash
  257. kraken query-orders <ORDER_ID> # status "closed" means it filled
  258. kraken balance
  259. ```
  260. A limit order that hasn't filled stays open; cancel it with
  261. `kraken order cancel <ORDER_ID>`.
  262. Futures orders use `kraken futures order buy` and `sell` with your Futures key.
  263. They have no `--validate`, so rehearse them with
  264. [futures paper trading](#futures-paper-trading) first. Sizes are in contracts:
  265. one `PF_XBTUSD` contract is 1 BTC.
  266. ## Sign in with OAuth
  267. `kraken auth login` signs you in with OAuth. You approve access on Kraken's own
  268. sign-in page, and the CLI creates and saves a restricted Spot API key for you.
  269. You skip the API settings page and the copy and paste.
  270. ```bash
  271. kraken auth login
  272. ```
  273. ### What the key can do
  274. - It can query balances, place, amend and cancel orders, read trades and ledger
  275. entries, use deposits and Earn, request exports, and open authenticated
  276. WebSocket streams.
  277. - It has no withdrawal rights.
  278. - It covers Spot only: spot crypto, xStocks and forex. Futures commands still
  279. use their own key (see [API keys & configuration](#api-keys--configuration)).
  280. - It expires after 90 days. `--valid-for` sets a shorter life, from 1 minute up
  281. to 90 days.
  282. | Option | What it does |
  283. | ------------------------ | ----------------------------------------------------------------------------------------------------- |
  284. | `--read-only` | Creates a key that can read balances, orders, trades, and ledger entries, but cannot trade. |
  285. | `--valid-for <DURATION>` | Sets how long the key stays valid, for example `30d` or `12h`. The default and the maximum are `90d`. |
  286. | `--no-browser` | Prints the sign-in URL without opening a browser. |
  287. ```bash
  288. kraken auth login --read-only --valid-for 30d
  289. ```
  290. You have 5 minutes to approve in the browser. After that the command stops with
  291. a `timeout` error, and you run it again.
  292. <details>
  293. <summary>What happens when you sign in</summary>
  294. 1. You run `kraken auth login` in a terminal. It refuses to run without one.
  295. 2. The CLI starts a listener on your own machine, on the first free port from
  296. 27461 to 27463, and opens Kraken's sign-in page in your browser. If all three
  297. ports are busy, sign-in fails.
  298. 3. You sign in on Kraken and approve access.
  299. 4. Kraken sends your browser back to `http://localhost:<port>/callback` with a
  300. one-time code.
  301. 5. The CLI exchanges the code for permission to create a key. This is a standard
  302. OAuth authorization-code flow with PKCE (S256). The CLI is a public OAuth
  303. client, so there is no client secret.
  304. 6. The CLI creates a restricted Spot API key and saves it to `config.toml`,
  305. which is created with `0600` permissions.
  306. 7. If you already had a sign-in key, the new one replaces it and the CLI deletes
  307. the old one. Anything still signing with the old key stops working. If the
  308. delete fails, the old key stays on your account until it expires.
  309. </details>
  310. ### Signing in over SSH
  311. Forward the three callback ports, then ask the CLI to print the sign-in URL and
  312. open it on your own machine. The listener takes the first free port of the
  313. three, so forward all of them.
  314. ```bash
  315. # On your own machine: connect with the callback ports forwarded.
  316. ssh -L 27461:localhost:27461 -L 27462:localhost:27462 -L 27463:localhost:27463 <host>
  317. # On the remote machine: print the sign-in URL, then open it on your own machine.
  318. kraken auth login --no-browser
  319. ```
  320. ### Checking, switching, and removing keys
  321. ```bash
  322. kraken auth show # which key is in use, and whether a flag or env var overrides it (alias: auth status)
  323. kraken auth test # checks the key in use against your account
  324. kraken auth switch sign-in # signs requests with the OAuth sign-in key
  325. kraken auth switch api-key # signs requests with the key from `kraken auth set` or `kraken setup`
  326. kraken auth reset # deletes every stored key from config.toml; revokes nothing on Kraken
  327. ```
  328. Your config can hold a sign-in key and an API key at the same time.
  329. [Credential resolution](#credential-resolution) explains which one signs.
  330. `auth reset` deletes every stored key from `config.toml`: the API key, the
  331. sign-in key, and the Futures key. It revokes nothing on Kraken, so the sign-in
  332. key keeps working until it expires. To revoke it at once, delete it where you
  333. manage API keys on kraken.com. An older release ignores the sign-in key and can
  334. drop it from `config.toml`, so delete the key in the Kraken UI before you
  335. downgrade.
  336. ### Using OAuth with AI agents
  337. OAuth sign-in is for a person at a terminal. `kraken auth login` refuses to run
  338. without one, the catalog marks it `dangerous`, and the MCP server does not serve
  339. it. An agent can't start it and should never try.
  340. A person signs in once, and the agent reuses the key:
  341. 1. A person runs `kraken auth login` once, in their own terminal.
  342. 2. The agent calls commands as usual, for example
  343. `kraken balance -o json 2>/dev/null`. The CLI signs with the stored OAuth
  344. key.
  345. 3. A key from a flag or an environment variable wins over the stored key.
  346. 4. When the sign-in key expires, calls that need a key return an `auth` error
  347. envelope. The CLI does not fall back to another stored key. Tell the person
  348. to run `kraken auth login` again.
  349. ## API keys & configuration
  350. Authenticated commands (trading, balances, order management) need a Kraken API
  351. key pair. Public market data and paper trading work without credentials.
  352. The easiest way to get a key is [OAuth sign-in](#sign-in-with-oauth). Create one
  353. by hand when you need a Futures key, specific permissions, or credentials for
  354. automation.
  355. ### Getting API keys
  356. **Spot** (covers trading, balances, funding, earn, subaccounts): **Settings >
  357. API** on kraken.com. Step-by-step guide:
  358. [How to create a spot API key](https://support.kraken.com/articles/360000919966-how-to-create-an-api-key).
  359. **Futures** (only for `kraken futures` commands):
  360. [sign in to Kraken Futures](https://www.kraken.com/login-futures), then go to
  361. **Settings > Create Key**. Full guide:
  362. [How to create a Futures API key](https://support.kraken.com/hc/en-us/articles/360022839451-How-to-create-an-API-key-for-Kraken-Futures).
  363. Grant the minimum permissions your workflow needs:
  364. - Read-only monitoring: "Query Funds" and "Query Open Orders & Trades" cover
  365. balances and open orders. Add "Query Closed Orders & Trades" for trade history
  366. and "Query Ledger Entries" for ledgers.
  367. - Trading: add the permissions to create, modify, cancel and close orders.
  368. - Leave withdrawal permission off unless a script needs to withdraw.
  369. ### Store a key you created
  370. `kraken setup` is an interactive wizard. It asks for your Spot key and,
  371. optionally, a Futures key. Run it in a normal terminal, because it reads your
  372. input.
  373. `kraken auth set` stores a key without asking you to type it. It always needs a
  374. Spot key and its secret. Pass the secret on stdin or from a file so it stays out
  375. of your shell history and process list, and add the Futures flags to store a
  376. Futures key in the same call:
  377. ```bash
  378. kraken auth set --api-key <YOUR_KEY> --api-secret-stdin
  379. kraken auth set --api-key <YOUR_KEY> --api-secret-file ~/kraken-secret.txt \
  380. --futures-api-key <FUTURES_KEY> --futures-api-secret-file ~/kraken-futures-secret.txt
  381. ```
  382. Delete the secret files once the keys are stored. `kraken setup` and
  383. `kraken auth set` write the same API key slot. If a working sign-in key is
  384. already active, the CLI asks which key to use in a terminal and keeps the active
  385. key in a script. To add only a Futures key and keep your sign-in key, use the
  386. Futures environment variables or the `config.toml` fields below.
  387. ### Environment variables (recommended for agents and automation)
  388. ```bash
  389. export KRAKEN_API_KEY="your-key"
  390. export KRAKEN_API_SECRET="your-secret"
  391. export KRAKEN_FUTURES_API_KEY="your-futures-key" # optional
  392. export KRAKEN_FUTURES_API_SECRET="your-futures-secret" # optional
  393. ```
  394. Set them in the environment that the agent or script starts from. A secrets
  395. manager keeps the secret out of your shell history, for example
  396. `export KRAKEN_API_SECRET="$(op read 'op://Private/Kraken/secret')"` with the
  397. 1Password CLI. An agent that is already running won't see variables you export
  398. afterwards. Never paste API keys into an AI chat.
  399. ### Config file
  400. Credentials live in `~/.config/kraken/config.toml` (Linux) or
  401. `~/Library/Application Support/kraken/config.toml` (macOS):
  402. ```toml
  403. [auth]
  404. api_key = "your-api-key"
  405. api_secret = "your-api-secret"
  406. futures_api_key = "your-futures-key" # optional
  407. futures_api_secret = "your-futures-secret" # optional
  408. ```
  409. ### Credential resolution
  410. Highest precedence first:
  411. 1. Command-line flags (`--api-key`, `--api-secret`). Spot and Futures commands
  412. share this pair.
  413. 2. Environment variables: `KRAKEN_API_KEY` and `KRAKEN_API_SECRET` for Spot,
  414. `KRAKEN_FUTURES_API_KEY` and `KRAKEN_FUTURES_API_SECRET` for Futures.
  415. 3. The stored key in `config.toml`. For Spot that is the active one of the API
  416. key (from `kraken auth set` or `kraken setup`) and the OAuth sign-in key
  417. (from `kraken auth login`).
  418. Which stored Spot key is active:
  419. | Situation | Active key |
  420. | -------------------------------------------------------------------- | ------------------------------------------------------------------- |
  421. | Only one key is stored | That key |
  422. | Both are stored and you never chose | The API key |
  423. | You store a new key while another key is active and working | In a terminal the CLI asks you; in a script it keeps the active key |
  424. | The active key has expired or is missing when you store a new one | The new key, without a prompt |
  425. | You run `kraken auth switch api-key` or `kraken auth switch sign-in` | The key you chose |
  426. The CLI changes the active key only when you choose one, or when you store a new
  427. key while the active one is expired or missing. It never falls back to the other
  428. key: an expired sign-in key stays active and fails with an `auth` error until
  429. you sign in again or run `kraken auth switch api-key`. `kraken auth show` tells
  430. you which key is in use.
  431. ### Security
  432. - The config file is created with `0600` permissions (owner read/write only).
  433. - Secrets are never logged, printed, or included in error messages.
  434. - Use `--api-secret-stdin` or `--api-secret-file` instead of `--api-secret` to
  435. keep secrets out of process listings.
  436. - For automation, prefer environment variables over command-line flags.
  437. <details>
  438. <summary>Advanced: API endpoint overrides</summary>
  439. | Variable | Default | Description |
  440. | -------------------------- | ----------------------------------------------- | ------------------------------------- |
  441. | `KRAKEN_SPOT_URL` | `https://api.kraken.com` | Spot REST API base URL |
  442. | `KRAKEN_FUTURES_URL` | `https://futures.kraken.com/derivatives/api/v3` | Futures REST API base URL |
  443. | `KRAKEN_WS_PUBLIC_URL` | `wss://ws.kraken.com/v2` | Public WebSocket endpoint |
  444. | `KRAKEN_WS_AUTH_URL` | `wss://ws-auth.kraken.com/v2` | Authenticated Spot WebSocket endpoint |
  445. | `KRAKEN_WS_L3_URL` | `wss://ws-l3.kraken.com/v2` | Level 3 order book WebSocket endpoint |
  446. | `KRAKEN_FUTURES_WS_URL` | `wss://futures.kraken.com/ws/v1` | Futures WebSocket endpoint |
  447. | `KRAKEN_FEEDBACK_ENDPOINT` | `https://cli-feedback.kraken.com/v1/feedback` | Product feedback ingest URL |
  448. Resolution: CLI flag (`--api-url`, `--futures-url`, `--ws-public-url`,
  449. `--ws-auth-url`, `--ws-l3-url`, `--ws-futures-url`) > environment variable >
  450. default. `KRAKEN_FEEDBACK_ENDPOINT` has no flag. Every override must use
  451. `https://` or `wss://` and point at a Kraken host.
  452. `KRAKEN_DANGER_ALLOW_ANY_URL_HOST=1` (`--danger-allow-any-url-host`) lifts the
  453. host check, and for `KRAKEN_FEEDBACK_ENDPOINT` it also allows `http://`. Use it
  454. for local testing only.
  455. </details>
  456. ## What you can trade
  457. Spot crypto, xStocks and forex share `kraken order` (add
  458. `--asset-class tokenized_asset` for xStocks; forex pairs such as `EURUSD` need
  459. no asset class to trade). Futures use `kraken futures order` with a separate
  460. Futures API key, and Earn has its own `kraken earn` commands. The spot and
  461. xStocks examples below use `--validate`, so Kraken checks them without placing
  462. them.
  463. | Asset class | Instruments | Margin | Commands | Example |
  464. | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
  465. | **Crypto spot** | 1,400+ pairs (BTC, ETH, SOL, and hundreds more) | Up to 10x on major pairs | `kraken order` | `kraken order buy BTCUSD 0.001 --type limit --price 50000 --validate` |
  466. | **Tokenized U.S. stocks & ETFs ([xStocks](https://www.kraken.com/xstocks))** | 170+ xStocks: AAPL, NVDA, TSLA, GOOGL, AMZN, MSFT, SPY, QQQ, and more | Up to 3x on select xStocks | `kraken order --asset-class tokenized_asset` | `kraken order buy AAPLx/USD 0.1 --type limit --price 200 --asset-class tokenized_asset --validate` |
  467. | **Forex** | 12 fiat pairs: EUR/USD, GBP/USD, USD/JPY, AUD/USD, and more | None | `kraken order` | `kraken ticker EURUSD --asset-class forex` |
  468. | **Perpetual futures** | 200+ contracts: crypto, 3 forex perps (EUR, GBP, CHF), stock, ETF and index perps (AAPL, NVDA, TSLA, SPY, QQQ, US 100), commodities, and pre-IPO | Up to 100x (BTC, ETH, SOL); 10x to 50x on most others; lower in some regions | `kraken futures order` | `kraken futures ticker PF_XBTUSD` |
  469. | **Inverse & fixed-date futures** | 22 contracts on BTC, ETH, SOL, LTC, XRP: inverse perpetuals (`PI_`), inverse fixed-date (`FI_`), and fixed-date (`FF_`) | Varies | `kraken futures order` | `kraken futures instruments` |
  470. | **Earn / staking** | Flexible, bonded, timed and instant strategies across multiple assets | n/a | `kraken earn` | `kraken earn strategies --asset ETH` |
  471. Futures sizes are in contracts: one `PF_XBTUSD` contract is 1 BTC, and `FI_`
  472. contracts are 1 USD each. Fixed-date symbols end in their expiry date
  473. (`YYMMDD`). `kraken futures instruments` lists the contracts that are trading
  474. now. Futures orders have no `--validate`, so rehearse them with
  475. [futures paper trading](#futures-paper-trading).
  476. _xStocks are not available in the USA. Availability for all products varies by
  477. jurisdiction._
  478. ## Paper trading
  479. Paper trading tests trading logic against live Kraken prices with simulated
  480. money. It needs no API key and no Kraken account. Spot and futures each have
  481. their own paper engine.
  482. ### Spot paper trading
  483. There are two ways to place a spot paper order:
  484. - `kraken paper buy` and `kraken paper sell` always simulate.
  485. - Inside a paper workspace (`KRAKEN_WORKSPACE` or `--workspace`), the live verbs
  486. `kraken order buy`, `balance`, `open-orders` and `trades-history` act on the
  487. simulated account too. A strategy that sticks to these verbs, with `--type`
  488. and `--price`, runs unchanged once you promote it to live (see Strategy
  489. workspaces in the [full command reference](#commands)). Inside a workspace,
  490. `order buy` and `sell` refuse `--cl-ord-id`, `--oflags` and most other
  491. advanced flags.
  492. `paper buy` defaults to a market order and `order buy` to a limit order, so pass
  493. `--type` when you switch. Paper supports `market` and `limit` orders, a
  494. configurable flat slippage model, and no partial fills.
  495. **Agent pattern:**
  496. ```bash
  497. kraken workspace create sandbox --capital 10000 --mode paper -o json
  498. export KRAKEN_WORKSPACE=sandbox
  499. kraken paper buy BTCUSD 0.01 -o json
  500. kraken paper sell BTCUSD 0.005 --type limit --price 90000 -o json
  501. kraken workspace status -o json
  502. kraken workspace reset --yes -o json # dangerous: only when your human asks for a reset
  503. unset KRAKEN_WORKSPACE
  504. ```
  505. **Human pattern:**
  506. ```bash
  507. kraken workspace create sandbox-eur --capital 5000 --currency EUR --mode paper
  508. export KRAKEN_WORKSPACE=sandbox-eur
  509. kraken paper buy BTCEUR 0.01
  510. kraken paper balance
  511. kraken paper status
  512. kraken paper orders
  513. kraken paper history
  514. kraken workspace reset
  515. unset KRAKEN_WORKSPACE
  516. ```
  517. | Command | Description |
  518. | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  519. | `kraken paper init [NAME] [--capital 10000] [--currency USD] [--fee-rate 0.0026] [--slippage-rate 0]` | Older shortcut for `workspace create --mode paper`. With no workspace selected it creates one named `global` |
  520. | `kraken paper reset [NAME] [--capital N] [--currency C] [--fee-rate R] [--slippage-rate S] [--yes]` | Shortcut for `workspace reset`: starts a new capital epoch. Open orders are dropped unfilled; `paper orders` and `paper history` start empty |
  521. | `kraken paper balance` | All balances (total, reserved, available) |
  522. | `kraken paper buy <PAIR> <VOL> [--type limit --price P]` | Paper buy (market or limit) |
  523. | `kraken paper sell <PAIR> <VOL> [--type limit --price P]` | Paper sell (market or limit) |
  524. | `kraken paper orders` | Open limit orders |
  525. | `kraken paper cancel <ORDER_ID>` | Cancel a limit order |
  526. | `kraken paper cancel-all` | Cancel all limit orders |
  527. | `kraken paper history` | Filled trade history |
  528. | `kraken paper status` | Portfolio value, unrealized P&L, trade count |
  529. Prices come from the public Kraken Ticker API (no auth needed). By default a
  530. 0.26% taker fee applies to every fill; set another rate with `--fee-rate`.
  531. Optional slippage simulation applies a flat rate to market orders: buys fill at
  532. `ask * (1 + slippage_rate)`, sells at `bid * (1 - slippage_rate)`. Default
  533. slippage is 0.0 (no simulation). A limit order always rests when placed, even
  534. when the market is already through its price. The next `paper buy`, `sell`,
  535. `orders`, `cancel`, `cancel-all`, `history` or `status` checks it against the
  536. live price, and once the market has crossed the limit it fills at the limit
  537. price, not at the better market price.
  538. In table mode, `paper buy`, `sell`, `cancel`, `cancel-all` and `status` lead
  539. with a `[PAPER] Simulated Trading` row, and `paper orders` and `history` put
  540. `[PAPER]` in their first column header. Their JSON carries `"mode": "paper"`, as
  541. does the JSON of `paper balance` and `paper init`. `paper init` shows a plain
  542. `Mode` row; the `paper balance` table and all `paper reset` output carry no
  543. marker.
  544. ### Futures paper trading
  545. Near-parity with live `kraken futures order` commands. Supports all 8 order
  546. types (market, limit, post, stop, take-profit, ioc, trailing-stop, fok),
  547. leverage and margin tracking, position aggregation/netting, liquidation
  548. simulation, and funding rate accrual. `--type` defaults to `limit`, and the fee
  549. rate to 0.05% (`--fee-rate 0.0005`). Known differences: `order-status` accepts a
  550. single ID (live accepts multiple), post-only orders are cancelled rather than
  551. simulating maker queue priority, and fills use the bid/ask snapshot with no
  552. depth-based slippage. Only IOC orders fill partially: they take the book depth
  553. available at the limit price and cancel the rest.
  554. The live commands differ in more than the prefix. `futures paper buy`/`sell`
  555. become `futures order buy`/`sell`, which take no `--leverage` (set it with
  556. `futures set-leverage`), and `futures paper orders` becomes
  557. `futures open-orders`. `edit-order`, `cancel`, `cancel-all`, `batch-order`,
  558. `order-status`, `positions`, `fills`, `leverage` and `set-leverage` keep their
  559. names under `futures`. `init`, `reset`, `balance` and `status` are paper-only;
  560. `futures accounts` shows the live wallet. Live `futures history` is public trade
  561. history; your own past orders and fills are in `futures history-orders` and
  562. `futures history-executions`.
  563. Futures paper state is global, not per workspace. Run it with no workspace
  564. selected (`unset KRAKEN_WORKSPACE` if an earlier example exported it): inside a
  565. workspace only `balance`, `status`, `orders`, `order-status`, `positions` and
  566. `fills` run; `history`, `leverage` and every mutation are refused.
  567. Successful JSON responses include `"mode": "futures_paper"`. Most table views
  568. are labeled `[FUTURES PAPER]` or `[FP]`.
  569. **Agent pattern:**
  570. ```bash
  571. kraken futures paper init --balance 10000 -o json
  572. kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json
  573. kraken futures paper sell PF_ETHUSD 5 --leverage 20 --type market -o json
  574. kraken futures paper positions -o json
  575. kraken futures paper status -o json
  576. kraken futures paper reset -o json
  577. ```
  578. **Human pattern:**
  579. ```bash
  580. kraken futures paper init --balance 10000 --currency USD
  581. kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market
  582. kraken futures paper sell PF_XBTUSD 1 --leverage 10 --type limit --price 70000
  583. kraken futures paper positions
  584. kraken futures paper balance
  585. kraken futures paper fills
  586. kraken futures paper history
  587. kraken futures paper reset
  588. ```
  589. | Command | Description |
  590. | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
  591. | `kraken futures paper init [--balance B] [--currency C] [--fee-rate R]` | Initialize futures paper account |
  592. | `kraken futures paper reset [--balance B] [--currency C] [--fee-rate R]` | Reset account (clear positions, orders, fills) |
  593. | `kraken futures paper balance` | Collateral, used margin, available margin, unrealized P&L |
  594. | `kraken futures paper status` | Equity, P&L since start, unrealized P&L, position/order counts |
  595. | `kraken futures paper buy <SYM> <SIZE> [--leverage L] [--type TYPE] ...` | Paper long (all 8 order types) |
  596. | `kraken futures paper sell <SYM> <SIZE> [--leverage L] [--type TYPE] ...` | Paper short (all 8 order types) |
  597. | `kraken futures paper orders` | Open resting orders |
  598. | `kraken futures paper order-status <ID>` | Query specific order |
  599. | `kraken futures paper edit-order --order-id <ID> [--size S] [--price P] [--stop-price SP]` | Edit a resting order |
  600. | `kraken futures paper cancel --order-id <ID>` | Cancel order (also supports `--cli-ord-id`) |
  601. | `kraken futures paper cancel-all [--symbol SYM]` | Cancel all (optional symbol filter) |
  602. | `kraken futures paper batch-order '<JSON>'` | Batch order placement |
  603. | `kraken futures paper positions` | Open positions with mark price, liquidation, P&L |
  604. | `kraken futures paper fills` | Fill history |
  605. | `kraken futures paper history` | Closed positions and cancelled orders |
  606. | `kraken futures paper leverage [--symbol SYM]` | Current leverage preferences |
  607. | `kraken futures paper set-leverage <SYM> <LEV>` | Set default leverage per symbol |
  608. `futures paper buy` and `sell` also take `--stop-price`,
  609. `--trigger-signal mark|index|last`, `--client-order-id`, `--reduce-only`,
  610. `--trailing-stop-max-deviation` and
  611. `--trailing-stop-deviation-unit percent|quote_currency`, the same as the live
  612. order commands.
  613. Prices come from the public Kraken Futures Ticker API (no auth needed). Taker
  614. fees are simulated. Positions track leverage, margin, and liquidation prices.
  615. Funding rates are accrued based on the public funding rate API. Spot paper and
  616. futures paper are fully independent: resetting one does not affect the other.
  617. ## For AI agents
  618. If you're an AI agent or building one, read [AGENTS.md](AGENTS.md) first: it is
  619. the full integration contract. [CONTEXT.md](CONTEXT.md) is a shorter version for
  620. tool-use prompts.
  621. | Resource | Description |
  622. | ------------------------------------------------------ | --------------------------------------------------------------------- |
  623. | [AGENTS.md](AGENTS.md) | Full integration guide: auth, invocation, errors, rate limits |
  624. | [CONTEXT.md](CONTEXT.md) | Runtime context for tool-using agents |
  625. | [agents/tool-catalog.json](agents/tool-catalog.json) | 188 commands with generated argument schemas, types, and safety flags |
  626. | [agents/error-catalog.json](agents/error-catalog.json) | 10 error categories with retry guidance |
  627. | [skills/](skills/) | Goal-oriented SKILL.md workflow packages |
  628. | [CLAUDE.md](CLAUDE.md) | Claude-specific integration guidance |
  629. ### Authenticating as an agent
  630. - A person is with you: ask them to open a new terminal window and run
  631. `kraken auth login` there. Never start it yourself. It needs an interactive
  632. terminal, and the catalog marks it `dangerous`. Then confirm with
  633. `kraken auth test -o json` (exit code 0 means the key works) and run
  634. `kraken auth show -o json`: `active_spot_source` names the key that signs,
  635. `overridden` is `true` when a flag or environment variable wins over the
  636. stored key, and `sign_in_key` carries `valid_until` and `expired`. See
  637. [Using OAuth with AI agents](#using-oauth-with-ai-agents).
  638. - Running unattended (CI, a server): the operator sets `KRAKEN_API_KEY` and
  639. `KRAKEN_API_SECRET` in the environment the agent starts from. Flags and
  640. environment variables take priority over stored keys.
  641. - Never ask for, accept, or paste API keys in a chat.
  642. ### Invocation
  643. ```bash
  644. kraken <command> [args...] -o json 2>/dev/null
  645. ```
  646. - stdout carries one JSON document on success, or a JSON error envelope on
  647. failure. Streaming commands such as `kraken ws ticker` write JSONL: one JSON
  648. object per line.
  649. - Exit code 0 means success, 1 a runtime or API failure, and 2 a usage error
  650. such as a bad flag or a missing argument.
  651. - stderr carries diagnostics only: structured JSON logs (warnings and errors by
  652. default, more with `-v` or `RUST_LOG`). Real-account orders and cancels, and
  653. commands in a live workspace, also print a plain-text `live:` banner there
  654. (not for `--validate` orders). Never parse stderr for data; read the `mode`
  655. field in the JSON to tell paper from live. For orders, capture stderr to a
  656. file instead of discarding it, so you can show your human any banner or
  657. warning.
  658. ### Rules for trading real money
  659. 1. The CLI places orders without a confirmation prompt. Before any command the
  660. catalog marks `dangerous`, confirm the pair, side, size and estimated cost
  661. with your human.
  662. 2. Run the order with `--validate` first. A validated order places nothing, so
  663. on the CLI it needs no approval (over MCP it is gated like the real order);
  664. confirm with your human between the validation and the real order.
  665. 3. Check where it goes. `KRAKEN_WORKSPACE` or `--workspace` decides, and the
  666. receipt's `mode` field says `paper` or `live`.
  667. 4. Give every order a new `--cl-ord-id`, such as a fresh UUID, and never reuse
  668. one. After a `network` error or an envelope with `"verify_first": true`, look
  669. the order up with `kraken open-orders --cl-ord-id <ID> -o json` and then
  670. `closed-orders` before you resubmit. For futures orders, withdrawals,
  671. transfers and Earn, use the lookups in the `network` row of the
  672. [error table](#error-envelopes). (Inside a workspace, `order buy` and `sell`
  673. refuse `--cl-ord-id` and most other advanced flags.)
  674. 5. Over MCP, set `acknowledged=true` only after your human approved that exact
  675. call.
  676. 6. Call `feedback` only when your human asks, and never put secrets or personal
  677. data in it.
  678. ### Reading results
  679. - `balance` is keyed by asset code (`BTC`, `USD`, `ETH`), and on the real
  680. account its values are JSON numbers. Outside a workspace the result has no
  681. `mode` field, so confirm that `KRAKEN_WORKSPACE` is unset and no `--workspace`
  682. flag is passed before you call it real money. Inside a workspace it returns
  683. `{"workspace": ..., "mode": ..., "balances": {"USD": {"total", "reserved", "available"}}}`
  684. instead.
  685. - Market data is keyed by the pair name Kraken returns: `XXBTZUSD` when you ask
  686. for `BTCUSD`, `BTC/USD` when you ask for `BTC/USD`. Read it with `.[]`.
  687. - An order receipt carries `mode`, `status` and `order_id` (Kraken's transaction
  688. ID). `kraken query-orders <ID> -o json` returns an object keyed by order ID,
  689. so read it with `.[]`. Each order carries `status` (`open`, `closed`,
  690. `canceled`, ...), `volume`, `volume_executed`, `cost`, `fee`, and `price` (the
  691. average fill price).
  692. - Workspace amounts are decimal strings, unlike the real-account `balance`
  693. values: `backing`, and the `total`, `reserved` and `available` of a workspace
  694. `balance`. Convert them with `tonumber` in jq before you compare them.
  695. To buy a dollar amount, make the volume a quote-currency amount with
  696. `--oflags viqc` (market buys only):
  697. ```bash
  698. kraken order buy BTCUSD 25 --type market --oflags viqc --validate -o json 2>/dev/null
  699. # after your human confirms; use a new client order ID for every order:
  700. CLID=$(uuidgen | tr 'A-Z' 'a-z')
  701. kraken order buy BTCUSD 25 --type market --oflags viqc --cl-ord-id "$CLID" -o json 2>>kraken-order.log
  702. kraken query-orders <ORDER_ID> -o json 2>/dev/null
  703. ```
  704. <details>
  705. <summary>Why agent-first?</summary>
  706. Most CLIs are built for humans at a terminal. This one is built for LLM-based
  707. agents, MCP tool servers, and automated pipelines that need to call Kraken
  708. reliably without custom API clients.
  709. - Structured output on request. Every command supports `-o json` (the default is
  710. a table), so agents don't scrape screens or run regex over table borders.
  711. - Consistent error envelopes. Errors are JSON objects with a stable `error`
  712. field (`auth`, `rate_limit`, `validation`, `api`, `network`, and more). Agents
  713. route on `error` without parsing human sentences.
  714. - Predictable exit codes: 0 for success, 1 for a runtime failure, 2 for a usage
  715. error. Combined with JSON errors on stdout, agents detect and classify
  716. failures programmatically.
  717. - Paper trading for safe iteration. Test strategies against live prices with
  718. `kraken paper` (spot) and `kraken futures paper` (perpetual futures) commands.
  719. Paper trading needs no API keys and no real money, and it uses the same basic
  720. order commands as live trading.
  721. - Market memory. `kraken record` captures live streams into a local DuckDB/JSONL
  722. tape library with integrity counters; finalized tapes replay into paper
  723. sessions and feed the autoresearch lab.
  724. - Full API surface. The catalog lists all 188 commands, covering Spot, Futures,
  725. xStocks, Forex, Funding, Earn, Subaccounts, and paper trading.
  726. `kraken-mcp -s all` serves 152 MCP tools; the default services (market,
  727. account, paper, workspace, feedback) serve the subset in their groups. Streams
  728. (Spot and Futures WebSocket, recording, replay, session start, playground,
  729. recipe run, the stream daemon), interactive commands, and the local credential
  730. commands `auth switch` and `auth reset` stay CLI-only; each catalog entry's
  731. `reach` field says which.
  732. - Built-in MCP server. Native Model Context Protocol support over stdio, with no
  733. subprocess wrapper.
  734. - Rate-limit aware. No client-side throttling. When the Kraken API rejects a
  735. request due to rate limits, the CLI returns an enriched error with
  736. `suggestion`, `retryable`, and `docs_url` fields so agents can read the
  737. documentation and adapt their strategy.
  738. Humans benefit from the same design: `--output table` renders clean tables,
  739. `kraken-shell` provides a REPL, and `kraken setup` walks through configuration.
  740. </details>
  741. ## Output and errors
  742. ### JSON (`-o json`)
  743. Every request/response command returns one JSON document on stdout.
  744. ```bash
  745. kraken ticker BTCUSD -o json
  746. # {"XXBTZUSD":{"ask_price":81401.4,"bid_price":81401.3,"last_price":81401.3,"volume_24h":1371.77,...}}
  747. ```
  748. Results are keyed by the pair name Kraken returns (`XXBTZUSD` here), with named
  749. fields and numeric values. WebSocket and other streaming commands emit JSONL
  750. (one JSON object per line).
  751. ### Table (`-o table`)
  752. Human-readable tables. This is the default when `-o` is not specified.
  753. ```text
  754. ┌──────────┬─────────┬─────────┬─────────┬───────────────┬────────────┬───────────┐
  755. │ Pair ┆ Ask ┆ Bid ┆ Last ┆ Volume (24h) ┆ High (24h) ┆ Low (24h) │
  756. ╞══════════╪═════════╪═════════╪═════════╪═══════════════╪════════════╪═══════════╡
  757. │ XXBTZUSD ┆ 79707.1 ┆ 79707.0 ┆ 79707.0 ┆ 1996.38136702 ┆ 81709.1 ┆ 79614.8 │
  758. └──────────┴─────────┴─────────┴─────────┴───────────────┴────────────┴───────────┘
  759. ```
  760. ### Error envelopes
  761. With `-o json`, a failure prints a JSON envelope on stdout with a stable `error`
  762. category and exits 1:
  763. ```json
  764. { "error": "auth", "message": "Authentication failed: EAPI:Invalid key" }
  765. ```
  766. In table mode, the default, the error is a plain `Error: ...` line on stderr.
  767. Argument and usage errors exit 2, and with `-o json` they also put a
  768. `validation` envelope on stdout.
  769. Route on `error`, not on `message`. The `message` field is human-readable and
  770. not stable.
  771. | Category | Retryable | Action |
  772. | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  773. | `auth` | No | Check API key and secret. If the OAuth sign-in key expired, run `kraken auth login` again |
  774. | `rate_limit` | Yes | Error includes `suggestion` with tier-specific limits, `docs_url` pointing to Kraken documentation, and `retryable` flag. Read `suggestion` and adapt strategy. |
  775. | `network` | Yes | Without `verify_first`, nothing was sent or the call was a read: retry with exponential backoff, max 5 retries. With `"verify_first": true`, a write may already have executed, so check its state before you resend it. Spot orders: `open-orders` and `closed-orders` (match on `--cl-ord-id` or `--userref`), then `trades-history` (match on the `ordertxid` from `closed-orders`). Futures orders: `futures open-orders`, `futures fills`, `futures history-orders`. Withdrawals and transfers: `withdrawal status`, `ledgers`, `futures transfers`. Earn: compare `amount_allocated.total.native` and `amount_allocated.pending.native` for the same `strategy_id` in `earn allocations` with the values recorded before the call (a missing `pending`, or a strategy that is not listed, counts as zero), and check `ledgers`; `earn allocate-status` and `earn deallocate-status` only say whether a known move is still pending. Resend only if the write is absent everywhere |
  776. | `validation` | No | Fix input parameters |
  777. | `api` | No | Inspect request and parameters |
  778. | `config` | No | Check config file or env vars |
  779. | `websocket` | Yes | Spot streams reconnect with backoff until interrupted. `futures ws` stops after 12 failed reconnects in a row. `ws` order methods: if the envelope has `"verify_first": true`, check open orders before resubmitting |
  780. | `io` | No | Check file paths and permissions |
  781. | `timeout` | Yes | An operation ran past its time budget (`session stop`, a WebSocket token request, browser sign-in). Re-run; if `session stop` keeps timing out, check `kraken session show` |
  782. | `parse` | No | Log raw response, possible API maintenance |
  783. A `futures ws` reconnect counts as failed unless the new connection stays up for
  784. 30 seconds.
  785. Full error catalog with envelopes and backoff strategies:
  786. [agents/error-catalog.json](agents/error-catalog.json).
  787. <details>
  788. <summary>Logging: -v, --log-format, RUST_LOG</summary>
  789. Diagnostics go through `tracing` to stderr only, so stdout stays the pure result
  790. and JSON channel. Logging is off by default except warnings and errors, so the
  791. `2>/dev/null` pattern is unaffected. The CLI never logs secrets or credentials,
  792. and private API response bodies are left out even at trace level. `kraken-mcp`
  793. also writes one `mcp_audit` JSONL line per tool call to stderr. The line records
  794. the argument names and the values of order and transfer fields (amounts, prices,
  795. pairs, addresses), never credentials, and `RUST_LOG` does not silence it. MCP
  796. clients often keep server stderr in their own log files.
  797. Format: logs are structured JSON (JSONL, one object per line) by default, so
  798. machines can parse them out of the box. A human-readable format is opt-in:
  799. ```bash
  800. kraken balance -o json -v 2>/dev/null | jq . # result on stdout; logs (JSON) on stderr
  801. kraken balance -v --log-format pretty # human-readable logs instead
  802. export KRAKEN_LOG_FORMAT=pretty # ...or via env (e.g. a dev shell profile)
  803. ```
  804. `--log-format` accepts `json` (default), `pretty`, or `compact`, and is
  805. independent of `-o`/`--output` (which formats the command result on stdout).
  806. Level: `RUST_LOG` (the standard `tracing` filter) controls it and wins whenever
  807. it is set. With `RUST_LOG` unset, `-v`/`--verbose` is a shortcut for debug-level
  808. kraken-cli logs:
  809. ```bash
  810. kraken balance -v # kraken-cli at debug, dependencies at warn
  811. RUST_LOG=warn,kraken=debug kraken balance # same, explicit
  812. RUST_LOG=kraken_rest=trace kraken ticker BTCUSD # HTTP request/response detail
  813. ```
  814. Note: a bare `RUST_LOG=debug` enables debug for _every_ crate (including
  815. dependencies like `tungstenite`); scope it to `kraken`, which matches every
  816. `kraken_*` crate, or just use `-v` for our diagnostics alone.
  817. </details>
  818. ## MCP server
  819. `kraken-mcp` is a built-in
  820. [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, so
  821. MCP clients can call Kraken as tools without a subprocess wrapper. Tool calls
  822. run through the same command path as CLI commands and inherit the same error
  823. handling and rate-limit behavior.
  824. <!-- prettier-ignore -->
  825. > [!WARNING]
  826. > MCP is local-first and designed for your own machine. Any agent connected to
  827. > this MCP server uses the same configured Kraken account and API key
  828. > permissions. Do not expose, tunnel, or share this server outside systems you
  829. > control. Always use `https://` and `wss://` endpoints. Treat this integration
  830. > as alpha and use least-privilege API keys.
  831. ```bash
  832. kraken-mcp # default: market, account, paper, workspace, feedback
  833. kraken-mcp -s market,account,paper,workspace,trade # adds live spot trading
  834. kraken-mcp -s all # all services; dangerous calls need approval (see below)
  835. kraken-mcp -s all --allow-dangerous # DANGER: no approval step; an agent can trade, withdraw and transfer
  836. ```
  837. `-s all` serves all 152 MCP tools; the default services serve the subset in
  838. their groups.
  839. `kraken-mcp` signs with `KRAKEN_API_KEY` and `KRAKEN_API_SECRET` (and
  840. `KRAKEN_FUTURES_API_KEY` and `KRAKEN_FUTURES_API_SECRET` for futures) when they
  841. are set in the server's environment. Otherwise it signs with the active stored
  842. key, including the OAuth sign-in key from `kraken auth login`, and reads that
  843. key again on every call that can sign. When a stored sign-in key expires, calls
  844. that need a key fail with an `auth` error, and a person runs `kraken auth login`
  845. again. The `auth login`, `auth set`, `auth switch`, and `auth reset` commands
  846. are not served over MCP.
  847. ### Approval for dangerous calls
  848. Dangerous tools carry the `destructive_hint` annotation and include
  849. `[DANGEROUS: requires human confirmation]` in the description. Unless you pass
  850. `--allow-dangerous`, the server runs in guarded mode, whichever services you
  851. load:
  852. - On a client that supports MCP elicitation, the server puts each dangerous call
  853. to you and runs it only if you approve. A prompt that gets no answer within
  854. 300 seconds fails closed.
  855. - Inside a paper workspace, `order buy`, `order sell`, `order cancel` and
  856. `order cancel-all` fill on the simulator, so they drop both markers and run
  857. without approval. Every other dangerous tool stays gated there.
  858. - `workspace create` with `mode: live` also asks for approval, because it
  859. allocates real money.
  860. <!-- prettier-ignore -->
  861. > [!WARNING]
  862. > A client that cannot present an elicitation gets no prompt from the server.
  863. > The call runs when the model sets `acknowledged=true` in its arguments. A
  864. > model should set it only after its human approved that exact call, and on
  865. > such a client your client's own tool-approval prompt is the only real check.
  866. > Keep it turned on. In autonomous mode (`--allow-dangerous`), neither is asked
  867. > for.
  868. ### Claude Code
  869. Install `kraken-cli` with the one-liner first, because the plugin starts the
  870. `kraken-mcp` binary that the installer puts on your PATH. Then install the
  871. plugin, which adds the MCP server and the agent skills. Its server runs
  872. `market,paper,feedback`, with no account access, so balances and live orders go
  873. through the `kraken` CLI unless you widen `-s`:
  874. ```text
  875. /plugin marketplace add krakenfx/kraken-cli
  876. /plugin install kraken-cli@kraken
  877. ```
  878. Or add only the MCP server. The full path works even before `kraken-mcp` is on
  879. your PATH:
  880. ```bash
  881. claude mcp add kraken -- "$HOME/.cargo/bin/kraken-mcp" -s market,paper,feedback
  882. ```
  883. If you set `CARGO_HOME`, use `$CARGO_HOME/bin/kraken-mcp` instead.
  884. If you installed `kraken-cli` while Claude Code was running, quit Claude Code
  885. and start it again from a new terminal window.
  886. ### Other MCP clients
  887. Claude Desktop, Cursor, Windsurf, Gemini CLI and other clients that read
  888. `mcpServers` JSON take this entry:
  889. ```json
  890. {
  891. "mcpServers": {
  892. "kraken": {
  893. "command": "kraken-mcp",
  894. "args": ["-s", "market,paper,feedback"]
  895. }
  896. }
  897. }
  898. ```
  899. VS Code takes the same entry under a top-level `"servers"` key in
  900. `.vscode/mcp.json`. Codex reads TOML in `~/.codex/config.toml`:
  901. ```toml
  902. [mcp_servers.kraken]
  903. command = "kraken-mcp"
  904. args = ["-s", "market,paper,feedback"]
  905. ```
  906. This set starts market data, paper trading, and the feedback tool, which uploads
  907. text, or a local file it names, to Kraken with no approval step (see
  908. [Service groups](#service-groups)). It needs no credentials. Add `account` to
  909. read your balances and orders, and `workspace` for paper workspaces. For live
  910. trading, use `market,account,paper,workspace,trade` with a least-privilege API
  911. key. If the client shows "Failed to connect", set `command` to the full path
  912. that `command -v kraken-mcp` prints.
  913. Gemini CLI users can install directly:
  914. `gemini extensions install https://github.com/krakenfx/kraken-cli`
  915. ### Service groups
  916. | Service | Auth | Risk |
  917. | ------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  918. | market | No | None |
  919. | account | Yes | Read-only, except `export-retrieve` and `export-delete` (dangerous) |
  920. | trade | Yes | Orders (dangerous) |
  921. | funding | Yes | Withdrawals, withdrawal cancel, and wallet transfers (dangerous) |
  922. | earn | Yes | Staking (dangerous) |
  923. | subaccount | Yes | Creating subaccounts and transfers (dangerous) |
  924. | futures | Mixed | Orders, cancels, transfers, and leverage/PnL/subaccount settings (dangerous) |
  925. | futures-paper | No | None (simulation) |
  926. | paper | No | Simulation; `reset` is dangerous; in a live workspace `status`/`balance` read the real account |
  927. | workspace | No | `reset` and `promote` are dangerous, and `create --mode live` needs the same approval (it allocates real money and needs credentials); live workspaces gate like the real account |
  928. | feedback | No | Uploads text, or a local file, to Kraken (see below) |
  929. | auth | Mixed | Read-only |
  930. Default: `market,account,paper,workspace,feedback`. The `feedback` tool calls
  931. the same upload path as `kraken feedback`. It sends the text you give it (at
  932. most 8192 bytes after trimming), the feedback type, the optional `--llm-model`
  933. value, the CLI version, the OS and architecture, the detected agent client, a
  934. stable install ID, a random event ID and a timestamp to
  935. `https://cli-feedback.kraken.com/v1/feedback` over HTTPS. Do not put secrets or
  936. personal data in it. Over MCP the tool also accepts `input_file`: it reads that
  937. local file and uploads its contents, with no approval step, so a model could
  938. upload any file it can name, including the config file that holds your stored
  939. keys. A failed upload fails the command and is not retried. Drop `feedback` from
  940. `-s` to turn the tool off, especially for an agent that reads untrusted input.
  941. The streaming groups (`websocket`, `futures-ws`) and `utility` (the setup
  942. wizard) are not served over MCP.
  943. ## Workspaces, sessions, and research
  944. Beyond single orders, the CLI runs a research loop on paper:
  945. 1. A **workspace** gives a strategy its own capital and ledger.
  946. 2. A **session** records an evaluation window.
  947. 3. A **tape** preserves replayable market data.
  948. 4. A **lab experiment** seals the hypothesis and pass criteria before the first
  949. run.
  950. ```bash
  951. # Create a paper workspace with its own $10,000.
  952. kraken workspace create momentum --capital 10000 --mode paper -o json
  953. export KRAKEN_WORKSPACE=momentum
  954. # Record in one terminal.
  955. kraken session start --symbols BTC/USD --channels ticker,trade \
  956. --label baseline --to jsonl -o json
  957. # Trade in another terminal and preserve the rationale.
  958. export KRAKEN_WORKSPACE=momentum
  959. kraken paper buy BTC/USD 0.01 -o json
  960. kraken session note --kind buy --symbol BTC/USD \
  961. --reason "breakout held above the prior high" -o json
  962. kraken session stop -o json
  963. # Review the closed window.
  964. kraken session show --session baseline -o json
  965. kraken explain pnl --session baseline -o json
  966. kraken workspace report momentum -o json
  967. ```
  968. For repeatable experiments, freeze the plan before the first session. A replay
  969. leg names a finalized tape: `replay:session:s1` is the baseline session above,
  970. the first one in this workspace (`kraken session list` shows each ordinal).
  971. ```bash
  972. kraken lab new breakout-v1 \
  973. --hypothesis "a confirmed breakout produces positive net return" \
  974. --min-return-pct 0 --max-drawdown-pct 2 --min-fills 1 \
  975. --session live:5m --session replay:session:s1 -o json
  976. kraken lab next breakout-v1 -o json
  977. kraken lab compare breakout-v1 -o json
  978. ```
  979. `--session live:5m` plans a 5-minute session on live prices inside the paper
  980. workspace; it places no real orders. When you are done, run
  981. `unset KRAKEN_WORKSPACE` so later commands reach your real account again.
  982. The command tables below cover each surface. Machine-readable contracts live in
  983. [agents/tool-catalog.json](agents/tool-catalog.json).
  984. ## Commands
  985. The published catalog contains 188 commands across 15 groups; 152 of them are
  986. callable as MCP tools, and the rest say why they are not. Parameter schemas live
  987. in [agents/tool-catalog.json](agents/tool-catalog.json). Long-running streams
  988. are in the catalog too, with `reach: stream`, and are documented below. They
  989. stay CLI-only.
  990. | Group | Commands | Auth | Description |
  991. | ------------- | -------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
  992. | market | 11 | No | Ticker, orderbook, OHLC, trades, spreads, asset info, tape library |
  993. | account | 18 | Yes | Balances, orders, trades, ledgers, positions, exports |
  994. | trade | 9 | Yes | Order placement, amendment, cancellation (spot, xStocks, forex) |
  995. | funding | 10 | Yes | Deposits, withdrawals, wallet transfers |
  996. | earn | 6 | Yes | Staking strategies and allocations |
  997. | subaccount | 2 | Yes | Create subaccounts, transfer between accounts |
  998. | futures | 39 | Mixed | Futures market data and trading |
  999. | futures-paper | 17 | No | Futures paper trading simulation with live prices |
  1000. | futures-ws | 9 | Mixed | Futures WebSocket streaming |
  1001. | websocket | 17 | Mixed | Spot WebSocket v2 streaming and request/response |
  1002. | paper | 17 | No | Spot paper trading simulation with live prices, P&L explanation, and the Autoresearch Lab |
  1003. | workspace | 25 | No | Strategy workspaces, recorded sessions, recipes, and extension scaffolds: per-strategy ledgers, session windows, decision logs, reports, promotion |
  1004. | feedback | 1 | No | Product feedback upload to Kraken |
  1005. | auth | 6 | Mixed | OAuth browser sign-in and credential management |
  1006. | utility | 1 | No | Interactive setup (the REPL is the `kraken-shell` binary) |
  1007. 43 commands are marked `dangerous`: orders and cancels (including the `ws` order
  1008. methods), withdrawals, transfers, staking, futures leverage/PnL/subaccount
  1009. settings, export retrieval and deletion, subaccount creation, paper and
  1010. workspace resets, workspace promotion, browser sign-in, and switching or
  1011. resetting the stored key. The CLI places orders without a confirmation prompt;
  1012. only some destructive commands, such as `cancel-all` and the resets, ask first
  1013. (skip the question with `--yes`). The MCP server gates the ones it serves (see
  1014. [Approval for dangerous calls](#approval-for-dangerous-calls)). The
  1015. authoritative list is the `dangerous` field in
  1016. [agents/tool-catalog.json](agents/tool-catalog.json).
  1017. <details>
  1018. <summary>Full command reference</summary>
  1019. ### Market data (public)
  1020. | Command | Description |
  1021. | --------------------------------------------------------------------------- | --------------------------------------------------------------- |
  1022. | `kraken status` | System status |
  1023. | `kraken server-time` | Server time |
  1024. | `kraken assets [--asset BTC,ETH] [--asset-class CLASS]` | Asset info |
  1025. | `kraken pairs [--pair BTCUSD] [--asset-class CLASS]` | Tradable pairs |
  1026. | `kraken ticker <PAIR...> [--asset-class tokenized_asset\|forex]` | Ticker data |
  1027. | `kraken ohlc <PAIR> [--interval 60] [--asset-class tokenized_asset\|forex]` | OHLC candles |
  1028. | `kraken orderbook <PAIR> [--count 25] [--asset-class tokenized_asset]` | L2 order book |
  1029. | `kraken orderbook-grouped <PAIR> [--depth 10] [--grouping 1]` | Grouped order book |
  1030. | `kraken trades <PAIR> [--count 1000] [--asset-class tokenized_asset]` | Recent trades |
  1031. | `kraken spreads <PAIR> [--since TS] [--asset-class tokenized_asset]` | Recent spreads |
  1032. | `kraken tape list` | Every recorded tape in the library: ref, backend, state, in use |
  1033. ### Account data (private)
  1034. | Command | Description |
  1035. | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
  1036. | `kraken orderbook-l3 <PAIR> [--depth 100]` | L3 order book |
  1037. | `kraken balance [--rebase-multiplier rebased\|base]` | All balances |
  1038. | `kraken extended-balance` | Extended balances (balance, credit, held) |
  1039. | `kraken credit-lines [--rebase-multiplier rebased\|base]` | Credit line details (VIP) |
  1040. | `kraken trade-balance [--asset USD] [--rebase-multiplier rebased\|base]` | Margin/equity summary |
  1041. | `kraken open-orders [--trades] [--cl-ord-id ID] [--rebase-multiplier rebased\|base]` | Open orders |
  1042. | `kraken closed-orders [--start TS] [--end TS] [--offset N] [--userref REF] [--cl-ord-id ID] [--closetime open\|close\|both] [--consolidate-taker] [--without-count] [--rebase-multiplier rebased\|base]` | Closed orders |
  1043. | `kraken query-orders <TXID...> [--trades] [--userref REF] [--consolidate-taker] [--rebase-multiplier rebased\|base]` | Query specific orders |
  1044. | `kraken trades-history [--type TYPE] [--trades] [--offset N] [--consolidate-taker] [--without-count] [--ledgers] [--rebase-multiplier rebased\|base]` | Trade history |
  1045. | `kraken query-trades <TXID...> [--trades] [--rebase-multiplier rebased\|base]` | Query specific trades |
  1046. | `kraken positions [--txid ID] [--show-pnl] [--consolidation market] [--rebase-multiplier rebased\|base]` | Open positions |
  1047. | `kraken ledgers [--asset BTC --type trade] [--asset-class CLASS] [--start TS] [--end TS] [--offset N] [--without-count] [--rebase-multiplier rebased\|base]` | Ledger entries |
  1048. | `kraken query-ledgers <ID...> [--trades] [--rebase-multiplier rebased\|base]` | Query specific ledger entries |
  1049. | `kraken volume [--pair BTCUSD] [--rebase-multiplier rebased\|base]` | Trade volume & fees |
  1050. | `kraken export-report --report trades --description "desc" [--format CSV\|TSV] [--fields F] [--starttm TS] [--endtm TS]` | Request export |
  1051. | `kraken export-status --report trades` | Export status |
  1052. | `kraken export-retrieve <ID>` | Download export |
  1053. | `kraken export-delete <ID>` | Delete export |
  1054. ### Trading
  1055. | Command | Description |
  1056. | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
  1057. | `kraken order buy <PAIR> <VOL> [--type TYPE] [--price P] [--oflags viqc] [--cl-ord-id ID] [--asset-class tokenized_asset] [--validate] ...` | Buy order. `--type` defaults to `limit`, which needs `--price`; `--type market --oflags viqc` buys a quote-currency amount |
  1058. | `kraken order sell <PAIR> <VOL> [--type TYPE] [--price P] [--cl-ord-id ID] [--asset-class tokenized_asset] [--validate] ...` | Sell order (same `--type`/`--price` rule) |
  1059. | `kraken order batch <JSON_FILE> [--pair P] [--asset-class tokenized_asset] [--deadline DL] [--validate]` | Batch orders (2-15) |
  1060. | `kraken order amend --txid <TXID> [--order-qty Q --limit-price P ...]` | Amend order in-place |
  1061. | `kraken order amend --cl-ord-id <ID> [--limit-price P ...]` | Amend by client order ID |
  1062. | `kraken order edit <TXID> [--price P]` | Edit order (cancel+replace) |
  1063. | `kraken order cancel <TXID...>` | Cancel by txid(s) |
  1064. | `kraken order cancel --cl-ord-id <ID>` | Cancel by client order ID |
  1065. | `kraken order cancel-batch <TXID...> [--cl-ord-ids ID...]` | Cancel batch (max 50 total) |
  1066. | `kraken order cancel-all [--yes]` | Cancel all |
  1067. | `kraken order cancel-after <SECS>` | Dead man's switch |
  1068. ### Funding
  1069. | Command | Description |
  1070. | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  1071. | `kraken deposit methods <ASSET> [--asset-class currency\|tokenized_asset] [--rebase-multiplier rebased\|base]` | Deposit methods |
  1072. | `kraken deposit addresses <ASSET> <METHOD> [--new] [--asset-class CLASS] [--amount AMT]` | Deposit addresses |
  1073. | `kraken deposit status [--asset A] [--asset-class CLASS] [--method M] [--start TS] [--end TS] [--cursor C] [--limit N] [--rebase-multiplier rebased\|base]` | Deposit status |
  1074. | `kraken withdraw <ASSET> <KEY> <AMOUNT> [--asset-class CLASS] [--address ADDR] [--max-fee F] [--rebase-multiplier rebased\|base]` | Withdraw funds |
  1075. | `kraken withdrawal methods [--asset A] [--asset-class CLASS] [--network N] [--rebase-multiplier rebased\|base]` | Withdrawal methods |
  1076. | `kraken withdrawal addresses [--asset A] [--asset-class CLASS] [--method M] [--key K] [--verified true\|false]` | Withdrawal addresses |
  1077. | `kraken withdrawal info <ASSET> <KEY> <AMOUNT>` | Withdrawal fee info |
  1078. | `kraken withdrawal status [--asset A] [--asset-class CLASS] [--method M] [--start TS] [--end TS] [--cursor C] [--limit N] [--rebase-multiplier rebased\|base]` | Withdrawal status |
  1079. | `kraken withdrawal cancel <ASSET> <REFID>` | Cancel pending withdrawal |
  1080. | `kraken wallet-transfer <ASSET> <AMT> --from <SOURCE_WALLET> --to <DEST_WALLET>` | Move funds from your Spot wallet to your Futures wallet (`--from` and `--to` take wallet names as Kraken spells them: `--from "Spot Wallet" --to "Futures Wallet"`; for account-to-account moves use `kraken subaccount transfer`) |
  1081. ### Earn
  1082. | Command | Description |
  1083. | ---------------------------------------------------------------------------------------------------------- | ------------------- |
  1084. | `kraken earn strategies [--asset ETH] [--lock-type flex bonded...] [--ascending] [--cursor C] [--limit N]` | List strategies |
  1085. | `kraken earn allocate <ID> <AMT>` | Allocate funds |
  1086. | `kraken earn deallocate <ID> <AMT>` | Deallocate funds |
  1087. | `kraken earn allocate-status <ID>` | Allocation status |
  1088. | `kraken earn deallocate-status <ID>` | Deallocation status |
  1089. | `kraken earn allocations [--ascending] [--converted-asset USD] [--hide-zero-allocations]` | Current allocations |
  1090. ### Subaccounts
  1091. | Command | Description |
  1092. | ------------------------------------------------------------------------------------------- | ------------------------- |
  1093. | `kraken subaccount create <USERNAME> <EMAIL>` | Create sub account |
  1094. | `kraken subaccount transfer <ASSET> <AMOUNT> --from IIBAN --to IIBAN [--asset-class CLASS]` | Transfer between accounts |
  1095. ### Futures: public market data
  1096. | Command | Description |
  1097. | ------------------------------------------------------------ | ------------------------ |
  1098. | `kraken futures instruments` | All contracts |
  1099. | `kraken futures tickers` | All tickers |
  1100. | `kraken futures ticker <SYMBOL>` | Single ticker |
  1101. | `kraken futures orderbook <SYMBOL>` | Order book |
  1102. | `kraken futures history <SYMBOL> [--since TS] [--before TS]` | Trade history |
  1103. | `kraken futures feeschedules` | Fee schedules |
  1104. | `kraken futures instrument-status [--symbol SYM]` | Instrument status |
  1105. | `kraken futures historical-funding-rates <SYMBOL>` | Historical funding rates |
  1106. ### Futures: trading (private)
  1107. | Command | Description |
  1108. | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
  1109. | `kraken futures order buy <SYM> <SIZE> [--type limit] [--price P] [--stop-price SP] [--trigger-signal mark\|index\|last] [--client-order-id ID] [--reduce-only] [--trailing-stop-max-deviation V] [--trailing-stop-deviation-unit percent\|quote_currency]` | Buy futures |
  1110. | `kraken futures order sell <SYM> <SIZE> [--type limit] [--price P] [--stop-price SP] ...` | Sell futures |
  1111. | `kraken futures edit-order --order-id ID [--size S] [--price P] [--stop-price SP]` | Edit existing order |
  1112. | `kraken futures cancel --order-id ID` | Cancel by order ID |
  1113. | `kraken futures cancel --cli-ord-id ID` | Cancel by client order ID |
  1114. | `kraken futures cancel-all [--symbol SYM] [--yes]` | Cancel all orders |
  1115. | `kraken futures cancel-after <SECS>` | Dead man's switch |
  1116. | `kraken futures batch-order '<JSON>'` or `kraken futures batch-order @file.json` | Batch order placement |
  1117. ### Futures: account data (private)
  1118. | Command | Description |
  1119. | --------------------------------------------------------------------------------- | ------------------------------------ |
  1120. | `kraken futures accounts` | Wallet/account info |
  1121. | `kraken futures open-orders` | Open orders |
  1122. | `kraken futures positions` | Open positions |
  1123. | `kraken futures fills [--since TS]` | Recent fills |
  1124. | `kraken futures leverage [--symbol SYM]` | Leverage preferences |
  1125. | `kraken futures set-leverage <SYMBOL> [LEVERAGE]` | Set leverage (omit for cross margin) |
  1126. | `kraken futures notifications` | Account notifications |
  1127. | `kraken futures transfers` | Transfer history |
  1128. | `kraken futures transfer <AMOUNT> <CURRENCY>` | Transfer between wallets |
  1129. | `kraken futures history-executions [--since TS] [--before TS] [--sort asc\|desc]` | Execution history |
  1130. | `kraken futures history-orders [--since TS] [--before TS] [--sort asc\|desc]` | Order history |
  1131. | `kraken futures history-triggers [--since TS] [--before TS] [--sort asc\|desc]` | Trigger history |
  1132. | `kraken futures history-account-log-csv [--since TS] [--before TS]` | Account log (CSV) |
  1133. | `kraken futures trading-instruments [--contract-type ...]` | Trading instruments (auth) |
  1134. | `kraken futures order-status <ORDER_ID>...` | Query order status (auth) |
  1135. | `kraken futures pnl-preferences` | Get PnL preferences (auth) |
  1136. | `kraken futures set-pnl-preference <SYMBOL> <PREFERENCE>` | Set PnL preference (auth) |
  1137. | `kraken futures unwind-queue` | Get unwind queue (auth) |
  1138. | `kraken futures assignment-programs` | Assignment programs (auth) |
  1139. | `kraken futures fee-schedule-volumes` | Fee schedule volumes (auth) |
  1140. | `kraken futures subaccounts` | List subaccounts (auth) |
  1141. | `kraken futures subaccount-status <UID>` | Subaccount trading status (auth) |
  1142. | `kraken futures set-subaccount-status <UID> <ENABLED>` | Set subaccount trading status (auth) |
  1143. | `kraken futures wallet-transfer <FROM> <TO> <UNIT> <AMOUNT>` | Transfer between wallets (auth) |
  1144. ### Futures: paper trading (no auth)
  1145. The full command table and flags are in
  1146. [Futures paper trading](#futures-paper-trading).
  1147. ### Futures WebSocket streaming
  1148. | Command | Description |
  1149. | -------------------------------------- | -------------------------------------- |
  1150. | `kraken futures ws ticker <MARKET...>` | Stream futures tickers (public) |
  1151. | `kraken futures ws trades <MARKET...>` | Stream futures trades (public) |
  1152. | `kraken futures ws book <MARKET...>` | Stream futures order book (public) |
  1153. | `kraken futures ws fills` | Stream fills (private, challenge auth) |
  1154. | `kraken futures ws open-orders` | Stream open orders (private) |
  1155. | `kraken futures ws open-positions` | Stream open positions (private) |
  1156. | `kraken futures ws balances` | Stream balances and margins (private) |
  1157. | `kraken futures ws notifications` | Stream notifications (private) |
  1158. | `kraken futures ws account-log` | Stream account log (private) |
  1159. ### WebSocket (streaming and request/response)
  1160. | Command | Description |
  1161. | -------------------------------------------------- | ---------------------------------------- |
  1162. | `kraken ws ticker <PAIR...> [--event-trigger bbo]` | Stream tickers |
  1163. | `kraken ws trades <PAIR...>` | Stream trades |
  1164. | `kraken ws book <PAIR...> [--depth 10]` | Stream L2 order book |
  1165. | `kraken ws ohlc <PAIR...> [--interval 1]` | Stream OHLC candles |
  1166. | `kraken ws instrument [PAIR...]` | Stream instrument metadata |
  1167. | `kraken ws executions` | Stream trade executions (auth) |
  1168. | `kraken ws balances` | Stream balance updates (auth) |
  1169. | `kraken ws level3 <PAIR...>` | Stream L3 order book (auth) |
  1170. | `kraken ws add-order` | Place order via WebSocket (auth) |
  1171. | `kraken ws amend-order` | Amend order via WebSocket (auth) |
  1172. | `kraken ws cancel-order` | Cancel order(s) via WebSocket (auth) |
  1173. | `kraken ws cancel-all` | Cancel all orders via WebSocket (auth) |
  1174. | `kraken ws cancel-after <TIMEOUT>` | Dead man's switch via WebSocket (auth) |
  1175. | `kraken ws batch-add` | Batch add orders via WebSocket (auth) |
  1176. | `kraken ws batch-cancel` | Batch cancel orders via WebSocket (auth) |
  1177. | `kraken ws ping` | Check the connection with a ping/pong |
  1178. ### Market memory (CLI-only; public channels need no auth)
  1179. | Command | Description |
  1180. | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
  1181. | `kraken record --symbols <PAIR...> --channels <CH...> [--tape NAME] [--to duckdb,jsonl]` | Capture live market data into a local tape; Ctrl-C/SIGTERM finalizes |
  1182. | `kraken streamd start --symbols <PAIR...> --channels <CH...>` | Multi-symbol, multi-channel JSONL stream to stdout |
  1183. `streamd` also takes the `executions` and `balances` channels, which need API
  1184. credentials like the matching `ws` streams, and skips `level3` with a warning.
  1185. `record` captures `ticker`, `trade`, `book` and `ohlc` only, and refuses any
  1186. other channel. Use `kraken ws level3` for L3 data.
  1187. Add `--monitor` to `ws`, `streamd`, or `record` for stderr JSONL health lines
  1188. (latency, trade gaps, staleness, heartbeats). See the
  1189. [market memory walkthrough](examples/03-market-memory.md).
  1190. `--to` defaults to `jsonl`, which every build has. `--to duckdb` needs a binary
  1191. built with the `record-duckdb` feature. The released binaries have it, and a
  1192. source build opts in (see [Installation](#installation)).
  1193. ### Strategy workspaces
  1194. A workspace is an allocation with a ledger. You give it capital, it records
  1195. everything that happens to that capital, and it reports P&L against it.
  1196. There are three scopes, and one command vocabulary across all of them:
  1197. | Scope | Capital is | Fills come from | `kraken order buy` |
  1198. | -------------- | -------------------------------- | ----------------------------- | ------------------------- |
  1199. | No workspace | your whole account | the venue | real order, whole account |
  1200. | `--mode paper` | simulated, minted | the simulator, at live prices | simulated |
  1201. | `--mode live` | **a slice of your real account** | the venue, reconciled by txid | **real order** |
  1202. Because the middle and bottom rows share a vocabulary, moving a strategy from
  1203. paper to live teaches you nothing new. You test with `order buy`, `open-orders`,
  1204. `balance`, `workspace status`, `trades-history`, and `workspace report`, and
  1205. after promotion you keep using exactly those. The verbs stay the same, and there
  1206. is no separate live command set. Inside any workspace, `order buy` and `sell`
  1207. take only `--type`, `--price`, `--validate` and `--reason`; `--cl-ord-id`,
  1208. `--oflags` and the other advanced flags work only with no workspace selected.
  1209. Because the commands are identical, the _output_ is what has to tell you where
  1210. you are. Order and status tables lead with a `Mode` row, order and trade lists
  1211. put `[PAPER]` or `[LIVE]` in their first column header, and the JSON carries a
  1212. `mode` field. A paper balance table carries no marker. The same `order buy`, in
  1213. the two modes:
  1214. ```text
  1215. $ kraken order buy BTC/USD 0.01 --type limit --price 60000 # paper workspace
  1216. ┌───────────┬───────────────────────────┐
  1217. │ Mode ┆ [PAPER] Simulated Trading │ ← simulated, no money moved
  1218. │ Session ┆ none │ ← the recording session, if any
  1219. │ Workspace ┆ sandbox │
  1220. │ Action ┆ Limit buy order placed │
  1221. │ Order ID ┆ PAPER-00003 │ ← a minted id
  1222. │ … ┆ … │
  1223. └───────────┴───────────────────────────┘
  1224. $ kraken order buy BTC/USD 0.01 --type limit --price 60000 # live workspace
  1225. live: this goes to the real Kraken account ← stderr
  1226. workspace 'prod' is an allocation ledger over that account, not a separate balance
  1227. ┌─────────────┬──────────────────────────────────────────────┐
  1228. │ Mode ┆ [LIVE] Real Money │ ← a REAL order at Kraken
  1229. │ Workspace ┆ prod │
  1230. │ Scope ┆ REAL orders — allocation of the real account │
  1231. │ Action ┆ Limit buy order placed │
  1232. │ Order ID ┆ OQABCD-1EFGH-2IJKLM │ ← a venue txid
  1233. │ … ┆ … │
  1234. │ Backing ┆ backed │ ← what backs it
  1235. │ Account ┆ 5000 USD │
  1236. │ Unallocated ┆ 4000 USD │
  1237. │ Spendable ┆ 400 USD │
  1238. └─────────────┴──────────────────────────────────────────────┘
  1239. ```
  1240. Both modes print the same core rows, with the same names and in the same order
  1241. (`Mode`, `Action`, `Order ID`, `Pair`, `OrderSide`, `Type`, `Volume`, `Price`),
  1242. so a script or an agent reads one format. A paper receipt adds `Session` and
  1243. `Workspace` right after `Mode`. A live receipt adds `Workspace` and `Scope`
  1244. there and ends with the backing rows (`Backing`, `Account`, `Unallocated`,
  1245. `Spendable`). `Mode` answers "is this real money?" and `Scope` answers "whose
  1246. money?", including with no workspace at all:
  1247. | Where you are | `Mode` | `Scope` |
  1248. | -------------- | --------------------------- | ---------------------------------------------- |
  1249. | No workspace | `[LIVE] Real Money` | `the WHOLE real account, no workspace limit` |
  1250. | `--mode paper` | `[PAPER] Simulated Trading` | no row (a `Workspace` row names it) |
  1251. | `--mode live` | `[LIVE] Real Money` | `REAL orders — allocation of the real account` |
  1252. Three further signals mark a live workspace's output:
  1253. 1. stderr carries the `live:` banner on every order, cancel, and read of the
  1254. live workspace's ledger (`--validate` dry runs excepted).
  1255. 2. Closing rows (`Backing`, `Account`, `Unallocated`, `Spendable`) set the
  1256. allocation against your real balance. Wide tables such as `open-orders` print
  1257. the same facts as labeled footer lines.
  1258. 3. Order IDs are the venue's own transaction IDs, never `PAPER-…`.
  1259. In `-o json` the same facts are `"mode": "live"`, `"scope": "allocation"`,
  1260. `"reconciled"`, and the `backing` object.
  1261. `workspace create --mode live` and `workspace promote` print the full
  1262. explanation once, at the moment you opt in.
  1263. Two contract fields describe the simulator's fill model and therefore apply to
  1264. paper only: `--fee-rate` and `--slippage-rate`. A live workspace's fills carry
  1265. Kraken's own fee, so its tables print `Fees: Kraken's own, charged per fill`
  1266. instead of the rates, and its capital row is labelled `Allocation` rather than
  1267. `Capital`, because it is a claim on money you already have, not capital the CLI
  1268. minted.
  1269. #### What a live allocation is, and is not
  1270. Say your account holds 1 BTC and you allocate 0.1 BTC to a workspace.
  1271. It is a real carve-out for accounting. Orders are real, fills are the venue's
  1272. own (reconciled by transaction ID, so the P&L is real and not notional), and
  1273. this CLI checks the allocation before every order. A spend the workspace's own
  1274. ledger cannot fund is refused before the venue sees it, the same way a paper
  1275. workspace refuses an order its capital cannot fund. The live check skips the
  1276. simulator's fee padding, so its numbers always match `workspace balance` rather
  1277. than paper's fee-padded refusals. Creating the workspace verifies your account
  1278. actually holds the allocation, net of what other live workspaces already claim,
  1279. and refuses if it does not.
  1280. It is not a subaccount, and Kraken enforces none of it. Funds, permissions and
  1281. positions stay shared with the whole account, so anything else using the same
  1282. API key (another workspace, another tool, the web UI) can spend allocated money.
  1283. That residual is reported rather than hidden: every live command carries a
  1284. `backing` object setting the allocation against your real balance. Nor is it a
  1285. security boundary: the workspace is plain local state (a manifest and a journal
  1286. on disk, not tamper-evident), so use it to scope and attribute an agent's
  1287. trading, never to contain an agent you do not trust.
  1288. ```bash
  1289. kraken workspace balance -o json | jq '.backing'
  1290. # { "status": "backed", "asset": "BTC", "allocation": "0.1",
  1291. # "account": "1", "allocated_elsewhere": "0.15",
  1292. # "unallocated": "0.75", "spendable": "0.0975" }
  1293. ```
  1294. `spendable` is the ledger's own figure: the allocation-asset balance free of
  1295. resting orders. An agent can size an order with it without a refusal round-trip.
  1296. For orders that spend the allocation asset it is exactly what the pre-order
  1297. check compares a spend against; an order on a pair carrying the allocation on
  1298. neither leg is gated in its own funding leg instead. A refusal itself is
  1299. structured the same way in both output modes: the JSON envelope carries
  1300. `refusal` (`allocation_budget`, `over_allocated`, or `unverified`) with
  1301. `available`/`required`/`backing` as typed fields, and the table render prints
  1302. the same facts as rows.
  1303. `status` is `backed`, `over_allocated`, or `unverified`. An over-allocated
  1304. workspace stops spending the allocated asset until you move funds back into the
  1305. account, and an unverified one (the real balance could not be read) stops
  1306. spending until it can be checked again, exactly as `workspace create` refuses an
  1307. allocation it cannot verify. The order that pays that asset back in (closing a
  1308. position) is always allowed, so neither a shortfall nor an outage can ever hold
  1309. you in a trade.
  1310. #### What carries over, and what cannot
  1311. Everything you use to run and review a strategy carries over. Recorded sessions
  1312. work in a live workspace: `session start` opens a window at your real equity,
  1313. records market data alongside your decisions, and `session stop` reconciles the
  1314. window by transaction ID. `explain pnl` decomposes it into price movement, fees
  1315. and spread exactly as it does on paper, and `workspace report`, `open-orders`,
  1316. `balance` and `trades-history` all read the same ledger.
  1317. Four things are refused in a live workspace, and each says so when you hit it:
  1318. | Refused | Why | Instead |
  1319. | ----------------------------------------------------------- | ----------------------------------------- | --------------------------------- |
  1320. | `paper buy`/`sell`/`orders`/`cancel`/`cancel-all`/`history` | simulates fills | `order buy`, or a paper workspace |
  1321. | `session start --from tape:…` | replay settles fills from recorded prices | record live (omit `--from`) |
  1322. | `lab new --session replay:…` | sealing a leg this scope cannot run | seal replay plans on paper |
  1323. | `workspace reset` | the journal holds real venue fills | reset a paper workspace |
  1324. Some verbs have no paper equivalent, so they are refused inside any paper or
  1325. live workspace: `order amend`, `edit`, `batch`, `cancel-batch` and
  1326. `cancel-after`; `withdraw`, `withdrawal cancel` and `wallet-transfer`;
  1327. `earn allocate` and `deallocate`; `subaccount transfer`; `futures order`,
  1328. `edit-order`, `cancel`, `cancel-all`, `cancel-after`, `batch-order`, `transfer`,
  1329. `wallet-transfer` and `set-subaccount-status`; and the `ws` order methods. Run
  1330. them with no workspace selected. Futures paper is refused too, apart from six
  1331. reads, because its state is global (see
  1332. [Futures Paper Trading](#futures-paper-trading)).
  1333. Scoring is not refused. `lab show`, `lab score`, `lab compare` and `lab next`
  1334. keep reading the experiment that justified the promotion. A scorecard folds the
  1335. session's own journal window and marks it against the tape recorded beside it,
  1336. so a paper-era session re-scores to the same numbers after the switch. That
  1337. matters because `workspace promote` grades its own checklist through the same
  1338. read. The scorecard is stamped with the scope it came from, so a live
  1339. workspace's sessions can never be mistaken for paper evidence.
  1340. The paper workspace is still worth keeping after promotion: it stays the place
  1341. you seal and run new hypotheses, replay legs included, while the live workspace
  1342. runs the one that already passed.
  1343. | Command | Description |
  1344. | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  1345. | `kraken workspace create <NAME> --capital <AMOUNT> --mode paper\|live [--currency USD] [--fee-rate R] [--slippage-rate R] [--allow-pairs PAIR...]` | Create a paper ledger, or allocate part of the real account to a live one. `--fee-rate`/`--slippage-rate` configure the simulator and apply to `--mode paper` only; `--mode live` needs working credentials so the allocation can be checked against your real balance |
  1346. | `kraken workspace list` | List named workspaces plus the real-account `default` workspace |
  1347. | `kraken workspace show [NAME]` | Show the durable workspace contract |
  1348. | `kraken workspace status [NAME]` | Mark account equity and P&L |
  1349. | `kraken workspace balance [NAME]` | Fold balances from the local journal; `default` delegates to Kraken |
  1350. | `kraken workspace reset [NAME] [--capital N] [--currency C] [--fee-rate R] [--slippage-rate S] [--yes]` | Start a new capital epoch on a paper workspace while retaining history; the options re-parameterize it (live workspaces refuse) |
  1351. | `kraken workspace report [NAME]` | Report session, manual-trade, reset, drift, and total account results |
  1352. | `kraken workspace promote [NAME]` | Promote qualified paper evidence to live execution |
  1353. Select a workspace with `--workspace <NAME>` or `KRAKEN_WORKSPACE=<NAME>`.
  1354. Both modes keep the same event-sourced journal, so `workspace status`,
  1355. `balance`, `report`, and `explain pnl` read identically; only the source of
  1356. fills differs.
  1357. Without a workspace, order verbs address the whole account exactly as before.
  1358. ### Recorded sessions
  1359. | Command | Description |
  1360. | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
  1361. | `kraken session start --symbols <PAIR...> [--label LABEL] [--experiment NAME]` | Start a live recorded evaluation window |
  1362. | `kraken session start --from tape:<NAME> [--speed N] [--label LABEL] [--experiment NAME]` | Start a replay-backed paper session |
  1363. | `kraken session stop` | Finalize the active session and its account window |
  1364. | `kraken session list` | List sessions and their derived state |
  1365. | `kraken session show [--session latest\|s<N>\|LABEL]` | Inspect the window, provenance, and valuation |
  1366. | `kraken session note --kind buy\|sell\|cancel\|skip\|alert --reason <TEXT> [--symbol PAIR] [--order-id ID]` | Append the reasoning behind a decision |
  1367. | `kraken session decisions [--session REF]` | Read the stable decision-log contract |
  1368. | `kraken session state get [--session REF]` | Read an agent's typed resumption cursor |
  1369. | `kraken session state set [FIELDS...]` | Replace the active session's resumption cursor |
  1370. | `kraken replay [--session REF] [--speed N]` | Play a recorded session's timeline back to stdout |
  1371. | `kraken playground [--symbols PAIR...] [--template SKILL] [--for 1h]` | One-command demo: a recorded session in the `playground` paper workspace |
  1372. `session start`, `record`, `replay`, `playground`, `recipe run`, and `streamd`
  1373. are CLI-only streams. Request/response operations around them remain available
  1374. through MCP.
  1375. ### Recipes
  1376. | Command | Description |
  1377. | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
  1378. | `kraken recipe create <NAME> [--from-session REF] [--driver SKILL] [--description TEXT] [--overwrite]` | Derive a reusable recipe from a stopped paper session: an editable `recipe.json` plus a draft `SKILL.md` |
  1379. | `kraken recipe list` | List the local recipe library |
  1380. | `kraken recipe show <NAME>` | Show a recipe's contract and where its artifacts live |
  1381. | `kraken recipe run <NAME> [--for 15m] [--from REF] [--speed N] [--experiment NAME] [--real-account]` | Provision (or reuse) its paper workspace and start the session it records; `--real-account` asks first |
  1382. A recipe records what to run again (driver skill, frozen strategy params, market
  1383. feeds, and provenance) as one portable directory under the global config dir. It
  1384. is an editable input, not sealed evidence; the lab's experiments keep the
  1385. sealing role.
  1386. ### Extensions
  1387. | Command | Description |
  1388. | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
  1389. | `kraken plugin init <NAME> --lang python\|bash [--kind indicator\|alert\|exporter\|driver] [--path DIR]` | Scaffold a runnable extension: entrypoint, `extension.json`, loadable `SKILL.md`, README |
  1390. | `kraken plugin list` | List scaffolded extensions: name, kind, language, entrypoint |
  1391. There is no plugin ABI: the CLI's versioned JSON output is the extension API.
  1392. The scaffolded entrypoint shells out to `kraken ... -o json` and prints;
  1393. kraken-cli never executes extension code.
  1394. ### Autoresearch Lab and P&L
  1395. | Command | Description |
  1396. | ------------------------------------------------------ | --------------------------------------------------------- |
  1397. | `kraken explain pnl [--session REF]` | Decompose a stopped session's P&L and attribute decisions |
  1398. | `kraken lab new <NAME> [EXPERIMENT OPTIONS...]` | Freeze a hypothesis, criteria, and session plan |
  1399. | `kraken lab show <NAME>` | Verify and show a sealed experiment |
  1400. | `kraken lab next <NAME>` | Return the next planned session command |
  1401. | `kraken lab score [--session REF] [--experiment NAME]` | Score a stopped session mechanically |
  1402. | `kraken lab curve [--session REF]` | Emit the marked equity curve point by point |
  1403. | `kraken lab compare <NAME>` | Compare every planned session, including named failures |
  1404. `session state` is operational; decisions, fills, marks, and sealed criteria
  1405. remain the evidence used for replay and scoring.
  1406. ### Feedback
  1407. | Command | Description |
  1408. | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  1409. | `kraken feedback <TYPE> (--input-string STR \| --input-file PATH) [--llm-model MODEL]` | Submit product feedback (`feature-request`, `friction`, or `bug`). Uploads to Kraken over HTTPS. Do not include secrets or PII. [Service groups](#service-groups) lists what is sent. |
  1410. ### Utility
  1411. | Command | Description |
  1412. | ---------------------------------------------- | ----------------------------------------------- |
  1413. | `kraken setup` | Interactive setup wizard |
  1414. | `kraken-shell` | Interactive REPL |
  1415. | `kraken auth login/set/show/switch/test/reset` | OAuth browser sign-in and credential management |
  1416. </details>
  1417. ## Examples
  1418. The guided walkthroughs in [examples/](examples/README.md) cover the bigger
  1419. features: the playground, paper workspaces, market recording, session replay
  1420. with P&L explain, the autoresearch lab, and driving all of it with agent skills.
  1421. None of them need a Kraken account, because all their trading happens in paper
  1422. workspaces. The one-liners below use `jq` (`brew install jq` or
  1423. `apt install jq`).
  1424. <!-- prettier-ignore -->
  1425. > [!CAUTION]
  1426. > The order one-liners below use `--validate`, so Kraken only checks them.
  1427. > Remove `--validate` and they trade real money on your account. The dead
  1428. > man's switch is the exception: it is live as soon as you run it. Run them
  1429. > with no workspace selected (`unset KRAKEN_WORKSPACE`). Inside a workspace the
  1430. > limit buy acts on that workspace, the `--oflags viqc` buy and `cancel-after`
  1431. > are refused, and the balance check never passes.
  1432. ### Limit buy at the current price
  1433. ```bash
  1434. PRICE=$(kraken ticker BTCUSD -o json | jq -r '.[].last_price')
  1435. kraken order buy BTCUSD 0.001 --type limit --price "$PRICE" --validate -o json
  1436. ```
  1437. ### Buy only below a price
  1438. ```bash
  1439. if kraken ticker BTCUSD -o json | jq -e '.[].ask_price < 75000' >/dev/null; then
  1440. kraken order buy BTCUSD 20 --type market --oflags viqc --validate -o json # $20 of BTC
  1441. fi
  1442. ```
  1443. ### Sell when your balance is above a threshold
  1444. ```bash
  1445. if kraken balance -o json | jq -e '(.BTC // 0) > 0.001' >/dev/null; then
  1446. kraken order sell BTCUSD 0.001 --type market --validate -o json
  1447. fi
  1448. ```
  1449. `balance` is keyed by asset code (`BTC`, `USD`, `ETH`). BTC you hold in Earn
  1450. appears under Kraken's raw code with a suffix, such as `XBT.F`, so add it to
  1451. `BTC` when you report total BTC.
  1452. ### Real-time price stream
  1453. ```bash
  1454. kraken ws ticker BTC/USD -o json | while read -r line; do
  1455. LAST=$(echo "$line" | jq -r '.data[0].last // empty')
  1456. [ -n "$LAST" ] && echo "BTC: $LAST"
  1457. done
  1458. ```
  1459. ### Stream multiple tickers
  1460. ```bash
  1461. kraken ws ticker BTC/USD ETH/USD SOL/USD -o json
  1462. ```
  1463. ### Dead man's switch
  1464. ```bash
  1465. kraken order cancel-after 60
  1466. ```
  1467. This has no `--validate`. It arms Kraken's dead man's switch: unless you call it
  1468. again within 60 seconds, Kraken cancels all your open orders. Each call restarts
  1469. the countdown, so a script keeps it alive by re-running it well inside the
  1470. timeout, for example every 15 to 30 seconds. `kraken order cancel-after 0` turns
  1471. it off. It needs API credentials and runs only with no workspace selected.
  1472. ## Agent skills
  1473. Ships with 59 agent skills: SKILL.md packages that walk an agent through a
  1474. workflow from start to finish. A few to start with:
  1475. | Skill | What it does |
  1476. | -------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
  1477. | [kraken-setup](skills/kraken-setup/SKILL.md) | Install, credentials, and a first paper-trading session |
  1478. | [kraken-spot-execution](skills/kraken-spot-execution/SKILL.md) | Spot orders with validation and confirmation gates |
  1479. | [kraken-dca-strategy](skills/kraken-dca-strategy/SKILL.md) | Dollar cost averaging with scheduled buys and cost tracking |
  1480. | [kraken-grid-trading](skills/kraken-grid-trading/SKILL.md) | Grid trading with layered orders across a price range |
  1481. | [kraken-liquidation-guard](skills/kraken-liquidation-guard/SKILL.md) | Prevent futures liquidation through margin monitoring and emergency procedures |
  1482. | [kraken-paper-to-live](skills/kraken-paper-to-live/SKILL.md) | Promote a validated paper strategy to live trading |
  1483. The full list is in the [Skills Index](skills/INDEX.md). The Claude Code plugin
  1484. installs the skills along with the MCP server.
  1485. ## Troubleshooting
  1486. **`command not found: kraken` after install**
  1487. The installer puts the binaries in `~/.cargo/bin` (or `$CARGO_HOME/bin`). Open a
  1488. new terminal, or restart your agent. To run it right now, use the full path:
  1489. `~/.cargo/bin/kraken --version` (or `$CARGO_HOME/bin/kraken --version`).
  1490. **macOS blocks the binary ("Apple could not verify")**
  1491. This only affects binaries downloaded with a web browser. The one-liner install
  1492. is not affected. In the folder where you unpacked the download, remove the
  1493. quarantine flag:
  1494. ```bash
  1495. xattr -d com.apple.quarantine kraken kraken-mcp kraken-shell
  1496. ```
  1497. **"EAPI:Invalid key" or authentication errors**
  1498. Check that `KRAKEN_API_KEY` and `KRAKEN_API_SECRET` are set correctly. Keys are
  1499. case-sensitive. Verify the API key has the required permissions for the command
  1500. (Query Funds for `balance`, Modify Orders for `order buy`, etc.). If you signed
  1501. in with OAuth, run `kraken auth show` to see which key is in use. A flag or an
  1502. environment variable overrides the stored key.
  1503. **Futures commands fail after OAuth sign-in**
  1504. The sign-in key covers Spot only. Create a Futures key (see
  1505. [Getting API keys](#getting-api-keys)), then set `KRAKEN_FUTURES_API_KEY` and
  1506. `KRAKEN_FUTURES_API_SECRET`, or add `futures_api_key` and `futures_api_secret`
  1507. to `config.toml`. `kraken setup` and `kraken auth set` can store it too, but
  1508. both also need a Spot API key.
  1509. **An order went to the paper account**
  1510. `KRAKEN_WORKSPACE` is still set from a paper example, so `kraken order buy` and
  1511. `kraken balance` act on that workspace. Run `unset KRAKEN_WORKSPACE`, or check
  1512. the `Mode` row (`mode` in JSON) before you trade.
  1513. **`kraken auth login` needs a terminal**
  1514. Run it yourself in a terminal window. It refuses to run from a script or an
  1515. agent.
  1516. **Browser sign-in times out**
  1517. You have 5 minutes to approve in the browser. An unfinished sign-in ends with a
  1518. `timeout` error. Run `kraken auth login` again and approve access in time. Over
  1519. SSH, forward the callback ports and use `--no-browser` (see
  1520. [Signing in over SSH](#signing-in-over-ssh)).
  1521. **Rate limit errors**
  1522. The CLI does not pre-throttle or retry rate-limited requests. The Kraken API
  1523. server enforces rate limits, and the CLI returns the error immediately with a
  1524. `suggestion` field containing tier-specific limits and a `docs_url` pointing to
  1525. the relevant Kraken documentation. Read the suggestion and adjust request
  1526. frequency. For sustained high-frequency use, prefer WebSocket streaming over
  1527. REST polling.
  1528. **"Failed to connect" or "No tools found" in MCP client**
  1529. The client cannot find `kraken-mcp` on its PATH. Quit the client and start it
  1530. again from a new terminal window, or set `command` to the absolute path that
  1531. `command -v kraken-mcp` prints in a new terminal. Most clients start the server
  1532. without a shell, so `~` and `$CARGO_HOME` stay unexpanded. If `kraken-mcp` is
  1533. missing, run the one-liner again: older releases installed `kraken` only. Run
  1534. `~/.cargo/bin/kraken-mcp -s market` (or the `$CARGO_HOME` path) in a terminal to
  1535. confirm the server starts; it prints one `server_start` line, then waits for a
  1536. client. Stop it with Ctrl-C. Check that your client configuration matches the
  1537. format in the [MCP server](#mcp-server) section.
  1538. **Spot paper trading state errors**
  1539. `Workspace '<NAME>' not found` means the paper account was never created: run
  1540. `kraken paper init` (or
  1541. `kraken workspace create <NAME> --mode paper --capital 10000`). To start an
  1542. existing account over, run `kraken paper reset --yes`, after stopping any
  1543. recording session with `kraken session stop`. A `malformed log line` error means
  1544. the journal itself is damaged, and reset cannot read it either: move that
  1545. workspace's `journal.jsonl` aside (in
  1546. `~/Library/Application Support/kraken/workspaces/<NAME>/` on macOS,
  1547. `~/.config/kraken/workspaces/<NAME>/` on Linux), then run
  1548. `kraken paper reset --yes`.
  1549. **Futures paper trading state errors**
  1550. Run `kraken futures paper reset` with no workspace selected. If the state file
  1551. itself cannot be read (for example, open orders saved by 0.4.1), reset fails
  1552. too: delete `futures_state.json` from the `paper/` folder of your config
  1553. directory (`~/Library/Application Support/kraken/paper/` on macOS,
  1554. `~/.config/kraken/paper/` on Linux) and run `kraken futures paper init`. Spot
  1555. and futures paper states are independent.
  1556. ## Star history
  1557. <!-- markdownlint-disable MD033 MD013 -->
  1558. <a href="https://www.star-history.com/#krakenfx/kraken-cli&Date">
  1559. <picture>
  1560. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=krakenfx/kraken-cli&type=Date&theme=dark" />
  1561. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=krakenfx/kraken-cli&type=Date" />
  1562. <img alt="Star history chart for krakenfx/kraken-cli" src="https://api.star-history.com/svg?repos=krakenfx/kraken-cli&type=Date" />
  1563. </picture>
  1564. </a>
  1565. <!-- markdownlint-enable MD033 MD013 -->
  1566. The chart tracks stars on
  1567. [krakenfx/kraken-cli](https://github.com/krakenfx/kraken-cli) over time.
  1568. ## Development
  1569. ```bash
  1570. cargo build # dev build
  1571. cargo test # run tests
  1572. cargo clippy --workspace --all-targets -- -D warnings # lint
  1573. just ready # the full local gate (see CONTRIBUTING.md)
  1574. ```
  1575. <details>
  1576. <summary>Architecture</summary>
  1577. The repository is a Cargo workspace. The three binaries ship from the
  1578. `kraken-cli` package; every front-end is a thin adapter over `kraken-app`.
  1579. | Crate | Role |
  1580. | ------------------ | ------------------------------------------------------------------------- |
  1581. | `kraken-cli` | The `kraken` binary, and the package that ships all three |
  1582. | `kraken-mcp` | The MCP server: tool discovery, gating, and audit |
  1583. | `kraken-shell` | The `kraken-shell` REPL |
  1584. | `kraken-app` | The engine behind every command |
  1585. | `kraken-contract` | The command tree, shared by every front-end |
  1586. | `kraken-auth` | Stored keys, the active key, and browser sign-in |
  1587. | `kraken-rest` | Every Spot and Futures REST endpoint as a type, over one signed transport |
  1588. | `kraken-core` | Typed wire model and error taxonomy for Spot WebSocket v2 |
  1589. | `kraken-ws` | Spot WebSocket v2 client: connection lifecycle and reconnects |
  1590. | `kraken-paper` | Event-sourced spot paper-trading engine |
  1591. | `kraken-workspace` | Isolated account scopes for paper and live |
  1592. | `kraken-session` | Session contract and timeline read model |
  1593. | `kraken-recording` | Market data recording, JSONL and DuckDB backends |
  1594. | `kraken-replay` | P&L decomposition and paced playback |
  1595. | `kraken-lab` | Autoresearch Lab read models: equity curve, scorecards |
  1596. | `kraken-recipe` | Session-derived recipes |
  1597. </details>
  1598. ## Contributing
  1599. Bug reports, feature requests, and pull requests are welcome. See
  1600. [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  1601. ## License & disclaimer
  1602. MIT. See [LICENSE](LICENSE).
  1603. This is experimental software. Commands interact with the live Kraken exchange
  1604. and can result in real financial transactions. Orders, withdrawals, and
  1605. transfers are irreversible once processed. The authors accept no liability for
  1606. financial losses. See [DISCLAIMER.md](DISCLAIMER.md) for full terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.