@hypelens/hypelens-agent-rail 0.1.15 → 0.1.16

package/README.md

@@ -2,13 +2,22 @@
 **Place, cancel, close Hyperliquid perps.** Agent wallet once · auto-round · **1bp on fills — no sub.**
 ## Install → approve → place
 ```bash
+# MCP stdio (Claude / Cursor / any MCP host)
 npx -y @hypelens/hypelens-agent-rail
+
+# Claude Code one-liner
+claude mcp add hypelens -- npx -y @hypelens/hypelens-agent-rail
+
+# OpenClaw / ClawHub skill (skill slug, not npm alone)
+clawhub install hypelens-agent-rail
+# skills.sh (needs public GH; polyparlay anon currently 404)
+npx skills add polyparlay/hypelens -s hypelens-agent-rail -y
 ```
 1. `hl_quickstart` (optional) → `hl_new_agent_wallet` → `HYPELENS_AGENT_PK`
 2. `hl_approve_payloads(agentAddress)` — **MASTER** signs approveAgent + ApproveBuilderFee **0.01%** once, then POST both
 3. `hl_place_order` / `hl_cancel_order` / `hl_close_position` / `hl_positions` / `hl_balances`
 
-**First place (testnet default):** after approve, `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2})` — **sizeUsd alone** auto-fetches mark and rounds size; `entryPx` optional. No feed required.
+**First place (testnet default):** after approve, `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2})` — **sizeUsd alone** auto-fetches mark and rounds size; `entryPx` optional. No feed required. On reject after sizeUsd, response includes `error` + `next` (margin / approve / min notional).
 
 Default **testnet**. `HYPELENS_NET=mainnet` for live. Fee: **1bp on fills** — no sub. Missing `HYPELENS_AGENT_PK` errors point at the same path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypelens/hypelens-agent-rail",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Place, cancel, and close Hyperliquid perps from OpenClaw/MCP. Agent wallet once, auto-round, 1bp on fills (no sub). First place: hl_place_order BTC sizeUsd 12. npx @hypelens/hypelens-agent-rail",
   "type": "module",
   "license": "MIT",

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

@@ -1,5 +1,5 @@
 ---
-name: hypelens-agent-rail
+name: Hyperliquid Place
 description: >-
   hyperliquid place cancel close — Hyperliquid perps rail for OpenClaw/MCP.
   Agent wallet once, auto-round, 1bp builder on fills (no sub). Keywords:
@@ -31,7 +31,7 @@ metadata:
 npx -y @hypelens/hypelens-agent-rail
 ```
 
-**ClawHub / OpenClaw:** `clawhub install hypelens-agent-rail` · **skills.sh:** `npx skills add polyparlay/hypelens`
+**ClawHub / OpenClaw:** `clawhub install hypelens-agent-rail` · **skills.sh:** `npx skills add polyparlay/hypelens -s hypelens-agent-rail -y` · **MCP:** `npx -y @hypelens/hypelens-agent-rail`
 
 ## Quickstart (place-ready)
 

package/src/exchange.js

@@ -132,6 +132,57 @@ async function resolveSizeAndPx({ coin, size, entryPx, sizeUsd }) {
   };
 }
 
+/** Extract HL place/cancel wire error + actionable next after sizeUsd resolve. */
+function interpretExchangeResult(body) {
+  if (!body || typeof body !== 'object') {
+    return { ok: false, error: 'empty exchange response', next: 'retry hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) on testnet' };
+  }
+  if (body.status === 'err' || body.status === 'error') {
+    const raw = typeof body.response === 'string' ? body.response : JSON.stringify(body.response || body);
+    return { ok: false, error: raw, next: hintFromHlError(raw) };
+  }
+  const statuses = body?.response?.data?.statuses;
+  if (Array.isArray(statuses)) {
+    for (const s of statuses) {
+      if (s && typeof s.error === 'string' && s.error) {
+        return { ok: false, error: s.error, next: hintFromHlError(s.error), statuses };
+      }
+    }
+    // resting / filled / etc
+    const resting = statuses.find((s) => s && (s.resting || s.filled));
+    if (resting) return { ok: true, error: null, next: null, statuses };
+    if (statuses.length) return { ok: true, error: null, next: null, statuses };
+  }
+  if (body.status === 'ok') return { ok: true, error: null, next: null };
+  return { ok: false, error: JSON.stringify(body), next: hintFromHlError(JSON.stringify(body)) };
+}
+
+function hintFromHlError(msg) {
+  const m = String(msg || '').toLowerCase();
+  if (m.includes('insufficient') || m.includes('margin') || m.includes('not enough')) {
+    return 'Fund agent on this net (default testnet) or lower sizeUsd; check hl_balances.equity then retry sizeUsd place';
+  }
+  if (m.includes('does not exist') || m.includes('user or api wallet') || m.includes('unknown user')) {
+    return 'MASTER must POST approveAgent + ApproveBuilderFee 1bp (hl_approve_payloads) before first place; then sizeUsd:12';
+  }
+  if (m.includes('builder') && (m.includes('fee') || m.includes('approval') || m.includes('approve'))) {
+    return 'MASTER must sign ApproveBuilderFee 0.01% (1bp) via hl_approve_payloads and POST it; then retry sizeUsd place';
+  }
+  if (m.includes('minimum') || m.includes('min ') || m.includes('$10') || m.includes('too small')) {
+    return 'Increase sizeUsd (BTC first place: sizeUsd:12) — HL min notional; auto-round may shrink tiny sizes to zero';
+  }
+  if (m.includes('oracle') || m.includes('price') && m.includes('far')) {
+    return 'Omit entryPx and pass sizeUsd only (uses mark), or set entryPx near mark; retry hl_place_order sizeUsd';
+  }
+  if (m.includes('leverage') || m.includes('max lev')) {
+    return 'Lower leverage (first place: leverage:2) or set coin max leverage on HL, then retry sizeUsd place';
+  }
+  if (m.includes('permit') || m.includes('agent') && m.includes('not')) {
+    return 'Run hl_approve_payloads(agentAddress) — MASTER signs approveAgent once, POST, then sizeUsd place';
+  }
+  return 'Check hl_exchange_status + hl_balances; ensure MASTER approved agent+1bp builder; retry hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) on testnet';
+}
+
 async function postL1(action) {
   const { actions, signer } = loadShipped();
   assertPlacementAllowed(actions);
@@ -142,7 +193,9 @@ async function postL1(action) {
     body: JSON.stringify({ action: signed.action, signature: signed.signature, nonce: signed.nonce })
   });
   const body = await res.json().catch(() => ({}));
-  return { ok: res.ok && body.status === 'ok', net: net(), response: body };
+  const interpreted = interpretExchangeResult(body);
+  const ok = res.ok && interpreted.ok;
+  return { ok, net: net(), response: body, error: interpreted.error, next: interpreted.next, statuses: interpreted.statuses || null };
 }
 
 async function clearinghouse(user) {
@@ -240,7 +293,7 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
     tpPx
   });
   const posted = await postL1(action);
-  return {
+  const out = {
     placed: posted.ok,
     net: posted.net,
     response: posted.response,
@@ -254,6 +307,14 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
     sizingWarn,
     feeModel: '1bp on fills only — no subscription'
   };
+  if (!posted.ok) {
+    out.error = posted.error || 'place rejected by exchange';
+    out.next = posted.next || hintFromHlError(posted.error || '');
+    if (posted.statuses) out.statuses = posted.statuses;
+  } else {
+    out.next = 'placed — cancel via hl_cancel_order; close via hl_close_position; fees 1bp on fills only';
+  }
+  return out;
 }
 
 /** Cancel by oid and/or cloid. */
@@ -266,7 +327,9 @@ export async function cancelOrder({ coin, oid = null, cloid = null }) {
   else if (oid != null) action = actions.buildCancelAction([{ assetIndex, oid: Number(oid) }]);
   else throw new Error('oid or cloid required — pass oid or cloid to hl_cancel_order');
   const posted = await postL1(action);
-  return { cancelled: posted.ok, net: posted.net, response: posted.response, coin: resolveCoin(coin).toUpperCase(), oid, cloid };
+  const out = { cancelled: posted.ok, net: posted.net, response: posted.response, coin: resolveCoin(coin).toUpperCase(), oid, cloid };
+  if (!posted.ok) { out.error = posted.error || 'cancel rejected'; out.next = posted.next || hintFromHlError(posted.error || ''); }
+  return out;
 }
 
 /** IOC reduce-only close for a coin (uses position size if size omitted). */

package/src/mcp.js

@@ -13,7 +13,7 @@ const wrap = (fn) => async (args) => {
 };
 
 export async function main() {
-  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.15' });
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.16' });
 
   server.tool('hl_quickstart',
     'CALL FIRST: place-ready bootstrap — wallet + MASTER ApproveBuilderFee 1bp once, then hl_place_order sizeUsd:12. Default testnet. 1bp fills, no sub.',