senpi-trading-runtime

What this skill does

# Senpi Trading Runtime — OpenClaw Plugin

On-chain position tracker with automated DSL (Dynamic Stop-Loss) exit engine. Monitors a wallet's positions on Hyperliquid for lifecycle events (open, close, edit, flip) and applies two-phase trailing stop-loss protection to all positions.

> **Install location (OpenClaw-managed hosts):** Senpi skills live at `/data/.openclaw/skills/`. The Senpi skill family is `senpi-onboard` (bootstrap + welcome), `senpi-entrypoint` (post-onboarding routing + the strategy-intent router + the fleet catalog), and `senpi-trading-runtime` (this skill — the build path). If you only see `senpi-trading-runtime` installed and not the other two, follow the raw-URL pointers in this doc — they work regardless of install state.

## ▶ Before you read this: classify the user's intent

The word "strategy" is overloaded — and **defaulting to the build-from-scratch path when the user just wanted a recommendation is the most common silent failure.** This skill is only for the build-a-new-autonomous-agent path (author code + `runtime.yaml` + DSL). Before you read further, do this:

**If the user's intent is anything other than an explicit, specific build-from-scratch request, ASK them to disambiguate:**

> "Do you want to (a) open a specific position you already have in mind, (b) copy a specific trader, or (c) get help picking or building a strategy from our catalog?"

Then route accordingly:

| User intent | Path |
|---|---|
| (a) "go long HYPE 10x", "open a short on BTC" — **specific named position** | MCP `strategy_create_custom_strategy` — execute directly. **Stop reading this doc.** |
| (b) "copy 0x...", "mirror this OG" — **explicit copy of a named trader** | MCP `strategy_create` — mirror them. **Stop reading this doc.** |
| (c) "help me pick a strategy", "what should I trade", "recommend a strategy", "what templates exist" — **open-ended, wants help deciding** | **Template-first picker:** walk the **Decision Tree in [`references/producer-patterns.md`](references/producer-patterns.md#decision-tree--help-a-user-pick-their-first-strategy)** — the canonical routing source (Layers 0–3). Cross-reference `catalog.json` for install metadata (name, tagline, install command, min_budget). Recommend 2–3 templates, install via `install_skill`. Build-from-scratch is the **fallback**, not the default. **Stop reading this doc unless the user explicitly picks "build new".** |
| The user explicitly chose "build new", or no fleet template fits their thesis | **Keep reading.** |

**Never default to `strategy_create_custom_strategy` for an ambiguous "what should I trade?" or "help me pick a strategy" query.** That tool is for positions the user named. Using it for open-ended queries surfaces a manual-position basket where the user wanted *strategy recommendations* — the exact failure mode this section exists to prevent.

The fleet install metadata (use for case (c), after the Decision Tree has narrowed to a candidate set):

```bash
curl -s https://raw.githubusercontent.com/Senpi-ai/senpi-skills/refs/heads/main/catalog.json
```

`catalog.json` is install/display metadata only — names, emojis, taglines, min_budget, version. All recommendation logic lives in the Decision Tree in `producer-patterns.md`.

Full router with the picker flow and the what-never-to-do list (raw URL — works whether or not `senpi-entrypoint` is installed):

[`https://raw.githubusercontent.com/Senpi-ai/senpi-skills/main/senpi-entrypoint/references/strategy-intent-routing.md`](https://raw.githubusercontent.com/Senpi-ai/senpi-skills/main/senpi-entrypoint/references/strategy-intent-routing.md)

## ▶ Building a new autonomous strategy? Read the fast path first

> **Start here: [`references/strategy-creation.md`](references/strategy-creation.md).** It's the self-contained fast path — the 5-step flow, the producer-only-emits-signals invariant, an archetype→example→DSL-preset table, an inline producer skeleton, a complete `runtime.yaml`, the DSL presets, and the gotchas, all in one fetch. **You should not need to read anything else to ship a working strategy.** The sections below are the deep reference, linked from `strategy-creation.md` for edge cases.

This skill is the canonical way to build a Senpi strategy. **Every strategy is built the same way** — on this runtime, with the Producer SDK, DSL exit engine, and risk guard-rails. There are **two on-ramps** to that one structure:

- **Path A — Start from a template.** Something close to your idea already exists. Pick the closest archetype in `producer-patterns.md`, clone the linked example agent, and swap in your asset / thresholds. Fastest path when a near-match exists.
- **Path B — Bring your own scanner/producer.** Your signal logic is novel and no template fits. Pick the archetype in `producer-patterns.md` that's *structurally* closest to your approach, then write a new producer on the SDK. **Your signal logic is yours; the surrounding structure is standard.**

Both paths follow the same read-order:

1. **[`references/producer-patterns.md`](references/producer-patterns.md)** — pick the archetype (universe trend-follower, single-asset alpha hunter, trader-follower, funding fade, etc.). Each links to a working example agent's `producer.py` + `runtime.yaml`. **Path A: clone the closest example. Path B: use it as your structural template.**
2. **[`references/python-producer-sdk.md`](references/python-producer-sdk.md)** — build (Path B) or tune (Path A) the producer on the bundled `senpi_runtime_helpers` SDK (`SenpiClient`, `producer_daemon`, `scanner_lock`, `tick_cache`). Don't hand-roll MCP calls or the daemon loop.
3. **[`references/yaml-schema.md`](references/yaml-schema.md)** — configure `runtime.yaml` (scanners, actions, decision gate).
4. **[`references/risk-gates.md`](references/risk-gates.md)** + **[`references/dsl-configuration.md`](references/dsl-configuration.md)** — declare risk guard-rails and tune the two-phase exit.
5. **[`references/senpi-helpers-cli.md`](references/senpi-helpers-cli.md)** — verify the daemon is alive and ticking after deploy.

### The invariant (both paths)

Whether you cloned a template or wrote your own scanner, the contract is identical:

- **The producer ONLY emits signals** via `push_signal` / `POST /signals`. It does **not** call `create_position`, **does not** write its own stop-loss / exit logic, and **does not** hand-roll a daemon loop or risk checks.
- **The runtime owns execution, DSL exits, and risk guard-rails** for every strategy — always. That's what keeps a bring-your-own scanner on the same rails as a proven template.

A "custom strategy" means **custom signal logic inside a standard producer**, not a custom harness. If you find yourself calling `create_position` or writing exit logic in the producer, stop — that belongs to the runtime.

### Recommended for every strategy: attach DSL

**Recommend DSL (Dynamic Stop-Loss) on every strategy, by default — both paths, every time.** It's the runtime's two-phase trailing exit (Phase 1 caps the loss, Phase 2 ratchets profit as the position runs) and it's the layer that keeps a position from running **unprotected** if the producer goes quiet, the host restarts, or an entry fills late. A strategy with no DSL carries naked-position risk: when anything interrupts the producer or the fill, nothing is managing the exit.

The user and their agent decide for themselves — DSL can be tuned or turned off — **but the recommended default is DSL on, for every strategy.** When proposing a strategy, default to attaching it and only drop it if the user explicitly opts out.

**Pick a preset — don't hand-author from zero.** Four named DSL presets cover the strategy spectrum (machine-readable in [`references/dsl-presets.yaml`](references/dsl-presets.yaml), copy-paste blocks + tuning in [`references/dsl-configuration.md`](references/dsl-configuration.md)):

| Preset | Use for |
|---|---|
| **`balanced`** ⭐ default | General-purpose / unsure — breathes early, runner