@hypelens/hypelens-agent-rail 0.1.26 → 0.1.28

package/README.md

@@ -14,7 +14,7 @@ Outside-agent Hyperliquid **place** rail. Builder fees → `0x9548B8E9554a196884
 
 ```bash
 cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
-# or: npx -y @hypelens/hypelens-agent-rail@0.1.26 hypelens-setup
+# or: npx -y @hypelens/hypelens-agent-rail@0.1.28 hypelens-setup
 ```
 
 `setup.mjs` / `hypelens-setup`:
@@ -23,15 +23,20 @@ cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
 3. Prints `maxBuilderFee` — place stays refused until approved (no silent $0)
 4. Next: fund agent if equity=0 → place on explicit trade intent
 
-## Quick path
+## Quick path (setup BEFORE start — start-mcp REFUSED without setup)
 
 ```bash
-npx -y @hypelens/hypelens-agent-rail@0.1.26
-# or sticky ClawHub:
+# npx setup then MCP:
+npx -y @hypelens/hypelens-agent-rail@0.1.28 hypelens-setup
+npx -y @hypelens/hypelens-agent-rail@0.1.28
+# sticky ClawHub (REQUIRED order — skip setup = $0 / start refused):
 clawhub install hyperliquid-place
-cd skills/hyperliquid-place/scripts && npm install && node start-mcp.mjs
+cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
+# then restart MCP host / node start-mcp.mjs (writes .setup-ok)
 ```
 
+**Paying path:** setup → maxBuilderFee>=10 → equity>0 → `hl_place_order(..., confirmTrade:true)` → `fillStatus=FILLED` (RESTING≠paid; rail auto-cancels RESTING sizeUsd→IOC once).
+
 Env:
 
 | Var | Role |
@@ -47,5 +52,6 @@ Env:
 2. `hl_approve_payloads(agentAddress)` — auto if master key; else MASTER signs ApproveBuilderFee **0.01%**
 3. `hl_balances` (+ fundHow if equity=0)
 4. On explicit trade intent: `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})`
+5. Poll until **`fillStatus=FILLED`** — RESTING≠paid (rail auto-cancel RESTING→IOC same turn once)
 
-Skipping ApproveBuilderFee = **$0 fees**. Place is hard-refused until on-chain `maxBuilderFee` covers 1bp.
+Skipping ApproveBuilderFee / setup / fund / FILLED = **$0 fees**. Place is hard-refused until on-chain `maxBuilderFee` covers 1bp. `start-mcp` REFUSED until `setup.mjs` wrote `.setup-ok`.

package/bin/hypelens-setup.js

@@ -16,6 +16,15 @@ import { createRequire } from 'node:module';
 const FORBIDDEN = '0x9548B8E9554a1968843B3C380431b10996247c88';
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
+function railVersion() {
+  try {
+    const require = createRequire(import.meta.url);
+    return require(join(ROOT, 'package.json')).version;
+  } catch {
+    return '0.1.27';
+  }
+}
+
 function loadRail() {
   process.env.HYPELENS_QUIET = '1';
   return import(pathToFileURL(join(ROOT, 'src', 'index.js')).href);
@@ -55,7 +64,8 @@ function mcpServerEntry(scriptsDir) {
   }
   return {
     command: 'npx',
-    args: ['-y', '@hypelens/hypelens-agent-rail@0.1.25'],
+    // Always pin THIS package version — stale pins break conversion
+    args: ['-y', `@hypelens/hypelens-agent-rail@${railVersion()}`],
     env: {
       HYPELENS_NET: process.env.HYPELENS_NET || 'mainnet',
       ...(process.env.HYPELENS_AGENT_PK ? { HYPELENS_AGENT_PK: process.env.HYPELENS_AGENT_PK } : {}),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hypelens/hypelens-agent-rail",
-  "version": "0.1.26",
-  "description": "Mainnet place rail. setup.mjs \u2192 ApproveBuilderFee; refuse place until maxBuilderFee>=10 AND equity>0; hl_place_order polls orderStatus and auto-cancels RESTING sizeUsd \u2192 IOC same turn until FILLED (RESTING\u2260paid); builder 1bp. npx @hypelens/hypelens-agent-rail@0.1.26",
+  "version": "0.1.28",
+  "description": "Mainnet place rail. REQUIRED: hypelens-setup/setup.mjs before start-mcp (start refused without .setup-ok). Refuse place until maxBuilderFee>=10 AND equity>0; hl_place_order polls orderStatus and auto-cancels RESTING sizeUsd\u2192IOC until FILLED; builder 1bp. npx @hypelens/hypelens-agent-rail@0.1.28",
   "type": "module",
   "license": "MIT",
   "bin": {