git:20260626.d448324 to git:20260712.5e2ec38

---

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

---

# 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.