recipe-playground-rebalance

name	recipe-playground-rebalance
version	1.1.0
description	Example driver: drive a portfolio-rebalance hypothesis into a recorded session.
metadata	{"openclaw":{"category":"recipe","domain":"sessions"},"requires":{"bins":["kraken"],"skills":["kraken-playground","kraken-rebalancing"]}}

Playground: Rebalance

PREREQUISITE: Load the following skills to execute this recipe: kraken-playground, kraken-rebalancing

This recipe is an example, not a boundary. Adapt its steps to your hypothesis, or write your own driver — see kraken-playground → Driving Your Own Hypothesis.

Test a target-allocation rebalancing hypothesis on live prices with no real money, recording the market data, paper trades, and the "why" behind each adjustment into one session for later replay and P&L analysis.

Important

Paper results may overstate live performance: fees and slippage are simulated and there are no partial fills (see kraken-paper-strategy). This recipe records a session inside a paper workspace; it never places a live order.

Every number that gates a trade or a skip (targets, threshold_usd, drift_pct) belongs in --strategy-params — it's what makes two sessions comparable knob-for-knob. A recurring run adds rounds and interval_s (see step 8). The values in the step-2 example are placeholders: a number the operator names (band, threshold, cadence) replaces the example verbatim — params that don't match the mandate record a hypothesis nobody asked to test. Over a long window this recipe is interventional — one visit per interval_s, paced by the harness (see kraken-playground → Running over a Window).

Quick Start

Rebalance a portfolio toward target allocations:

Hold a portfolio 50% BTC, 35% ETH, 15% SOL over 24 hours. 
Rebalance when any asset drifts more than 5% from target AND the delta exceeds $50. 
Check every 2 hours. Report final weights and P&L.

Start the Session

Work inside a paper workspace (create one once: kraken workspace create rebalance --capital 10000 --mode paper), then:

export KRAKEN_WORKSPACE=rebalance

kraken session start \
  --symbols BTC/USD,ETH/USD,SOL/USD --channels ticker --to duckdb,jsonl \
  --label rebalance-$(date +%Y%m%d-%H%M%S) \
  --strategy recipe-playground-rebalance \
  --strategy-params '{"targets":{"BTCUSD":0.50,"ETHUSD":0.35,"SOLUSD":0.15},"interval_s":7200,"drift_pct":5,"threshold_usd":50}' \
  -o json 2>/dev/null &

# The session_started stdout line carries the id: {"type":"session_started","session":"s<n>",...}

Print the session id to the user right after starting, and again in the final report — it is the handle for resuming the /loop, checking kraken session show, and locating the artifacts.

Schedule the Rounds

/loop owns the pacing. Set its interval to interval_s and it fires each round on cadence (late under jitter, never early). Parse the interval from the user's request: "every 2 hours" to 2h, "every 4 hours" to 4h, "every day" to 24h.

The scheduler floor is 60 seconds (/loop, cron, and ScheduleWakeup all clamp to a one-minute minimum). interval_s must be >= 60. If the user asks for a sub-minute cadence, clamp to 60 and tell them — never set a sub-minute interval_s and never let the report claim a cadence the harness cannot run.

/loop 2h "Run one rebalance round for session s<n> in workspace rebalance per recipe-playground-rebalance"

Do not re-add an elapsed-time gate inside the round. /loop already enforces the spacing. The round cursor lives in the session's typed state cell — a rebalance round writes one decision per leg, so the decision log cannot count rounds; the cursor can. Reasons stay narrative (keep "round N" in them for the story; nothing parses it). Stop once the cursor reaches rounds:

LAST_ROUND=$(kraken session state get --session s<n> -o json 2>/dev/null \
  | jq '.cursor.round // 0')
if [ "${LAST_ROUND:-0}" -ge "$ROUNDS" ]; then
  kraken session stop -o json 2>/dev/null
  exit 0
fi
ROUND=$((LAST_ROUND + 1))

Between legs, record progress so a crashed firing resumes at the first missing leg instead of re-trading executed ones; completing the round writes only the round (the replace drops legs_done automatically):

kraken session state set --round "$LAST_ROUND" --legs-done "BTC/USD" \
  --note "round $ROUND: leg 1 of 3 done" -o json 2>/dev/null   # after each leg
kraken session state set --round "$ROUND" -o json 2>/dev/null   # round complete

On a fresh firing, state get's legs_done names any half-done round — but a crash can land between a leg executing and its legs_done write, so never trust the cursor alone before re-trading: cross-check the evidence (kraken session decisions, reasons mentioning the in-flight round) and skip any leg that already filled. The cursor is the fast path; the decision log is the truth. The first firing is the seed round: every asset is underweight, so it allocates the whole portfolio toward the targets.

Each Round

On each firing: READ, THINK, ACT.

READ: a fresh balance and each symbol's price. Read the balance every round — never carry a snapshot across rounds or across trades within a round; each fill mutates cash and holdings.

kraken paper balance -o json 2>/dev/null
kraken ticker BTCUSD -o json 2>/dev/null | jq -r '.[] | .last_price'   # repeat per symbol

kraken paper balance returns {"balances":{"USD":{"total","reserved","available"},...}}. Cash is .balances.USD.available; a holding is .balances.<ASSET>.total (0 if the key is absent). Price is the ticker's last-trade close (.[] | .last_price).

Fail loud before any leg trades: validate the cash figure and EVERY price before computing deltas — a rebalance acts on several legs, so one silently failed read sizes every order from garbage. On an empty read, note an alert and end the firing (the claimed round stays claimed; the next firing retries):

if [ -z "$CASH" ] || [ -z "$PRICE_BTC" ]; then
  kraken session note --kind alert \
    --reason "round $ROUND aborted: READ failed (cash='$CASH' btc='$PRICE_BTC')" -o json 2>/dev/null
  exit 0
fi

THINK: value the portfolio, then decide each leg.

• total_value = cash + Σ(holdings × price)
• Per symbol: value = holdings × price, current_pct = value / total_value × 100, target_pct = target × 100, drift = current_pct − target_pct, delta_usd = target_value − value where target_value = total_value × target.
• A leg needs action only when |drift| > drift_pct AND |delta_usd| > threshold_usd. Otherwise leave it.

ACT: sells before buys. Execute every overweight leg (delta_usd < 0) first so its proceeds land back in cash, then execute the underweight legs. Size each buy against a fee/slippage reserve so the last leg never rejects: keep the buy cost at or below available_cash / (1 + fee_rate + slippage_rate) (defaults 0.0026 fee, 0.0 slippage — read them from paper status if unsure). Between legs, re-read the balance rather than assuming the pre-trade cash, and skip or shrink a buy the remaining cash can no longer fund.

# Overweight — sell the excess first
kraken order sell BTC/USD <volume> --type market \
  --reason "rebalance round N: BTC/USD weight <current_pct>% above target <target_pct>%; selling <volume>" \
  -o json 2>/dev/null

# Underweight — buy toward target, capped by fee-reserved cash
kraken order buy SOL/USD <volume> --type market \
  --reason "rebalance round N: SOL/USD weight <current_pct>% below target <target_pct>%; buying <volume>" \
  -o json 2>/dev/null

If no leg breaches both thresholds, note a single skip:

kraken session note --kind skip --symbol BTC/USD \
  --reason "skip round N: all weights within <drift_pct>%/$<threshold_usd> band" \
  -o json 2>/dev/null

Always pass the numeric reason so the decision log carries the "why" behind every round.

Stop and Review

kraken session stop -o json 2>/dev/null
kraken session show -o json 2>/dev/null | jq '.summary'

kraken session decisions --session s<n> -o json 2>/dev/null \
  | jq -c '.decisions[] | {kind, symbol, reason, timestamp}'

Report:

• Final weights vs targets (50/35/15)
• Number of rebalance trades vs skips
• Cumulative turnover (fees paid)
• P&L vs a buy-and-hold baseline
• Did the drift_pct/threshold_usd band hold the portfolio?

Hard Rules

• This recipe records a session inside a paper workspace. It never places a live order.
• /loop drives the pace and the agent runs each round; the CLI has no scheduler and runs no strategy. The scheduler floor is 60s — no sub-minute cadence.
• Read a fresh balance every round and after each fill. Never size a trade off a stale snapshot — the seed round alone issues three buys, and a fixed pre-trade cash figure overspends once fees are charged.
• Sells before buys, and reserve fees on every buy, so a multi-leg round cannot reject its last order after earlier fills were already recorded.
• Keep every gating number (targets, drift_pct, threshold_usd, interval_s) in --strategy-params and the arithmetic in jq/bc, so a rerun on the same tape reproduces the decisions.
• The session directory (session.json, decisions.jsonl, and the tape sinks) is owned by the CLI recorder. The agent only reads it, and only for the stop-time summary. Never write, edit, or append inside it — every trade and skip goes through kraken order buy / kraken session note, so the recorder stays the single writer.
• If you hit a mismatch between what you are trying to do and the CLI's interface or responses — including a mismatch between this skill and the installed CLI version's contract — feel free to submit feedback with kraken feedback.