connect-kraken git:20260709.5f5b25cA

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

---
name: connect-kraken
description: >-
  Use when the user wants to connect their Kraken account to trade through the
  agent WITHOUT creating or handling an API key — "connect Kraken with OAuth",
  "log in with Kraken", "connect Kraken without a key", "I don't want to manage
  a Kraken key". This is the KEYLESS (OAuth) mode: the user consents once in a
  browser and the Mangrove platform holds the grant and trades on their behalf.
  It is the sibling of the BYOK `setup-kraken` skill — if the user is willing to
  create and hold their own key locally, use setup-kraken instead; if they want
  Mangrove to manage access, use this.
---

# Connect Kraken (keyless, OAuth)

The agent's job here: connect the user's **Kraken account** for trading through
the agent **without the user ever creating, copying, or holding an API key**.

## The model — say this up front

- **No key, ever.** The user consents once on Kraken's own site (a browser
  OAuth screen). Mangrove's platform holds the resulting grant, KMS-encrypted,
  and mints a short-lived, scoped key **per order** — nothing long-lived exists
  anywhere, and no credential is ever pasted in chat or stored on this machine.
- **You choose what you authorize.** At connect time you pick a mode:
  - **view** — read-only: balances and history. (default)
  - **execute** — view **plus** order placement/cancellation.
  The choice drives what Kraken's consent screen grants; Mangrove can never do
  more than you approved. Deposits/withdrawals are never requested.
- **Revocable two ways.** Disconnect in Mangrove, or revoke the app under
  Kraken's Connected Apps settings.
- **Contrast with BYOK (`setup-kraken`):** that mode keeps your own key on your
  machine and talks to Kraken directly, no Mangrove account needed. This mode
  needs a Mangrove account but never asks you to touch a key.

## Step 1 — Start the connect

Call `POST /api/v1/agent/cex/oauth/connect-start` with `{"mode": "view"}` or
`{"mode": "execute"}`. It returns `{authorize_url, state}`.

Show the user the `authorize_url` and tell them: **open this in your browser,
sign in to Kraken, and approve.** If they chose `execute`, the consent screen
will list trading permissions; if `view`, it won't. That screen is the consent
— read it before approving.

## Step 2 — Wait for the connection

Poll `GET /api/v1/agent/cex/oauth/status` until `connected` is true. Confirm the
returned `connection.mode` matches what they intended (`view` vs `execute`).

## Step 3 — Use it

- `GET /api/v1/agent/cex/oauth/balances` — balances (works in either mode).
- `POST /api/v1/agent/cex/oauth/orders` — place or dry-run an order. Always run
  once with `"validate_only": true` first and show the user the venue's own
  description of what would execute; place the live order only on their explicit
  go-ahead. An `execute`-mode connection is required — a `view` connection is
  refused by the platform.

## Guardrails — never

- Never ask the user for a Kraken API key or secret in this flow. If they want
  to provide one, that's the **other** skill (`setup-kraken`), not this one.
- Never place a live order without a preceding validate-only preview the user
  approved.
- Never claim a trade is attributed/placed without echoing the returned
  `tx_ids` and venue description.

## Where this fits

`setup-kraken` (BYOK) and `connect-kraken` (OAuth) are siblings. Pick by the
user's preference: hold-your-own-key-locally vs let-Mangrove-manage-access.
Everything downstream (validate-then-place, telemetry) is the same.