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 + ~135 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.36.0 | All-wallet portfolio, positions, DSL protection, per-strategy mandate reads; every wallet — Senpi and the ones you added — in one list by value, managed and read-only subtotals |
senpi-market-pulse | 1.10.0 | Daily cross-asset market read (crypto, equities, commodities, macro, funding regime); the positions check includes your saved wallets, read-only |
senpi-smart-money | 1.7.0 | Where the most-profitable wallets are positioned vs. the crowd; the alignment check includes your saved wallets, read-only |
senpi-signals | 2.11.0 | Non-obvious market developments (funding extremes, proven cohort vs the 4h crowd, momentum events, cross-asset laggards), ranked through a trade lens and a news lens — read from Senpi's backend, the same Senpi Signals the app and the browser extension show; on demand, no cron |
senpi-trader-research | 1.7.0 | Rank + vet Hyperliquid traders before copying them (mirror-aware: copyability, min-budget, live book); your saved wallets go to the quant desk, never the copy shortlist |
senpi-improve-trades | 1.24.0 | Retrospective review + health checks off the telemetry event log: PnL net of fees, exit quality, peak-to-exit give-back, missed signals, leaks, crashes; your saved wallets reviewed read-only as manual trades, in one book with your Senpi strategies ordered by value |
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, pre-IPO) at 1–10× leverage, 74 advanced / 13 starter, mostly long/short. The range is deliberate — directional and market-neutral, single-asset and whole-universe, momentum and mean-reversion, copy-trading and macro, everyday starters and crisis insurance:
| Archetype | # | What it does | Examples |
|---|
| Trend-following | 22 | Ride durable multi-timeframe trends | Spider, Elephant, Python, Lynx |
| Single-market specialist | 15 | Master one asset deeply | Kodiak (SOL), Coyote (BTC/ETH), Falcon (pre-IPO) |
| Breakout / momentum | 16 | Buy the break, gated on trend + smart money | Hawk, Badger, Hare (crypto session scalp), Kite (SMC/ICT) |
| Structural / neutral | 9 | Non-directional (DCA, market-neutral, thematic) | Tortoise (DCA), Cougar |
| Contrarian / fade | 8 | Fade crowding once it exhausts | Camel (funding), Owl, Pangolin |
| Copy-trading | 9 | Mirror proven traders | Jackal, Whalehunter, Shadow (multi-trader fresh-entry mirror) |
| Macro thesis | 4 | Read the regime, set a posture, rotate by attrition | Chimp (daily), Gorilla (weekly), Rotator (3h conviction rebalance) |
| Event-driven | 1 | IPO / new-listing convexity | Magpie |
| Risk parity | 2 | Equal-risk / diversified capital preservation across uncorrelated classes | Ox, Mandate (no-leverage crypto + RWA) |
| Tail-risk | 1 | Standing insurance + crisis convexity | Rhino |
Browse the live set with senpi-strategy-discover rather than any hand-maintained list — the catalog is the source of truth.
The runtime contract (@senpi-ai/runtime)
The supervisor that turns a package into a live, risk-managed strategy. A strategy author only writes scan() + config; the runtime owns the rest.
scan(inputs, ctx) — your scanner, called every interval_seconds. inputs are the config from runtime.yaml; ctx gives you ctx.senpi_mcp.call_tool(...) (read market/discovery/leaderboard data) and ctx.state (a bounded, persistent per-scanner store for dedup/history). You return signals ({score, direction, ...}); you never place an order.- Two-phase DSL exit engine — a pure tick function evaluates hard-timeout → dead-weight → weak-peak → phase-1 breach → phase-2 tier advance on every price update, and emits typed close reasons (
tier_breach, max_retrace, trailing_floor, weak_peak, hard_timeout, …).
- Risk guard rails — daily-loss halt, drawdown circuit breaker, consecutive-loss + per-asset cooldowns, max-entries-per-day turnover cap. Blocked signals are logged with a reason code (
no_slots, no_margin, risk_gate_*, asset_banned).
- Telemetry event log — every decision an agent makes is recorded to a per-strategy on-disk event stream (
position.opened, dsl.created/tier_advanced/closed, signal.outcome, order.filled/failed, runtime.paused, …), readable via openclaw senpi events / explain / audit. This is the observability layer: it's what senpi-improve-trades mines for exit quality, leaks, blocked signals, and health checks (crashes, missed runs, protection gaps) — so an agent can review and improve its own work, and you can see exactly what it did and why.
- Skills auto-upgrade — a manifest-driven coordinator keeps installed skills current (semver-gated by a
maxMajor ceiling), so agents pick up improvements without manual re-installs.
Getting started
The fastest path is to deploy an agent directly on senpi.ai — it stands up a full agent host (the runtime plugin + Senpi MCP) for you, no infra to run.
To run a strategy by hand on your own OpenClaw host:
# 1. Install the runtime plugin + configure Senpi MCP (SENPI_AUTH_TOKEN)
openclaw plugins install @senpi-ai/runtime
# 2. Pick a strategy (or ask the agent: "what should I trade?")
# → senpi-strategy-discover ranks strategies/catalog.json against your goals
# 3. Deploy — creates a funded wallet per instance, deploys, verifies the scanner ticked
python3 ~/.openclaw/skills/senpi-strategy-ops/scripts/deploy.py <id> --budget <usd>
# 4. Monitor
openclaw senpi status # liveness; strategy is live once its scanner has a recent tick
# 5. Close — flattens positions, returns funds
python3 ~/.openclaw/skills/senpi-strategy-ops/scripts/close.py <id>
To build a new strategy, start with senpi-strategy-author and the senpi-trading-runtime contract.
Requirements
- An OpenClaw agent host (Linux, Python 3.8+) with the
@senpi-ai/runtime plugin
- A funded Hyperliquid wallet per strategy instance (no shared capital)
- A Senpi MCP access token (
SENPI_AUTH_TOKEN)
Repo layout
senpi-skills/
├── senpi-portfolio/ senpi-market-pulse/ senpi-smart-money/ ← analyze
│ senpi-trader-research/ senpi-improve-trades/ senpi-account-status/ senpi-signals/
├── senpi-strategy-discover/ senpi-strategy-author/ ← run a strategy
│ senpi-strategy-ops/ senpi-trading-runtime/
├── senpi-deposit-withdraw-transfer/ senpi-why/ ← money / positioning
│
├── strategies/ ← 80+ strategy packages + the registry
│ ├── catalog.json ← GENERATED index
│ └── <id>/ … ← strategy.yaml + <instance>/{runtime.yaml, scanners/}
│
└── CLAUDE.md ← repo conventions for AI editors
License
MIT — Built by Senpi. Backed by Lemniscap and Coinbase Ventures.
Trading perpetual futures carries substantial risk of loss. Senpi is software, not financial advice; strategies can and do lose money. Nothing here is a promise of returns.
