krakenfx/kraken-cli
GitHub: krakenfx/kraken-cli
首个面向 AI agent 的多资产类别交易命令行工具，内置 MCP server 和模拟交易引擎，让 LLM 直接操作 Kraken 交易所。
Stars: 597 | Forks: 72
# Kraken CLI
首个用于交易加密货币、股票、外汇和衍生品的 AI 原生 CLI。
完整的 Kraken API 访问。内置 MCP server。支持实盘和模拟交易。单一二进制文件。
兼容 Cursor、Claude、Codex、Copilot、Gemini、Goose 和 OpenClaw。
在你的 AI agent 中尝试以下操作：
## 目录
- [安装](#installation)
- [可交易品种](#what-you-can-trade)
- [快速开始](#quick-start)
- [MCP Server](#mcp-server)
- [模拟交易](#paper-trading)
- [命令](#commands)
- [API Keys 与配置](#api-keys--configuration)
- [验证二进制文件](#verifying-binaries)
- [贡献](#contributing)
- [许可证与免责声明](#license--disclaimer)
## 安装
单一二进制文件，无运行时依赖。
### 一键安装
```
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/krakenfx/kraken-cli/releases/latest/download/kraken-cli-installer.sh | sh
```
自动检测你的操作系统和架构，下载对应的二进制文件并安装。支持 macOS（Apple Silicon 和 Intel）以及 Linux（x86_64 和 ARM64）。Windows：请使用 WSL。
验证是否正常工作：
```
kraken status && kraken ticker BTCUSD
```
预构建的二进制文件也可以在 [GitHub Releases](https://github.com/krakenfx/kraken-cli/releases) 页面下载。
## 可交易品种
一个二进制文件涵盖六大资产类别。所有交易命令均使用相同接口在各类资产间通用；只需在需要的地方传入 `--asset-class` 即可。
| 资产类别 | 交易标的 | 杠杆 | 标志 | 示例 |
|---|---|---|---|---|
| **加密货币现货** | 1,400+ 交易对 (BTC, ETH, SOL 及数百种更多币种) | 主要交易对最高 10x | _(默认)_ | `kraken order buy BTCUSD 0.001 --type limit --price 50000` |
| **代币化美股及 ETF ([xStocks](https://www.kraken.com/xstocks))** | 79 种资产: AAPL, NVDA, TSLA, GOOGL, AMZN, MSFT, SPY, QQQ 等 | 排名前 10 最高 3x | `--asset-class tokenized_asset` | `kraken order buy AAPLx/USD 0.1 --type limit --price 200 --asset-class tokenized_asset` |
| **外汇** | 11 个法币对: EUR/USD, GBP/USD, USD/JPY, AUD/USD 等 | — | `--asset-class forex` | `kraken ticker EURUSD --asset-class forex` |
| **永续期货** | 317 个合约: 加密货币，5 个外汇永续，11 个股票/指数永续 (AAPL, NVDA, TSLA, SPY, QQQ, S&P 500) | 最高 50x | _(期货引擎)_ | `kraken futures order buy PF_XBTUSD 1 --type limit --price 50000` |
| **反向与定期期货** | 20 个合约: BTC, ETH, SOL, LTC, XRP, ADA, DOGE, LINK | 不等 | _(期货引擎)_ | `kraken futures order buy FI_XBTUSD_260327 1 --type limit --price 50000` |
| **理财 / 质押** | 跨越多种资产的灵活和定期策略 | — | — | `kraken earn strategies --asset ETH` |
*xStocks 在美国不可用。所有产品的可用性因司法管辖区而异。*
## 面向 AI Agents
如果你是一个 AI agent 或正在构建一个，请从这里开始：
| 资源 | 描述 |
|----------|-------------|
| [CONTEXT.md](CONTEXT.md) | 面向使用工具的 agents 的运行时上下文 |
| [AGENTS.md](AGENTS.md) | 完整集成指南：认证、调用、错误、频率限制 |
| [agents/tool-catalog.json](agents/tool-catalog.json) | 151 个命令，包含参数 schema、类型和安全标志 |
| [agents/error-catalog.json](agents/error-catalog.json) | 9 种错误类别及重试指南 |
| [skills/](skills/) | 50 个目标导向的 SKILL.md 工作流包 |
| [CLAUDE.md](CLAUDE.md) | 特定于 Claude 的集成指南 |
核心调用模式：
```
kraken [args...] -o json 2>/dev/null
```
- 成功时 stdout 总是输出有效的 JSON，失败时则输出 JSON 错误信封。
- 退出码为 0 表示成功。非零表示失败。
- stderr 仅用于输出诊断信息（使用 `-v` 启用）。永远不要从 stderr 解析数据。
## 验证二进制文件
发布版的二进制文件使用 [minisign](https://jedisct1.github.io/minisign/) 签名。[Releases](https://github.com/krakenfx/kraken-cli/releases) 页面上的每个构件都有对应的 `.minisig` 签名文件。
**公钥：**
```
RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd
```
**验证下载的二进制文件：**
```
minisign -Vm kraken-cli-aarch64-apple-darwin.tar.gz -P RWQJue8SwPzZBZO8Up5ppAUqm0wM/gK5yjnam+Dbf7KbY0utkiO+7XCd
```
安装 minisign：`brew install minisign` (macOS) 或 `apt install minisign` (Linux)。
## 快速开始
公共市场数据无需凭证：
```
kraken ticker BTCUSD -o json
kraken orderbook BTCUSD --count 10 -o json
kraken trades BTCUSD --count 20 -o json
kraken ohlc BTCUSD --interval 60 -o json
```
使用认证：
```
export KRAKEN_API_KEY="your-key"
export KRAKEN_API_SECRET="your-secret"
kraken balance -o json
kraken open-orders -o json
kraken order buy BTCUSD 0.001 --type limit --price 50000 -o json
```
面向人类（表格输出，交互式设置）：
```
kraken setup
kraken ticker BTCUSD
kraken balance
kraken shell
```
## API Keys 与配置
需要认证的命令（交易、余额、订单管理）需要一对 Kraken API key。公共市场数据和模拟交易无需凭证即可使用。
### 获取 API keys
**现货**（涵盖交易、余额、资金、理财、子账户）：kraken.com 上的 [Settings > API](https://www.kraken.com)。完整指南：[How to create a spot API key](https://support.kraken.com/articles/360000919966-how-to-create-an-api-key)。
**期货**（仅用于 `kraken futures` 命令）：Futures 界面上的 [Settings > Create Key](https://www.kraken.com/login-futures)。完整指南：[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)。
请授予你的工作流所需的最低权限。对于只读监控，"Query Funds" 和 "Query Open Orders & Trades" 就足够了。
### 环境变量（推荐 agents 使用）
```
export KRAKEN_API_KEY="your-key"
export KRAKEN_API_SECRET="your-secret"
export KRAKEN_FUTURES_API_KEY="your-futures-key" # optional
export KRAKEN_FUTURES_API_SECRET="your-futures-secret" # optional
```
### 配置文件（面向人类）
将凭证存储在 `~/.config/kraken/config.toml` 中：
```
[auth]
api_key = "your-api-key"
api_secret = "your-api-secret"
[settings]
default_pair = "BTCUSD"
output = "table"
```
或者使用交互式向导：`kraken setup`。
### 凭证解析顺序
按优先级从高到低：
1. 命令行标志（`--api-key`, `--api-secret`）
2. 环境变量（`KRAKEN_API_KEY`, `KRAKEN_API_SECRET`）
3. 配置文件（`~/.config/kraken/config.toml`）
### 安全性
- 配置文件创建时具有 `0600` 权限（仅所有者可读写）
- 密钥永远不会被记录、打印或包含在错误消息中
- 使用 `--api-secret-stdin` 或 `--api-secret-file` 代替 `--api-secret`，以避免密钥出现在进程列表中
- 对于自动化，推荐使用环境变量而非命令行标志
## MCP Server
`kraken-cli` 包含一个通过 stdio 运行的内置 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。无需子进程包装器。
MCP 工具调用通过与其享相同错误处理和频率限制行为的 CLI 命令相同的命令路径运行。
```
kraken mcp # read-only (market, account, paper)
kraken mcp -s all # all services, dangerous calls require acknowledged=true
kraken mcp -s all --allow-dangerous # all services, no per-call confirmation
kraken mcp -s market,trade,paper # specific services
```
配置你的 MCP 客户端（Claude Desktop、ChatGPT、Codex、Gemini CLI、Cursor、VS Code、Windsurf 等）：
```
{
"mcpServers": {
"kraken": {
"command": "kraken",
"args": ["mcp", "-s", "all"]
}
}
}
```
Gemini CLI 用户可以直接安装：`gemini extensions install https://github.com/krakenfx/kraken-cli`
### 服务组
| 服务 | 需要认证 | 风险 |
|---------|------|------|
| market | 否 | 无 |
| account | 是 | 只读 |
| trade | 是 | 订单 (危险) |
| funding | 是 | 提现 (危险) |
| earn | 是 | 质押 (危险) |
| subaccount | 是 | 转账 (危险) |
| futures | 混合 | 订单 (危险) |
| futures-paper | 否 | 无 (模拟) |
| paper | 否 | 无 (模拟) |
| auth | 否 | 只读 |
默认值：`market,account,paper`。流式组（`websocket`、`futures-ws`）在 MCP v1 中被排除。
危险工具带有 `destructive_hint` 注释，并在描述中包含 `[DANGEROUS: requires human confirmation]`。在受保护模式（默认）下，危险调用必须包含 `acknowledged=true`。在自主模式（`--allow-dangerous`）下，此要求被禁用。
## 命令
13 个组中的 151 个命令。对于机器可读的参数 schema，请加载 [agents/tool-catalog.json](agents/tool-catalog.json)。
| 组 | 命令数 | 需要认证 | 描述 |
|-------|----------|------|-------------|
| market | 10 | 否 | Ticker、orderbook、OHLC、trades、spreads、资产信息 |
| account | 18 | 是 | 余额、订单、交易、账本、持仓、导出 |
| trade | 9 | 是 | 订单下单、修改、取消 (现货、xStocks、外汇) |
| funding | 10 | 是 | 充值、提现、钱包转账 |
| earn | 6 | 是 | 质押策略和分配 |
| subaccount | 2 | 是 | 创建子账户、账户间转账 |
| futures | 39 | 混合 | 期货市场数据和交易 |
| futures-paper | 17 | 否 | 使用实时价格的期货模拟交易 |
| futures-ws | 9 | 混合 | 期货 WebSocket 流式传输 |
| websocket | 15 | 混合 | 现货 WebSocket v2 流式传输和请求/响应 |
| paper | 10 | 否 | 使用实时价格的现货模拟交易 |
| auth | 4 | 否 | 凭证管理 |
| utility | 2 | 否 | 交互式设置和 REPL shell |
有 34 个命令被标记为 `dangerous`（订单、提现、转账、cancel-all、质押）。权威列表位于 [agents/tool-catalog.json](agents/tool-catalog.json) 的 `dangerous` 字段中。
[--asset-class tokenized_asset\|forex]` | Ticker 数据 |
| `kraken ohlc [--interval 60] [--asset-class tokenized_asset\|forex]` | OHLC K线 |
| `kraken orderbook [--count 25] [--asset-class tokenized_asset]` | L2 订单簿 |
| `kraken orderbook-grouped [--depth 10] [--grouping 1]` | 分组订单簿 |
| `kraken trades [--count 1000] [--asset-class tokenized_asset]` | 最近成交 |
| `kraken spreads [--since TS] [--asset-class tokenized_asset]` | 最近价差 |
### 账户数据（私有）
| 命令 | 描述 |
|---------|-------------|
| `kraken orderbook-l3 [--depth 100]` | L3 订单簿 |
| `kraken balance [--rebase-multiplier rebased\|base]` | 所有余额 |
| `kraken extended-balance` | 扩展余额 (余额、信用、冻结) |
| `kraken credit-lines [--rebase-multiplier rebased\|base]` | 信用额度详情 (VIP) |
| `kraken trade-balance [--asset USD] [--rebase-multiplier rebased\|base]` | 保证金/净值摘要 |
| `kraken open-orders [--trades] [--cl-ord-id ID] [--rebase-multiplier rebased\|base]` | 未结订单 |
| `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]` | 已平仓订单 |
| `kraken query-orders [--trades] [--userref REF] [--consolidate-taker] [--rebase-multiplier rebased\|base]` | 查询特定订单 |
| `kraken trades-history [--type TYPE] [--trades] [--offset N] [--consolidate-taker] [--without-count] [--ledgers] [--rebase-multiplier rebased\|base]` | 交易历史 |
| `kraken query-trades [--trades] [--rebase-multiplier rebased\|base]` | 查询特定交易 |
| `kraken positions [--txid ID] [--show-pnl] [--consolidation market] [--rebase-multiplier rebased\|base]` | 未平仓位 |
| `kraken ledgers [--asset BTC --type trade] [--asset-class CLASS] [--start TS] [--end TS] [--offset N] [--without-count] [--rebase-multiplier rebased\|base]` | 账本条目 |
| `kraken query-ledgers [--trades] [--rebase-multiplier rebased\|base]` | 查询特定账本条目 |
| `kraken volume [--pair BTCUSD] [--rebase-multiplier rebased\|base]` | 交易量与手续费 |
| `kraken export-report --report trades --description "desc" [--format CSV\|TSV] [--fields F] [--starttm TS] [--endtm TS]` | 请求导出 |
| `kraken export-status --report trades` | 导出状态 |
| `kraken export-retrieve ` | 下载导出文件 |
| `kraken export-delete ` | 删除导出文件 |
### 交易
| 命令 | 描述 |
|---------|-------------|
| `kraken order buy [--type limit --price P] [--asset-class tokenized_asset] [--validate] ...` | 买入订单 |
| `kraken order sell [--type limit --price P] [--asset-class tokenized_asset] [--validate] ...` | 卖出订单 |
| `kraken order batch [--pair P] [--asset-class tokenized_asset] [--deadline DL] [--validate]` | 批量订单 (2-15) |
| `kraken order amend --txid [--order-qty Q --limit-price P ...]` | 原地修改订单 |
| `kraken order amend --cl-ord-id [--limit-price P ...]` | 通过客户端订单 ID 修改 |
| `kraken order edit [--price P]` | 编辑订单 (取消+替换) |
| `kraken order cancel ` | 通过 txid(s) 取消 |
| `kraken order cancel --cl-ord-id ` | 通过客户端订单 ID 取消 |
| `kraken order cancel-batch [--cl-ord-ids ID...]` | 批量取消 (最多共 50 个) |
| `kraken order cancel-all [--yes]` | 全部取消 |
| `kraken order cancel-after ` | 死人开关 |
### 资金
| 命令 | 描述 |
|---------|-------------|
| `kraken deposit methods [--asset-class currency\|tokenized_asset] [--rebase-multiplier rebased\|base]` | 充值方式 |
| `kraken deposit addresses [--new] [--asset-class CLASS] [--amount AMT]` | 充值地址 |
| `kraken deposit status [--asset A] [--asset-class CLASS] [--method M] [--start TS] [--end TS] [--cursor C] [--limit N] [--rebase-multiplier rebased\|base]` | 充值状态 |
| `kraken withdraw [--asset-class CLASS] [--address ADDR] [--max-fee F] [--rebase-multiplier rebased\|base]` | 提现 |
| `kraken withdrawal methods [--asset A] [--asset-class CLASS] [--network N] [--rebase-multiplier rebased\|base]` | 提现方式 |
| `kraken withdrawal addresses [--asset A] [--asset-class CLASS] [--method M] [--key K] [--verified true\|false]` | 提现地址 |
| `kraken withdrawal info ` | 提现手续费信息 |
| `kraken withdrawal status [--asset A] [--asset-class CLASS] [--method M] [--start TS] [--end TS] [--cursor C] [--limit N] [--rebase-multiplier rebased\|base]` | 提现状态 |
| `kraken withdrawal cancel ` | 取消待处理的提现 |
| `kraken wallet-transfer --from IIBAN --to IIBAN` | 钱包转账 |
### 理财
| 命令 | 描述 |
|---------|-------------|
| `kraken earn strategies [--asset ETH] [--lock-type flex bonded...] [--ascending] [--cursor C] [--limit N]` | 列出策略 |
| `kraken earn allocate ` | 分配资金 |
| `kraken earn deallocate ` | 解除分配资金 |
| `kraken earn allocate-status ` | 分配状态 |
| `kraken earn deallocate-status ` | 解除分配状态 |
| `kraken earn allocations [--ascending] [--converted-asset USD] [--hide-zero-allocations]` | 当前分配 |
### 子账户
| 命令 | 描述 |
|---------|-------------|
| `kraken subaccount create ` | 创建子账户 |
| `kraken subaccount transfer --from IIBAN --to IIBAN [--asset-class CLASS]` | 账户间转账 |
### 期货：公共市场数据
| 命令 | 描述 |
|---------|-------------|
| `kraken futures instruments` | 所有合约 |
| `kraken futures tickers` | 所有 tickers |
| `kraken futures ticker ` | 单个 ticker |
| `kraken futures orderbook ` | 订单簿 |
| `kraken futures history [--since TS] [--before TS]` | 交易历史 |
| `kraken futures feeschedules` | 费率计划 |
| `kraken futures instrument-status [--symbol SYM]` | 标的状态 |
### 期货：交易（私有）
| 命令 | 描述 |
|---------|-------------|
| `kraken futures order buy [--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]` | 买入期货 |
| `kraken futures order sell [--type limit] [--price P] [--stop-price SP] ...` | 卖出期货 |
| `kraken futures edit-order --order-id ID [--size S] [--price P] [--stop-price SP]` | 修改现有订单 |
| `kraken futures cancel --order-id ID` | 通过订单 ID 取消 |
| `kraken futures cancel --cli-ord-id ID` | 通过客户端订单 ID 取消 |
| `kraken futures cancel-all [--symbol SYM] [--yes]` | 取消所有订单 |
| `kraken futures cancel-after ` | 死人开关 |
| `kraken futures batch-order ''` 或 `kraken futures batch-order @file.json` | 批量下单 |
### 期货：账户数据（私有）
| 命令 | 描述 |
|---------|-------------|
| `kraken futures accounts` | 钱包/账户信息 |
| `kraken futures open-orders` |结订单 |
| `kraken futures positions` | 未平仓位 |
| `kraken futures fills [--since TS]` | 最近成仓 |
| `kraken futures leverage [--symbol SYM]` | 杠杆偏好 |
| `kraken futures set-leverage ` | 设置杠杆 |
| `kraken futures notifications` | 账户通知 |
| `kraken futures transfers` | 转账历史 |
| `kraken futures transfer ` | 钱包间转账 |
| `kraken futures history-executions [--since TS] [--before TS] [--sort asc\|desc]` | 执行历史 |
| `kraken futures history-orders [--since TS] [--before TS] [--sort asc\|desc]` | 订单历史 |
| `kraken futures history-triggers [--since TS] [--before TS] [--sort asc\|desc]` | 触发历史 |
| `kraken futures history-account-log-csv [--since TS] [--before TS]` | 账户日志 (CSV) |
| `kraken futures trading-instruments [--contract-type ...]` | 交易标的 (需认证) |
| `kraken futures historical-funding-rates ` | 历史资金费率 |
| `kraken futures order-status ...` | 查询订单状态 (需认证) |
| `kraken futures pnl-preferences` | 获取 PnL 偏好 (需认证) |
| `kraken futures set-pnl-preference ` | 设置 PnL 偏好 (需认证) |
| `kraken futures unwind-queue` | 获取 unwind 队列 (需认证) |
| `kraken futures assignment-programs` | 分配计划 (需认证) |
| `kraken futures fee-schedule-volumes` | 费率计划交易量 (需认证) |
| `kraken futures subaccounts` | 列出子账户 (需认证) |
| `kraken futures subaccount-status ` | 子账户交易状态 (需认证) |
| `kraken futures set-subaccount-status ` | 设置子账户交易状态 (需认证) |
| `kraken futures wallet-transfer ` | 钱包间转账 (需认证) |
### 期货：模拟交易（无需认证）
| 命令 | 描述 |
|---------|-------------|
| `kraken futures paper init [--balance 10000] [--currency USD] [--fee-rate 0.0005]` | 初始化期货模拟账户 |
| `kraken futures paper reset [--balance B] [--currency C] [--fee-rate R]` | 重置账户 (清除持仓、订单、成仓) |
| `kraken futures paper balance` | 抵押品、已用保证金、可用保证金、未实现 P&L |
| `kraken futures paper status` | 账户摘要：净值、起始以来 P&L、未实现 P&L、持仓/订单计数 |
| `kraken futures paper buy [--leverage L] [--type TYPE] [--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]` | 模拟做多 (全部 8 种订单类型) |
| `kraken futures paper sell [--leverage L] [--type TYPE] [--price P] ...` | 模拟做空 (全部 8 种订单类型) |
| `kraken futures paper orders` | 未结挂单 |
| `kraken futures paper order-status ` | 查询特定订单 |
| `kraken futures paper edit-order --order-id [--size S] [--price P] [--stop-price SP]` | 修改挂单 |
| `kraken futures paper cancel --order-id ` | 通过订单 ID 或 `--cli-ord-id` 取消 |
| `kraken futures paper cancel-all [--symbol SYM]` | 取消全部 (可选标的过滤) |
| `kraken futures paper batch-order ''` | 批量下单 |
| `kraken futures paper positions` | 包含标记价格、强平价格、未实现 P&L 的未平仓位 |
| `kraken futures paper fills [--since TS]` | 成仓历史 |
| `kraken futures paper history` | 已平仓位和已取消订单及已实现 P&L |
| `kraken futures paper leverage [--symbol SYM]` | 当前杠杆偏好 |
| `kraken futures paper set-leverage ` | 为单个标的设置默认杠杆 |
### 期货 WebSocket 流式传输
| 命令 | 描述 |
|---------|-------------|
| `kraken futures ws ticker ` | 流式传输期货 tickers (公共) |
| `kraken futures ws trades ` | 流式传输期货 trades (公共) |
| `kraken futures ws book ` | 流式传输期货订单簿 (公共) |
| `kraken futures ws fills` | 流式传输成仓 (私有，挑战认证) |
| `kraken futures ws open-orders` | 流式传输未结订单 (私有) |
| `kraken futures ws open-positions` | 流式传输未平仓位 (私有) |
| `kraken futures ws balances` | 流式传输余额和保证金 (私有) |
| `kraken futures ws notifications` | 流式传输通知 (私有) |
| `kraken futures ws account-log` | 流式传输账户日志 (私有) |
### WebSocket（流式传输和请求/响应）
| 命令 | 描述 |
|---------|-------------|
| `kraken ws ticker [--event-trigger bbo]` | 流式传输 tickers |
| `kraken ws trades ` | 流式传输 trades |
| `kraken ws book [--depth 10]` | 流式传输 L2 订单簿 |
| `kraken ws ohlc [--interval 1]` | 流式传输 OHLC K线 |
| `kraken ws instrument [PAIR...]` | 流式传输标的元数据 |
| `kraken ws executions` | 流式传输交易执行 (需认证) |
| `kraken ws balances` | 流式传输余额更新 (需认证) |
| `kraken ws level3 ` | 流式传输 L3 订单簿 (需认证) |
| `kraken ws add-order` | 通过 WebSocket 下单 (需认证) |
| `kraken ws amend-order` | 通过 WebSocket 修改订单 (需认证) |
| `kraken ws cancel-order` | 通过 WebSocket 取消订单 (需认证) |
| `kraken ws cancel-all` | 通过 WebSocket 取消所有订单 (需认证) |
| `kraken ws cancel-after ` | 通过 WebSocket 启死人开关 (需认证) |
| `kraken ws batch-add` | 通过 WebSocket 批量添加订单 (需认证) |
| `kraken ws batch-cancel` | 通过 WebSocket 批量取消订单 (需认证) |
### 实用工具
| 命令 | 描述 |
|---------|-------------|
| `kraken setup` | 交互式设置向导 |
| `kraken shell` | 交互式 REPL |
| `kraken auth set/show/test/reset` | 凭证管理 |
## 模拟交易
模拟交易提供了一个安全的沙盒，可基于 Kraken 实时价格测试交易逻辑。无需 API keys，无需账户，没有真实资金。两个独立的模拟引擎分别覆盖现货和期货。
### 现货模拟交易
命令接口与实盘现货交易几乎对等。通过更改前缀在模拟盘和实盘之间切换：`kraken paper buy` 对比 `kraken order buy`。已知差异：模拟盘仅支持 `market` 和 `limit` 订单类型；未对滑点和部分成交进行建模。
**Agent 模式：**
```
kraken paper init --balance 10000 -o json
kraken paper buy BTCUSD 0.01 -o json
kraken paper sell BTCUSD 0.005 --type limit --price 70000 -o json
kraken paper status -o json
kraken paper reset -o json
```
**人类模式：**
```
kraken paper init --balance 5000 --currency EUR
kraken paper buy BTCUSD 0.01
kraken paper balance
kraken paper status
kraken paper orders
kraken paper history
kraken paper reset
```
| 命令 | 描述 |
|---------|-------------|
| `kraken paper init [--balance 10000] [--currency USD]` | 初始化模拟账户 |
| `kraken paper reset` | 对账挂单，然后重置 |
| `kraken paper balance` | 所有余额 (总计、已冻结、可用) |
| `kraken paper buy [--type limit --price P]` | 模拟买入 (市价或限价) |
| `kraken paper sell [--type limit --price P]` | 模拟卖出 (市价或限价) |
| `kraken paper orders` | 未结限价单 |
| `kraken paper cancel ` | 取消限价单 |
| `kraken paper cancel-all` | 取消所有限价单 |
| `kraken paper history` | 已成交流易历史 |
| `kraken paper status` | 投资组合价值、未实现 P&L、交易笔数 |
价格来源于公共 Kraken Ticker API（无需认证）。所有成交将收取 0.26% 的 Taker 费用（Kraken Starter 等级默认值）。当实时市场价格穿越订单价格时，限价单将以限价成交。
在表格模式下，所有输出都会标记为 `[PAPER]`，在 JSON 模式中包含 `"mode": "paper"`。
### 期货模拟交易
与实盘 `kraken futures order` 命令近乎对等。支持所有 8 种订单类型（market、limit、post、stop、take-profit、ioc、trailing-stop、fok）、杠杆和保证金追踪、持仓聚合/净值化、强平模拟以及资金费率累积。已知差异：`order-status` 接受单个 ID（实盘接受多个），post-only 订单会被取消而不是模拟 maker 排队优先级，成仓使用买卖快照而没有基于深度的滑点，并且未对部分成交进行建模。通过将 `futures paper` 替换为 `futures order` 在模拟盘和实盘之间切换。
成功的 JSON 响应包含 `"mode": "futures_paper"`。大多数表格视图标记为 `[FUTURES PAPER]` 或 `[FP]`。
**Agent 模式：**
```
kraken futures paper init --balance 10000 -o json
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market -o json
kraken futures paper sell PF_ETHUSD 5 --leverage 20 --type market -o json
kraken futures paper positions -o json
kraken futures paper status -o json
kraken futures paper reset -o json
```
**人类模式：**
```
kraken futures paper init --balance 10000 --currency USD
kraken futures paper buy PF_XBTUSD 1 --leverage 10 --type market
kraken futures paper sell PF_XBTUSD 1 --leverage 10 --type limit --price 70000
kraken futures paper positions
kraken futures paper balance
kraken futures paper fills
kraken futures paper history
kraken futures paper reset
```
| 命令 | 描述 |
|---------|-------------|
| `kraken futures paper init [--balance B] [--currency C] [--fee-rate R]` | 初始化期货模拟账户 |
| `kraken futures paper reset [--balance B] [--currency C] [--fee-rate R]` | 重置账户 (清除持仓、订单、成仓) |
| `kraken futures paper balance` | 抵押品、已用保证金、可用保证金、未实现 P&L |
| `kraken futures paper status` | 净值、起始以来 P&L、未实现 P&L、持仓/订单计数 |
| `kraken futures paper buy [--leverage L] [--type TYPE] ...` | 模拟做多 (全部 8 种订单类型) |
| `kraken futures paper sell [--leverage L] [--type TYPE] ...` | 模拟做空 (全部 8 种订单类型) |
| `kraken futures paper orders` | 未结挂单 |
| `kraken futures paper order-status ` | 查询特定订单 |
| `kraken futures paper edit-order --order-id [--size S] [--price P] [--stop-price SP]` | 修改挂单 |
| `kraken futures paper cancel --order-id ` | 取消订单 (也支持 `--cli-ord-id`) |
| `kraken futures paper cancel-all [--symbol SYM]` | 取消全部 (可选标的过滤) |
| `kraken futures paper batch-order ''` | 批量下单 |
| `kraken futures paper positions` | 包含标记价格、强平、P&L 的未平仓位 |
| `kraken futures paper fills [--since TS]` | 成仓历史 |
| `kraken futures paper history` | 已平仓位和已取消订单 |
| `kraken futures paper leverage` | 当前杠杆偏好 |
| `kraken futures paper set-leverage ` | 为每个标的设置默认杠杆 |
价格来源于公共 Kraken Futures Ticker API（无需认证）。Taker 费用为模拟得出。持仓跟踪杠杆、保证金和强平价格。资金费率根据公共资金费率 API 进行累积。现货模拟和期货模拟完全独立：重置其中一个不会影响另一个。
## 示例
### 基于实时价格的条件单
```
PRICE=$(kraken ticker BTCUSD -o json | jq -r '.[].c[0]')
kraken order buy BTCUSD 0.001 --type limit --price "$PRICE" -o json
```
### 投资组合再平衡检查
```
BTC=$(kraken balance -o json | jq -r '.BTC // "0"')
if [ "$(echo "$BTC > 0.001" | bc)" -eq 1 ]; then
kraken order sell BTCUSD 0.001 --type market -o json
fi
```
### 实时价格流
```
kraken ws ticker BTC/USD -o json | while read -r line; do
LAST=$(echo "$line" | jq -r '.data[0].last // empty')
[ -n "$LAST" ] && echo "BTC: $LAST"
done
```
### 多 ticker 流式传输
```
kraken ws ticker BTC/USD ETH/USD SOL/USD -o json
```
### 死人开关
```
kraken order cancel-after 60
```
如果 CLI 在 60 秒内未重置计时器，则取消所有结订单。
## Agent 技能
内置 50 项涵盖交易策略、市场分析和投资组合管理的 agent 技能。请参阅完整的[技能索引](skills/INDEX.md)。
## 开发
```
cargo build # dev build
cargo test # run tests
cargo clippy -- -D warnings # lint
```
## 贡献
欢迎提交 Bug 报告、功能请求和 Pull requests。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证与免责声明
MIT。请参阅 [LICENSE](LICENSE)。
本软件为实验性质。命令与真实的 Kraken 交易所进行交互，可能导致真实的金融交易。订单、提现和转账一旦处理即不可撤销。作者对财务损失不承担任何责任。完整条款请参阅 [DISCLAIMER.md](DISCLAIMER.md)。
从源码构建
需要 [Rust](https://rustup.rs/)。 ``` cargo install --git https://github.com/krakenfx/kraken-cli ``` 或者克隆并构建： ``` git clone https://github.com/krakenfx/kraken-cli.git cd kraken-cli cargo install --path . ```为什么 Agent 优先？
大多数 CLI 是为终端前的人类构建的。而这个是为基于 LLM 的 agents、MCP 工具服务器和自动化流水线构建的，它们需要在不定制 API 客户端的情况下可靠地调用 Kraken。 - **默认结构化输出。** 每个命令都支持 `-o json`。无需屏幕抓取，也无需对表格边框使用正则表达式。 - **一致的错误信封。** 错误是包含稳定 `error` 字段（`auth`、`rate_limit`、`validation`、`api`、`network`）的 JSON 对象。Agents 可以基于 `error` 路由，而无需解析人类可读的句子。 - **可预测的退出码。** 成功是 0，失败是非零。结合 stdout 上的 JSON 错误，agents 能够以编程方式检测和分类失败。 - **用于安全迭代的模拟交易。** 使用 `kraken paper`（现货）和 `kraken futures paper`（永续期货）命令以实时价格测试策略。无需 API keys，没有真实资金，与实盘交易接口一致。 - **完整的 API 接口。** 151 个命令，涵盖 Spot、Futures、xStocks、Forex、Funding、Earn、Subaccounts、WebSocket 流式传输，以及现货和期货的模拟交易。 - **内置 MCP server。** 通过 stdio 原生支持 Model Context Protocol。无需子进程包装器。 - **感知频率限制。** 无客户端节流。当 Kraken API 因频率限制拒绝请求时，CLI 会返回一个包含 `suggestion`、`retryable` 和 `docs_url` 字段的增强错误，以便 agents 能够阅读文档并调整其策略。 人类同样受益于这种设计：`--output table` 渲染整洁的表格，`kraken shell` 提供一个 REPL，而 `kraken setup` 将引导你完成配置。高级：API endpoint 覆盖
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `KRAKEN_SPOT_URL` | `https://api.kraken.com` | 现货 REST API 基础 URL | | `KRAKEN_FUTURES_URL` | `https://futures.kraken.com/derivatives/api/v3` | 期货 REST API 基础 URL | | `KRAKEN_WS_PUBLIC_URL` | `wss://ws.kraken.com/v2` | 公共 WebSocket 端点 | | `KRAKEN_WS_AUTH_URL` | `wss://ws-auth.kraken.com/v2` | 已认证的现货 WebSocket 端点 | | `KRAKEN_WS_L3_URL` | `wss://ws-l3.kraken.com/v2` | Level 3 订单簿 WebSocket 端点 | | `KRAKEN_FUTURES_WS_URL` | `wss://futures.kraken.com/ws/v1` | 期货 WebSocket 端点 | 解析顺序：CLI 标志 > 环境变量 > 默认值。仅接受 `https://` 和 `wss://` 方案。输出与错误
### JSON (`-o json`) 主要输出格式。每个命令在 stdout 上返回有效的 JSON。 ``` kraken ticker BTCUSD -o json # {"BTCUSD":{"a":["67234.10","1","1.000"],"b":["67234.00","1","1.000"],...}} ``` WebSocket 命令发出 NDJSON（每行一个 JSON 对象）用于流式传输。 ### 表格 (`-o table`) 人类可读的表格。未指定 `-o` 时的默认值。 ``` ┌──────────┬──────────┬──────────┬──────────┬────────────┐ │ Pair │ Ask │ Bid │ Last │ Volume ... │ ├──────────┼──────────┼──────────┼──────────┼────────────┤ │ BTCUSD │ 67234.10 │ 67234.00 │ 67234.10 │ 1234.56 │ └──────────┴──────────┴──────────┴──────────┴────────────┘ ``` ### 错误信封 失败时，stdout 包含一个带有稳定 `error` 类别的 JSON 信封： ``` {"error": "auth", "message": "Authentication failed: EAPI:Invalid key"} ``` 根据 `error` 进行路由，而不是根据 `message`。`message` 字段是人类可读的且不稳定。 | 类别 | 可重试 | 操作 | |----------|-------------------| | `auth` | 否 | 检查 API key 和 secret | | `rate_limit` | 是 | 错误包含针对特定等级限制的 `suggestion`，指向 Kraken 文档的 `docs_url` 以及 `retryable` 标志。阅读 `suggestion` 并调整策略。 | | `network` | 是 | 指数退避，最多重试 5 次 | | `validation` | 否 | 修复输入参数 | | `api` | 否 | 检查请求和参数 | | `config` | 否 | 检查配置文件或环境变量 | | `websocket` | 是 | 以有节制的退避和安全预算重新连接（每个流生命周期最多 12 次重新连接尝试） | | `io` | 否 | 检查文件路径和权限 | | `parse` | 否 | 记录原始响应，可能是 API 维护中 | 包含信封和退避策略的完整错误目录：[agents/error-catalog.json](agents/error-catalog.json)。 ### 详细模式 (`-v`) 请求/响应诊断信息发送到 stderr，保持 stdout 干净： ``` kraken balance -o json -v 2>/dev/null | jq . ```完整命令参考
### 市场数据（公共） | 命令 | 描述 | |---------|-------------| | `kraken status` | 系统状态 | | `kraken server-time` | 服务器时间 | | `kraken assets [--asset BTC,ETH] [--asset-class CLASS]` | 资产信息 | | `kraken pairs [--pair BTCUSD] [--asset-class CLASS]` | 可交易对 | | `kraken ticker故障排除
**macOS 阻止了二进制文件** ``` xattr -d com.apple.quarantine /usr/local/bin/kraken ``` **"EAPI:Invalid key" 或认证错误** 检查 `KRAKEN_API_KEY` 和 `KRAKEN_API_SECRET` 是否设置正确。密钥区分大小写。验证 API key 是否具有该命令所需的权限（例如 `balance` 需要 Query Funds，`order buy` 需要 Modify Orders 等）。 **频率限制错误** CLI 不会预先节流或重试受频率限制的请求。Kraken API 服务器强制执行频率限制，CLI 会立即返回错误，并附带一个包含特定等级限制的 `suggestion` 字段和指向相关 Kraken 文档的 `docs_url`。请阅读建议并调整请求频率。对于持续的高频使用，推荐使用 WebSocket 流式传输而不是 REST 轮询。 **在 MCP 客户端中 "No tools found"** 验证 `kraken` 是否在你的 PATH 中。在终端中运行 `kraken mcp -s market` 以确认服务器是否启动。检查你的客户端配置是否符合 [MCP Server](#mcp-server) 部分中的 JSON 格式。 **现货模拟交易状态错误** 运行 `kraken paper reset` 以清除并重新初始化。 **期货模拟交易状态错误** 运行 `kraken futures paper reset` 以清除并重新初始化。现货和期货的模拟状态是独立的。架构
``` src/ main.rs -- CLI entry point, clap parsing, exit codes lib.rs -- AppContext, shared dispatcher, module re-exports auth.rs -- HMAC-SHA512 signing (Spot + Futures), nonce management config.rs -- Config file I/O, credential resolution, secret wrappers client.rs -- HTTP clients with transient-error retry and enriched rate-limit errors errors.rs -- Unified error types with category-based JSON envelopes paper.rs -- Spot paper trading state engine (local simulation) futures_paper.rs -- Futures paper trading engine (leverage, margin, liquidation, funding) shell.rs -- Interactive REPL with rustyline telemetry.rs -- Agent client identification, instance tracking, user-agent commands/ -- One module per command group mod.rs -- Module re-exports helpers.rs -- Shared utilities (JSON extraction, output formatting) market.rs -- Public market data account.rs -- Private account data trade.rs -- Spot trading funding.rs -- Deposits, withdrawals, wallet transfers earn.rs -- Staking/earn subaccount.rs -- Subaccount management futures.rs -- Futures trading and market data futures_paper.rs -- Futures paper trading commands futures_ws.rs -- Futures WebSocket v1 streaming websocket.rs -- Spot WebSocket v2 streaming paper.rs -- Spot paper trading commands auth.rs -- Credential management commands utility.rs -- Setup wizard mcp/ -- Built-in MCP server mod.rs -- Service group parsing, streaming exclusion filters server.rs -- ServerHandler impl, tool dispatch, env-based URL resolution registry.rs -- Tool registry built from clap tree + tool-catalog.json schema.rs -- JSON Schema generation from clap argument metadata output/ -- Rendering layer mod.rs -- Format dispatch, CommandOutput type table.rs -- Human-readable table output json.rs -- JSON output and NDJSON streaming ```标签：AI原生, API集成, Crypto, FinTech, Kraken, LLM集成, MCP服务器, Rust, 人工智能, 加密货币交易, 单文件二进制, 可观测性, 可视化界面, 命令行界面, 外汇交易, 开源, 模拟交易, 用户模式Hook绕过, 算法交易, 网络流量审计, 股票交易, 自动化交易, 通知系统, 量化交易, 金融科技, 金融衍生品