@hypelens/hypelens-agent-rail 0.1.1

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hypelens/hypelens-agent-rail",
+  "version": "0.1.1",
+  "description": "Real-data Hyperliquid risk intelligence + risk-checked execution for AI trading agents. MCP server + SDK. Liquidation walls, cascade chains, whale book, pre-trade checks from a 1,100-wallet real-position crawl \u2014 free. Execution routed with the HypeLens builder code.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "hypelens-rail-mcp": "bin/hypelens-rail-mcp.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "bin/",
+    "vendor/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test 'test/*.test.mjs'",
+    "prepack": "node scripts/bundle-vendor.mjs",
+    "mcp": "node bin/hypelens-rail-mcp.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polyparlay/hypelens.git",
+    "directory": "agent-rail"
+  },
+  "keywords": [
+    "hyperliquid",
+    "mcp",
+    "model-context-protocol",
+    "trading-agent",
+    "liquidation",
+    "perps",
+    "risk",
+    "eliza",
+    "ai-agent"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/bundle-vendor.mjs

@@ -0,0 +1,13 @@
+// prepack: copy the shipped extension modules into agent-rail/vendor so the
+// published npm package is self-contained. The rail evals these verbatim.
+import { copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RAIL = join(dirname(fileURLToPath(import.meta.url)), '..');
+const EXT = join(RAIL, '..', 'extension');
+mkdirSync(join(RAIL, 'vendor'), { recursive: true });
+for (const f of [['vendor/hl-sdk.js', 'hl-sdk.js'], ['exchange/hl-signer.js', 'hl-signer.js'], ['exchange/hl-actions.js', 'hl-actions.js'], ['viewmodel.js', 'viewmodel.js']]) {
+  copyFileSync(join(EXT, f[0]), join(RAIL, 'vendor', f[1]));
+  console.log('bundled', f[1]);
+}

package/server.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.polyparlay/hypelens-agent-rail",
+  "description": "Real-data Hyperliquid risk intelligence for trading agents: liquidation walls, cascade chains, whale book, and pre-trade liq checks from a live 1,100-wallet position crawl — plus risk-checked, testnet-gated order placement.",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/polyparlay/hypelens",
+    "source": "github",
+    "subfolder": "agent-rail"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registry_type": "npm",
+      "registry_base_url": "https://registry.npmjs.org",
+      "identifier": "hypelens-agent-rail",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environment_variables": [
+        {
+          "name": "HYPELENS_AGENT_PK",
+          "description": "Optional: agent-wallet private key for order placement (risk tools need no key)",
+          "is_required": false,
+          "is_secret": true
+        },
+        {
+          "name": "HYPELENS_NET",
+          "description": "Optional: 'testnet' (default) or 'mainnet' (placement hard-blocked until enabled)",
+          "is_required": false,
+          "is_secret": false
+        }
+      ]
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,23 @@
+# Smithery.ai listing config — https://smithery.ai/docs/config
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      hypelensAgentPk:
+        type: string
+        description: "Optional agent-wallet private key for order placement. Risk tools (walls, cascade, pretrade check, whale book) work without any key."
+      hypelensNet:
+        type: string
+        enum: [testnet, mainnet]
+        default: testnet
+        description: "Execution network. Mainnet placement is hard-blocked in code until operator-enabled."
+  commandFunction: |-
+    (config) => ({
+      command: 'node',
+      args: ['bin/hypelens-rail-mcp.js'],
+      env: {
+        ...(config.hypelensAgentPk ? { HYPELENS_AGENT_PK: config.hypelensAgentPk } : {}),
+        ...(config.hypelensNet ? { HYPELENS_NET: config.hypelensNet } : {})
+      }
+    })

package/src/core.js

@@ -0,0 +1,178 @@
+// HypeLens Agent Rail — RISK CORE (free tools).
+// Data: the public HypeLens intel feed (1,100-wallet real-position crawl,
+// refreshed every 15 min) + one unauthenticated HL info call for mark/meta.
+// Models: the SHIPPED extension viewmodel (liqPrice, huntRiskCluster,
+// suggestClearLeverage, computeCascade) — evaluated, never reimplemented.
+// Every response carries honesty fields: coverage_pct, data_age_s, source.
+import { readFileSync } from 'node:fs';
+import { loadShipped } from './load.js';
+
+const FEED_URL = process.env.HYPELENS_FEED_URL
+  || 'https://raw.githubusercontent.com/polyparlay/hypelens/main/docs/feed/hypelens-intel.json';
+const INFO = { mainnet: 'https://api.hyperliquid.xyz/info', testnet: 'https://api.hyperliquid-testnet.xyz/info' };
+const FEED_TTL_MS = 60e3, META_TTL_MS = 30e3;
+const BIG_WALL = 10e6, MAGNET_NEAR = 0.015; // same thresholds as calibration PREREG
+
+let _feed = null, _feedAt = 0, _meta = null, _metaAt = 0;
+
+export async function getFeed() {
+  if (_feed && Date.now() - _feedAt < FEED_TTL_MS) return _feed;
+  if (process.env.HYPELENS_FEED_FILE) {
+    _feed = JSON.parse(readFileSync(process.env.HYPELENS_FEED_FILE, 'utf8'));
+  } else {
+    const r = await fetch(FEED_URL, { headers: { 'Cache-Control': 'no-cache' } });
+    if (!r.ok) throw new Error('feed HTTP ' + r.status);
+    _feed = await r.json();
+  }
+  _feedAt = Date.now();
+  return _feed;
+}
+
+export async function getMeta(net = 'mainnet') {
+  if (_meta && Date.now() - _metaAt < META_TTL_MS) return _meta;
+  const r = await fetch(INFO[net], {
+    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 byCoin = {};
+  meta.universe.forEach((u, i) => {
+    const c = ctxs[i] || {};
+    byCoin[u.name] = {
+      assetIndex: i, szDecimals: u.szDecimals, maxLeverage: u.maxLeverage,
+      markPx: parseFloat(c.markPx), oiNtl: parseFloat(c.openInterest) * parseFloat(c.markPx) || null,
+      dayNtlVlm: parseFloat(c.dayNtlVlm) || null
+    };
+  });
+  _meta = byCoin; _metaAt = Date.now();
+  return byCoin;
+}
+
+// test hook — inject fixtures instead of network
+export function _setFixtures({ feed, meta } = {}) {
+  if (feed !== undefined) { _feed = feed; _feedAt = feed ? Date.now() : 0; }
+  if (meta !== undefined) { _meta = meta; _metaAt = meta ? Date.now() : 0; }
+}
+
+function coinIntel(feed, coin) {
+  const d = feed.coins && feed.coins[coin.toUpperCase()];
+  if (!d) throw new Error('coin not in feed: ' + coin + ' (have: ' + Object.keys(feed.coins || {}).join(',') + ')');
+  // feed positions: [liqPx, notionalUsd, sideIdx(0=long,1=short), addr, entryPx, acctValue?]
+  const positions = (d.positions || []).map((p) => ({
+    price: p[0], sizeUsd: p[1], side: p[2] === 0 ? 'long' : 'short', addr: p[3], entryPx: p[4]
+  }));
+  return { ...d, positions };
+}
+
+// Wall binning — port of extension/background.js bundleIntel (0.4% bins,
+// ±50% of mark, top 12 by notional). Side = position side of the bin majority
+// is approximated by price vs mark exactly as the extension does.
+export function binWalls(positions, mark) {
+  const bins = new Map(), binW = mark ? mark * 0.004 : 1;
+  for (const l of positions) {
+    if (!mark || Math.abs(l.price - mark) / mark > 0.5) continue;
+    const k = Math.round(l.price / binW), b = bins.get(k) || { sum: 0 };
+    b.sum += l.sizeUsd; b.price = k * binW; b.side = l.price >= mark ? 'short' : 'long';
+    bins.set(k, b);
+  }
+  return [...bins.values()]
+    .map((b) => ({ price: b.price, sizeUsd: Math.round(b.sum), side: b.side, distPct: mark ? ((b.price - mark) / mark) * 100 : null }))
+    .sort((a, b) => b.sizeUsd - a.sizeUsd).slice(0, 12);
+}
+
+function honesty(feed, d) {
+  return {
+    coverage_pct: d.coverage ? d.coverage.pct : null,
+    data_age_s: feed.updated ? Math.max(0, Math.round((Date.now() - Date.parse(feed.updated)) / 1000)) : null,
+    source: 'real positions — union(top-500 acct, top-700 weekly vol) HL leaderboard crawl; NOT estimates'
+  };
+}
+
+export async function walls(coin) {
+  const [feed, meta] = [await getFeed(), await getMeta()];
+  const d = coinIntel(feed, coin);
+  const mark = (meta[coin.toUpperCase()] || {}).markPx || d.mark;
+  const w = binWalls(d.positions, mark);
+  let magnet = null;
+  for (const l of d.positions) {
+    if (l.sizeUsd < BIG_WALL) continue;
+    const dist = Math.abs(l.price - mark) / mark;
+    if (dist <= MAGNET_NEAR && (!magnet || l.sizeUsd > magnet.sizeUsd)) {
+      magnet = { price: l.price, sizeUsd: l.sizeUsd, distPct: +(dist * 100).toFixed(2), side: l.price < mark ? 'below' : 'above' };
+    }
+  }
+  const below = d.positions.filter((p) => p.price < mark), above = d.positions.filter((p) => p.price > mark);
+  const sum = (a) => Math.round(a.reduce((s, p) => s + p.sizeUsd, 0));
+  return {
+    coin: coin.toUpperCase(), mark, walls: w,
+    nearest: w.slice().sort((a, b) => Math.abs(a.distPct) - Math.abs(b.distPct))[0] || null,
+    totalLiqBelowUsd: sum(below), totalLiqAboveUsd: sum(above),
+    magnet, ...honesty(feed, d)
+  };
+}
+
+export async function cascade(coin, dir) {
+  if (dir !== 'up' && dir !== 'down') throw new Error("dir must be 'up' or 'down'");
+  const { VM } = loadShipped();
+  const [feed, meta] = [await getFeed(), await getMeta()];
+  const d = coinIntel(feed, coin);
+  const m = meta[coin.toUpperCase()] || {};
+  const vm = {
+    coin: coin.toUpperCase(), markPx: m.markPx || d.mark, oiNtl: m.oiNtl, dayNtlVlm: m.dayNtlVlm,
+    liqLevels: d.positions.map((p) => ({ price: p.price, sizeUsd: p.sizeUsd }))
+  };
+  const c = VM.computeCascade(vm, dir);
+  return {
+    coin: vm.coin, dir, mark: vm.markPx,
+    cascade: c ? {
+      triggerPx: c.triggerPx, terminalPx: c.terminalPx, totalLiqUsd: Math.round(c.totalLiqUsd),
+      hops: c.hops.length, dropFrac: c.dropFrac, depthSource: c.depthSource
+    } : null,
+    note: c ? 'chain-reaction estimate from real tracked positions (model k=' + VM.CASCADE_K + ')' : 'no armed chain in this direction',
+    ...honesty(feed, d)
+  };
+}
+
+export async function pretradeCheck({ coin, dir, leverage, entryPx = null, sizeUsd = null }) {
+  if (dir !== 'long' && dir !== 'short') throw new Error("dir must be 'long' or 'short'");
+  if (!(leverage > 0)) throw new Error('leverage must be > 0');
+  const { VM } = loadShipped();
+  const [feed, meta] = [await getFeed(), await getMeta()];
+  const d = coinIntel(feed, coin);
+  const m = meta[coin.toUpperCase()];
+  if (!m) throw new Error('coin not in HL meta: ' + coin);
+  if (leverage > m.maxLeverage) throw new Error('leverage ' + leverage + ' exceeds max ' + m.maxLeverage + ' for ' + coin);
+  const entry = entryPx || m.markPx;
+  const mmf = VM.maintMarginFraction(m.maxLeverage);
+  const liqPx = VM.liqPrice(entry, leverage, dir, mmf);
+  const clusters = binWalls(d.positions, m.markPx);
+  const hit = VM.huntRiskCluster(liqPx, clusters, dir);
+  const clear = hit ? VM.suggestClearLeverage(entry, dir, mmf, clusters, leverage - 1, m.maxLeverage) : null;
+  const casc = VM.computeCascade({
+    coin: coin.toUpperCase(), markPx: m.markPx, oiNtl: m.oiNtl, dayNtlVlm: m.dayNtlVlm,
+    liqLevels: d.positions.map((p) => ({ price: p.price, sizeUsd: p.sizeUsd }))
+  }, dir === 'long' ? 'down' : 'up');
+  const cascadeReachesLiq = Boolean(casc && VM.cascadeHitsPrice(casc, liqPx));
+  const verdict = hit ? 'danger' : cascadeReachesLiq ? 'warning' : 'ok';
+  return {
+    coin: coin.toUpperCase(), dir, leverage, entryPx: entry, sizeUsd,
+    liqPx, distToLiqPct: +((Math.abs(liqPx - entry) / entry) * 100).toFixed(2),
+    liqInsideWall: Boolean(hit), wall: hit || null,
+    suggestedClearLeverage: clear ? clear.lev : null,
+    cascadeReachesLiq,
+    cascade: casc ? { triggerPx: casc.triggerPx, terminalPx: casc.terminalPx, totalLiqUsd: Math.round(casc.totalLiqUsd) } : null,
+    verdict, ...honesty(feed, d)
+  };
+}
+
+export async function whaleBook(coin, topN = 10) {
+  const feed = await getFeed();
+  const d = coinIntel(feed, coin);
+  return {
+    coin: coin.toUpperCase(), mark: d.mark,
+    positions: d.positions.slice().sort((a, b) => b.sizeUsd - a.sizeUsd).slice(0, Math.min(topN, 50))
+      .map((p) => ({ addr: p.addr, side: p.side, notionalUsd: Math.round(p.sizeUsd), entryPx: p.entryPx, liqPx: p.price })),
+    nTracked: d.positions.length, ...honesty(feed, d)
+  };
+}

package/src/exchange.js

@@ -0,0 +1,88 @@
+// HypeLens Agent Rail — EXECUTION (builder-code monetized).
+// Reuses Module 3 verbatim: hl-actions.js builds every action (builder fee
+// pinned inside buildOrderAction), hl-signer.js signs through the vendored
+// SDK with the deterministic-hash gate. TESTNET-FIRST: mainnet placement is
+// hard-blocked by MAINNET_PLACEMENT_ENABLED=false inside the shipped
+// hl-actions.js — flipping it requires the operator's testnet money-path
+// proof + explicit sign-off, exactly like the extension.
+//
+// Env: HYPELENS_AGENT_PK   — agent-wallet private key (approved via approveAgent)
+//      HYPELENS_NET        — 'testnet' (default) | 'mainnet' (blocked until enabled)
+import { loadShipped } from './load.js';
+import { pretradeCheck } 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,
+    signerReady: st.ok, signerError: st.ok ? null : st.error,
+    hasAgentKey: Boolean(process.env.HYPELENS_AGENT_PK)
+  };
+}
+
+function assertPlacementAllowed(actions) {
+  if (net() === 'mainnet' && !actions.MAINNET_PLACEMENT_ENABLED) {
+    throw new Error('MAINNET PLACEMENT DISABLED — testnet money-path proof + operator sign-off required (Module 3 gate). 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)');
+}
+
+// One-time master-wallet approvals (EIP-712 payloads the MASTER signs in the
+// user's own wallet — the rail never touches the master key):
+//   1. approveAgent(agentAddress)  2. approveBuilderFee (0.01% to HypeLens)
+export function approvePayloads(agentAddress) {
+  const { actions } = loadShipped();
+  return {
+    approveAgent: actions.buildApproveAgent(net(), agentAddress),
+    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 i = meta.universe.findIndex((u) => u.name === coin.toUpperCase());
+  if (i < 0) throw new Error('coin not on ' + net() + ': ' + coin);
+  return { assetIndex: i, szDecimals: meta.universe[i].szDecimals };
+}
+
+// Risk-checked order placement. Refuses verdict='danger' (liq inside a wall)
+// unless override=true — the rail's whole point.
+export async function placeOrder({ coin, isBuy, size, entryPx, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
+  const { actions, signer } = loadShipped();
+  assertPlacementAllowed(actions);
+  let risk = null;
+  if (!skipRiskCheck && leverage) {
+    // risk data is mainnet-real even when executing on testnet
+    risk = await pretradeCheck({ coin, dir: isBuy ? 'long' : 'short', leverage, entryPx });
+    if (risk.verdict === 'danger' && !override) {
+      return { placed: false, refused: 'liq price ' + risk.liqPx + ' lands inside a $' + Math.round(risk.wall.sizeUsd / 1e6) + 'M wall — pass override:true to force', risk };
+    }
+  }
+  const { assetIndex, szDecimals } = await assetMeta(coin);
+  const action = actions.buildOrderAction({ assetIndex, szDecimals, isBuy, entryPx, size, slPx, tpPx });
+  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 { placed: res.ok && body.status === 'ok', net: net(), response: body, risk, builderFeeAttached: true };
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { walls, cascade, pretradeCheck, whaleBook, getFeed, getMeta, binWalls } from './core.js';
+export { status as exchangeStatus, placeOrder, approvePayloads, newAgentWallet } from './exchange.js';

package/src/load.js

@@ -0,0 +1,39 @@
+// Loads the SHIPPED HypeLens modules (viewmodel, exchange actions, signer,
+// vendored HL SDK) into globalThis — same eval pattern the calibration
+// harness uses. The rail never reimplements model or wire math; it evals the
+// exact files the extension ships. Dev layout reads from ../extension;
+// published layout reads from ./vendor (populated by scripts/bundle-vendor.mjs).
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SRC = dirname(fileURLToPath(import.meta.url));
+const RAIL = join(SRC, '..');
+const REPO = join(RAIL, '..');
+
+export function assetPath(rel) {
+  const candidates = [join(RAIL, 'vendor', rel.split('/').pop()), join(REPO, 'extension', rel)];
+  for (const p of candidates) if (existsSync(p)) return p;
+  throw new Error('cannot locate shipped module: ' + rel + ' (tried ' + candidates.join(', ') + ')');
+}
+
+const g = globalThis;
+let _loaded = false;
+export function loadShipped() {
+  if (_loaded) return api();
+  g.window = g;
+  // order matters: sdk → signer (self-tests against sdk) → actions → viewmodel
+  for (const rel of ['vendor/hl-sdk.js', 'exchange/hl-signer.js', 'exchange/hl-actions.js', 'viewmodel.js']) {
+    // eslint-disable-next-line no-eval
+    (0, eval)(readFileSync(assetPath(rel), 'utf8'));
+  }
+  _loaded = true;
+  return api();
+}
+
+function api() {
+  if (!g.HLVM) throw new Error('HLVM did not load');
+  if (!g.HLX3 || !g.HLX3.actions || !g.HLX3.signer) throw new Error('HLX3 did not load');
+  if (!g.HLSDK) throw new Error('HLSDK did not load');
+  return { VM: g.HLVM, actions: g.HLX3.actions, signer: g.HLX3.signer, sdk: g.HLSDK };
+}

package/src/mcp.js

@@ -0,0 +1,63 @@
+// HypeLens Agent Rail — MCP stdio server.
+// Free risk tools + testnet-gated execution for any MCP client
+// (Claude Code/Desktop, Cursor, custom agents).
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { walls, cascade, pretradeCheck, whaleBook } from './core.js';
+import { status, placeOrder, approvePayloads, newAgentWallet } from './exchange.js';
+
+const j = (v) => ({ content: [{ type: 'text', text: JSON.stringify(v, null, 1) }] });
+const wrap = (fn) => async (args) => {
+  try { return j(await fn(args)); }
+  catch (e) { return { content: [{ type: 'text', text: 'ERROR: ' + (e && e.message ? e.message : e) }], isError: true }; }
+};
+
+export async function main() {
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.0' });
+
+  server.tool('hl_walls',
+    'Liquidation walls for a Hyperliquid coin from REAL tracked whale positions (not estimates): binned clusters, nearest wall, totals above/below mark, magnet flag (≥$10M within 1.5%).',
+    { coin: z.string().describe("Coin symbol, e.g. 'BTC'") },
+    wrap(({ coin }) => walls(coin)));
+
+  server.tool('hl_cascade',
+    'Liquidation-cascade chain estimate: if price moves in a direction, which walls trigger, where the chain terminates, and total notional liquidated on the way.',
+    { coin: z.string(), dir: z.enum(['up', 'down']).describe('Price direction to simulate') },
+    wrap(({ coin, dir }) => cascade(coin, dir)));
+
+  server.tool('hl_pretrade_check',
+    'ALWAYS call before opening a Hyperliquid perp position. Computes your liquidation price and checks it against real liq walls and cascade paths. verdict: ok | warning (a cascade can reach your liq) | danger (your liq sits inside a crowded wall — reduce leverage; a clear leverage is suggested).',
+    { coin: z.string(), dir: z.enum(['long', 'short']), leverage: z.number().positive(), entryPx: z.number().positive().optional().describe('Defaults to current mark'), sizeUsd: z.number().positive().optional() },
+    wrap((a) => pretradeCheck(a)));
+
+  server.tool('hl_whale_book',
+    'Top tracked whale positions for a coin: address, side, notional, entry, liquidation price.',
+    { coin: z.string(), topN: z.number().int().positive().max(50).optional() },
+    wrap(({ coin, topN }) => whaleBook(coin, topN || 10)));
+
+  server.tool('hl_exchange_status',
+    'Execution readiness: network (testnet-first; mainnet placement is hard-blocked pending operator sign-off), signer self-test, builder-fee config, agent-key presence.',
+    {}, wrap(() => status()));
+
+  server.tool('hl_new_agent_wallet',
+    'Generate a fresh agent wallet (private key + address) for Hyperliquid API trading. Store the key yourself; then have the MASTER wallet sign the approve payloads.',
+    {}, wrap(() => newAgentWallet()));
+
+  server.tool('hl_approve_payloads',
+    'EIP-712 payloads the MASTER wallet must sign once: approveAgent(agentAddress) and approveBuilderFee (0.01% HypeLens builder fee). The rail never touches the master key.',
+    { agentAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
+    wrap(({ agentAddress }) => approvePayloads(agentAddress)));
+
+  server.tool('hl_place_order',
+    'Place a risk-checked Hyperliquid perp order (GTC limit, optional SL/TP, HypeLens builder code attached). TESTNET unless mainnet is operator-enabled. Refuses orders whose liq price sits inside a wall unless override=true.',
+    {
+      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 the pre-trade risk check'),
+      override: z.boolean().optional(), skipRiskCheck: z.boolean().optional()
+    },
+    wrap((a) => placeOrder(a)));
+
+  await server.connect(new StdioServerTransport());
+}

package/test/exchange.test.mjs

@@ -0,0 +1,74 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { loadShipped } from '../src/load.js';
+import { status, placeOrder, newAgentWallet, approvePayloads } from '../src/exchange.js';
+import { _setFixtures } from '../src/core.js';
+
+test('shipped modules load in node; signer self-test passes', () => {
+  const { actions, signer, VM } = loadShipped();
+  assert.equal(signer.selfTest().ok, true, signer.selfTest().error || '');
+  assert.equal(typeof VM.computeCascade, 'function');
+  assert.equal(actions.BUILDER, '0x9548B8E9554a1968843B3C380431b10996247c88');
+});
+
+test('every order action carries the pinned builder fee', () => {
+  const { actions } = loadShipped();
+  const a = actions.buildOrderAction({ assetIndex: 0, szDecimals: 5, isBuy: true, entryPx: 100000, size: 0.01, slPx: 95000, tpPx: 111000 });
+  assert.deepEqual(a.builder, { b: actions.BUILDER.toLowerCase(), f: 10 });
+  assert.equal(a.grouping, 'normalTpsl');
+  assert.equal(a.orders.length, 3);
+  assert.equal(a.orders[1].r, true); // SL reduce-only
+});
+
+test('mainnet placement is hard-blocked', async () => {
+  process.env.HYPELENS_NET = 'mainnet';
+  process.env.HYPELENS_AGENT_PK = '0x' + '1'.repeat(64);
+  await assert.rejects(
+    () => placeOrder({ coin: 'BTC', isBuy: true, size: 0.01, entryPx: 100000, skipRiskCheck: true }),
+    /MAINNET PLACEMENT DISABLED/);
+  delete process.env.HYPELENS_NET;
+  delete process.env.HYPELENS_AGENT_PK;
+});
+
+test('placement without agent key fails closed', async () => {
+  delete process.env.HYPELENS_AGENT_PK;
+  await assert.rejects(
+    () => placeOrder({ coin: 'BTC', isBuy: true, size: 0.01, entryPx: 100000, skipRiskCheck: true }),
+    /HYPELENS_AGENT_PK not set/);
+});
+
+test('risk gate refuses danger orders without override', async () => {
+  process.env.HYPELENS_NET = 'testnet';
+  process.env.HYPELENS_AGENT_PK = '0x' + '1'.repeat(64);
+  _setFixtures({
+    feed: {
+      updated: new Date().toISOString(),
+      coins: { BTC: { mark: 100000, coverage: { pct: 53 }, positions: [[94800, 50e6, 0, '0xaaa0000000000000000000000000000000000001', 104000]] } }
+    },
+    meta: { BTC: { assetIndex: 0, szDecimals: 5, maxLeverage: 40, markPx: 100000, oiNtl: 2e9, dayNtlVlm: 2e9 } }
+  });
+  // leverage chosen so liq falls near 94800 wall; if the model puts liq inside
+  // the wall the order must be refused (no network call is made on refusal)
+  const r = await placeOrder({ coin: 'BTC', isBuy: true, size: 0.01, entryPx: 100000, leverage: 18 })
+    .catch((e) => ({ threw: String(e.message) }));
+  if (r.refused) {
+    assert.match(r.refused, /wall/);
+    assert.equal(r.placed, false);
+  } else {
+    // liq didn't land in the wall under the shipped model — acceptable; the
+    // testnet POST path was then exercised or asset lookup failed. Either way
+    // the call must not report a successful mainnet placement.
+    assert.notEqual(r.net, 'mainnet');
+  }
+  delete process.env.HYPELENS_AGENT_PK;
+  delete process.env.HYPELENS_NET;
+});
+
+test('agent wallet + approve payloads are well-formed', () => {
+  const w = newAgentWallet();
+  assert.match(w.address, /^0x[0-9a-fA-F]{40}$/);
+  const p = approvePayloads(w.address);
+  assert.equal(p.approveAgent.action.type, 'approveAgent');
+  assert.equal(p.approveBuilderFee.action.maxFeeRate, '0.01%');
+  assert.equal(p.approveBuilderFee.primaryType, 'HyperliquidTransaction:ApproveBuilderFee');
+});

package/test/risk.test.mjs

@@ -0,0 +1,86 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { binWalls, pretradeCheck, walls, cascade, whaleBook, _setFixtures } from '../src/core.js';
+
+// Synthetic fixture: BTC at 100,000 with a fat long wall at 95,000.
+const FEED = {
+  updated: new Date().toISOString(),
+  coins: {
+    BTC: {
+      mark: 100000, oiUsd: 2e9, coverage: { pct: 53 },
+      positions: [
+        [95000, 30e6, 0, '0xaaa0000000000000000000000000000000000001', 104000],
+        [94900, 15e6, 0, '0xaaa0000000000000000000000000000000000002', 103000],
+        [99500, 12e6, 0, '0xaaa0000000000000000000000000000000000003', 101000],
+        [112000, 20e6, 1, '0xbbb0000000000000000000000000000000000004', 98000],
+        [140000, 5e6, 1, '0xbbb0000000000000000000000000000000000005', 90000]
+      ]
+    }
+  }
+};
+const META = { BTC: { assetIndex: 0, szDecimals: 5, maxLeverage: 40, markPx: 100000, oiNtl: 2e9, dayNtlVlm: 2e9 } };
+
+test('binWalls: bins by 0.4% of mark, sides by price vs mark, sorted by size', () => {
+  const w = binWalls(FEED.coins.BTC.positions.map((p) => ({ price: p[0], sizeUsd: p[1] })), 100000);
+  assert.ok(w.length >= 3);
+  // 95000 → bin 238 (95200), 94900 → bin 237 (94800): adjacent bins, no merge
+  assert.equal(w[0].sizeUsd, 30e6);
+  assert.equal(w[0].side, 'long');
+  assert.ok(Math.abs(w[0].distPct + 5) < 1);
+  assert.equal(w[1].sizeUsd, 20e6); // the 112000 short wall ranks second
+  // 140000 is outside ±50%? no — inside; but check the 112000 short bin exists
+  assert.ok(w.some((x) => x.side === 'short'));
+});
+
+test('walls(): magnet detected only within 1.5% and ≥$10M', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  const r = await walls('BTC');
+  assert.equal(r.magnet.sizeUsd, 12e6); // 99500 wall is 0.5% away and ≥$10M
+  assert.equal(r.magnet.side, 'below');
+  assert.equal(r.coverage_pct, 53);
+  assert.ok(r.totalLiqBelowUsd > r.totalLiqAboveUsd);
+});
+
+test('pretradeCheck: high leverage lands in the wall → danger + clear-leverage suggestion', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  // long entry 100k: find a leverage whose liq is ~95k (inside the 45M wall)
+  const r = await pretradeCheck({ coin: 'BTC', dir: 'long', leverage: 18, entryPx: 100000 });
+  assert.equal(typeof r.liqPx, 'number');
+  assert.ok(r.liqPx < 100000);
+  if (r.liqInsideWall) {
+    assert.equal(r.verdict, 'danger');
+    assert.ok(r.suggestedClearLeverage == null || r.suggestedClearLeverage < 18);
+  } else {
+    assert.ok(['ok', 'warning'].includes(r.verdict));
+  }
+});
+
+test('pretradeCheck: low leverage clears the walls', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  const r = await pretradeCheck({ coin: 'BTC', dir: 'long', leverage: 2, entryPx: 100000 });
+  assert.equal(r.liqInsideWall, false);
+  assert.notEqual(r.verdict, 'danger');
+});
+
+test('pretradeCheck: rejects leverage above max', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  await assert.rejects(() => pretradeCheck({ coin: 'BTC', dir: 'long', leverage: 41 }), /exceeds max/);
+});
+
+test('cascade: returns model output shape from shipped computeCascade', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  const r = await cascade('BTC', 'down');
+  assert.equal(r.dir, 'down');
+  if (r.cascade) {
+    assert.ok(r.cascade.triggerPx > 0);
+    assert.ok(r.cascade.totalLiqUsd > 0);
+  }
+});
+
+test('whaleBook: sorted by notional, capped, honest fields present', async () => {
+  _setFixtures({ feed: FEED, meta: META });
+  const r = await whaleBook('BTC', 3);
+  assert.equal(r.positions.length, 3);
+  assert.ok(r.positions[0].notionalUsd >= r.positions[1].notionalUsd);
+  assert.ok(r.source.includes('NOT estimates'));
+});