Skip to main content
skill CX Codex

senpi-trading-runtime — Claude Code skill: what it does

senpi-trading-runtime — a skill for Claude Code, Codex, and Cursor covering the @senpi-ai/runtime engine contract on Hyperliquid. Guides development of runtime.yaml and the scan(inputs, ctx) handler.

Apache-2.0 131 installs ★ 143 updated 2026-11-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a claude-code
Open on GitHub

What senpi-trading-runtime does

Supported across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. This skill acts as infrastructure documentation for building Hyperliquid strategies under @senpi-ai/runtime. Your Python code strictly produces signals via scan(inputs, ctx), while the runtime engine handles order sizing, scheduling, risk halting, and DSL trailing stops.

Strategy code queries market details read-only through ctx.senpi_mcp.call_tool and tracks state via ctx.state. Partial exits are prohibited by design: every DSL stop or runtime exit terminates the whole position, and any scanner attempt to invoke edit_position triggers a runtime PermissionError.

Every live launch mandates a clean run of openclaw senpi validate. It executes a single tick without funding to write .senpi-proof.json, which the deployment gate requires before creating a wallet.

What it helps with

  • verify the scan(inputs, ctx) return schema for candidate trading signals
  • configure runtime.yaml guardrails and DSL trailing-stop tiers
  • run dry-tick verification via openclaw senpi validate prior to deployment
  • patch live strategy code using openclaw senpi update without dropping stop-losses

Example prompts for the agent

  • Audit my scan(inputs, ctx) implementation against the senpi-trading-runtime specifications.
  • Help me write a runtime.yaml config with risk guardrails for Hyperliquid.
  • Explain how to run openclaw senpi update --apply --code-only to update scan.py safely.

How to install senpi-trading-runtime

1Skills CLI (Vercel)

npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a claude-code

2Manually: put the files in place

~/.claude/skills/senpi-trading-runtime/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/senpi-trading-runtime/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about senpi-trading-runtime

How to install senpi-trading-runtime in Claude Code?

Run npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a claude-code. The definition will be placed into ~/.claude/skills/senpi-trading-runtime/SKILL.md.

What is senpi-trading-runtime?

It is a reference skill that explains the execution model of the Senpi trading engine, outlining data flow, scanner constraints, and deployment commands.

Does the runtime support scaling out of positions?

No, the runtime only supports full position exits. Scanner attempts to call edit_position to scale down will raise a PermissionError on every tick.

Source text

SKILL.md · Apache-2.0
---
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 (the Ratchet Stop / tier ladder) or the risk guard rails (a latched
  daily-loss or drawdown halt) — 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.16"
  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.
- **What it does NOT own: partial exits.** Every exit the runtime can make (DSL, `CLOSE_POSITION`)
  closes the WHOLE position, and `edit_position` — the only reduce — is blocked to scanners. A rule
  like "take 25% off at +10% ROE and let the rest run" cannot be authored in a runtime package at
  all; a scanner that tries raises `PermissionError` every tick while the log reads as if the rule
  is working. Details: `references/runtime-concepts.md` → DSL Exit Engine.

## 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                           # the job's verified report (read-only); poll it with deploy.py status, below
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. Then run
**`python3 deploy.py status`** until the job is terminal (it calls the gateway directly, ~1 s per read)
and relay its report; do NOT re-run `create` to check on a deploy.

**`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 <runtime_id> — 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 <runtime_id>.` 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 <runtime_id> --name runtime.updated   # an entry for this apply (code-only edits too)
openclaw senpi update ./pkg --id <runtime_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 — the daily loss and drawdown halts
**latch**: they stay CLOSED after PnL recovers and survive restarts; a latched halt is the user's call, never
clear it or resume entries without their explicit approval → `senpi-strategy-author/references/risk-gates.md`), `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`.

**Trade approvals (OpenClaw 10.x).** `status` can also begin with one box-level line, `WARNING trade
approvals: this box cannot tell chat turns from scheduled runs, so every run is asked, scheduled ones
included. Reason: <reason>.` It appears whatever the runtimes say, and only on an OpenClaw 10.x box
whose config needs a fix (the reason names the setting). Relay it to the user as a box setup problem
for Senpi support; nothing on the strategy side changes it. On OpenClaw 5.x there is no such line:
every run is asked there by design. `--json` carries the same fact as `approvals.turnClassification`
(`available` / `unavailable`, with `reason`, and `hostLimit: true` on 5.x). The `WARNING trade
approvals` line is about the box, not a runtime: it does not mean a runtime is unhealthy, and its
absence on 5.x is normal. When the box can classify runs, a trade tool that needs approval asks the
user only from a direct chat turn. From a cron or heartbeat run, or another background run, the call
is refused before it runs: `The trade was not executed: <tool> needs the user's approval, and this
scheduled run (cron) has no way to ask for it. …`. Nothing was executed. Do what the refusal says:
tell the user what you were about to do and that they can ask for it in chat, and do not retry it from
that run through another tool or script. A trade the user set to "Always allow" runs in any run kind.

**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`.

© Senpi · Apache-2.0 · Senpi-ai/senpi-skills

Similar skills

All skills for Finance and business →

Project sponsors

Companies that keep this analytics open