Caracal Strategy

🐱 CARACAL v1.0 — Volatility Hedge Fund

Caracal runs two concurrent strategy wallets that harvest volatility expansion. One producer script (caracal-producer.py) serves both; the CARACAL_LEG env var selects which book a given daemon is. It trades movement, not direction — each book takes the breakout long or short, whichever way it breaks.

> The edge is volatility. Compression precedes expansion, and a breakout > from a low-volatility coil has higher follow-through than a breakout in > already-volatile tape. Caracal only fires when a name has been coiling > (recent ATR bar is an outsized move.

| Book | Universe | Wallet env | Runtime | Scanner | |---|---|---|---|---| | breakout | Liquid main-DEX crypto | CARACAL_BREAKOUT_WALLET | runtime-breakout.yaml | caracal_breakout_signals | | catalyst | Liquid XYZ (equities/energy/metals/indices) | CARACAL_CATALYST_WALLET | runtime-catalyst.yaml | caracal_catalyst_signals |

The two books differ only in universe (crypto vs XYZ) — they share the same volatility-breakout engine. The catalyst book turns Jason's macro themes (oil/Iran, AI infra) into vol sources: it rides whichever way the catalyst breaks, 24/7 (XYZ trades through weekends).

The volatility-breakout signal (both books)

Each tick the producer scans the leg's liquid universe (top universeMaxNames by 24h volume) and, per name, fetches 1h+4h candles and computes:

• Range breakout — current price vs the prior breakoutBars (default 20)

bar high/low. Break up → LONG; break down → SHORT. No break → skip.

• Compression precondition — recent ATR (recentBars) ÷ baseline ATR

(baseBars). ≤ squeezeTight (0.70) = tight coil; ≤ squeezeLoose (0.90) = mild coil; otherwise penalized (a break with no prior coil has less edge).

• Expansion surge — breakout-bar true range ÷ baseline ATR. ≥ surgeStrong

(2.0×) / ≥ surgeMod (1.3×).

• Higher-TF agreement — the break aligned with 4h structure follows through more.

Scoring (raw integer; minScore 5)

| Component | Pts | |---|---| | Range breakout (the trigger) | +3 | | Compression coil | +2 (≤0.70) / +1 (≤0.90) / −1 (no coil) | | Expansion surge | +2 (≥2.0×) / +1 (≥1.3×) | | 4h agreement | +1 (with break) / −1 (against) |

Direction is the break direction — both books trade LONG and SHORT.

Execution & exit (both books)

• slots 3, margin_pct 18%, tick 300s
• strict 5x leverage clamp, then each asset's Hyperliquid venue max
• DSL tight fast-capture: a failed breakout reverses fast, so cut quickly —

phase1 max_loss 12% / retrace 7 / 1 breach; weak_peak_cut ON (3h @ 2.0), dead_weight_cut ON (6h), hard_timeout 2d (vol events resolve fast); phase2 ladder 8%→lock30 / 18%→50 / 35%→68 / 60%→80 / 100%→90 (locks early — expansion can round-trip)

Leverage clamping (both books)

Desired = maxLeverage 5; clamped to each asset's HL venue max; the runtime gate rejects any leverage above 5.

XYZ handling

The catalyst book trades XYZ — candle fetches route with dex="xyz" (the producer keys off the xyz: prefix). XYZ trades 24/7 on Hyperliquid, so there is no weekend gating (oil stayed active through recent geopolitics). The main/xyz clearinghouse sections are two VIEWS of ONE cross-margined wallet, so get_positions() takes accountValue ONCE via max() — never sums.

Risk gates (risk.guard_rails)

| Gate | breakout | catalyst | |---|---|---| | dailylosslimitpct | 12 | 12 | | maxentriesperday | 8 | 8 | | maxconsecutivelosses | 5 | 5 | | cooldownminutes | 45 | 45 | | drawdownhaltpct | 20 | 20 | | perassetcooldownminutes | 120 | 120 | | dataretentionhours | 72 | 72 | | drawdownresetondayrollover | true | true |

Entries and exits both use FEE_OPTIMIZED_LIMIT (ensure_execution_as_taker true; 30s maker-first window — breakouts need timely fills).

Files

| File | Purpose | |---|---| | runtime-breakout.yaml | Crypto breakout-book runtime spec | | runtime-catalyst.yaml | XYZ catalyst-book runtime spec | | scripts/caracal-producer.py | Book-aware producer daemon (one script, both books) | | scripts/caracal_config.py | Leg resolution + SenpiClient wrapper + helpers | | config/caracal-breakout-config.json | Crypto book tunables (squeeze/surge thresholds) | | config/caracal-catalyst-config.json | XYZ book tunables |

Operator install

See [README.md](README.md) — the two books are two daemons (CARACAL_LEG=breakout and CARACAL_LEG=catalyst) on two equally-funded wallets, each with its own runtime YAML.

Hard rule for user-conversation Claude sessions

User-conversation Claude sessions MUST NOT call any of: create_position, close_position, edit_position, ratchet_stop_add, ratchet_stop_edit, ratchet_stop_delete, cancel_order, strategy_close, strategy_close_positions.

These tools are reserved for the producer daemon (entry path) and the DSL ratchet engine (exit path). User-conversation sessions are read-only. Each producer daemon handles real signals on its next tick.

License

Apache-2.0 — Copyright 2026 Senpi (https://senpi.ai)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Senpi-ai
• Source: Senpi-ai/senpi-skills
• License: MIT

Install and usage instructions live in the source repository linked above.