npm package: @senpi/trading-runtime
Description: Trading runtime plugin for OpenClaw
Latest version: 1.0.20

# @senpi/trading-runtime

[![npm version](https://img.shields.io/npm/v/@senpi/trading-runtime.svg)](https://www.npmjs.com/package/@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

```bash
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:

```json
{
  "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:
   ```bash
   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):
   ```bash
   openclaw senpi trading-strategy create -p ~/my-strategy.yaml
   ```

4. List strategies:
   ```bash
   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](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](docs/install/existing-openclaw.md) for the full install sequence, config stanza, and troubleshooting.

## Docs

- [Architecture](docs/runtime-docs/design/architecture.md)
- [Skills YAML schema](docs/runtime-docs/design/skills-yaml-schema.md)
- [Integration guide](docs/runtime-docs/integration-guide.md)
- [Runtime API](docs/runtime-docs/runtime-api.md)

## Changelog

[CHANGELOG.md](CHANGELOG.md)

## Development

```bash
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](CLAUDE.md) and [docs/runtime-docs/](docs/runtime-docs/) for conventions and design.