--- name: senpi-trading-runtime description: >- How a Senpi trading strategy interacts with the runtime engine (@senpi-ai/runtime) on Hyperliquid: a strategy runs from a runtime.yaml pointing at a Python module that exports scan(inputs, ctx), which the runtime supervises and calls each interval, then owns execution, risk guard_rails, and two-phase DSL trailing-stop exits. Use when working with runtime.yaml, the scan(inputs, ctx) contract, external_scanner, ctx, or the DSL exit engine — including verifying open positions are protected by DSL (have a working stop-loss). The shared runtime contract the lifecycle skills reference. NOT for building, installing, or picking a strategy (→ senpi-strategy-author / senpi-strategy-ops / senpi-strategy-discover). license: Apache-2.0 metadata: author: Senpi version: "4.1.7" platform: senpi exchange: hyperliquid --- # Senpi Trading Runtime — the runtime contract This skill is **infrastructure**: the canonical knowledge of how the Senpi runtime (**`@senpi-ai/runtime`**) behaves and how a strategy interacts with it. The lifecycle skills — author (build), ops (install/monitor), discover (recommend) — reference this one for the contract. ## The runtime model A strategy runs from a **`runtime.yaml`** that points at an in-repo Python module. The runtime **spawns and supervises** that module and calls a frozen **`scan(inputs, ctx)`** every `interval_seconds`. The division of labor is fixed: - **Your code produces signals — nothing else.** `scan(inputs, ctx)` *reads* market and account data and *returns* a `list[dict]` of candidate signals. It does not open, close, size, schedule, or execute anything. - **Zero model cost, and the only loop there is.** The runtime ticks every `interval_seconds` without a model call. Never put an agent-turn cron beside it — a producer, a re-check, a watcher — each firing is a full model call. There is no paper-trading mode: a strategy is tested with `senpi validate` (one real tick, no wallet) and then run live at the $10 floor. - **The runtime owns everything downstream:** scheduling (`interval_seconds`), spawning + supervising + restarting the scanner, validating (`signal_data_schema`) + de-duplicating the signals you return, **sizing & order execution** (`FEE_OPTIMIZED_LIMIT`), slot accounting, `risk.guard_rails`, the two-phase **DSL** trailing-stop exits, and **crash-safe position reconcile** on restart. ## How your code talks to the runtime The interaction surface is small and one-directional — you read, you return signals, the runtime acts. - **`runtime.yaml`** declares the scanner(s), the action gate, the exit engine, and the risk guard-rails, and passes author tunables down via `inputs:`. → `references/runtime-yaml.md` - **`scan(inputs, ctx)`** is the single entry point. `inputs` is the runtime's `inputs:` map; `ctx` gives you: - **`ctx.senpi_mcp.call_tool(name, args)`** — the Senpi MCP client, **read-only** (market, account, leaderboard, discovery, `strategy_get*`, …). It is the only way to fetch data. - **`ctx.state`** — transactional, runtime-persisted history (`last()` / `append()` / `len`) for dedup, rotation, and first-seen ledgers; advances only on a clean tick. - **`ctx.wallet`** — the strategy's wallet address. - → `references/scan-contract.md` - **The return value** is a `list[dict]`, one per candidate signal (`asset`, `direction`, `marginPct`, `leverage`, `data{}`). The runtime validates each `data{}` against the runtime.yaml's `signal_data_schema`, then sizes, executes, and manages exits. Keep the thesis logic in a sibling pure **`scoring.py`** (no I/O, no MCP) so it is unit-testable; `scan.py` does the reads + state, `scoring.py` does the math. ## Runtime commands (essentials) The plugin registers a `senpi` command group on the gateway. Deploying a strategy and checking it: ```bash openclaw plugins install @senpi-ai/runtime openclaw senpi validate # THE GATE, pre-money: one real tick, no wallet; a PASS records the proof deploy requires openclaw senpi deploy -p --budget # ONE verb, detached: funds preflight → wallet create+fund → install → one observed tick openclaw senpi deploy status # poll until terminal; the verified report (read-only) openclaw senpi runtime list # id, source, status ("running — NO ENTRY SCANNERS" = scanners never wired) ``` **Deploy a package through `senpi-strategy-ops`' `deploy.py create --budget `**, which resolves the package, runs the structural preflight and drives that same verb. The verb owns the gates — the live-universe check (`[E_UNIVERSE_NOT_LIVE]`, pre-money), the funds preflight, the `skillName`/`skillVersion` attribution and the verified tick. **`runtime create` is internal**: it installs a runtime and skips every one of those, so it is not the deploy path. **`senpi validate` is the gate every deploy runs through** — it loads the scanners and runs one real tick with no wallet and no funding, and a full unscoped PASS at live depth is what writes the `.senpi-proof.json` `senpi deploy` refuses to fund a package without. Run it before `deploy`, once per instance, pointed at the directory holding that instance's `runtime.yaml`. **To CHANGE a strategy that is already live** → `openclaw senpi update`, not a delete-and-redeploy. Deleting a runtime abandons its DSL position files, so every open position loses the trailing stop the strategy already promised and its replacement re-adopts from scratch at whatever price it finds. `update` swaps the components in place and keeps DSL state, scanner stores and action history — no wallet is created, nothing is funded, and no position is closed. ```bash openclaw senpi update ./pkg # PLAN — what changes, what it leaves alone openclaw senpi update ./pkg --apply # commit (needs the same proof deploy needs) openclaw senpi update ./pkg --apply --code-only # assert only scan.py changed; refuses if not ``` It plans by default; `--apply` is the only way to commit. `phase2.tiers` is what users call the **ratchet**; with no open position, the edit plus `--apply` is the whole change. **`dsl_preset` changes are forward-only** — new entries only, while every open position keeps a snapshot of the preset it was opened under (other `exit:` fields, e.g. `order_type`, are read live and DO reach open positions). Refused outright, changing nothing: a different `strategy.wallet` (that is a new deployment, and the old wallet's positions would be left unmanaged), an external scanner renamed or moved (state is keyed by name and position together, and inserting or removing one moves every external scanner below it — appending at the end moves nobody and is allowed), or a changed `action_type` under a stable name. `--apply` also needs a passing proof that covers the recipe being applied, so point it at the package DIRECTORY: a recipe handed over as bare text has nothing to verify against and is refused. Exit `2` means the runtime was never touched; exit `1` means an apply was attempted and it may not be where you left it — read the message before retrying. **Saved is not applied.** Without `--apply`, `update` changes nothing, and only the first line of its output says so — `Dry run for — nothing has been applied.` — so never pipe `openclaw senpi` output through `tail` or `head`. A scanner imports `scan.py` once, when it starts, so a running strategy keeps its old code until `--apply` restarts its scanners (a crash or a gateway restart would load the edit too, unannounced). `senpi validate` runs the copy on disk, never the running one, and re-running `deploy` on a strategy that is already running applies nothing. The edit is live once the apply exits `0` with `Updated .` as its first line and no `WARNING` that its external scanners are NOT running, and the running strategy shows it: ```bash openclaw senpi events -r --name runtime.updated # an entry for this apply (code-only edits too) openclaw senpi update ./pkg --id # read-only: a recipe edit that landed plans "The recipe is unchanged." ``` Until both reads show it, tell the user the edit is **saved, not applied**. What a tick keeps and what discards one: `references/scan-contract.md`. Beyond `validate`, `deploy`/`deploy status`, `update` and `runtime list/delete`, the CLI exposes the runtime's live state — `senpi dsl positions|inspect|closes` (the exit engine), `senpi action list|inspect|history|decisions` (the decision layer), `senpi risk` (am I allowed to trade, and why not), `senpi audit` (backend trade trail with AI reasoning), `senpi scanner` (per-scanner health, liveness, and a `(no signals yet)` flag for scanners that run but produce nothing), `senpi events`/`senpi explain ` (the local domain-event log — the trade narrative, and one asset's stitched lifecycle), `senpi status`/`senpi state` (health — fail-closed: an external scanner never proven by a tick reads `unknown`, not `healthy`; non-healthy scanners get their own line with restart count and cause), and `senpi guide …` (in-shell reference). Full surface with every option → `references/runtime-cli.md`. **To confirm open positions are actually stop-loss protected** (a position with no DSL shows up as an *absence* in `dsl positions`, so it's easy to miss) → the verdict procedure in `references/dsl-protection-check.md`. ## The reference set | Read this | For | |---|---| | `references/runtime-concepts.md` | How the runtime behaves end to end: the runtime pipeline, `position_tracker`, and the two-phase DSL exit engine | | `references/runtime-yaml.md` | The `runtime.yaml` schema — every section, the `external_scanner` fields, the risk guard-rails | | `references/scan-contract.md` | The author contract in depth: `scan(inputs, ctx)`, the `ctx` surface, the signal shape, and `scoring.py` | | `references/runtime-cli.md` | The full `openclaw senpi …` command surface — **validate** (the pre-deploy gate: flags, depths, exit codes, the proof it records), deploy, runtime, dsl, action, status/state, skills, guide | | `references/dsl-protection-check.md` | **Verify open positions are DSL-protected** — the PROTECTED / UNPROTECTED / STOP-NOT-ON-VENUE verdict + the open-vs-tracked reconciliation | ## Package naming (load-bearing) The runtime package is **`@senpi-ai/runtime`** (with `-ai`) — the one users install on their hosts. Always write it with the `-ai`.