setup-kraken git:20260712.5e2ec38A

Immutable. This exact content never changes and is served at /api/v1/blob/fed6a986e6f972e6.

---
name: setup-kraken
description: >-
  Use when the user wants to connect their own Kraken account to trade on it
  through the agent — "set up Kraken", "connect my Kraken", "trade on Kraken",
  "add/use my Kraken API key", "I want to trade on a CEX", or when moving toward
  live centralized-exchange trading on Kraken. Guides the user to create a
  LEAST-PRIVILEGE Kraken API key, store it securely without ever pasting it in
  chat, and explains the local bring-your-own-key (BYOK) model: the client-side
  SDK connects to Kraken DIRECTLY with the user's key — the key stays on the
  user's machine and never reaches a Mangrove server. The keyless OAuth path
  (Mangrove holds the grant and submits on the user's behalf, server-side) is
  the sibling `connect-kraken` skill, NOT this one — offer it when the user
  doesn't want to create or manage an API key.
---

# Setup Kraken (local BYOK)

The agent's job in this skill: walk the user through connecting **their own
Kraken account** so they can trade it through the agent, using **their own
Kraken API key kept on their machine**. This is the **local BYOK** mode.

## The model — say this up front

- **Your key, your machine, direct to Kraken.** In this mode the client-side
  Mangrove SDK connects to **api.kraken.com directly** with the user's API key.
  The key **never goes to a Mangrove server** and is never sent in chat.
- **Kraken is one venue in a multi-venue aggregator.** The Mangrove Markets API
  spans DEX venues (1inch / XPMarket / Jupiter) and CEX (Kraken). This skill
  covers the Kraken CEX venue via the user's own key.
- **There is a second mode (not this skill): OAuth2.** Once enabled, the user
  authorizes Mangrove and the **server** submits orders on their behalf via a
  per-user OAuth2 grant. That is exchange-venue-specific and server-side. If the
  user asks for "log in with Kraken / don't want to manage a key," that's the
  OAuth2 path — tell them it's coming and stop; do not improvise it here.

## Security primer — give this unprompted (mirror the wallet Stage-4.5 primer)

1. **Never paste your API key or secret into this chat.** The agent must never
   see it. `.claude/hooks/block-wallet-secrets.sh` guards pasted secrets — don't
   work around it. The key is entered out-of-band (see Step 3).
2. **Least privilege.** Enable only the permissions needed to trade; leave
   **Withdraw Funds OFF**. A trading key should never be able to move funds off
   the exchange.
3. **Real funds.** Kraken spot has **no testnet** — orders execute against real
   balances. Start with a tiny amount and use **validate-only** (dry-run) orders
   before any real fill.
4. **Scope it down.** Set an **IP allowlist** on the key and a **key expiry** if
   the user can; consider a sub-account dedicated to agent trading.

## Step 1 — Create the API key on Kraken

Direct the user (in their browser, signed in to Kraken):

> Kraken → **Settings → API → Create API key**.

**Enable (trading, least privilege):**
- Query Funds
- Query Open Orders & Trades
- Query Closed Orders & Trades
- Create & Modify Orders
- Cancel/Close Orders

**Leave OFF:**
- **Withdraw Funds** (critical — never enable for an agent key)
- Account Management / Account Transfers
- Export Data / WebSockets (unless a later feature needs them)

**Optional hardening:** IP allowlist (the machine running the agent), key
expiry, nonce window. Have the user copy the **API Key** and **Private Key**
(secret) — Kraken shows the secret only once.

## Step 2 — Confirm scope before storing

Read back what they enabled and confirm **Withdraw is OFF**. If withdrawal is
enabled, tell them to delete the key and recreate it without it — do not proceed
with a withdrawal-capable key.

## Step 3 — Store the key securely (never in chat)

The key is stored **encrypted at rest on the user's machine** (Fernet, same
SecretVault model as wallet secrets) and entered out-of-band in their terminal —
**not** pasted into this chat. Follow the same pattern as wallet import:

- The user runs the Kraken-key stash command in a terminal (the agent never sees
  the plaintext); the agent receives only an opaque, TTL-bound vault reference.

> **Status / prerequisite (be honest with the user):** the local-BYOK execution
> path is still being built — specifically (a) a Kraken-key stash command
> mirroring `scripts/stash-secret.sh` (today that script is wallet-key only,
> posting to `/wallet/stash-secret`), (b) the client-side `KrakenClient` in the
> `mangrovemarkets` SDK, and (c) the agent `cex_*` trade tools that use it. Until
> those land, complete Steps 1–2 (create + scope the key) and tell the user the
> key-storage + trading steps will be available shortly; do **not** ask them to
> paste the key anywhere as a stopgap.

## Step 4 — Verify (once the execution path exists)

Confirm with a **read-only** call first — fetch Kraken balances — to prove the
key works and is correctly scoped, before any order. Then place a single
**validate-only** order to confirm the order path without executing a fill.

## Guardrails — never

- Never ask the user to paste the API key/secret in chat; never echo or store it
  in plaintext, logs, config files, or the DB.
- Never proceed with a key that has **Withdraw Funds** enabled.
- Never place a live order without an explicit user go; default to validate-only
  for the first order and start with a small size.
- Don't conflate this with OAuth2 — if the user wants Mangrove to trade on their
  behalf without holding a key, that's the server-side OAuth2 mode (separate).

## Where this fits

Analogous to **Stage 4.5 (Connect wallet)** in `trading-bot-workflow.md`, but for
a CEX venue: it's the "connect your exchange to go live" step. Paper/backtest
flows (Stages 0–4) need no Kraken key.