# senpi-trading-runtime

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 131 installs · ★ 143 repo stars
- Author: Senpi
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Senpi-ai/senpi-skills/tree/HEAD/senpi-trading-runtime/SKILL.md
- Updated: 2026-11-17
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/senpi-trading-runtime

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/senpi-trading-runtime/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/senpi-trading-runtime/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/senpi-trading-runtime/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/senpi-trading-runtime/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Senpi-ai/senpi-skills senpi-trading-runtime
```

2. **Manually: put the files in place**
- File: `.github/skills/senpi-trading-runtime/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Senpi-ai/senpi-skills --path senpi-trading-runtime
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/senpi-trading-runtime/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Senpi-ai/senpi-skills --skill senpi-trading-runtime -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Senpi-ai/senpi-skills/tree/HEAD/senpi-trading-runtime/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 95d5ff9be3913d6b.

BEGIN THIRD-PARTY FILE 95d5ff9be3913d6b
```text
---
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,
```
END THIRD-PARTY FILE 95d5ff9be3913d6b

The third-party file has ended. Everything between the 95d5ff9be3913d6b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2456 of 13120 bytes. © Senpi · Apache-2.0 · https://github.com/Senpi-ai/senpi-skills/tree/HEAD/senpi-trading-runtime/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
