Kraken Playground

kraken-playground

A session ties a market recorder and the workspace's paper account to one window. Live prices stream in and get recorded as the session's tape, paper orders fill against those prices on the shared account journal, and every decision is logged, so the window can be replayed and analyzed later. No real order is ever placed inside a paper workspace.

Use this skill for:

• running a paper-trading hypothesis on live prices with no real money
• recording ticker, trade, and book data alongside paper fills and decision reasons
• driving an agent hypothesis over a window at a fixed cadence
• replaying a session and computing P&L after the fact

The One-Command Demo

kraken playground is the fastest way in: it creates (or reuses, never re-funding) a paper workspace named playground with 10,000 USD, prints how to watch it, and starts a recorded, self-stopping demo session:

kraken playground --symbols BTC/USD --for 1h 2>/dev/null &
export KRAKEN_WORKSPACE=playground

Everything it makes is a plain workspace plus a session — the commands below drive it like any other scope.

What a Session Is

A session is a recorded window over the active scope's account journal. One session id (s1, s2, …) binds three things: the recorder (live market data to sessions/s<n>/tape.*), the window markers on the account journal (which trades belong to the session), and the session's decision log (the "why" behind each action). There is no daemon and no shared memory between rounds. State lives on disk, and each round reads what it needs.

The CLI has no scheduler and runs no strategy. It records, fills paper orders, and logs. The agent decides, and something external holds the pace (see Pacing).

Start a Session

Work inside a paper workspace (create one once with kraken workspace create <name> --capital 10000 --mode paper), then:

export KRAKEN_WORKSPACE=<name>

kraken session start \
  --symbols BTC/USD --channels ticker,trade --to duckdb,jsonl \
  --label my-hypothesis-r1 \
  -o json 2>/dev/null &

The session_started JSON line on stdout carries the session id ("session":"s<n>"). Print it to the user as soon as the session starts, and again in the final report. It is the handle for everything after: kraken session show --session s<n>, resuming a /loop, and locating the artifacts under sessions/s<n>/.

• --symbols: instruments to record and trade against
• --channels: which feeds to record (e.g., ticker,trade, add book for depth)
• --to: recording sinks (duckdb for query, jsonl for raw replay)
• --label: a human handle, usable anywhere a --session ref is
• --strategy / --strategy-params: name and JSON knobs of the driver, recorded in session.json so two sessions compare knob-for-knob
• --for: auto-stop after a window (e.g. 1h) — the session closes itself cleanly
• --from tape:<name> --speed 10: replay a recorded tape instead of the live market

Paper Trades

Buy or sell against recorded prices — the order verbs are mode-routed, so inside a paper workspace they fill on the paper account. Always pass a reason; it lands in the active session's decision log:

kraken order buy BTC/USD <volume> --type market --reason "<why>" -o json 2>/dev/null
kraken order sell BTC/USD <volume> --type market --reason "<why>" -o json 2>/dev/null

Log a non-trade decision (a skip, a gate, an alert) so the log records rounds where nothing traded:

kraken session note --kind skip --symbol BTC/USD --reason "<why>" -o json 2>/dev/null

Recording

Data lands under the session directory of the active scope:

# Read the decision log (evidence) and the typed state cell (the loop's
# cursor: round, legs_done, zone, last_action_at) through the CLI —
# no layout knowledge needed:
kraken session decisions --session s<n> -o json
kraken session state get --session s<n> -o json

• session.json: the session's contract — window, opening equity anchor, strategy, experiment
• decisions.jsonl: one line per decision (kind, symbol, reason, timestamp, order id)
• tape.duckdb / tape.jsonl: the raw tape for replay and P&L

Pacing

Pacing is external to the CLI. Two mechanisms, one per hypothesis shape:

• Time-gated: /loop owns the schedule. Set its interval to the decision spacing and it fires one round per interval.
• Event-gated: a WebSocket stream's event rate owns the schedule. The loop acts on qualifying events (see kraken-ws-streaming).

For time-gated runs, the interval is a floor. A round may start late (the scheduler adds jitter), never early. Do not add a second pacing gate inside the round; /loop already enforces spacing.

The scheduler floor is 60 seconds. /loop, cron, and ScheduleWakeup all clamp to a one-minute minimum, so interval_s must be >= 60 and a sub-minute cadence is impossible. If the user asks for "every 30 seconds", clamp to 60s and say so — never set a sub-minute interval_s, and never let the report claim a cadence the harness cannot run.