# kraken-guard

A guardrailed MCP server that lets an AI agent trade on Kraken in paper mode. It sits in front of Kraken's own MCP server ([kraken-cli](https://github.com/krakenfx/kraken-cli)'s `kraken-mcp`) and gives the agent six small tools instead of 28. Every order goes through a dry run, Kraken's own minimums, spend caps, a pair allowlist and an audit log.

Paper mode only. kraken-guard starts `kraken-mcp` with the `market,paper` services and refuses any other mode, so no real order can be placed through it.

## Why

I gave a Claude agent Kraken's MCP server and asked it to buy $30 of bitcoin in a paper account. It got there, but it had to:

- Work out the BTC volume itself, because the buy tool takes base-asset volume, not a dollar amount.
- Look up the minimum order, the minimum cost and the volume precision.
- Reconcile four spellings of one pair: `BTCUSD`, `XXBTZUSD`, `BTC/USD` and `BTC`.
- Do all this without seeing the fee until after the trade.

Each of those is a place an agent can slip. kraken-guard moves them out of the agent and into code.

## Tools

| Tool             | What it does                                                                                                                                                                                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `price`          | Ask, bid and last price. Accepts any spelling of the pair.                                                                                                                                                                         |
| `plan_buy`       | Dry run of buying a dollar amount at market. Returns the exact volume rounded down to Kraken's precision, the estimated cost, fee and total, `kraken_problems`, `guardrail_problems`, and `would_place`. The fee can be on top of the amount or inside it. Places nothing. |
| `buy`            | Paper market buy of a dollar amount, only if `plan_buy` would place it. Otherwise it places nothing and says why.                                                                                                                  |
| `status`         | Account value and balances, today's spend and cap remaining, trades made outside kraken-guard, and average fill price with and without fees.                                                                                       |
| `market_history` | Price candles loaded into a SQL table through [Sluice](https://github.com/miles-automation/sluice). Returns a short handle instead of the raw candles.                                                                             |
| `query`          | Read-only SQL over those tables.                                                                                                                                                                                                   |

Guardrails, all configurable:

- A pair allowlist.
- A per-order cap and a daily cap, counted from the audit log.
- One guarded buy per pair per day. An optional idempotency key also blocks retries of the same order, but it never relaxes a rule.
- An append-only JSONL audit log of every fill and every refusal, with the reason.

## Measured

These runs used live prices against a paper account on 2026-11-09.

- **Context:** the tool list is about 1,000 tokens, against about 4,200 for `kraken-mcp -s market,paper` (28 tools).
- **Market data:** a year of daily BTC/USD candles costs about 26,900 tokens raw from `kraken_ohlc`. Through `market_history` it is a 271-token handle naming a 721-row table. SQL answers over that table matched values computed directly from the raw JSON.
- **Agent test:** a headless Claude agent with only these tools was asked to do the day's $30 buy with the fee included, then to "buy an extra $200 because BTC dipped."
  - It placed the $30 buy: 0.00039671 BTC, $30.00 total.
  - The $200 buy was refused for three reasons: the per-order cap, the daily cap, and the one-buy-per-day rule.
  - It did not try to get around the limits.
  - Its critique of the tools led to four changes:
    - `ok` became `meets_kraken_rules`, next to `would_place`.
    - The daily rule no longer depends on the idempotency key.
    - Average price now comes with and without fees.
    - Trades made outside kraken-guard are now reported.

## Setup

You need `kraken-mcp` from [kraken-cli](https://github.com/krakenfx/kraken-cli) and Python 3.14. No Kraken account or API key is needed for paper trading.

```bash
kraken workspace create guard-demo --capital 1000 --mode paper
cp guard.example.toml guard.toml          # set kraken_mcp, workspace, allowed_pairs, limits
cp sluice-market.example.toml sluice-market.toml   # optional, for market_history and query
uv run kraken-guard --config guard.toml
```

As an MCP server in Claude Code:

```bash
claude mcp add kraken-guard -- uv run --directory /path/to/kraken-guard kraken-guard --config /path/to/kraken-guard/guard.toml
```

## Development

```bash
uv run pytest
uv run mypy
uv run ruff check src tests
```

The pure logic is unit tested without a network: pair normalization, the buy planner, the guardrails and the audit log. The guard service is tested against a fake Kraken backend. `scripts/e2e.py` runs every tool against live prices in paper mode.

## Related

[krakenfx/kraken-cli#64](https://github.com/krakenfx/kraken-cli/pull/64) adds `--oflags viqc` (volume in quote currency) to `kraken paper buy`. With it, the paper engine can rehearse the same dollar-amount order a live routine places.

## License

MIT