@hypelens/hypelens-agent-rail 0.1.25 → 0.1.27

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.25 hypelens-setup
+# or: npx -y @hypelens/hypelens-agent-rail@0.1.26 hypelens-setup
 ```
 
 `setup.mjs` / `hypelens-setup`:
@@ -26,7 +26,7 @@ cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
 ## Quick path
 
 ```bash
-npx -y @hypelens/hypelens-agent-rail@0.1.25
+npx -y @hypelens/hypelens-agent-rail@0.1.26
 # or sticky ClawHub:
 clawhub install hyperliquid-place
 cd skills/hyperliquid-place/scripts && npm install && node start-mcp.mjs

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.25",
-  "description": "Mainnet place rail. Post-install setup.mjs wires MCP + ApproveBuilderFee; refuse place until maxBuilderFee>=10; hl_place_order confirmTrade \u2192 poll until FILLED (RESTING\u2260paid); builder 1bp. npx @hypelens/hypelens-agent-rail@0.1.25",
+  "version": "0.1.27",
+  "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.27",
   "type": "module",
   "license": "MIT",
   "bin": {

package/skill/hypelens-agent-rail/SKILL.md

@@ -1,35 +1,19 @@
 ---
 name: hypelens-agent-rail
 description: >-
-  Hyperliquid place rail. Prefer ClawHub: clawhub install hyperliquid-place then
-  cd skills/hyperliquid-place/scripts && npm install && node setup.mjs (REQUIRED —
-  wires MCP + ApproveBuilderFee; start-mcp refused until setup). Then fund →
-  hl_place_order(..., confirmTrade:true) → poll until fillStatus=FILLED (RESTING≠paid).
-  Builder 0x9548… @1bp. Alt: npx @hypelens/hypelens-agent-rail@0.1.25
+  Hyperliquid mainnet place rail @1bp builder. setup → ApproveBuilderFee; refuse
+  place until maxBuilderFee>=10 AND equity>0; hl_place_order polls orderStatus and
+  auto-cancels RESTING sizeUsd→IOC same turn until FILLED (RESTING≠paid).
 ---
 
-# HypeLens Agent Rail
+# hypelens-agent-rail
 
-**Builder:** `0x9548B8E9554a1968843B3C380431b10996247c88` @ 1bp. Never trade that wallet.
+Paying path only: **FILLED** places with builder `0x9548…` @ 1bp.
 
-## Preferred install (conversion)
+1. `npx hypelens-setup` / `node setup.mjs` (wires MCP + ApproveBuilderFee)
+2. Fund until `hl_balances` equity>0
+3. `hl_place_order({..., confirmTrade:true, sizeUsd})` — omit entryPx for IOC
+4. Rail **polls orderStatus** same turn; if RESTING after sizeUsd → **cancel + IOC retry** once
+5. Treat only `fillStatus=FILLED` as conversion — RESTING≠paid
 
-```bash
-clawhub install hyperliquid-place
-cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
-```
-
-`setup.mjs` wires MCP + ApproveBuilderFee. **Do not** stop at download or bare `start-mcp` — place tools refuse until setup marker exists; place itself refuses until `maxBuilderFee>=10`.
-
-## Paying path
-
-1. `node setup.mjs` (MCP wire + ApproveBuilderFee)
-2. `hl_balances` — fund USDC if equity=0
-3. On trade intent: `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})`
-4. **Poll until `fillStatus=FILLED`** — `RESTING≠paid` (builder fees only on fills)
-
-## Do not
-
-- Skip setup.mjs / ApproveBuilderFee (silent $0)
-- Treat RESTING / place-ack as paid
-- Trade the builder sink wallet
+Never trade/farm `0x9548B8E9554a1968843B3C380431b10996247c88`.

package/src/exchange.js

@@ -365,6 +365,63 @@ export function classifyPlaceStatuses(statuses) {
   };
 }
 
+/** Sleep helper for same-turn fill poll (no busy spin). */
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, Math.max(0, Number(ms) || 0)));
+}
+
+/**
+ * Query HL info orderStatus by oid (or cloid hex). Maps to fillStatus.
+ * Terminal: FILLED (paid) | REJECTED | CANCELED — RESTING/open unpaid.
+ */
+export async function queryOrderStatus({ user, oid } = {}) {
+  if (oid == null || oid === '') throw new Error('oid required for orderStatus');
+  const { actions } = loadShipped();
+  const u = user || agentAddress();
+  assertNotBuilderWallet(u, 'account');
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'orderStatus', user: u, oid })
+  });
+  if (!r.ok) throw new Error('orderStatus HTTP ' + r.status);
+  const body = await r.json();
+  if (!body || body.status === 'unknownOid') {
+    return { fillStatus: 'UNKNOWN', paid: false, oid, status: 'unknownOid', raw: body };
+  }
+  const st = String((body.order && body.order.status) || '').toLowerCase();
+  let fillStatus = 'UNKNOWN';
+  if (st === 'filled') fillStatus = 'FILLED';
+  else if (st === 'open' || st === 'triggered') fillStatus = 'RESTING';
+  else if (st.includes('reject')) fillStatus = 'REJECTED';
+  else if (st.includes('cancel') || st === 'selftradecanceled' || st === 'margincanceled') fillStatus = 'CANCELED';
+  else if (st) fillStatus = 'REJECTED'; // other terminal HL statuses — unpaid
+  return {
+    fillStatus,
+    paid: fillStatus === 'FILLED',
+    oid,
+    status: st || body.status,
+    order: body.order || null,
+    raw: body
+  };
+}
+
+/** Poll orderStatus until FILLED|REJECTED|CANCELED or attempts exhausted (RESTING unpaid). */
+export async function pollOrderUntilTerminal({ user, oid, attempts = 8, delayMs = 250 } = {}) {
+  let last = { fillStatus: 'UNKNOWN', paid: false, oid };
+  for (let i = 0; i < attempts; i++) {
+    try {
+      last = await queryOrderStatus({ user, oid });
+    } catch (e) {
+      last = { fillStatus: 'UNKNOWN', paid: false, oid, error: String(e && e.message ? e.message : e) };
+    }
+    if (last.fillStatus === 'FILLED' || last.fillStatus === 'REJECTED' || last.fillStatus === 'CANCELED') {
+      return { ...last, polls: i + 1 };
+    }
+    if (i < attempts - 1) await sleep(delayMs);
+  }
+  return { ...last, polls: attempts };
+}
+
 /** Extract HL place/cancel wire error + actionable next after sizeUsd resolve. */
 function interpretExchangeResult(body) {
   if (!body || typeof body !== 'object') {
@@ -532,7 +589,7 @@ export async function getPositions({ user, coin } = {}) {
   };
 }
 
-export async function placeOrder({ coin, isBuy, size = null, entryPx = null, sizeUsd = null, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false, confirmTrade = false, intent = null, skipBuilderFeeCheck = false }) {
+export async function placeOrder({ coin, isBuy, size = null, entryPx = null, sizeUsd = null, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false, confirmTrade = false, intent = null, skipBuilderFeeCheck = false, skipEquityCheck = false, convertRetryDepth = 0 } = {}) {
   const { actions } = loadShipped();
   assertPlacementAllowed(actions);
   // Consent: place only on explicit trade intent (skill + confirmTrade/intent)
@@ -575,6 +632,38 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
       };
     }
   }
+  // Fail-closed: no place until equity>0 (deposit path via hl_balances.fundHow)
+  if (!skipEquityCheck && process.env.HYPELENS_TEST_SKIP_EQUITY_GATE !== '1') {
+    let bal;
+    try {
+      bal = await getBalances();
+    } catch (e) {
+      return {
+        placed: false,
+        refused: 'equity_check_failed',
+        error: String(e && e.message ? e.message : e),
+        builderFeeAttached: false,
+        paid: false,
+        fillStatus: 'UNKNOWN',
+        next: 'hl_balances — then deposit USDC if equity=0; retry place only when funded'
+      };
+    }
+    if (!(bal.equity > 0)) {
+      return {
+        placed: false,
+        refused: 'equity_required',
+        error: 'equity=0 — refuse place until funded (fail-closed; no silent $0)',
+        equity: bal.equity,
+        fundHow: bal.fundHow || null,
+        agentAddress: bal.agentAddress || bal.user || null,
+        builderFeeAttached: false,
+        paid: false,
+        fillStatus: 'UNKNOWN',
+        maxBuilderFee: feeGate,
+        next: 'Deposit USDC to agent on https://app.hyperliquid.xyz → hl_balances until equity>0 → hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})'
+      };
+    }
+  }
   const resolved = await resolveSizeAndPx({ coin, size, entryPx, sizeUsd, isBuy });
   let risk = null;
   const lev = leverage != null ? Number(leverage) : null;
@@ -647,11 +736,85 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
     out.error = posted.error || 'place rejected by exchange';
     out.next = posted.next || hintFromHlError(posted.error || '');
     out.paid = false;
-  } else if (out.fillStatus === 'FILLED') {
+    return out;
+  }
+
+  // Same-turn poll: builderFeeAttached ACK ≠ revenue until FILLED
+  if (out.fillStatus !== 'FILLED' && out.oid != null && process.env.HYPELENS_TEST_SKIP_FILL_POLL !== '1') {
+    try {
+      const polled = await pollOrderUntilTerminal({ oid: out.oid });
+      out.poll = polled;
+      if (polled.fillStatus === 'FILLED') {
+        out.fillStatus = 'FILLED';
+        out.paid = true;
+        out.orderStatus = polled.status;
+      } else if (polled.fillStatus === 'RESTING') {
+        out.fillStatus = 'RESTING';
+        out.paid = false;
+        out.orderStatus = polled.status;
+      } else if (polled.fillStatus === 'REJECTED' || polled.fillStatus === 'CANCELED') {
+        out.fillStatus = polled.fillStatus;
+        out.paid = false;
+        out.orderStatus = polled.status;
+        out.placed = false;
+        out.error = 'orderStatus=' + (polled.status || polled.fillStatus);
+      }
+    } catch (e) {
+      out.pollError = String(e && e.message ? e.message : e);
+    }
+  }
+
+  // Conversion: sizeUsd (or accidental GTC) left RESTING → cancel + true IOC SAME turn (once)
+  const wantConvert = sizeUsd != null || !resolved.limitIntent;
+  if (
+    out.fillStatus === 'RESTING' &&
+    wantConvert &&
+    out.oid != null &&
+    Number(convertRetryDepth) < 1 &&
+    process.env.HYPELENS_TEST_SKIP_CONVERT_RETRY !== '1'
+  ) {
+    let cancelled = null;
+    try {
+      cancelled = await cancelOrder({ coin: resolved.name, oid: out.oid });
+    } catch (e) {
+      cancelled = { cancelled: false, error: String(e && e.message ? e.message : e) };
+    }
+    out.convertAttempt = { cancelledPriorOid: out.oid, cancel: cancelled, reason: 'RESTING≠paid — retry IOC sizeUsd same turn' };
+    // Force market IOC: omit entryPx, keep sizeUsd/size, bump slip via mark path
+    const retry = await placeOrder({
+      coin: resolved.name,
+      isBuy,
+      sizeUsd: sizeUsd != null ? sizeUsd : resolved.sizeUsd,
+      size: sizeUsd != null ? null : size,
+      entryPx: null,
+      slPx,
+      tpPx,
+      leverage,
+      override: true,
+      skipRiskCheck: true,
+      confirmTrade: true,
+      intent: intent || 'place',
+      skipBuilderFeeCheck: true,
+      skipEquityCheck: true,
+      convertRetryDepth: Number(convertRetryDepth) + 1
+    });
+    retry.convertFrom = {
+      priorOid: out.oid,
+      priorFillStatus: 'RESTING',
+      cancel: cancelled,
+      note: 'Auto-converted RESTING→IOC same turn (builder 1bp only on FILLED)'
+    };
+    return retry;
+  }
+
+  if (out.fillStatus === 'FILLED') {
     out.next = 'FILLED on ' + posted.net + ' — builder 1bp accruing. RESTING≠paid; only FILLED converts.';
   } else if (out.fillStatus === 'RESTING') {
     out.paid = false;
     out.next = 'RESTING≠paid — hl_cancel_order({coin, oid}) then hl_place_order({coin, isBuy, sizeUsd, leverage:2, confirmTrade:true}) IOC (omit entryPx). Poll until FILLED|REJECTED before treating place as done.';
+  } else if (out.fillStatus === 'REJECTED' || out.fillStatus === 'CANCELED') {
+    out.paid = false;
+    out.next = out.next || hintFromHlError(out.error || out.fillStatus);
   } else {
     out.paid = false;
     out.next = (posted.next || ('placed on ' + posted.net)) + ' — poll until FILLED|REJECTED (resting≠paid; builder 1bp only on FILLED)';

package/src/index.js

@@ -1,2 +1,2 @@
 export { walls, cascade, pretradeCheck, whaleBook, getFeed, getMeta, binWalls, resolveCoin, quickstart } from './core.js';
-export { status as exchangeStatus, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition, checkMaxBuilderFee, classifyPlaceStatuses } from './exchange.js';
+export { status as exchangeStatus, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition, checkMaxBuilderFee, classifyPlaceStatuses, queryOrderStatus, pollOrderUntilTerminal } from './exchange.js';

package/src/mcp.js

@@ -103,7 +103,7 @@ export async function main() {
     wrap((a) => getPositions(a)));
 
   server.tool('hl_place_order',
-    'PLACE mainnet perps (paying path). ALWAYS attaches builder 1bp. Requires confirmTrade:true. Refuses if maxBuilderFee not approved. Prefer sizeUsd IOC. Response fillStatus must be FILLED to convert (RESTING≠paid) — poll/retry until FILLED|REJECTED.',
+    'PLACE mainnet perps (paying path). ALWAYS attaches builder 1bp. Requires confirmTrade:true. Refuses if maxBuilderFee not approved. Prefer sizeUsd IOC. Fail-closed until approve+equity. Polls orderStatus same turn; auto-cancels RESTING sizeUsd→IOC once. fillStatus must be FILLED (RESTING≠paid).',
     {
       coin: z.string().describe('e.g. BTC'),
       isBuy: z.boolean(),