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
This branch runs the strategy corpus on Aftermath Perpetuals V2 through one adapter, rather than porting 99 packages individually. Hyperliquid is removed from the execution path — not proxied underneath it.
Nothing is armed. Every strategy ships disabled, no transaction is signed or submitted, and no submit route exists in any transport allowlist.
git clone <this repo> && cd senpi-skills-af
# 1. One secret: your wallet ADDRESS. Never a key.
cp .env.example .env
$EDITOR .env # set AF_WALLET_ADDRESS
# 2. Preflight. Prints a pass/fail table, exits non-zero on failure.
set -a && . ./.env && set +a
python3 -m aftermath_runtime doctor
# 3. What the adapter can and cannot serve.
python3 -m aftermath_runtime coverage
# 4. Everything, offline, with the network denied process-wide.
python3 ci/run_offline_tests.pydoctor needs no network. To check the live API as well:
AFTERMATH_ALLOW_LIVE_READS=1 python3 -m aftermath_runtime doctor --livePython 3.12, standard library only. No dependencies to install.
| One adapter | aftermath_runtime/adapter.py — the upstream MCP tool surface, served by Aftermath V2. Every strategy goes through it; no strategy file talks to the API. |
| Mock twin | aftermath_runtime/mock.py — interface-identical, zero network, zero keys. Parity is enforced by a test. |
| Gas, your choice | sponsored (default, needs no SUI) · self · dynamic (you pick the coin). One config value. |
| Atomic primitives | cancel-and-place-orders for every requote, place-scale-order for ladders, a composed onboarding PTB. |
| A gate you cannot skip | build → preview → inspect → (would-sign) → reconcile. sign_inspected() accepts only what inspect() produces. |
| Safety in the adapter | circuit breakers, a heartbeat kill switch with verified cancellation, SIGINT/SIGTERM cancel-all, serialised deposits, refresh-after-mutation. |
No markets are live on Aftermath yet. Zero markets is expected before the
relaunch. doctor warns; it never fails. Strategies will simply find nothing to
trade.
The vendored skills name a dead host. AFTERMATH_SKILLS_REF/ is pinned to
AftermathFinance/skills@5b614db and is correct about V2 features — but names
the retired API host in 22 places and the live one in zero. The live OpenAPI
document carries the same trap in its own servers block. Take their patterns,
never their URLs; see
AFTERMATH_SKILLS_REF/README-DELTA.md.
The host is defined exactly once, in aftermath_runtime/config.py, and a test
fails if it leaks anywhere else.
Every variable is documented with a safe default in
.env.example. Only AF_WALLET_ADDRESS is required.
| variable | default | meaning |
|---|---|---|
AF_WALLET_ADDRESS |
— | required. Your Sui wallet address. Never a key. |
AF_GAS_MODE |
sponsored |
sponsored · self · dynamic |
AF_GAS_COIN_TYPE |
— | required for dynamic: which coin pays gas |
AF_GAS_BUDGET_MIST |
50000000 |
always explicit, never auto-estimated |
AF_ARMED |
unset | the single flag that allows a transaction to be BUILT |
AF_API_BASE_URL |
https://v2-preview.aftermath.finance |
production mainnet, despite the hostname |
AF_COLLATERAL_COIN_TYPE |
USDC on Sui | doctor verifies markets exist for it |
AF_ACCOUNT_ID |
auto | discovered via POST /api/perpetuals/accounts/owned |
Upstream Senpi is pinned to c3ef08a670581cd20a9d80df17d36f13266605ae and its
strategies/ tree is byte-for-byte untouched (CI enforces it). The Aftermath
integration contract is pinned independently to
AftermathFinance/skills@5b614db62dcd2e58f442e93661f608fe7b073c32
(aftermath-perpetuals v3.0.0) plus the V2-preview OpenAPI digest, and the
vendored bytes are verified against their SHA-256 digests on every run.
No strategy is enabled until the Aftermath field, market, sizing, and execution
contracts pass. See aftermath-overlay/README.md,
the generated coverage summary, and the
generated field matrices.
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.
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.
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.
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. Itsinstances[]array is what makes a package expand into 1–N deployed strategies, one wallet each, split byfunding_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 supervisesscan(), calling it everyinterval_secondsand 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; runsenpi-trading-runtime/scripts/gen_catalog.py).senpi-strategy-discoverranks it.
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.
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 80+ templates span the full cross-asset spectrum (majors, alts, universe crypto, XYZ equities, commodities, indices, pre-IPO) at 3–10× leverage, 70 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 | 14 | Buy the break, gated on trend + smart money | Hawk, Badger, Condor, Orca |
| Structural / neutral | 10 | Non-directional (DCA, market-neutral, thematic) | Tortoise (DCA), Turbine, Cougar |
| Contrarian / fade | 8 | Fade crowding once it exhausts | Camel (funding), Owl, Pangolin |
| Copy-trading | 8 | Mirror proven traders | Albatross, Jackal, Whalehunter |
| Macro thesis | 3 | Read the regime, set a posture, rotate by attrition | Chimp (daily), Gorilla (weekly) |
| Event-driven | 1 | IPO / new-listing convexity | Magpie |
| Risk parity | 1 | Equal-risk across uncorrelated classes | Ox |
| 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 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 everyinterval_seconds.inputsare the config fromruntime.yaml;ctxgives youctx.senpi_mcp.call_tool(...)(read market/discovery/leaderboard data) andctx.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 viaopenclaw senpi events / explain / audit. This is the observability layer: it's whatsenpi-improve-tradesmines 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
maxMajorceiling), so agents pick up improvements without manual re-installs.
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 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 senpi-strategy-ops/scripts/close.py <id>To build a new strategy, start with senpi-strategy-author and the senpi-trading-runtime contract.
- An OpenClaw agent host (Linux, Python 3.8+) with the
@senpi-ai/runtimeplugin - A funded Hyperliquid wallet per strategy instance (no shared capital)
- A Senpi MCP access token (
SENPI_AUTH_TOKEN)
senpi-skills/
├── senpi-portfolio/ senpi-market-pulse/ senpi-smart-money/ ← analyze
│ senpi-trader-research/ senpi-improve-trades/ senpi-account-status/
├── 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
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.