otter-strategy

name: otter-strategy description: >- OTTER v2.0.0 — Open Interest Velocity Hunter (senpi_runtime_helpers migration). Plumbing-only port from v1.0. NO thesis change. NO scoring change. Producer ports onto senpi_runtime_helpers (in-process SenpiClient + direct HTTP POST to runtime /signals + producer_daemon long-lived loop). Trades the rate of change of OI on Hyperliquid perps — when 1h OI delta is >= 5% AND price moves in the same direction by >= 0.5%, that's fresh leveraged positioning with directional conviction (TOP-LEFT or TOP-RIGHT quadrant of the OI/price matrix). Otter follows the flow for 1-3 hours then exits. Conviction-scaled leverage (5/7/10 by score) per the fleet-winning pattern. license: MIT metadata: author: jason-goldberg version: "2.0.1" platform: senpi exchange: hyperliquid requires: - senpi-trading-runtime

🦦 OTTER v1.0 — Open Interest Velocity Hunter

A new fleet archetype. Built v2-runtime-native from day 1 (no v1 to migrate from). Otter is the FIRST fleet agent to use OI velocity as a primary trading signal — every other agent (Mamba, Condor, Barracuda, Pangolin) reads OI as a snapshot filter (size threshold) but none track delta over time.

Thesis (one paragraph)

Open Interest is the total notional of open perpetual contracts on an asset. Spot trading doesn't generate OI — only fresh perp positions do. So OI growth = real new leveraged capital deployed. When OI grows materially (>= 5% in 1h) and price moves in the same direction by

= 0.5%, that's fresh institutional/sophisticated positioning with directional conviction. Otter rides that flow for 1-3 hours, then exits on DSL hard timeout. The 4-quadrant interpretation:

Otter only trades the TOP-LEFT and TOP-RIGHT quadrants — fresh leveraged positioning with directional conviction.

What it inherits from fleet winners

Differentiation from the fleet

Producer behavior

Runs every 5 minutes via cron. On each tick:

1. Reentrancy guard: acquires state/<wallet-hash>/producer.lock. fcntl LOCK_EX | LOCK_NB.
2. Read account value via strategy_get_clearinghouse_state for sizing.
3. Fetch the universe via market_list_instruments (~60 crypto perps, XYZ filtered out at parse time).
4. Update OI history: append current sample {ts, oi, mark_px} per asset to state/<wallet-hash>/oi-history.json. Trim to last 60 samples per asset (5h rolling window at 5min cadence).
5. Compute deltas per asset with sufficient history:
   • 1h OI delta % (12 samples back)
   • 4h OI delta % (48 samples back, optional confirmation)
   • 1h price delta % (12 samples back)
6. Apply hard gates (TOP quadrants only):
   • 1h OI delta >= 5% (fresh leveraged flow)
   • 1h price delta aligned with OI delta direction (same sign), magnitude >= 0.5%
   • 4h OI delta >= 0% (no recent net unwinding masking the 1h growth)
   • OI USD >= $1M (liquidity floor)
7. Score each survivor:
   • 1h OI Δ tier: 4 (5-10%), 5 (10-20%), 6 (>20%)
   • 4h OI Δ confirmation: +2 if >= 10% same direction
   • 4h OI Δ contradiction: -2 if < 0
   • 1h price Δ magnitude: +1 (>1%), +2 (>2%)
   • SM concentration aligned: +2 if leaderboard_get_markets shows top traders in same direction
   • Spread check (market_get_asset_data orderbook): +1 (≤5 bps), +2 (≤2 bps); REJECT if >5 bps
   • Time-of-day modifier: +1 active window / -2 chop zone
8. MIN_SCORE 9 to fire.
9. Per-asset 240min cooldown (defense-in-depth alongside runtime).
10. Conviction-scaled leverage: 5x at 9-10, 7x at 11-12, 10x at 13+.
11. Emit top candidate via client.push_signal() (direct HTTP POST to the runtime API).

NO execution code. NO position-tracking. NO DSL state. The runtime owns all of that.

Bootstrap behavior

On first deploy, OI history is empty. First 12 cron ticks (1 hour) build the rolling window with no signals emitted — output reports note:"bootstrapping_history". After that, 1h delta is computable. After 48 ticks (4 hours), 4h confirmation also active.

This is normal and expected. New deployments need 1h to warm up; alert agents that 0 trades in the first hour is by design.

Entry flow

Producer daemon (5 min tick)
  ↓ Update rolling OI history (60 samples × ~60 assets = ~5h × 60 = 300 cells)
  ↓ Detect 1h OI Δ >= 5% with price aligned (TOP quadrant)
  ↓ Score >= 9 (multi-factor confluence)
  ↓ client.push_signal(scanner="otter_signals", ...)
Runtime
  ↓ Schema-validates fields against runtime.yaml
  ↓ LLM gate (decision_model = ${OTTER_DECISION_MODEL})
  ↓ Pass-through unless malformed
  ↓ OPEN_POSITION via FEE_OPTIMIZED_LIMIT (maker-only, 60s, NO taker fallback)
DSL (runtime-managed, exits via maker-first)
  ↓ Phase 1 max_loss 12% (≈ 2.4% price stop at 5x)
  ↓ Phase 2 tiers (5/30, 10/55, 15/75, 20/85)
  ↓ hard_timeout 240min (4h positioning thesis horizon)
  ↓ weak_peak_cut 60min @ 1.5%, dead_weight_cut 90min
  ↓ Exit via FEE_OPTIMIZED_LIMIT (maker-first, 60s, taker fallback)

Required env vars

The runtime YAML uses these substitutions:

The producer reads:

Producer install (on OpenClaw host)

Source path in the senpi-skills repo: otter/. Install destination on the OpenClaw host: /data/workspace/skills/otter-strategy/. The two names differ — repo uses otter, install dir uses the SKILL.md name field.

# 1. Pull the skill files (source: senpi-skills/main/otter/)
mkdir -p /data/workspace/skills/otter-strategy/{scripts,config}

for f in runtime.yaml scripts/otter-producer.py scripts/otter_config.py config/otter-config.json; do
  curl -s https://raw.githubusercontent.com/Senpi-ai/senpi-skills/main/otter/$f \
    -o /data/workspace/skills/otter-strategy/$f
done

# 2. Install the runtime
WALLET_ADDRESS=0x... \
TELEGRAM_CHAT_ID=... \
OTTER_DECISION_MODEL=<your-preferred-model> \
  openclaw senpi runtime create --path /data/workspace/skills/otter-strategy/runtime.yaml

# 3. Launch the producer daemon (5 min tick).
# OTTER_WALLET (NOT generic STRATEGY_ADDRESS) is required by the producer.
SENPI_AUTH_TOKEN=<your-token> \
OTTER_WALLET=0x... \
  nohup python3 -u /data/workspace/skills/otter-strategy/scripts/otter-producer.py \
  > /tmp/otter-producer.log 2>&1 &

# Note: first 12 ticks (1 hour) will report "bootstrapping_history" — by design.

# 4. Verify
openclaw senpi runtime list                              # expect: otter-tracker running
openclaw senpi status --runtime otter-tracker
senpi-helpers list                                       # daemon visible with recent LAST_TICK
senpi-helpers health otter-<wallet-suffix>               # exit 0 = healthy
senpi-helpers stats otter-<wallet-suffix> --hours 1      # signals posted + error histogram

# Inspect producer state:
ls -la /data/workspace/skills/otter-strategy/state/<wallet-hash>/
# Expect: producer.lock + oi-history.json with mtime in last few minutes.

Risk envelope (declarative, runtime-enforced)

Scoring (max ~17 points)

MIN_SCORE 9 to fire. Hard gate: 1h OI Δ >= 5% (raw signal floor).

Expected behavior

Silence is correct. OI velocity events are infrequent — the agent should be quiet most of the time. Don't improvise.

What's intentionally NOT here

• No XYZ assets. XYZ OI dynamics differ (commodities/equities OI is dominated by hedgers, not leveraged speculators). Bald Eagle's territory.
• No bottom-quadrant trades. OI ↓ + price-aligned moves are exhaustion signals; that's Pangolin/Owl's lane.
• No taker fallback on entries. OI velocity isn't urgent — if maker can't fill in 60s, the trade isn't ripe.
• No funding-rate filter. Funding is independent of OI velocity; would over-filter.
• No counter-quadrant trades. Otter follows flow, doesn't fade it.

License

MIT — Built by Senpi (https://senpi.ai). Source: https://github.com/Senpi-ai/senpi-skills

Skill Attribution

When creating a strategy, include skill_name and skill_version in the call. See references/skill-attribution.md for details.