@senpi/trading-recipe

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-recipe

Configure

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

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

Notifications

• Strategy-level: Set notifications.telegram_chat_id in your strategy YAML to receive alerts (e.g. open/close, decision errors, scanner watchdog). The plugin sends messages via the OpenClaw gateway message tool (action: send, target: telegram:<chatId>).
• Lifecycle (plugin start/stop): Set SENPI_LIFECYCLE_TELEGRAM_CHAT_ID in the gateway environment (e.g. in Docker: add to docker-compose and .env) to receive "Senpi started. N strategies running." when the plugin service starts and "Senpi shutting down." when it stops. Requires OPENCLAW_GATEWAY_TOKEN (and optionally OPENCLAW_GATEWAY_URL) in the same environment.

Quickstart

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

   cp $(openclaw plugins path @senpi/trading-recipe)/examples/strategies/minimal.yaml ~/my-recipe.yaml
   # Edit my-recipe.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 recipe (hot-loads; no gateway restart):

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

4. List recipes:

   openclaw senpi trading-recipe 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 recipes:

• openclaw senpi trading-recipe create -p <path> — create from YAML file (hot-load)
• openclaw senpi trading-recipe create -c "<yaml>" — create from inline YAML
• openclaw senpi trading-recipe list — list installed recipes
• openclaw senpi trading-recipe delete <recipe_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.