[new-plugin] hyperliquid-aigrid v1.2.6

[dddd86971-cloud]

[new-plugin] hyperliquid-aigrid v1.2.0

Season 1 Developer Challenge submission — strategy plugin for Hyperliquid perps.

This PR replaces #344 (which was titled liqgrid — renamed for clearer brand association with Hyperliquid).

Summary

hyperliquid-aigrid turns a trader's one-sentence Hyperliquid view into a deterministic, risk-capped grid strategy:

User: "BTC 90k-95k range, $300 at 2x"
   ↓
hyperliquid-aigrid Skill (natural-language parsing)
   ├─► hyperliquid-plugin            → mark price + 1h candles
   ├─► api.hyperliquid.xyz/info      → live funding rate (read-only)
   └─► hyperliquid-aigrid binary     → deterministic plan
   ↓
Dry-run plan + 7-day backtest preview:
   • 23 tick-aligned rungs, concentrated near mark
   • funding-tilted ±20% (collects funding as alpha)
   • stop-loss + max-loss bound, hard caps enforced
   ↓
User: "go live"
   ↓
hyperliquid-plugin order ... --strategy-id hyperliquid-aigrid
hyperliquid-plugin tpsl  ... --strategy-id hyperliquid-aigrid
   ↓
Agentic Wallet TEE signing → on-chain fills

What makes it different (vs other Hyperliquid grid Skills)

1. Deterministic binary, not LLM math — grid prices, stop-loss, sizing run in compiled TypeScript engine. Same inputs → byte-identical outputs. Stable planHash SHA-256 fingerprint.
2. Funding rate as alpha — when |annualized funding| ≥ 10%, per-rung notional tilts up to ±20% toward the side that collects funding. Hyperliquid-specific.
3. Concentrated-liquidity rung sizing — Gaussian fill-probability weighting. Mark-near rungs get more capital, edge rungs less. Same total notional, higher expected fill density.
4. 75-combo parameter optimizer (hyperliquid-aigrid optimize) — sweeps 5 widths × 5 leverages × 3 profiles, Calmar-ranked.
5. Built-in backtest (hyperliquid-aigrid backtest) — deterministic candle-by-candle simulation. Realized PnL / max DD / Sharpe before live trading.
6. Zero-friction quickstart (hyperliquid-aigrid quickstart) — given coin + notional + candles, binary picks (rangeLow, rangeHigh, leverage, profile) from recent vol regime.

Safety posture (advanced risk)

• Dry-run by default on every session
• Max $5,000 notional / 10× leverage / 50 rungs (hard-coded in src/types.ts:CAPS)
• Stop-loss bounded to ≤ 30% of notional (warning + explicit user accept above threshold)
• First-session training wheels (capped $200 / 2× regardless of user request)
• No private key handling — all signing via Agentic Wallet TEE through hyperliquid-plugin
• All write ops carry --strategy-id hyperliquid-aigrid for leaderboard attribution

Source

• Repo: dddd86971-cloud/hyperliquid-aigrid
• Pinned commit: aed9868e8950ecb6b49c852bc75e92fd150ecd6d
• Language: TypeScript (compiled to JS, distributed via bun install -g)
• Self-tests: 30 invariants — determinism, cap enforcement, tick alignment, risk-profile monotonicity, input validation, funding bias, concentrated-liquidity sizing, backtest determinism, quickstart, optimize ranking
• License: MIT

Pre-submission checklist

• plugin.yaml, .claude-plugin/plugin.json, SKILL.md, SUMMARY.md, LICENSE all present
• name = hyperliquid-aigrid (lowercase, 18 chars, within 2-40)
• version = 1.2.0 consistent across all three files
• author.github = dddd86971-cloud matches PR author
• license = MIT (valid SPDX)
• category = strategy (per the strategy-plugin spec)
• dependent_plugin = [hyperliquid-plugin@^0.3.9]
• risk_level = advanced, supported_venues = [hyperliquid]
• description = 195 chars (within 200)
• api_calls = ["https://api.hyperliquid.xyz"] (read-only info endpoint for funding + candles)
• All write ops carry --strategy-id hyperliquid-aigrid
• SKILL.md sections: Overview / Pre-flight / Commands / Error Handling / Security Notices
• No hardcoded credentials / private keys / mnemonics
• No pre-compiled binaries committed (CI compiles TS)
• PR only modifies files in skills/hyperliquid-aigrid/
• Source repo binary builds locally (TypeScript → JS, #!/usr/bin/env node shebang on dist/index.js)
• 30/30 self-tests pass

🤖 Generated with Claude Code

[dddd86971-cloud]

v1.2.2 update — purely additive output extension

Source SHA 66bd3f57 → b0fdd423. plugin.yaml version and source_commit bumped accordingly.

What's new:

• 3 new GridPlan output fields (buySideNotionalUsd, sellSideNotionalUsd, rangeWidthPct) — direct visibility of funding-bias tilt and grid geometry without walking levels[].
• expected fills/day < 1 warning — flags grids that would sit idle at current vol; suggests tightening range to ±2σ daily of mark.
• SKILL.md formalizes the REFUSE-prefix abort rule as pre-execution check [new-plugin] test-rust-cli v1.0.0 — E2E verification #3.
• Self-tests: 33 → 37 (4 new cases covering the additions).

planHash is unchanged for the same input bytes — the new fields are derived from existing inputs (levels[], rangeLow, rangeHigh, markPrice) and not part of the hashable spec. Cached planHash references in user UIs / audit logs remain valid.

Same shape as before (no breaking changes), no algorithm shifts, no new caps. Rebased cleanly on origin/main.

[dddd86971-cloud]

v1.2.3 update — notional-aware quickstart range

Source SHA b0fdd423 → dd30dec42. plugin.yaml bumped accordingly.

This fixes a real product gap discovered during live testing: a $24 small-account user calling quickstart got the same ±4-7% range as a $5000 user, which spread their forced 4 rungs across ~1% gaps when hourly vol was only ~0.3%. Result: grid sat inactive for hours waiting for outlier moves.

v1.2.3 picks the tighter of two derivations:

• (a) natural geometry: (rungs - 1) × σ_hourly × profileGap where rungs = clamp(floor(notional × lev / minOrder), 4, 50). Each gap ≈ one hourly σ.
• (b) vol envelope: k × σ_daily × √7 × profileWidth (the old formula, now used only as an upper bound).

Real-world impact at σ_d=1.35% (BTC calm day):

Account	Pre-1.2.3	Post-1.2.3	Source
$24	±4.4%	±0.41%	natural — 4 rungs
$100	±4.4%	±2.61%	natural — 20 rungs
$5000	±4.4%	±4.36%	vol envelope (unchanged)

Plus a tiny notional warning when notional × leverage < MIN_GRID_COUNT × minOrder, with the exact bump amount to restore full coverage.

plan() semantics unchanged — only quickstart() was touched. Plans built from explicit (rangeLow, rangeHigh) have byte-identical output to v1.2.2. Self-tests 37 → 41 (all green).

[dddd86971-cloud]

v1.2.4 update — fee-aware plan output, driven by live testing on this PR

Source SHA dd30dec42 → 098a21aa. plugin.yaml bumped accordingly.

Discovered during live $24-account 4-rung grid testing on this PR that maker fills on Hyperliquid tier-0 carry a 1.5 bps fee even when crossed: false (observed: a 0.00016 BTC × $77,822 maker buy paid $0.001867 USDC = 1.5 bps of $12.45 notional).

v1.2.4 makes the fee economics visible in plan output instead of leaving users to guess whether their grid is profitable in absolute USD:

• avgRungGapPct — gap between adjacent same-side rungs
• expectedFeePerRoundtripUsd — 2 × rungNotional × leverage × feeRateMaker
• breakEvenGapPct — 2 × feeRateMaker; below this gap fees > gross
• feeAwareNetEdgePerRoundtripUsd — gross excursion − round-trip fee

Plus optional MarketMeta.feeRateMaker / feeRateTaker (defaults match HL tier-0: 1.5 / 4.5 bps) and a fee-erosion warning when avgRungGapPct < 2 × breakEvenGapPct.

Real example from the live $24 grid (gap 0.275%, default maker 1.5 bps):

• gross/RT = $0.034
• fee/RT = $0.0036 (10.6% of gross)
• net/RT = $0.0294
• breakEven = 0.030% (gap is 9× breakEven — comfortable)

plan() / quickstart() semantics, planHash, and levels[] byte-identical to v1.2.3. Self-tests 41 → 45 (all green).

[dddd86971-cloud]

v1.2.5 update — grid-cancel-rung + grid-roll user commands

Source SHA 098a21aa → 41ca8f93. plugin.yaml bumped accordingly.

This is a Skill-orchestration release — no binary changes. plan() / quickstart() semantics, planHash, and dist/ output are byte-identical to v1.2.4. Only SKILL.md adds two new user-facing commands.

Why these matter: users naturally say things like "撤掉最下面那个 buy", "cancel the $77,608 rung", "网格往上挪", "tighten the grid", "follow the price". Pre-v1.2.5 the Skill had no documented flow for these — the user had to manually orchestrate grid-close → grid-plan → grid-open (three commands, three confirmations, error-prone if any step fails).

• grid-cancel-rung — cancel ONE rung via natural-language reference. Documented disambiguation table maps "lowest" / "highest" / "closest to mid" / "the buy at $X" to a specific oid. If ambiguous, the Skill enumerates candidates and asks instead of guessing. The other rungs stay intact.

• grid-roll — atomically re-center the active grid around current mark. One confirmation; internally:

  1. Runs grid-quickstart with current markPrice + fresh candles + same totalNotional / riskProfile (so v1.2.3's notional-aware geometry still applies)
  2. Surfaces side-by-side old vs. new rungs + planHash for user confirmation
  3. Cancels old rungs (or roll + flatten to also close the existing position first)
  4. Places new rungs

  Safety rules: refuses if the existing position would be liquidated by the new range; refuses if any old rungs fail to cancel before placing new ones; never lets state become inconsistent.

Self-tests: 45 (unchanged). The decision to keep these as orchestration-only docs (not binary subcommands) is deliberate — the binary stays pure compute, and the agent layer handles user-intent disambiguation where it belongs. This also keeps planHash byte-stable across v1.2.4 → v1.2.5.

[dddd86971-cloud]

v1.2.6 update — explain surfaces fee fields; backtest + optimize fee-aware

Source SHA 41ca8f93 → c45a8ef3. plugin.yaml bumped accordingly.

Fixes a visibility gap discovered while monitoring the live $24-account grid on this PR: the v1.2.2 buy/sell aggregates and v1.2.4 fee-economics fields were computed by the binary but explain never rendered them — users had to jq raw JSON. v1.2.6 adds two new sections to explain:

Notional split:
  buy-side:        $12.00
  sell-side:       $12.00  (ratio buy/sell 1.000 — neutral)

Fee economics (per completed roundtrip):
  rung gap:        0.263%  (break-even 0.030% — 8.8× margin)
  expected fee:    $0.0036  (maker × 2 legs)
  net edge / RT:   $0.0280
  est. daily net:  $0.1820  (6.5 RT/day × $0.0280)

runBacktest and runOptimize are now fee-aware:

• BacktestResult adds feesPaidUsd + realizedPnlNetUsd. Every simulated fill incurs price × sizeCoin × feeRateMaker (default 1.5 bps HL tier-0, overridable via marketMeta.feeRateMaker).
• OptimizeCandidate exposes the same breakdown. score is now realizedPnlNetUsd / max(maxDD, 1) instead of gross — prevents tight fee-eroding grids from topping the ranking.

Real impact on a 75-combo BTC sweep:

	gross	fees	net	score
Top candidate	$2.062	$0.172 (8.3%)	$1.89	1.89

Backwards compat preserved: realizedPnlUsd unchanged (still gross). Old callers continue to work; new callers prefer realizedPnlNetUsd. computeGridPlan() and quickstart() semantics, planHash, and levels[] byte-identical to v1.2.5. Self-tests 45 → 49.

[Noah3595]

Plugin Store DApp Popularity Contest

• 💰 Prize Pool: 17,700 USDC
• 📅 Period: Apr 23 – May 7, 23:59 (UTC+8)
• 🧩 Featured Basic Skills: Polymarket Plugin | Hyperliquid Plugin

---

About the Contest

Plugin Store is the decentralized agent plugin marketplace on Onchain OS.

This contest focuses on two trading-related Basic Skills in Plugin Store — the Polymarket Plugin and the Hyperliquid Plugin — and encourages developers to build more high-quality strategy Skills around them.

Contest Rules

• Strategy Skills must be built on top of the Polymarket Plugin or the Hyperliquid Plugin.
• Each strategy Skill is ranked across three independent dimensions: trading volume, number of trades, and number of unique trading addresses.

Scoring Rules

• Stats are aggregated per Skill. If you submit multiple Skills, each one is scored and competes independently.
• Only trades initiated through Onchain OS and executed via the Polymarket Plugin or Hyperliquid Plugin are counted. Trades that bypass the Basic Skill are excluded.
• Leaderboards are synced daily in the official community. Final standings are locked at May 7, 23:59 (UTC+8).

Four Steps to Participate

1. Open Plugin Store and install the Polymarket Plugin or the Hyperliquid Plugin.
2. Build your own strategy on top of the Plugin.
3. Use your strategy — the three metrics will be tracked automatically.
4. Submit the entry form: https://forms.gle/gFCef1Y4qCv49L2z7

Three Leaderboards · 5,900 USDC each · 17,700 USDC in total

Trading Volume | Number of Trades | Unique Trading Addresses

• Top 1 — 1,300 USDC
• Top 2 — 800 USDC
• Top 3–5 — 600 USDC × 3
• Top 6–10 — 400 USDC × 5

A single Skill can win on multiple leaderboards. All prizes are paid in USDC.

⚠️ Red Lines

Sybil attacks · Plagiarism · Malicious code

The contest follows fair-play principles. Any confirmed violation will result in immediate removal from the leaderboards.

---

⚠️ Skills/Plugins not officially listed on OKX Plugin Store have not been reviewed by OKX. Please be aware of the risks when installing or running third-party Skills.