@hypelens/hypelens-agent-rail 0.1.1

package/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+vendor/
+*.tgz

package/README.md

@@ -0,0 +1,71 @@
+# HypeLens Agent Rail
+
+**Eyes and hands for AI agents trading Hyperliquid perps.** Real-data liquidation
+intelligence (free) + risk-checked execution (builder-code monetized), as an MCP
+server and a plain Node SDK.
+
+- **Real, not estimated**: walls/cascades come from a live crawl of ~1,100 top
+  Hyperliquid wallets (union of top-500 by account value and top-700 by weekly
+  volume), refreshed every 15 minutes. Every response carries `coverage_pct`
+  and `data_age_s` — we tell you exactly how much of open interest we see.
+- **Risk-checked execution**: `hl_place_order` computes your liquidation price
+  and *refuses* orders whose liq lands inside a crowded wall (override
+  available). SL/TP ship in the same atomic order group.
+- **Testnet-first**: mainnet placement is hard-blocked in code until the
+  operator's testnet money-path sign-off — the same gate as the HypeLens
+  extension's Module 3.
+
+## Quickstart (MCP)
+
+```bash
+# Claude Code
+claude mcp add hypelens -- npx hypelens-agent-rail
+
+# any MCP client — stdio server:
+npx hypelens-agent-rail
+```
+
+Tools: `hl_walls`, `hl_cascade`, `hl_pretrade_check`, `hl_whale_book`,
+`hl_exchange_status`, `hl_new_agent_wallet`, `hl_approve_payloads`,
+`hl_place_order`.
+
+## Quickstart (SDK)
+
+```js
+import { walls, pretradeCheck, placeOrder } from 'hypelens-agent-rail';
+
+const w = await walls('BTC');           // real liq walls + magnet flag
+const r = await pretradeCheck({ coin: 'BTC', dir: 'long', leverage: 20 });
+if (r.verdict !== 'danger') {
+  await placeOrder({ coin: 'BTC', isBuy: true, size: 0.01, entryPx: r.entryPx,
+                     slPx: r.liqPx * 1.02, leverage: 20 });   // testnet until enabled
+}
+```
+
+Execution env: `HYPELENS_AGENT_PK` (agent wallet key you generate with
+`hl_new_agent_wallet`; the master wallet signs two one-time EIP-712 approvals —
+agent + 0.01% builder fee — via `hl_approve_payloads`). `HYPELENS_NET=testnet`
+(default).
+
+## How it's built
+
+The rail evals the exact modules the HypeLens Chrome extension ships —
+`viewmodel.js` (liq math, cascade model), `hl-actions.js` (wire-format action
+builders, builder fee pinned), `hl-signer.js` + vendored signing SDK
+(deterministic-hash-gated) — never a reimplementation. Same data, same model,
+same safety gates as the extension overlay on app.hyperliquid.xyz.
+
+## Economics, stated plainly
+
+Risk tools are free, forever. Execution routed through the rail carries the
+HypeLens builder code at **1 basis point (0.01%)** — $0.10 per $1,000 traded —
+approved explicitly by the user's master wallet with a hard `maxFeeRate`, and
+revocable on-chain at any time.
+
+## Test
+
+```bash
+npm test          # 13 tests: model load, wire format, mainnet block, risk gate
+```
+
+MIT. Part of [HypeLens](https://github.com/polyparlay/hypelens).

package/ROLLOUT.md

@@ -0,0 +1,67 @@
+# Agent Rail — rollout plan (2026-07-22)
+
+No "post on CT and pray." Every channel below is a named registry, community, or
+direct counterparty with a concrete submission mechanic. Revenue ground truth is
+on-chain: builder-fee receipts at 0x9548…7c88 + count of distinct wallets that
+signed `approveBuilderFee`.
+
+## Wave 1 — publish + registries (this week; mostly Claude-executable)
+
+| # | Venue | Mechanic | Who |
+|---|---|---|---|
+| 1 | **npm** (`hypelens-agent-rail`) — makes `npx` quickstart real; npm search is a discovery surface itself | `npm publish` from agent-rail/ (prepack bundles vendor) | **Operator**: npm account/token. Claude: everything else |
+| 2 | **Official MCP Registry** (registry.modelcontextprotocol.io) — what Claude/Cursor/clients browse | add `server.json`, publish via `mcp-publisher` CLI (GitHub auth) | Claude preps; operator authorizes GitHub auth |
+| 3 | **Smithery.ai** — largest MCP directory, shows install counts (our adoption KPI) | GitHub sign-in + add repo (one click) + `smithery.yaml` | Claude preps yaml; **operator**: one-click connect |
+| 4 | **Glama / PulseMCP / mcp.so** MCP directories | submission forms / PRs | Claude |
+| 5 | **awesome-mcp-servers** + **awesome-hyperliquid** GitHub lists | PRs | Claude |
+| 6 | Split to standalone repo `polyparlay/agent-rail`? | better star/discovery surface than a subdir | Operator decision; Claude executes |
+
+## Wave 2 — where HL agent devs actually are (next week)
+
+| # | Venue | Mechanic | Who |
+|---|---|---|---|
+| 7 | **Hyperliquid Discord** #api-traders / #builder-codes — where HL routes every bot dev asking API questions | working demo post + answer threads; this is support-driven distribution, not broadcast | Claude drafts; operator posts (account) |
+| 8 | **Hyper Foundation builder grants / ecosystem page** — funding AND official listing; grantees get promoted by HL itself | application; reuse `marketing/pitch/PITCH-CORE.md` grant skin (Jul 17) | Claude drafts full application; operator submits |
+| 9 | **ElizaOS plugin registry** (elizaos-plugins org) — the largest open agent framework; an existing `plugin-hyperliquid` proves demand and has NO risk tools and NO real liq data | thin plugin wrapping the SDK; PR to registry index | Claude |
+| 10 | **Bankr skills catalog** (BankrBot/skills, ~5 entries) | SKILL.md PR teaching Bankr agents `pretrade_check` | Claude (already scoped) |
+| 11 | **Coinbase AgentKit** action provider | PR adding HL risk actions | Claude (secondary) |
+
+## Wave 3 — direct B2B (the % of real volume; starts as soon as Wave 1 is live)
+
+Named counterparties, each with a specific ask — data licensing for platforms
+that already have their own builder codes, rail integration for those that don't:
+
+| Target | Why them | Ask |
+|---|---|---|
+| **pvp.trade, Insilico, Dexari, Mizar** (established HL frontends/terminals) | have builder-code flow, have NO real-position liq data (all use estimates or nothing) | license the feed/pretrade-check as white-label API ($/mo) — they keep their code, we sell the eyes |
+| **Capacitr, Hypurr, Nexus Trading Labs** (Bankr's HL-adjacent agents, measured small but live) | free rail integration = instant differentiation for them | integrate free risk tools; execution via our rail where they lack their own |
+| **Top HL vault leaders / copy-trade operators** — addresses already in our feed | they route size programmatically; our whale drill-down IS their risk profile | direct note: "here's your own liq exposure on our map" + rail/API |
+| **HL trading-bot OSS maintainers** (hyperliquid-python-sdk ecosystem, ccxt-hyperliquid users) | devs who wire bots by hand | PR examples + README links |
+
+Reuse `marketing/pitch/OUTREACH-SENDS.md` (partner skin) for all of the above.
+
+## Gate to revenue
+
+Builder fees only accrue on **mainnet** flow. The one blocking item is the
+standing Module 3 gate: **operator testnet money-path proof → explicit sign-off
+→ flip `MAINNET_PLACEMENT_ENABLED`** in `extension/exchange/hl-actions.js`
+(rail inherits it automatically). Wave 1-2 proceed regardless — risk tools are
+mainnet-real today and are the acquisition hook.
+
+## Pre-registered adoption gates (no dust)
+
+- **Week 2** (from npm publish): ≥25 installs (Smithery + npm downloads) OR ≥2
+  live integration conversations from Wave 3 → continue. Below both → the
+  problem is packaging/pitch; iterate THAT, don't add features.
+- **Week 6**: ≥1 platform integration signed OR ≥$50/wk builder-fee revenue
+  on-chain OR ≥200 weekly `pretrade_check` calls → invest (Eliza-native vault
+  product, alerts). Below all three → write the verdict to memory, keep the
+  rail published at zero marginal cost, stop investing.
+
+## Operator one-time checklist (~2h total)
+1. npm account + `npm publish` (or hand Claude a token)
+2. Smithery GitHub connect (one click)
+3. MCP-registry GitHub auth for `mcp-publisher`
+4. Decide: split `polyparlay/agent-rail` repo?
+5. HL Discord + grant submission (Claude drafts everything)
+6. Testnet proof session (~30 min with testnet USDC) → mainnet sign-off

package/bin/hypelens-rail-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../src/mcp.js';
+main().catch((e) => { console.error('hypelens-rail-mcp fatal:', e); process.exit(1); });