kraken-pro

管理 Kraken 交易账户——投资组合、市场数据、交易、收益/质押、账本导出。通过 python-kraken-sdk 的 REST API。当用户想要检查加密货币投资组合、获取价格、下/取消订单、管理质押、导出税收分类账、存款/提取资金或以任何方式与 Kraken 交互时使用。

# Kraken Skill

Manage your Kraken exchange account via CLI.

## Setup

```bash
pip3 install -r requirements.txt
```

Set credentials via environment variables or OpenClaw config (`skills.entries.kraken-pro.env`).

Get API key: https://www.kraken.com/u/security/api

## Commands

Run: `python3 kraken_cli.py <command> [options]`

All commands accept `--json` for raw JSON output.

### Portfolio (auth required)

| Command | Description |
|---------|-------------|
| summary | Portfolio overview (handles flex vs bonded earn correctly) |
| net-worth | Single net worth number |
| holdings | Asset breakdown with USD values |
| balance | Raw asset quantities |

### Market Data (no auth)

| Command | Description |
|---------|-------------|
| ticker --pair XBTUSD | Price and 24h stats |
| pairs | Trading pairs |
| assets | Asset list |

### Order History (auth required)

| Command | Description |
|---------|-------------|
| open-orders | Active orders |
| closed-orders [--limit N] | Completed orders |
| trades [--limit N] [--csv] | Trade execution history (CSV for export) |

### Ledger (auth required)

```
ledger [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--asset BTC] [--type trade|deposit|withdrawal|staking] [--csv] [--limit N]
```

Auto-paginates (Kraken returns max 50/request). `--csv` dumps raw Kraken data.

### Trading (auth required)

All trading commands require `--confirm`. Use `--validate` for dry-run.

| Command | Description |
|---------|-------------|
| buy --pair XBTUSD --type market\|limit --amount N [--price P] --confirm | Place buy order |
| sell --pair XBTUSD --type market\|limit --amount N [--price P] --confirm | Place sell order |
| cancel-order --id OXXXXX --confirm | Cancel specific order |
| cancel-all --confirm | Cancel all open orders |

**Always confirm with the user before placing real orders. Use `--validate` first.**

### Earn/Staking (auth required)

| Command | Description |
|---------|-------------|
| earn-positions | Current staking allocations |
| earn-strategies | Available yield programs |
| earn-status | Pending requests |
| earn-allocate --strategy-id ID --amount N --confirm | Stake funds |
| earn-deallocate --strategy-id ID --amount N --confirm | Unstake funds |

### Funding (auth required)

| Command | Description |
|---------|-------------|
| deposit-methods --asset BTC | Deposit methods for an asset |
| deposit-address --asset BTC | Get deposit address |
| withdraw --asset BTC --key NAME --amount N --confirm | Withdraw to saved address |
| withdraw-status | Recent withdrawal status |

**Withdrawal notes:**
- Addresses must be pre-configured in Kraken's web UI (can't add via API)
- Can't list saved address names via API — ask the user for the key name
- Addresses are per-asset: a SOL address won't work for USDC withdrawals even if it's the same wallet. Each asset needs its own entry.
- `--key` is the saved address name in Kraken, not the actual address

## Example Usage

| User Request | Command |
|---|---|
| What's my portfolio? | summary |
| BTC price? | ticker --pair XBTUSD |
| Export 2025 ledger for taxes | ledger --start 2025-01-01 --end 2025-12-31 --csv |
| Export trade history | trades --csv |
| Buy 0.1 BTC at market | buy --pair XBTUSD --type market --amount 0.1 --confirm |
| Show staking positions | earn-positions |

## Kraken Pair Naming

Kraken uses non-standard names: XBT (not BTC), XETH (not ETH), Z-prefix for fiat (ZUSD, ZCAD). When unsure of a pair name, run `pairs --json` and grep for the asset.

## Portfolio Logic

Kraken has two earn types:
- **Auto Earn (flex):** in main wallet, included in trade balance equity
- **Bonded staking:** separate earn wallet, NOT in trade balance

`summary` calculates: **Total = Trade Balance Equity + Bonded Staking Only**

## API Permissions

| Feature | Permission |
|---------|-----------|
| Balances, portfolio, ledger | Query Funds |
| Orders, trades (view) | Query Open/Closed Orders & Trades |
| Place/cancel orders | Create & Modify Orders |
| Earn allocate/deallocate | Withdraw Funds |
| Withdrawals | Withdraw Funds |
| Market data | None |

---

## 中文说明

# Kraken Skill

通过 CLI 管理你的 Kraken 交易所账户。

## Setup

```bash
pip3 install -r requirements.txt
```

通过环境变量或 OpenClaw 配置（`skills.entries.kraken-pro.env`）设置凭据。

获取 API 密钥：https://www.kraken.com/u/security/api

## Commands

运行：`python3 kraken_cli.py <command> [options]`

所有命令均接受 `--json` 以输出原始 JSON。

### 投资组合（需要认证）

| Command | Description |
|---------|-------------|
| summary | 投资组合概览（正确处理 flex 与 bonded earn） |
| net-worth | 单个净值数字 |
| holdings | 按资产细分及其美元价值 |
| balance | 原始资产数量 |

### 市场数据（无需认证）

| Command | Description |
|---------|-------------|
| ticker --pair XBTUSD | 价格及 24 小时统计 |
| pairs | 交易对 |
| assets | 资产列表 |

### 订单历史（需要认证）

| Command | Description |
|---------|-------------|
| open-orders | 活跃订单 |
| closed-orders [--limit N] | 已完成订单 |
| trades [--limit N] [--csv] | 成交执行历史（CSV 用于导出） |

### 账本（需要认证）

```
ledger [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--asset BTC] [--type trade|deposit|withdrawal|staking] [--csv] [--limit N]
```

自动分页（Kraken 每次请求最多返回 50 条）。`--csv` 导出原始 Kraken 数据。

### 交易（需要认证）

所有交易命令均需 `--confirm`。使用 `--validate` 进行试运行。

| Command | Description |
|---------|-------------|
| buy --pair XBTUSD --type market\|limit --amount N [--price P] --confirm | 下买单 |
| sell --pair XBTUSD --type market\|limit --amount N [--price P] --confirm | 下卖单 |
| cancel-order --id OXXXXX --confirm | 取消指定订单 |
| cancel-all --confirm | 取消所有未成交订单 |

**下真实订单前务必与用户确认。请先使用 `--validate`。**

### 收益/质押（需要认证）

| Command | Description |
|---------|-------------|
| earn-positions | 当前质押分配 |
| earn-strategies | 可用收益计划 |
| earn-status | 待处理请求 |
| earn-allocate --strategy-id ID --amount N --confirm | 质押资金 |
| earn-deallocate --strategy-id ID --amount N --confirm | 解除质押资金 |

### 资金（需要认证）

| Command | Description |
|---------|-------------|
| deposit-methods --asset BTC | 某资产的存款方式 |
| deposit-address --asset BTC | 获取存款地址 |
| withdraw --asset BTC --key NAME --amount N --confirm | 提现至已保存的地址 |
| withdraw-status | 近期提现状态 |

**提现注意事项：**
- 地址必须事先在 Kraken 的网页界面中配置（无法通过 API 添加）
- 无法通过 API 列出已保存的地址名称——请向用户询问 key 名称
- 地址按资产区分：即使是同一钱包，SOL 地址也无法用于 USDC 提现。每种资产都需要各自的条目。
- `--key` 是 Kraken 中已保存的地址名称，而非实际地址

## 使用示例

| User Request | Command |
|---|---|
| 我的投资组合如何？ | summary |
| BTC 价格？ | ticker --pair XBTUSD |
| 导出 2025 年账本用于报税 | ledger --start 2025-01-01 --end 2025-12-31 --csv |
| 导出成交历史 | trades --csv |
| 以市价买入 0.1 BTC | buy --pair XBTUSD --type market --amount 0.1 --confirm |
| 显示质押持仓 | earn-positions |

## Kraken 交易对命名

Kraken 使用非标准名称：XBT（而非 BTC）、XETH（而非 ETH）、法币加 Z 前缀（ZUSD、ZCAD）。当不确定交易对名称时，运行 `pairs --json` 并 grep 该资产。

## 投资组合逻辑

Kraken 有两种收益类型：
- **Auto Earn (flex)：** 位于主钱包中，计入交易余额权益
- **Bonded staking：** 独立的收益钱包，**不**计入交易余额

`summary` 计算方式：**总额 = 交易余额权益 + 仅 Bonded Staking**

## API 权限

| Feature | Permission |
|---------|-----------|
| 余额、投资组合、账本 | Query Funds |
| 订单、成交（查看） | Query Open/Closed Orders & Trades |
| 下单/取消订单 | Create & Modify Orders |
| 收益分配/解除分配 | Withdraw Funds |
| 提现 | Withdraw Funds |
| 市场数据 | None |