recipe-playground-dca
GitHub用于在模拟环境中测试基于时间的定投(DCA)策略假设。支持固定周期或价格 dips 触发买入,记录完整决策过程并计算 P&L,全程使用纸交易环境避免真实资金风险。
触发场景
安装
npx skills add krakenfx/kraken-cli --skill recipe-playground-dca -g -y
SKILL.md
Frontmatter
{
"name": "recipe-playground-dca",
"version": "1.0.0",
"metadata": {
"openclaw": {
"domain": "sessions",
"category": "recipe"
},
"requires": {
"bins": [
"kraken"
],
"skills": [
"kraken-playground",
"kraken-dca-strategy"
]
}
},
"description": "Example driver: drive a time-based dollar-cost-averaging hypothesis into a recorded session."
}
Playground: DCA (Time-Gated)
PREREQUISITE: Load
kraken-playgroundandkraken-dca-strategyto run this recipe. This recipe is an example, not a boundary. Adapt the steps to your hypothesis, or write your own driver (seekraken-playground→ Driving Your Own Hypothesis).
Test a dollar-cost-averaging hypothesis on live prices with no real money. Buy on a fixed cadence, optionally only when price dips below a short-term average, and record every buy, skip, and average cost into one session for later replay and P&L.
Use this skill for:
- running a time-based DCA hypothesis over a window
- gating each buy on a dip below a short-term average
- recording every decision with the numbers behind it
Important
This recipe records a session inside a paper workspace. With that workspace named on every session and order call and checked each round (see Hard Rules), it never places a live order. Paper results may overstate live performance: fees and slippage are simulated and there are no partial fills (see kraken-paper-strategy).
Pacing is external. /loop owns the schedule and fires one round per interval (see kraken-playground → Pacing). One decision per interval, paced from outside, so the session is interventional over the window (see kraken-playground → Running over a Window).
Params
Every number that gates a buy or skip goes in --strategy-params, not only in prose reasons. That is what makes two sessions comparable knob-for-knob:
dollars_per_buy: quote currency deployed per qualifying roundrounds: session length in decision roundsinterval_s: spacing between rounds; set the/loopinterval to this valuedip_threshold_pct(dip-gated variant): only buy when price is at least this far below the short-term average; omit for unconditional time-based DCA
Quick Start
Natural language:
Dollar-cost-average into Bitcoin over 10 hours. Buy $100 every hour if the
price dips more than 0.10% below the 1-hour SMA. Record all buys, skips, and
average cost. At the end, show P&L.
Start the Session
Work inside a paper workspace (create one once: kraken workspace create dca --capital 10000 --mode paper). Every session and order command below names it with --workspace dca. An exported KRAKEN_WORKSPACE does not reach a later shell, such as a /loop fire, and without a workspace kraken order buy trades the real account.
kraken --workspace dca session start \
--symbols BTC/USD --channels ticker,trade --to duckdb,jsonl \
--label dca-btc-$(date +%Y%m%d-%H%M%S) \
--strategy recipe-playground-dca \
--strategy-params '{"dollars_per_buy":100,"rounds":10,"interval_s":3600,"dip_threshold_pct":-0.10}' \
-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 hour" to 1h, "every 30 minutes" to 30m, "twice a day" to 12h.
The scheduler floor is 60 seconds (/loop, cron, and ScheduleWakeup all clamp to a one-minute minimum). interval_s must be >= 60; a sub-minute cadence is impossible — clamp to 60 and tell the user if they ask for less.
/loop 1h "Run one DCA round for session s<n> in workspace dca per recipe-playground-dca"
Do not re-add an elapsed-time gate inside the round. /loop already enforces the spacing.
Each Round
On each firing: stop if the session is complete, otherwise READ, THINK, ACT.
Check the last completed round against rounds. The round cursor lives in the session's typed state cell (kraken session state get/set) — not in the decision log, whose reasons stay free narrative (keep writing "round N" in them for the post-mortem story, but nothing parses it). Reading the cursor is O(1) however long the session runs, and a typo'd field refuses at set instead of silently steering the loop:
ROUNDS=10 # the `rounds` you set in --strategy-params
SESSION_ID=s1 # from the session_started line
# The buys below are simulated only while dca is a paper workspace.
[ "$(kraken workspace show dca -o json 2>/dev/null | jq -r '.mode')" = paper ] \
|| { echo "workspace dca is missing or not paper; no round runs" >&2; exit 1; }
# The typed cursor is the loop's memory: unset reads as round 0, but a failed
# read must end the firing rather than restart at round 1.
STATE=$(kraken --workspace dca session state get --session "$SESSION_ID" -o json 2>/dev/null) || exit 1
LAST_ROUND=$(echo "$STATE" | jq '.cursor.round // 0')
if [ "${LAST_ROUND:-0}" -ge "$ROUNDS" ]; then
kraken --workspace dca session stop -o json 2>/dev/null
exit 0
fi
ROUND=$((LAST_ROUND + 1))
# CLAIM the round BEFORE acting: a crash after the claim skips one buy
# (harmless); the reverse order would redo the round and buy twice. `set`
# replaces the whole cursor — carry every field your strategy tracks.
kraken --workspace dca session state set --round "$ROUND" -o json 2>/dev/null || exit 1
READ: price and the short-term average. Mind the response shapes: the ticker
is keyed by Kraken's INTERNAL pair name (XXBTZUSD, not BTC/USD), so read
the price through the value (.[].last_price). The ohlc rows live under
.candles; read that array directly — the sibling last cursor would poison
naive iteration of the object.
PRICE=$(kraken ticker BTCUSD -o json 2>/dev/null | jq -r '.[].last_price')
# True 1h SMA: the last twelve 5-minute closes (NOT --interval 60, whose
# full-window mean is a multi-day average).
SMA=$(kraken ohlc BTCUSD --interval 5 -o json 2>/dev/null | jq '[.candles[-12:][].close] | add / length')
Fail loud, never fabricate: if either value comes back empty, the round must not guess — note an alert and end the firing, or the decision log fills with plausible-looking false reasons:
if [ -z "$PRICE" ] || [ -z "$SMA" ]; then
kraken --workspace dca session note --kind alert --symbol BTC/USD \
--reason "round $ROUND aborted: READ failed (price='$PRICE' sma='$SMA')" -o json 2>/dev/null
exit 0
fi
Compute in jq/bc, do not eyeball it.
THINK:
vs_sma = (price - sma) / sma * 100- If the ticker spread is wider than 1%, skip and note it. A wide spread distorts the paper fill.
- If
vs_sma <= dip_threshold_pct, buydollars_per_buy / priceunits. Otherwise skip.
ACT (buy):
kraken --workspace dca order buy BTC/USD <volume> --type market \
--reason "DCA round N: BTC/USD at <price> is <vs_sma>% below 1h SMA <sma> (threshold <dip>%); deploying \$<dollars_per_buy>" \
-o json 2>/dev/null
Inside the paper workspace the order fills on the paper account, and the reason lands in the active session's decision log.
ACT (skip):
kraken --workspace dca session note --kind skip --symbol BTC/USD \
--reason "skip round N: BTC/USD at <price> is <vs_sma>% from 1h SMA (threshold <dip>%)" \
-o json 2>/dev/null
The round is already claimed, so nothing to write after acting: buy or skip, log the reason, and exit the firing.
Always pass the numeric reason so the decision log carries the "why" behind every round.
Stop and Review
kraken --workspace dca session stop -o json 2>/dev/null
kraken --workspace dca session show -o json 2>/dev/null | jq '.summary'
kraken --workspace dca explain pnl --session latest -o json 2>/dev/null | jq '{anchor, waterfall: [.components[] | {kind, amount}]}'
kraken --workspace dca session decisions --session "$SESSION_ID" -o json 2>/dev/null \
| jq -c '.decisions[] | {kind, symbol, reason, timestamp}'
Report:
- total deployed vs expected (
dollars_per_buy × rounds) - buys vs skips, with dip measurements
- average fill cost vs window mean
- P&L, and whether the dip threshold fit the tape
Hard Rules
- This recipe records a session inside the paper workspace
dcaand never places a live order, because every session and order command passes--workspace dcaand every round exits unlesskraken workspace show dcareports modepaper. Drop either andkraken order buycan trade the real account. /loopdrives the pace and the agent runs each round. The CLI has no scheduler and runs no strategy.- Do not add a pacing gate inside the round;
/loopenforces spacing. - A scheduled
/loopfire only runs what the agent may invoke unprompted. Keep the round's commands permitted non-interactively in exactly these forms:kraken workspace show dca,kraken ticker,kraken ohlc, andkraken --workspace dcafollowed bysession state,session note,session stopororder buy. Otherwise a fire stalls waiting on an approval you never see. Never permit a barekraken order buy: outside a workspace it is a real order. - Keep every gating number in
--strategy-paramsand the arithmetic injq/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,mkdir, or append inside it — every buy and skip goes throughkraken 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
新增 interval_s 和 dip_threshold_pct 参数配置说明;补充启动会话及打印 session id 的操作指引。
- aa56e59 2026-08-20 04:46


