@senpi/trading-runtime

Event-driven automated trading plugin for OpenClaw. Orchestrates scanners, LLM-based trade decisions, and a DSL trailing stop-loss exit engine.

Prerequisites

• OpenClaw >= 2026.2.0
• Node >= 22
• Senpi API key (for live trading)

Install

openclaw plugins install @senpi/trading-runtime

Configure

Add the plugin to your OpenClaw config (e.g. ~/.openclaw/openclaw.json or via openclaw config set). Use the plugin id trading-runtime as the key:

{
  "plugins": {
    "entries": {
      "trading-runtime": {
        "enabled": true,
        "config": {
          "stateDir": "~/.openclaw/senpi-state",
          "apiKey": "YOUR_SENPI_API_KEY"
        }
      }
    }
  }
}

Quickstart

1. Copy a minimal strategy template and set your wallet:

   cp $(openclaw plugins path @senpi/trading-runtime)/examples/strategies/minimal.yaml ~/my-strategy.yaml
   # Edit my-strategy.yaml: replace ${WALLET_ADDRESS} or set WALLET_ADDRESS in env

2. Set environment variables (e.g. .env): SENPI_API_KEY, WALLET_ADDRESS.

3. Load the strategy (hot-loads; no gateway restart):

   openclaw senpi trading-strategy create -p ~/my-strategy.yaml

4. List strategies:

   openclaw senpi trading-strategy list

5. Watch gateway logs for scanner runs and signal processing.

Strategy templates

| File | Style | Scanners | Use case | |------|-------|----------|----------| | minimal.yaml | Watch-only | emerging_movers | Verify setup; no positions | | wolf.yaml | Aggressive | emerging_movers | Early entry on FIRST_JUMP | | viper.yaml | Moderate | prescreener + momentum | Candle-based breakouts | | fox.yaml | OI-driven | prescreener + oi_tracker | OI-driven entries | | dsl-showcase.yaml | DSL reference | emerging_movers | Annotated exit config |

Templates live under examples/strategies/ in the package. See examples/strategies/README.md.

CLI reference

Trading strategies:

• openclaw senpi trading-strategy create -p <path> — create from YAML file (hot-load)
• openclaw senpi trading-strategy create -c "<yaml>" — create from inline YAML
• openclaw senpi trading-strategy list — list installed strategies
• openclaw senpi trading-strategy delete <trading_strategy_id> — remove by id

In-shell reference:

• openclaw senpi guide — overview
• openclaw senpi guide scanners — scanner types and config fields
• openclaw senpi guide actions — action types and decision modes
• openclaw senpi guide dsl — DSL two-phase exit engine
• openclaw senpi guide examples — print minimal strategy YAML
• openclaw senpi guide schema — full YAML schema
• openclaw senpi guide version — plugin version and changelog URL

Guide skill

Once published, the @senpi-guide skill on ClawHub provides the same reference in chat. Install with clawhub install skills/senpi-guide/ (or from the ClawHub UI).

Install on an existing OpenClaw setup

If you already have OpenClaw installed (local, VPS, or self-hosted), see Installing on existing OpenClaw for the full install sequence, config stanza, and troubleshooting.

Docs

• Architecture
• Skills YAML schema
• Integration guide
• Runtime API

Changelog

CHANGELOG.md

Development

npm run build   # install deps + compile TypeScript
npm test        # unit + integration tests (no credentials required)
npm run dev     # build + run

Pre-commit runs npm run build && npm test. See CLAUDE.md and docs/runtime-docs/ for conventions and design.