Agent Skills › krakenfx/kraken-cli › recipe-playground-rebalance

recipe-playground-rebalance

GitHub

该技能用于在模拟环境中测试投资组合再平衡假设,记录市场数据与交易决策以进行回放和盈亏分析。通过参数化目标权重、漂移阈值等,实现可复现的自动化策略验证,确保不执行真实资金交易。

skills/recipe-playground-rebalance/SKILL.md krakenfx/kraken-cli

触发场景

用户需要测试投资组合再平衡策略 用户希望在无风险环境下模拟交易并分析结果

安装

npx skills add krakenfx/kraken-cli --skill recipe-playground-rebalance -g -y
更多选项

不安装直接使用

npx skills use krakenfx/kraken-cli@recipe-playground-rebalance

指定 Agent (Claude Code)

npx skills add krakenfx/kraken-cli --skill recipe-playground-rebalance -a claude-code -g -y

安装 repo 全部 skill

npx skills add krakenfx/kraken-cli --all -g -y

预览 repo 内 skill

npx skills add krakenfx/kraken-cli --list

SKILL.md

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

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. With that workspace named on every session, balance and order call and checked each round (see Hard Rules), 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 Schedule the Rounds). The values in the Start the Session 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). Every session, balance and order command below names it with --workspace rebalance. An exported KRAKEN_WORKSPACE does not reach a later shell, such as a /loop fire, and without a workspace kraken order buy and kraken order sell trade the real account.

kraken --workspace rebalance 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},"rounds":12,"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:

ROUNDS=12   # the `rounds` you set in --strategy-params

# The trades below are simulated only while rebalance is a paper workspace.
[ "$(kraken workspace show rebalance -o json 2>/dev/null | jq -r '.mode')" = paper ] \
  || { echo "workspace rebalance is missing or not paper; no round runs" >&2; exit 1; }

# A failed read must end the firing rather than restart at round 1.
STATE=$(kraken --workspace rebalance session state get --session s<n> -o json 2>/dev/null) || exit 1
LAST_ROUND=$(echo "$STATE" | jq '.cursor.round // 0')
if [ "${LAST_ROUND:-0}" -ge "$ROUNDS" ]; then
  kraken --workspace rebalance session stop -o json 2>/dev/null
  exit 0
fi
# A stopped session refuses the cursor writes below, so trading on would repeat legs.
[ "$(kraken --workspace rebalance session show --session s<n> -o json 2>/dev/null | jq -r '.status')" = recording ] \
  || { echo "session s<n> is not recording; no round runs" >&2; exit 1; }
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 --workspace rebalance session state set --round "$LAST_ROUND" --legs-done "BTC/USD" \
  --note "round $ROUND: leg 1 of 3 done" -o json 2>/dev/null || exit 1   # after each leg
kraken --workspace rebalance session state set --round "$ROUND" -o json 2>/dev/null || exit 1   # 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.

BALANCE=$(kraken --workspace rebalance paper balance -o json 2>/dev/null)
CASH=$(echo "$BALANCE" | jq -r '.balances.USD.available // empty')
PRICE_BTC=$(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 --workspace rebalance 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 kraken workspace show rebalance 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 --workspace rebalance 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 --workspace rebalance 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 --workspace rebalance 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 --workspace rebalance session stop -o json 2>/dev/null
kraken --workspace rebalance session show -o json 2>/dev/null | jq '.summary'

kraken --workspace rebalance 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 the paper workspace rebalance and never places a live order, because every session, balance and order command passes --workspace rebalance and every round exits unless kraken workspace show rebalance reports mode paper. Drop either and the orders can trade the real account.
  • /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, rounds, 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.

版本历史

  • 671cdd7 当前 2026-11-03 05:49
  • aa56e59 2026-08-20 04:46

同 Skill 集合

skills/kraken-alert-patterns/SKILL.md
skills/kraken-autonomy-levels/SKILL.md
skills/kraken-basis-trading/SKILL.md
skills/kraken-dca-strategy/SKILL.md
skills/kraken-earn-staking/SKILL.md
skills/kraken-error-recovery/SKILL.md
skills/kraken-fee-optimization/SKILL.md
skills/kraken-funding-carry/SKILL.md
skills/kraken-funding-ops/SKILL.md
skills/kraken-futures-risk/SKILL.md
skills/kraken-grid-trading/SKILL.md
skills/kraken-lab-experiment/SKILL.md
skills/kraken-liquidation-guard/SKILL.md
skills/kraken-market-intel/SKILL.md
skills/kraken-mcp-integration/SKILL.md
skills/kraken-multi-pair/SKILL.md
skills/kraken-order-types/SKILL.md
skills/kraken-paper-strategy/SKILL.md
skills/kraken-paper-to-live/SKILL.md
skills/kraken-playground/SKILL.md
skills/kraken-portfolio-intel/SKILL.md
skills/kraken-rate-limits/SKILL.md
skills/kraken-rebalancing/SKILL.md
skills/kraken-risk-operations/SKILL.md
skills/kraken-setup/SKILL.md
skills/kraken-spot-execution/SKILL.md
skills/kraken-stop-take-profit/SKILL.md
skills/kraken-subaccount-ops/SKILL.md
skills/kraken-tax-export/SKILL.md
skills/kraken-twap-execution/SKILL.md
skills/kraken-ws-streaming/SKILL.md
skills/recipe-basis-trade-entry/SKILL.md
skills/recipe-daily-pnl-report/SKILL.md
skills/recipe-drawdown-circuit-breaker/SKILL.md
skills/recipe-earn-yield-compare/SKILL.md
skills/recipe-emergency-flatten/SKILL.md
skills/recipe-fee-tier-progress/SKILL.md
skills/recipe-funding-rate-scan/SKILL.md
skills/recipe-futures-hedge-spot/SKILL.md
skills/recipe-launch-grid-bot/SKILL.md
skills/recipe-morning-market-brief/SKILL.md
skills/recipe-multi-pair-breakout-watch/SKILL.md
skills/recipe-paper-strategy-backtest/SKILL.md
skills/recipe-playground-dca-triggered/SKILL.md
skills/recipe-playground-dca/SKILL.md
skills/recipe-playground-price-alert/SKILL.md
skills/recipe-playground-webhook/SKILL.md
skills/recipe-portfolio-snapshot-csv/SKILL.md
skills/recipe-price-level-alerts/SKILL.md

元信息

文件数
0
版本
671cdd7
Hash
47bcefb9
收录时间
2026-08-20 04:46

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-17 21:01
浙ICP备14020137号-1