Senpi — Open-Source AI Trading for Hyperliquid

An AI that runs your Hyperliquid strategy 24/7 — reads the whole market, finds the edge, sizes the trade, and protects the position while you sleep.

This repository is the open-source layer of the Senpi Hyperliquid AI Harness: the skills that give a Senpi agent its trading capabilities, and the strategy templates it can deploy. MIT-licensed, readable, forkable.

Deploy an agent: senpi.ai · Arena: senpi.ai/arena · Exchange: Hyperliquid

---

The Senpi Hyperliquid AI Harness

Senpi 2.0 isn't a chatbot with a trading API bolted on. It's a harness — a disciplined stack that wraps a market-tuned AI model in deterministic execution and risk machinery, so an autonomous agent can trade real capital without hallucinating a position or forgetting a stop.

                    ┌─────────────────────────────────────────────┐
   You (chat) ────▶ │  Senpi Samurai  — the model                 │   tuned for Hyperliquid
                    │  not a generalist in a trading costume      │
                    └───────────────────────┬─────────────────────┘
                                            │
                    ┌───────────────────────▼─────────────────────┐
                    │  OpenClaw host + agent workspace            │   AGENTS.md: skills-first routing,
                    │  (memory, guardrails, heartbeats)           │   guardrails, name-free
                    └───────────────────────┬─────────────────────┘
                                            │  match intent → skill
                    ┌───────────────────────▼─────────────────────┐
                    │  SKILLS  (this repo, open source)           │   12 skills: analyze, discover,
                    │  hidden-engine pattern: script → JSON → talk│   author, deploy, review …
                    └───────────────────────┬─────────────────────┘
                                            │  call tools
                    ┌───────────────────────▼─────────────────────┐
                    │  Senpi MCP surface  (62 tools)               │   market · discovery · leaderboard
                    │  market / strategy / execution / DSL / …    │   strategy · execution · ratchet-stop
                    └───────────────────────┬─────────────────────┘
                                            │
                    ┌───────────────────────▼─────────────────────┐
                    │  @senpi-ai/runtime  — the supervisor plugin │   runs scan(inputs, ctx) on interval,
                    │  scan() · sizing · risk gates · two-phase   │   owns execution + the DSL exits
                    │  DSL exits · telemetry event log            │
                    └───────────────────────┬─────────────────────┘
                                            │
                                     ┌──────▼──────┐
                                     │ Hyperliquid │   perps: ~230 crypto + ~95 equities/
                                     └─────────────┘   metals/indices/pre-IPO, 24/7

What's open source (this repo): the skills and the strategy templates — the parts you'd want to read, audit, fork, or contribute to. What's the platform: the Samurai model, the OpenClaw host integration, the MCP backend, and the @senpi-ai/runtime supervisor (installed as a managed plugin).

The two talk through a clean contract: skills call MCP tools; strategies export scan(inputs, ctx); the runtime owns everything downstream. Nothing in this repo places an order directly — it goes through the supervised runtime, which is where sizing, risk, and exits live.

---

The skills

A Senpi agent's capabilities are skills — each one packages the right multi-step workflow for a class of request, so the model reaches for a proven path instead of hand-assembling raw tool calls (a known source of double-counted collateral, misread sub-wallets, and "your position is unprotected" false alarms).

Every analytical skill follows the hidden-engine pattern: a vendored, stdlib-only mcp_client.py + a deterministic Python engine that emits structured JSON + a SKILL.md that narrates the result under hard guardrails (no fabricated forward numbers, honest data sourcing, process-over-outcome). The engine gathers and computes; the model judges and explains.

| Skill | Ver | Role | |---|---|---| | Analyze | | | | senpi-portfolio | 1.7.1 | All-wallet portfolio, positions, DSL protection, per-strategy mandate reads | | senpi-market-pulse | 1.1.1 | Daily cross-asset market read (crypto, equities, commodities, macro, funding regime) | | senpi-smart-money | 1.1.1 | Where the most-profitable wallets are positioned vs. the crowd | | senpi-trader-research | 1.0.2 | Rank + vet Hyperliquid traders before copying them | | senpi-improve-trades | 1.1.1 | Retrospective review + health checks off the telemetry event log: exit quality, missed signals, leaks, crashes, "if I'd held" counterfactual | | senpi-account-status | 1.1.1 | Points, loyalty tier, fees, Arena standing, referrals | | Run a strategy | | | | senpi-strategy-discover | 2.3.0 | Conversational picker — rank the catalog against your worldview | | senpi-strategy-author | 2.4.2 | Build/edit a DSL-protected strategy package, one decision at a time | | senpi-strategy-ops | 2.2.1 | Deploy / monitor / close a named strategy (deploy.py, close.py) | | senpi-trading-runtime | 3.0.2 | The runtime contract reference: scan(inputs, ctx), runtime.yaml, DSL | | Move money / positioning | | | | senpi-deposit-withdraw-transfer | 1.0.1 | The money-movement rails (funds in via embedded wallet; out via the app) | | senpi-why | 1.0.3 | "Why Senpi / vs. other tools" — the positioning answer |

Skills compose: improve-trades pulls in market-pulse + smart-money + portfolio; discover hands a chosen package to ops; author hands a built package to ops. The agent routes by intent, not keywords, and never re-implements one skill inside another.

---

The strategy templates

A strategy is a deployable package under strategies/ — a market thesis compiled into scanner logic + risk config + exits, that runs on its own funded wallet. There are 80+ in the catalog today, forward-tested across $10M+ in notional trade value and battle-tested in the public Agents Arena, where Senpi agents have traded $30M+ in notional volume.

Package anatomy

strategies/spider/
├── strategy.yaml            ← manifest: id, version, catalog{} (discovery metadata), instances[]
├── swing/                   ← one instance = one wallet (multi-wallet funds have several)
│   ├── runtime.yaml         ← the executable spec: strategy, scanners, actions, exit, risk
│   └── scanners/
│       ├── scan.py          ← exports scan(inputs, ctx) → list of signals
│       └── scoring.py       ← pure, unit-testable thesis math
└── scalp/  …                ← a second instance (different cadence, different wallet)

• strategy.yaml — source of truth for deploy + attribution. Its instances[] array is what makes a package expand into 1–N deployed strategies, one wallet each, split by funding_share. 21 of them are multi-wallet (e.g. long+short funds, core+ballast, hedge+escalation).
• runtime.yaml — the runtime's self-contained spec. The runtime spawns and supervises scan(), calling it every interval_seconds and owning everything after: signal validation, conviction-weighted sizing (margin_pct), execution (FEE_OPTIMIZED_LIMIT), slot accounting, risk.guard_rails, and the DSL exits. No separate scanner daemon.
• strategies/catalog.json — the generated registry index (never hand-edit; run senpi-trading-runtime/scripts/gen_catalog.py). senpi-strategy-discover ranks it.

Every strategy exits through the DSL

There are no manual close actions. Exits are 100% owned by the runtime's two-phase DSL (Dynamic Stop-Loss), configured in each runtime.yaml's exit: block:

• Phase 1 — survive. A hard stop (max_loss_pct) cuts losers fast from entry. This protects the position the moment it opens.
• Phase 2 — lock. As a winner runs, a ratcheting ladder of tiers[] (trigger_pct → lock_hw_pct) trails the stop upward, banking a growing share of the high-water mark while keeping the tail alive.

That asymmetry — lose small, let winners run — is the engine behind every strategy template.

And a risk engine wraps the whole strategy

The DSL protects each position; a portfolio-level risk engine governs the whole strategy — deterministic guards the model can't prompt its way around, enforced every tick:

• Circuit breakers — a daily-loss halt and an intraday drawdown breaker stop trading on a bad day.
• Turnover brakes — max-entries-per-day plus consecutive-loss and per-asset cooldowns throttle overtrading, because fees are the quiet killer of every bot.
• Hard gates — margin, notional, and leverage limits reject any signal that would breach them, each logged with a reason code (no_slots, no_margin, risk_gate_*, asset_banned).
• Conviction-weighted sizing — position size scales off the live account (margin_pct) and the signal's own score, not a fixed lot.

The scanner proposes; the runtime's risk engine disposes.

The strategy templates, by archetype

The 80+ templates span the full cross-asset spectrum (majors, alts, universe crypto, XYZ equities, commodities, indices