@hypelens/hypelens-agent-rail 0.1.12 → 0.1.14

package/README.md

@@ -1,18 +1,16 @@
 # @hypelens/hypelens-agent-rail
-
-**Place, cancel, and close Hyperliquid perps from OpenClaw/MCP.** Agent wallet once, auto-round, **1bp on fills only — no subscription.**
-
-## Install + setup
-
+**Place, cancel, close Hyperliquid perps.** Agent wallet once · auto-round · **1bp on fills — no sub.**
+## Install → approve → place
 ```bash
 npx -y @hypelens/hypelens-agent-rail
 ```
-
-1. `hl_new_agent_wallet` — store as `HYPELENS_AGENT_PK`
+1. `hl_new_agent_wallet` → `HYPELENS_AGENT_PK`
 2. `hl_approve_payloads` — master signs approveAgent + ApproveBuilderFee **0.01%** once
 3. `hl_place_order` / `hl_cancel_order` / `hl_close_position` / `hl_positions` / `hl_balances`
 
-Default net is **testnet**. Set `HYPELENS_NET=mainnet` for live. Fee: **1bp on fills** — no sub.
+**First place (testnet):** after approve, call `hl_place_order` with `{coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}` — size/px auto-round; no feed required.
+
+Default **testnet**. `HYPELENS_NET=mainnet` for live. Fee: **1bp on fills** — no sub.
 
 ## Optional after install: sizing edge
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hypelens/hypelens-agent-rail",
-  "version": "0.1.12",
-  "description": "Place, cancel, and close Hyperliquid perps from OpenClaw/MCP. Agent wallet once, auto-round, 1bp on fills (no sub). npx @hypelens/hypelens-agent-rail",
+  "version": "0.1.14",
+  "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",
   "bin": {

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

@@ -1,50 +1,59 @@
 ---
 name: hypelens-agent-rail
 description: >-
-  Place, cancel, and close Hyperliquid perps from OpenClaw/MCP. Agent wallet
-  once, auto-round, 1bp builder. Use when the agent must open/close HL perps
-  with minimal failed txs.
+  hyperliquid place cancel close — Hyperliquid perps rail for OpenClaw/MCP.
+  Agent wallet once, auto-round, 1bp builder on fills (no sub). Keywords:
+  hyperliquid place cancel close order perps hl_place_order hl_cancel_order
+  hl_close_position trading-agent.
 metadata:
   openclaw:
+    emoji: "📈"
     requires:
-      env:
-        - HYPELENS_NET
+      bins:
+        - npx
+    envVars:
+      - name: HYPELENS_NET
+        required: false
+        description: testnet (default) or mainnet
+      - name: HYPELENS_AGENT_PK
+        required: false
+        description: agent-wallet pk required only to place/cancel/close
+      - name: HYPELENS_FEED_URL
+        required: false
+        description: optional denser heat (advisory if unset — does not block place)
 ---
 
-# HypeLens Agent Rail
+# HypeLens Agent Rail — Place / Cancel / Close Hyperliquid Perps
 
-## Place / cancel / close / positions @ 1bp on fills
-
-Approve builder once, then place/cancel/close Hyperliquid perps and read balances/positions. **1bp (0.01%) on fills only — no subscription.**
+**Place, cancel, and close Hyperliquid perps orders** from OpenClaw/MCP. Agent wallet once, auto-round, **1bp (0.01%) on fills only — no subscription.**
 
 ```bash
 npx -y @hypelens/hypelens-agent-rail
 ```
 
-**ClawHub / OpenClaw:** `clawhub install hypelens-agent-rail`
+**ClawHub / OpenClaw:** `clawhub install hypelens-agent-rail` · **skills.sh:** `npx skills add polyparlay/hypelens`
 
-## Setup (next to install)
+## Quickstart (place-ready)
 
-1. `hl_new_agent_wallet` → store as `HYPELENS_AGENT_PK`
-2. `hl_approve_payloads(agentAddress)` → master signs approveAgent + ApproveBuilderFee **1bp** once
-3. `hl_place_order` / `hl_cancel_order` / `hl_close_position` / `hl_positions` / `hl_balances`
+1. Call `hl_quickstart` first
+2. `hl_new_agent_wallet` → store as `HYPELENS_AGENT_PK`
+3. `hl_approve_payloads(agentAddress)` → master signs approveAgent + ApproveBuilderFee **1bp** once
+4. `hl_place_order` / `hl_cancel_order` / `hl_close_position` / `hl_positions` / `hl_balances`
 
-## Sizing rule
 
-Warn if notional `sizeUsd` is more than **20% of account equity**. Size from balance; confirm mark before place.
+**First place (testnet):** after approve, call hl_place_order with coin BTC, isBuy true, sizeUsd 12, leverage 2 — size/px auto-round; feed optional.
+Default net is **testnet**. Set `HYPELENS_NET=mainnet` for live. Missing intel feed is **advisory** — does **not** block place.
 
-## Optional after install: heat / whale book
+## Sizing rule
 
-`hl_walls`, `hl_whale_book`, `hl_cascade`, `hl_pretrade_check` improve size/entry. Missing feed is **advisory** — does not block place.
+Warn if notional `sizeUsd` is more than **20% of account equity**. Size from balance; confirm mark before place.
 
 ## Tools
 
-- **Place path:** `hl_place_order`, `hl_cancel_order`, `hl_close_position`, `hl_balances`, `hl_positions`, `hl_exchange_status`, `hl_quickstart`
+- **Place path:** `hl_quickstart`, `hl_exchange_status`, `hl_place_order`, `hl_cancel_order`, `hl_close_position`, `hl_balances`, `hl_positions`
 - **Setup:** `hl_new_agent_wallet`, `hl_approve_payloads`
-- **Optional edge:** `hl_walls`, `hl_whale_book`, `hl_cascade`, `hl_pretrade_check`
+- **Optional edge (after install):** `hl_walls`, `hl_whale_book`, `hl_cascade`, `hl_pretrade_check`
 
-## Env
+## Keywords
 
-- `HYPELENS_NET` — `testnet` (default) or `mainnet`
-- `HYPELENS_AGENT_PK` — required to place/cancel/close
-- `HYPELENS_FEED_URL` / `HYPELENS_FEED_FILE` — optional denser heat (advisory if unset)
+hyperliquid · place · cancel · close · order · perps · hl_place_order · mcp · openclaw · builder

package/src/core.js

@@ -443,10 +443,25 @@ export async function pretradeCheckFull(args) {
   };
 }
 
-/** First-discovery: place-ready bootstrap (heat/sizing optional after install). */
+/** First-discovery: place-ready bootstrap FIRST (heat/sizing optional after).
+ * Optional sample_walls fetched after bootstrap object is assembled.
+ */
 export async function quickstart({ coin = 'BTC' } = {}) {
   const { actions } = loadShipped();
   const net = process.env.HYPELENS_NET || 'testnet';
+  const bootstrap = {
+    ready: 'place/cancel/close/positions @ 1bp on fills — no subscription',
+    install: 'npx -y @hypelens/hypelens-agent-rail',
+    steps: [
+      'hl_new_agent_wallet → store as HYPELENS_AGENT_PK',
+      'hl_approve_payloads(agentAddress) → master signs approveAgent + ApproveBuilderFee 1bp once',
+      'hl_place_order / hl_cancel_order / hl_close_position / hl_positions / hl_balances',
+      'Optional after: hl_walls / hl_whale_book / hl_cascade / hl_pretrade_check (advisory if no full feed)'
+    ],
+    fee: '1bp (0.01%) on fills only',
+    package: '@hypelens/hypelens-agent-rail',
+    first_place_example: { coin: 'BTC', isBuy: true, sizeUsd: 12, leverage: 2, note: 'testnet default; size/px auto-round; feed optional' }
+  };
   let sample_walls = null;
   let sample_error = null;
   try {
@@ -455,6 +470,7 @@ export async function quickstart({ coin = 'BTC' } = {}) {
     sample_error = e && e.message ? e.message : String(e);
   }
   return {
+    bootstrap,
     value_prop: AGENT_VALUE,
     install: 'npx -y @hypelens/hypelens-agent-rail',
     builder_fee: '1bp (0.01%)',
@@ -478,6 +494,8 @@ export async function quickstart({ coin = 'BTC' } = {}) {
       '5. Optional after install: hl_walls / hl_whale_book / hl_cascade / hl_pretrade_check for sizing edge'
     ],
     sizing_rule: 'Warn if sizeUsd > 20% of account equity; size from balance; confirm mark before place.',
+    first_place_example: bootstrap.first_place_example,
+    next_if_blocked: 'If place errors on missing key: hl_new_agent_wallet → HYPELENS_AGENT_PK → hl_approve_payloads → hl_place_order(first_place_example)',
     why_route_volume_here: AGENT_VALUE,
     sample_walls,
     sample_error,

package/src/exchange.js

@@ -26,12 +26,12 @@ function assertPlacementAllowed(actions) {
   if (net() === 'mainnet' && !actions.MAINNET_PLACEMENT_ENABLED) {
     throw new Error('MAINNET PLACEMENT DISABLED — Set HYPELENS_NET=testnet.');
   }
-  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set — run the approve flow first (see approvePayloads)');
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set — call hl_quickstart, then hl_new_agent_wallet → set HYPELENS_AGENT_PK, hl_approve_payloads (master signs 1bp), then hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) on testnet');
 }
 
 function agentAddress() {
   const { signer } = loadShipped();
-  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set');
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set — hl_new_agent_wallet → export HYPELENS_AGENT_PK=<pk> before place/balances/cancel/close');
   return signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
 }
 
@@ -163,7 +163,7 @@ export async function cancelOrder({ coin, oid = null, cloid = null }) {
   let action;
   if (cloid) action = actions.buildCancelByCloidAction([{ assetIndex, cloid }]);
   else if (oid != null) action = actions.buildCancelAction([{ assetIndex, oid: Number(oid) }]);
-  else throw new Error('oid or cloid required');
+  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 };
 }
@@ -175,10 +175,10 @@ export async function closePosition({ coin, size = null, px = null, user } = {})
   const name = resolveCoin(coin).toUpperCase();
   const { positions } = await getPositions({ user, coin: name });
   const pos = positions[0];
-  if (!pos || !pos.szi) throw new Error('no open position for ' + name);
+  if (!pos || !pos.szi) throw new Error('no open position for ' + name + ' — check hl_positions first');
   const absSz = Math.abs(pos.szi);
   const closeSz = size != null ? Number(size) : absSz;
-  if (!(closeSz > 0) || closeSz > absSz + 1e-12) throw new Error('bad close size');
+  if (!(closeSz > 0) || closeSz > absSz + 1e-12) throw new Error('bad close size — omit size for full close, or size <= abs(szi)');
   const isBuy = pos.szi < 0; // short -> buy to close
   let entryPx = px;
   if (entryPx == null) {

package/src/exchange.js.bak-clearerr

@@ -0,0 +1,211 @@
+// HypeLens Agent Rail — EXECUTION (builder-code monetized).
+// Reuses Module 3: hl-actions.js builds actions (builder fee pinned on place/close),
+// hl-signer.js signs through the vendored SDK. Default HYPELENS_NET=testnet.
+// Fee model: 1bp (0.01%) on fills only — no subscription. BUILDER_F=10.
+// Risk/heat advisory when feed missing; danger-wall refuses unless override.
+import { loadShipped } from './load.js';
+import { pretradeCheckFull, fullFeedConfigured, resolveCoin } from './core.js';
+
+const net = () => process.env.HYPELENS_NET || 'testnet';
+
+export function status() {
+  const { actions, signer } = loadShipped();
+  const st = signer.selfTest();
+  return {
+    net: net(),
+    mainnetPlacementEnabled: actions.MAINNET_PLACEMENT_ENABLED,
+    builder: actions.BUILDER, builderFeeTenthsBp: actions.BUILDER_F, maxFeeRate: actions.MAX_BUILDER_FEE_RATE,
+    feeModel: '1bp on fills only — no subscription',
+    signerReady: st.ok, signerError: st.ok ? null : st.error,
+    hasAgentKey: Boolean(process.env.HYPELENS_AGENT_PK),
+    fullFeedConfigured: fullFeedConfigured()
+  };
+}
+
+function assertPlacementAllowed(actions) {
+  if (net() === 'mainnet' && !actions.MAINNET_PLACEMENT_ENABLED) {
+    throw new Error('MAINNET PLACEMENT DISABLED — Set HYPELENS_NET=testnet.');
+  }
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set — run the approve flow first (see approvePayloads)');
+}
+
+function agentAddress() {
+  const { signer } = loadShipped();
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set');
+  return signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
+}
+
+export function approvePayloads(agentAddressArg) {
+  const { actions } = loadShipped();
+  return {
+    approveAgent: actions.buildApproveAgent(net(), agentAddressArg),
+    approveBuilderFee: actions.buildApproveBuilderFee(net()),
+    note: 'Sign both with the MASTER wallet (EIP-712), POST each as {action, signature, nonce} to ' + actions.NET[net()].exchange
+  };
+}
+
+export function newAgentWallet() {
+  const { signer, sdk } = loadShipped();
+  const pk = sdk.randomPrivateKey();
+  return { privateKey: pk, address: signer.addressFromPrivateKey(pk), note: 'store as HYPELENS_AGENT_PK; approve via approvePayloads(address)' };
+}
+
+async function assetMeta(coin) {
+  const { actions } = loadShipped();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'meta' })
+  });
+  const meta = await r.json();
+  const name = resolveCoin(coin).toUpperCase();
+  const i = meta.universe.findIndex((u) => u.name === name);
+  if (i < 0) throw new Error('coin not on ' + net() + ': ' + coin);
+  return { assetIndex: i, szDecimals: meta.universe[i].szDecimals, name };
+}
+
+async function postL1(action) {
+  const { actions, signer } = loadShipped();
+  assertPlacementAllowed(actions);
+  const nonce = actions.nonce();
+  const signed = await signer.signL1(process.env.HYPELENS_AGENT_PK, action, nonce, net() === 'testnet', null);
+  const res = await fetch(actions.NET[net()].exchange, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    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 };
+}
+
+async function clearinghouse(user) {
+  const { actions } = loadShipped();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'clearinghouseState', user })
+  });
+  if (!r.ok) throw new Error('clearinghouseState HTTP ' + r.status);
+  return r.json();
+}
+
+/** Balances / margin summary for the agent (or explicit user). */
+export async function getBalances({ user } = {}) {
+  const u = user || agentAddress();
+  const state = await clearinghouse(u);
+  const ms = state.marginSummary || {};
+  const equity = Number(ms.accountValue || 0);
+  return {
+    net: net(),
+    user: u,
+    marginSummary: ms,
+    withdrawable: state.withdrawable ?? null,
+    equity,
+    sizingWarnThresholdUsd: equity * 0.2,
+    sizing_rule: 'Warn if sizeUsd > 20% of account equity; size from balance; confirm mark before place.',
+    feeModel: '1bp on fills only — no subscription'
+  };
+}
+
+/** Open perp positions (assetPositions). */
+export async function getPositions({ user, coin } = {}) {
+  const u = user || agentAddress();
+  const state = await clearinghouse(u);
+  let positions = (state.assetPositions || []).map((ap) => {
+    const p = ap.position || ap;
+    return {
+      coin: p.coin,
+      szi: Number(p.szi || 0),
+      entryPx: p.entryPx != null ? Number(p.entryPx) : null,
+      positionValue: p.positionValue != null ? Number(p.positionValue) : null,
+      unrealizedPnl: p.unrealizedPnl != null ? Number(p.unrealizedPnl) : null,
+      leverage: p.leverage || null,
+      liquidationPx: p.liquidationPx != null ? Number(p.liquidationPx) : null,
+      marginUsed: p.marginUsed != null ? Number(p.marginUsed) : null
+    };
+  }).filter((p) => p.szi !== 0);
+  if (coin) {
+    const c = resolveCoin(coin).toUpperCase();
+    positions = positions.filter((p) => (p.coin || '').toUpperCase() === c);
+  }
+  return { net: net(), user: u, positions };
+}
+
+export async function placeOrder({ coin, isBuy, size, entryPx, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  let risk = null;
+  if (!skipRiskCheck && leverage) {
+    risk = await pretradeCheckFull({ coin, dir: isBuy ? 'long' : 'short', leverage, entryPx });
+    if (risk.refuseReason === 'full_feed_unconfigured') {
+      risk = { ...risk, advisory: true, feedAdvisory: true, note: (risk.note || '') + ' Place allowed without full feed; heat is advisory.' };
+    }
+    if (risk.verdict === 'danger' && risk.refuseReason !== 'full_feed_unconfigured' && !override) {
+      const wallSz = risk.wall && risk.wall.sizeUsd != null
+        ? Math.round(risk.wall.sizeUsd / 1e6)
+        : (risk.wall && risk.wall.sizeUsdCoarse != null ? Math.round(risk.wall.sizeUsdCoarse / 1e6) : '?');
+      return {
+        placed: false,
+        refused: 'liq price ' + risk.liqPx + ' lands inside a $' + wallSz + 'M wall — pass override:true to force',
+        risk,
+        builderFeeAttached: false
+      };
+    }
+  }
+  const { assetIndex, szDecimals } = await assetMeta(coin);
+  const action = actions.buildOrderAction({ assetIndex, szDecimals, isBuy, entryPx, size, slPx, tpPx });
+  const posted = await postL1(action);
+  return { placed: posted.ok, net: posted.net, response: posted.response, risk, builderFeeAttached: posted.ok };
+}
+
+/** Cancel by oid and/or cloid. */
+export async function cancelOrder({ coin, oid = null, cloid = null }) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  const { assetIndex } = await assetMeta(coin);
+  let action;
+  if (cloid) action = actions.buildCancelByCloidAction([{ assetIndex, cloid }]);
+  else if (oid != null) action = actions.buildCancelAction([{ assetIndex, oid: Number(oid) }]);
+  else throw new Error('oid or cloid required');
+  const posted = await postL1(action);
+  return { cancelled: posted.ok, net: posted.net, response: posted.response, coin: resolveCoin(coin).toUpperCase(), oid, cloid };
+}
+
+/** IOC reduce-only close for a coin (uses position size if size omitted). */
+export async function closePosition({ coin, size = null, px = null, user } = {}) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  const name = resolveCoin(coin).toUpperCase();
+  const { positions } = await getPositions({ user, coin: name });
+  const pos = positions[0];
+  if (!pos || !pos.szi) throw new Error('no open position for ' + name);
+  const absSz = Math.abs(pos.szi);
+  const closeSz = size != null ? Number(size) : absSz;
+  if (!(closeSz > 0) || closeSz > absSz + 1e-12) throw new Error('bad close size');
+  const isBuy = pos.szi < 0; // short -> buy to close
+  let entryPx = px;
+  if (entryPx == null) {
+    const { actions: a2 } = loadShipped();
+    const r = await fetch(a2.NET[net()].info, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: 'metaAndAssetCtxs' })
+    });
+    const [meta, ctxs] = await r.json();
+    const i = meta.universe.findIndex((u) => u.name === name);
+    if (i < 0) throw new Error('coin not in meta: ' + name);
+    entryPx = Number(ctxs[i].markPx);
+    // slip 0.5% through for IOC fill
+    entryPx = isBuy ? entryPx * 1.005 : entryPx * 0.995;
+  }
+  const { assetIndex, szDecimals } = await assetMeta(name);
+  const action = actions.buildCloseAction({ assetIndex, szDecimals, isBuy, entryPx, size: closeSz });
+  const posted = await postL1(action);
+  return {
+    closed: posted.ok,
+    net: posted.net,
+    response: posted.response,
+    coin: name,
+    size: closeSz,
+    isBuy,
+    entryPx,
+    builderFeeAttached: posted.ok,
+    feeModel: '1bp on fills only — no subscription'
+  };
+}

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.12' });
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.13' });
 
   server.tool('hl_quickstart',
     'CALL FIRST: place-ready bootstrap — install, agent wallet + ApproveBuilderFee 1bp once, then place/cancel/close/positions. 1bp on fills, no sub. Heat optional after.',