# Senpi Trading Runtime

> 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).

- Skill: `jiayaoqijia/senpi-trading-runtime` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add jiayaoqijia/senpi-trading-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiayaoqijia/senpi-trading-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: Apache-2.0
- Author: jiayaoqijia (https://skillmd.com/u/jiayaoqijia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jiayaoqijia/senpi-trading-runtime

---


# 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 <dir-with-runtime.yaml>        # THE GATE, pre-money: one real tick, no wallet; a PASS records the proof deploy requires
openclaw senpi deploy -p <package-dir> --budget <usd>  # 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 <id> --budget <usd>`**, 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. **`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.

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 <asset>` (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`.