@hypelens/hypelens-agent-rail 0.1.14 → 0.1.15

package/README.md

@@ -4,13 +4,13 @@
 ```bash
 npx -y @hypelens/hypelens-agent-rail
 ```
-1. `hl_new_agent_wallet` → `HYPELENS_AGENT_PK`
-2. `hl_approve_payloads` — master signs approveAgent + ApproveBuilderFee **0.01%** once
+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):** after approve, call `hl_place_order` with `{coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}` — size/px auto-round; 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.
 
-Default **testnet**. `HYPELENS_NET=mainnet` for live. Fee: **1bp on fills** — no sub.
+Default **testnet**. `HYPELENS_NET=mainnet` for live. Fee: **1bp on fills** — no sub. Missing `HYPELENS_AGENT_PK` errors point at the same path.
 
 ## Optional after install: sizing edge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypelens/hypelens-agent-rail",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "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

@@ -37,12 +37,12 @@ npx -y @hypelens/hypelens-agent-rail
 
 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
+3. `hl_approve_payloads(agentAddress)` → **MASTER** signs approveAgent + ApproveBuilderFee **1bp** once, then POST both
 4. `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). Feed optional.
 
-**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.
+Default net is **testnet**. Set `HYPELENS_NET=mainnet` for live. Missing intel feed is **advisory** — does **not** block place. Missing PK errors name the same wallet → approve → sizeUsd path.
 
 ## Sizing rule
 

package/src/core.js

@@ -460,7 +460,7 @@ export async function quickstart({ coin = 'BTC' } = {}) {
     ],
     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' }
+    first_place_example: { coin: 'BTC', isBuy: true, sizeUsd: 12, leverage: 2, note: 'testnet default; sizeUsd alone → auto mark + szDecimals round; entryPx optional; feed optional' }
   };
   let sample_walls = null;
   let sample_error = null;
@@ -490,12 +490,12 @@ export async function quickstart({ coin = 'BTC' } = {}) {
       '1. Install: npx -y @hypelens/hypelens-agent-rail',
       '2. hl_new_agent_wallet → HYPELENS_AGENT_PK',
       '3. hl_approve_payloads → master signs approveAgent + ApproveBuilderFee 1bp once',
-      '4. hl_place_order (auto size/px rounding + lev defaults + cloid/status) — then cancel/close as needed',
+      '4. hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) — auto mark + size round; then cancel/close as needed',
       '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)',
+    next_if_blocked: 'Missing PK: hl_new_agent_wallet → HYPELENS_AGENT_PK → hl_approve_payloads (MASTER signs) → hl_place_order(first_place_example). Wrong net: default is testnet; set HYPELENS_NET=mainnet only for live.',
     why_route_volume_here: AGENT_VALUE,
     sample_walls,
     sample_error,

package/src/exchange.js

@@ -22,32 +22,46 @@ export function status() {
   };
 }
 
+const MISSING_PK = 'HYPELENS_AGENT_PK not set — hl_new_agent_wallet → export HYPELENS_AGENT_PK=<pk>, hl_approve_payloads (MASTER signs approveAgent + ApproveBuilderFee 1bp once), then hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) on testnet (default). Set HYPELENS_NET=mainnet only for live.';
+
 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 — 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');
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error(MISSING_PK);
 }
 
 function agentAddress() {
   const { signer } = loadShipped();
-  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');
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error(MISSING_PK);
   return signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
 }
 
 export function approvePayloads(agentAddressArg) {
   const { actions } = loadShipped();
+  const exchange = actions.NET[net()].exchange;
   return {
+    net: net(),
     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
+    fee: '1bp (0.01%) on fills only — no subscription',
+    steps: [
+      'Sign approveAgent + ApproveBuilderFee with the MASTER wallet (EIP-712) — never the agent pk',
+      'POST each {action, signature, nonce} to ' + exchange,
+      'Then hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) on testnet (size/px auto-round; no entryPx needed)'
+    ],
+    note: 'MASTER signs both once → POST to ' + exchange + ' → first place with sizeUsd (auto mark + szDecimals round). Default net=testnet; HYPELENS_NET=mainnet for live.'
   };
 }
 
 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)' };
+  return {
+    privateKey: pk,
+    address: signer.addressFromPrivateKey(pk),
+    note: 'export HYPELENS_AGENT_PK=<privateKey>; then hl_approve_payloads(address) for MASTER to sign 1bp once; then hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2})'
+  };
 }
 
 async function assetMeta(coin) {
@@ -63,6 +77,61 @@ async function assetMeta(coin) {
   return { assetIndex: i, szDecimals: meta.universe[i].szDecimals, name };
 }
 
+/** Mark + meta for sizeUsd auto-round (one round-trip). */
+async function assetMetaAndMark(coin) {
+  const { actions } = loadShipped();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'metaAndAssetCtxs' })
+  });
+  if (!r.ok) throw new Error('metaAndAssetCtxs HTTP ' + r.status);
+  const [meta, ctxs] = 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);
+  const markPx = Number(ctxs[i].markPx);
+  if (!(markPx > 0)) throw new Error('no markPx for ' + name + ' on ' + net());
+  return { assetIndex: i, szDecimals: meta.universe[i].szDecimals, name, markPx };
+}
+
+/**
+ * Resolve coin size + entryPx. Preferred first-place path: sizeUsd only
+ * (fetches mark, size = sizeUsd/mark, rounds to szDecimals). Explicit size+entryPx still works.
+ */
+async function resolveSizeAndPx({ coin, size, entryPx, sizeUsd }) {
+  const { actions } = loadShipped();
+  const needMark = entryPx == null || (size == null && sizeUsd != null);
+  const meta = needMark ? await assetMetaAndMark(coin) : await assetMeta(coin);
+  let px = entryPx != null ? Number(entryPx) : meta.markPx;
+  if (!(px > 0)) throw new Error('entryPx required (or omit and pass sizeUsd for auto mark)');
+  let sz = size != null ? Number(size) : null;
+  let usedSizeUsd = sizeUsd != null ? Number(sizeUsd) : null;
+  if (sz == null) {
+    if (!(usedSizeUsd > 0)) {
+      throw new Error('size or sizeUsd required — first place: {coin:"BTC", isBuy:true, sizeUsd:12, leverage:2} (auto mark + szDecimals round; entryPx optional)');
+    }
+    sz = usedSizeUsd / px;
+  } else if (usedSizeUsd == null) {
+    usedSizeUsd = sz * px;
+  }
+  sz = actions.roundToDecimals(sz, meta.szDecimals);
+  // Validate wire size will not collapse to 0
+  const wire = actions.sizeToWire(sz, meta.szDecimals);
+  if (wire === '0') {
+    throw new Error('size rounds to zero at ' + meta.szDecimals + ' decimals — increase sizeUsd (BTC first place: sizeUsd:12) or pass a larger size');
+  }
+  return {
+    assetIndex: meta.assetIndex,
+    szDecimals: meta.szDecimals,
+    name: meta.name,
+    size: sz,
+    entryPx: px,
+    sizeUsd: usedSizeUsd,
+    markPx: meta.markPx ?? null,
+    autoRounded: size == null || entryPx == null
+  };
+}
+
 async function postL1(action) {
   const { actions, signer } = loadShipped();
   assertPlacementAllowed(actions);
@@ -128,12 +197,14 @@ export async function getPositions({ user, coin } = {}) {
   return { net: net(), user: u, positions };
 }
 
-export async function placeOrder({ coin, isBuy, size, entryPx, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
+export async function placeOrder({ coin, isBuy, size = null, entryPx = null, sizeUsd = null, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
   const { actions } = loadShipped();
   assertPlacementAllowed(actions);
+  const resolved = await resolveSizeAndPx({ coin, size, entryPx, sizeUsd });
   let risk = null;
-  if (!skipRiskCheck && leverage) {
-    risk = await pretradeCheckFull({ coin, dir: isBuy ? 'long' : 'short', leverage, entryPx });
+  const lev = leverage != null ? Number(leverage) : null;
+  if (!skipRiskCheck && lev) {
+    risk = await pretradeCheckFull({ coin, dir: isBuy ? 'long' : 'short', leverage: lev, entryPx: resolved.entryPx, sizeUsd: resolved.sizeUsd });
     if (risk.refuseReason === 'full_feed_unconfigured') {
       risk = { ...risk, advisory: true, feedAdvisory: true, note: (risk.note || '') + ' Place allowed without full feed; heat is advisory.' };
     }
@@ -145,14 +216,44 @@ export async function placeOrder({ coin, isBuy, size, entryPx, slPx = null, tpPx
         placed: false,
         refused: 'liq price ' + risk.liqPx + ' lands inside a $' + wallSz + 'M wall — pass override:true to force',
         risk,
-        builderFeeAttached: false
+        builderFeeAttached: false,
+        size: resolved.size,
+        entryPx: resolved.entryPx,
+        sizeUsd: resolved.sizeUsd
       };
     }
   }
-  const { assetIndex, szDecimals } = await assetMeta(coin);
-  const action = actions.buildOrderAction({ assetIndex, szDecimals, isBuy, entryPx, size, slPx, tpPx });
+  let sizingWarn = null;
+  try {
+    const bal = await getBalances();
+    if (bal.equity > 0 && resolved.sizeUsd > bal.equity * 0.2) {
+      sizingWarn = 'sizeUsd ' + Math.round(resolved.sizeUsd) + ' > 20% of equity ' + Math.round(bal.equity) + ' — size down or confirm';
+    }
+  } catch (_) { /* balances optional for place */ }
+  const action = actions.buildOrderAction({
+    assetIndex: resolved.assetIndex,
+    szDecimals: resolved.szDecimals,
+    isBuy,
+    entryPx: resolved.entryPx,
+    size: resolved.size,
+    slPx,
+    tpPx
+  });
   const posted = await postL1(action);
-  return { placed: posted.ok, net: posted.net, response: posted.response, risk, builderFeeAttached: posted.ok };
+  return {
+    placed: posted.ok,
+    net: posted.net,
+    response: posted.response,
+    risk,
+    builderFeeAttached: posted.ok,
+    coin: resolved.name,
+    size: resolved.size,
+    entryPx: resolved.entryPx,
+    sizeUsd: resolved.sizeUsd,
+    autoRounded: resolved.autoRounded,
+    sizingWarn,
+    feeModel: '1bp on fills only — no subscription'
+  };
 }
 
 /** Cancel by oid and/or cloid. */

package/src/mcp.js

@@ -13,10 +13,10 @@ const wrap = (fn) => async (args) => {
 };
 
 export async function main() {
-  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.13' });
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.15' });
 
   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.',
+    'CALL FIRST: place-ready bootstrap — wallet + MASTER ApproveBuilderFee 1bp once, then hl_place_order sizeUsd:12. Default testnet. 1bp fills, no sub.',
     { coin: z.string().optional().describe("Optional coin for sample walls (default BTC)") },
     wrap(({ coin }) => quickstart({ coin })));
 
@@ -29,7 +29,7 @@ export async function main() {
     {}, wrap(() => newAgentWallet()));
 
   server.tool('hl_approve_payloads',
-    'Setup: EIP-712 payloads for MASTER to sign once — approveAgent + ApproveBuilderFee 0.01% (1bp). No subscription.',
+    'Setup: EIP-712 payloads for MASTER to sign once — approveAgent + ApproveBuilderFee 0.01% (1bp). Then POST both; then sizeUsd place. No sub.',
     { agentAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
     wrap(({ agentAddress }) => approvePayloads(agentAddress)));
 
@@ -44,11 +44,15 @@ export async function main() {
     wrap((a) => getPositions(a)));
 
   server.tool('hl_place_order',
-    'PLACE Hyperliquid perps @ 1bp on fills — auto size/price rounding + leverage defaults. Heat feed optional (advisory). No subscription.',
+    'PLACE Hyperliquid perps @ 1bp on fills. Preferred: sizeUsd (auto mark + szDecimals round; entryPx optional). Or pass size+entryPx. Heat advisory. No sub.',
     {
-      coin: z.string(), isBuy: z.boolean(), size: z.number().positive().describe('Size in coin units'),
-      entryPx: z.number().positive(), slPx: z.number().positive().optional(), tpPx: z.number().positive().optional(),
-      leverage: z.number().positive().optional().describe('Enables advisory pre-trade risk check'),
+      coin: z.string().describe('e.g. BTC'),
+      isBuy: z.boolean(),
+      sizeUsd: z.number().positive().optional().describe('Preferred first-place notional USD — auto mark + size round (e.g. 12)'),
+      size: z.number().positive().optional().describe('Coin units; optional if sizeUsd set'),
+      entryPx: z.number().positive().optional().describe('Limit px; omit with sizeUsd to use mark'),
+      slPx: z.number().positive().optional(), tpPx: z.number().positive().optional(),
+      leverage: z.number().positive().optional().describe('Optional; enables advisory pre-trade risk check (first place: 2)'),
       override: z.boolean().optional(), skipRiskCheck: z.boolean().optional()
     },
     wrap((a) => placeOrder(a)));