Skip to content
Back to search

senpi-skills

Open-source AI agent skills + 80+ strategy templates for autonomous trading on Hyperliquid — build, deploy, and protect strategies across crypto, equities, commodities & indices, with two-phase trailing-stop (DSL) exits.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/senpi-ai/senpi-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/senpi-ai/senpi-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/senpi-ai--senpi-skills/badge.svg)](/listings/senpi-ai--senpi-skills)

HTML

<a href="/listings/senpi-ai--senpi-skills"><img src="/api/listings/senpi-ai--senpi-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The fastest path is to **[deploy an agent directly on senpi.ai](https://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](https://openclaw.ai) 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`](senpi-strategy-author/) and the [`senpi-trading-runtime`](senpi-trading-runtime/) contract.

Requirements

- An [OpenClaw](https://openclaw.ai) agent host (Linux, Python 3.8+) with the `@senpi-ai/runtime` plugin - A funded Hyperliquid wallet per strategy instance (no shared capital) - A [Senpi](https://senpi.ai) MCP access token (`SENPI_AUTH_TOKEN`)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 212 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Senpi — Open-Source AI Trading for Hyperliquid
  2. **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.**
  3. This repository is the **open-source layer** of the Senpi Hyperliquid AI Harness: the [skills](#the-skills) that give a Senpi agent its trading capabilities, and the [strategy templates](#the-strategy-templates) it can deploy. MIT-licensed, readable, forkable.
  4. **Deploy an agent:** [senpi.ai](https://senpi.ai) · **Arena:** [senpi.ai/arena](https://senpi.ai/arena) · **Exchange:** [Hyperliquid](https://hyperliquid.xyz)
  5. ---
  6. ## The Senpi Hyperliquid AI Harness
  7. 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.
  8. ```
  9. ┌─────────────────────────────────────────────┐
  10. You (chat) ────▶ │ Senpi Samurai — the model │ tuned for Hyperliquid
  11. │ not a generalist in a trading costume │
  12. └───────────────────────┬─────────────────────┘
  13. │
  14. ┌───────────────────────▼─────────────────────┐
  15. │ OpenClaw host + agent workspace │ AGENTS.md: skills-first routing,
  16. │ (memory, guardrails, heartbeats) │ guardrails, name-free
  17. └───────────────────────┬─────────────────────┘
  18. │ match intent → skill
  19. ┌───────────────────────▼─────────────────────┐
  20. │ SKILLS (this repo, open source) │ 12 skills: analyze, discover,
  21. │ hidden-engine pattern: script → JSON → talk│ author, deploy, review …
  22. └───────────────────────┬─────────────────────┘
  23. │ call tools
  24. ┌───────────────────────▼─────────────────────┐
  25. │ Senpi MCP surface (62 tools) │ market · discovery · leaderboard
  26. │ market / strategy / execution / DSL / … │ strategy · execution · ratchet-stop
  27. └───────────────────────┬─────────────────────┘
  28. │
  29. ┌───────────────────────▼─────────────────────┐
  30. │ @senpi-ai/runtime — the supervisor plugin │ runs scan(inputs, ctx) on interval,
  31. │ scan() · sizing · risk gates · two-phase │ owns execution + the DSL exits
  32. │ DSL exits · telemetry event log │
  33. └───────────────────────┬─────────────────────┘
  34. │
  35. ┌──────▼──────┐
  36. │ Hyperliquid │ perps: ~230 crypto + ~135 equities/
  37. └─────────────┘ metals/indices/pre-IPO, 24/7
  38. ```
  39. **What's open source (this repo):** the **skills** and the **strategy templates** — the parts you'd want to read, audit, fork, or contribute to.
  40. **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).
  41. 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.
  42. ---
  43. ## The skills
  44. 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).
  45. 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.
  46. | Skill | Ver | Role |
  47. |---|---|---|
  48. | **Analyze** | | |
  49. | [`senpi-portfolio`](senpi-portfolio/) | 1.38.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 |
  50. | [`senpi-market-pulse`](senpi-market-pulse/) | 1.11.0 | Daily cross-asset market read (crypto, equities, commodities, macro, funding regime); the positions check includes your saved wallets, read-only |
  51. | [`senpi-smart-money`](senpi-smart-money/) | 1.8.0 | Where the most-profitable wallets are positioned vs. the crowd, and what they just did; the alignment check includes your saved wallets, read-only |
  52. | [`senpi-signals`](senpi-signals/) | 2.12.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 |
  53. | [`senpi-trader-research`](senpi-trader-research/) | 1.8.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 |
  54. | [`senpi-improve-trades`](senpi-improve-trades/) | 1.25.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 |
  55. | [`quant-desk`](quant-desk/) | 1.50.0 | **Quant Desk** — the desk your AI Quant produces. "run AI quant" / "run quant" / "run quant desk" on **any** Hyperliquid address → 90 days of fills, fees, funding; six 0–100 dimensions, a quant score, leaks priced as charged counterfactuals, protection audit, you vs the proven and hot cohorts, market fit, where your edge is. No address? It finds you candidates by account size. A senpi user's whole book — every strategy wallet, closed ones included — is one desk via `--book`. Public data, read-only; Senpi discovery when a token is present |
  56. | [`senpi-account-status`](senpi-account-status/) | 1.10.0 | Points and rank, the Senpi trading fee (none on a paid plan), referrals — and the AI-credits usage meter: chat + tool turns spend plan credits; not trading money; the balance is the meter in the app header, which no tool reads. Carries the plan catalog (Pro/Advanced/Quant; Starter closed to new subscribers), the end of the free-credit milestones, and what a lapsed plan pauses (the agent and every strategy on it) |
  57. | **Run a strategy** | | |
  58. | [`senpi-strategy-discover`](senpi-strategy-discover/) | 2.57.0 | Conversational picker — rank the catalog against your worldview; each pick's exits and position size quoted from its full card; holdings context includes your saved wallets (read-only, never a budget) |
  59. | [`senpi-strategy-author`](senpi-strategy-author/) | 3.17.0 | Build/edit a DSL-protected strategy package, one decision at a time |
  60. | [`senpi-strategy-ops`](senpi-strategy-ops/) | 3.32.0 | Deploy / monitor / close a named strategy (`deploy.py`, `close.py`) |
  61. | [`senpi-trade`](senpi-trade/) | 1.12.0 | Direct trade or mirror a specific trader — manual positions + copy trading, one decision at a time |
  62. | [`senpi-trading-runtime`](senpi-trading-runtime/) | 4.1.16 | The runtime contract reference: `scan(inputs, ctx)`, `runtime.yaml`, DSL |
  63. | **Move money / positioning** | | |
  64. | [`senpi-deposit-withdraw-transfer`](senpi-deposit-withdraw-transfer/) | 1.6.4 | The money-movement rails (funds in via the funding card — deposit address or in-card USDC purchase; out via the app); top-ups prechecked against perps and traced to Spot when they fail, withdrawals at the exact available figure, fees stated before money moves |
  65. | [`senpi-why`](senpi-why/) | 1.7.0 | "What makes Senpi different" — your AI quant: reads the market, reviews your trading, runs your strategy 24/7, wherever you trade |
  66. 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.
  67. ---
  68. ## The strategy templates
  69. A **strategy** is a deployable **package** under [`strategies/`](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](https://senpi.ai/arena), where Senpi agents have traded **$30M+ in notional volume**.
  70. ### Package anatomy
  71. ```
  72. strategies/spider/
  73. ├── strategy.yaml ← manifest: id, version, catalog{} (discovery metadata), instances[]
  74. ├── swing/ ← one instance = one wallet (multi-wallet funds have several)
  75. │ ├── runtime.yaml ← the executable spec: strategy, scanners, actions, exit, risk
  76. │ └── scanners/
  77. │ ├── scan.py ← exports scan(inputs, ctx) → list of signals
  78. │ └── scoring.py ← pure, unit-testable thesis math
  79. └── scalp/ … ← a second instance (different cadence, different wallet)
  80. ```
  81. - **`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).
  82. - **`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.**
  83. - **`strategies/catalog.json`** — the generated registry index (never hand-edit; run [`senpi-trading-runtime/scripts/gen_catalog.py`](senpi-trading-runtime/scripts/)). `senpi-strategy-discover` ranks it.
  84. ### Every strategy exits through the DSL
  85. 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:
  86. - **Phase 1 — survive.** A hard stop (`max_loss_pct`) cuts losers fast from entry. This protects the position the moment it opens.
  87. - **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.
  88. That asymmetry — lose small, let winners run — is the engine behind every strategy template.
  89. ### And a risk engine wraps the whole strategy
  90. 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:
  91. - **Circuit breakers** — a daily-loss halt and an intraday drawdown breaker stop trading on a bad day.
  92. - **Turnover brakes** — max-entries-per-day plus consecutive-loss and per-asset cooldowns throttle overtrading, because fees are the quiet killer of every bot.
  93. - **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`).
  94. - **Conviction-weighted sizing** — position size scales off the live account (`margin_pct`) and the signal's own score, not a fixed lot.
  95. The scanner proposes; the runtime's risk engine disposes.
  96. ### The strategy templates, by archetype
  97. 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:
  98. | Archetype | # | What it does | Examples |
  99. |---|---|---|---|
  100. | Trend-following | 22 | Ride durable multi-timeframe trends | Spider, Elephant, Python, Lynx |
  101. | Single-market specialist | 15 | Master one asset deeply | Kodiak (SOL), Coyote (BTC/ETH), Falcon (pre-IPO) |
  102. | Breakout / momentum | 16 | Buy the break, gated on trend + smart money | Hawk, Badger, Hare (crypto session scalp), Kite (SMC/ICT) |
  103. | Structural / neutral | 9 | Non-directional (DCA, market-neutral, thematic) | Tortoise (DCA), Cougar |
  104. | Contrarian / fade | 8 | Fade crowding once it exhausts | Camel (funding), Owl, Pangolin |
  105. | Copy-trading | 9 | Mirror proven traders | Jackal, Whalehunter, Squid (multi-trader fresh-entry mirror) |
  106. | Macro thesis | 4 | Read the regime, set a posture, rotate by attrition | Chimp (daily), Gorilla (weekly), Rotator (3h conviction rebalance) |
  107. | Event-driven | 1 | IPO / new-listing convexity | Magpie |
  108. | Risk parity | 2 | Equal-risk / diversified capital preservation across uncorrelated classes | Ox, Mandate (no-leverage crypto + RWA) |
  109. | Tail-risk | 1 | Standing insurance + crisis convexity | Rhino |
  110. Browse the live set with `senpi-strategy-discover` rather than any hand-maintained list — the catalog is the source of truth.
  111. ---
  112. ## The runtime contract (`@senpi-ai/runtime`)
  113. The supervisor that turns a package into a live, risk-managed strategy. A strategy author only writes `scan()` + config; the runtime owns the rest.
  114. - **`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.
  115. - **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`, …).
  116. - **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`).
  117. - **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.
  118. - **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.
  119. ---
  120. ## Getting started
  121. The fastest path is to **[deploy an agent directly on senpi.ai](https://senpi.ai)** — it stands up a full agent host (the runtime plugin + Senpi MCP) for you, no infra to run.
  122. To run a strategy by hand on your own [OpenClaw](https://openclaw.ai) host:
  123. ```bash
  124. # 1. Install the runtime plugin + configure Senpi MCP (SENPI_AUTH_TOKEN)
  125. openclaw plugins install @senpi-ai/runtime
  126. # 2. Pick a strategy (or ask the agent: "what should I trade?")
  127. # → senpi-strategy-discover ranks strategies/catalog.json against your goals
  128. # 3. Deploy — creates a funded wallet per instance, deploys, verifies the scanner ticked
  129. python3 ~/.openclaw/skills/senpi-strategy-ops/scripts/deploy.py <id> --budget <usd>
  130. # 4. Monitor
  131. openclaw senpi status # liveness; strategy is live once its scanner has a recent tick
  132. # 5. Close — flattens positions, returns funds
  133. python3 ~/.openclaw/skills/senpi-strategy-ops/scripts/close.py <id>
  134. ```
  135. To **build a new strategy**, start with [`senpi-strategy-author`](senpi-strategy-author/) and the [`senpi-trading-runtime`](senpi-trading-runtime/) contract.
  136. ### Requirements
  137. - An [OpenClaw](https://openclaw.ai) agent host (Linux, Python 3.8+) with the `@senpi-ai/runtime` plugin
  138. - A funded Hyperliquid wallet per strategy instance (no shared capital)
  139. - A [Senpi](https://senpi.ai) MCP access token (`SENPI_AUTH_TOKEN`)
  140. ---
  141. ## Repo layout
  142. ```
  143. senpi-skills/
  144. ├── senpi-portfolio/ senpi-market-pulse/ senpi-smart-money/ ← analyze
  145. │ senpi-trader-research/ senpi-improve-trades/ senpi-account-status/ senpi-signals/
  146. ├── senpi-strategy-discover/ senpi-strategy-author/ ← run a strategy
  147. │ senpi-strategy-ops/ senpi-trading-runtime/
  148. ├── senpi-deposit-withdraw-transfer/ senpi-why/ ← money / positioning
  149. │
  150. ├── strategies/ ← 80+ strategy packages + the registry
  151. │ ├── catalog.json ← GENERATED index
  152. │ └── <id>/ … ← strategy.yaml + <instance>/{runtime.yaml, scanners/}
  153. │
  154. └── CLAUDE.md ← repo conventions for AI editors
  155. ```
  156. ## License
  157. MIT — Built by [Senpi](https://senpi.ai). Backed by [Lemniscap](https://lemniscap.com) and [Coinbase Ventures](https://www.coinbase.com/ventures).
  158. > 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.