Tereno Hyper CLI

🛡️ Preserve the edge before the order reaches Hyperliquid

Not a terminal. Not a bot. Not a dashboard.

hlguard is a read-only execution guard between a strategy and an order. It measures current spread, displayed-book impact, fees and a safety buffer against the edge your strategy says it has — then returns TRADE, REDUCE_TO, DON'T_TRADE or INSUFFICIENT_DATA.

npx -y tereno-hyper-cli

# Or keep the script-first command
npx -y tereno-hyper-cli simulate trade.json

⚡ Why this exists

A trading strategy can be right and still lose money because the execution was wrong. A thin book, spread and taker fee can consume a small edge before the position even exists.

Tereno Hyper CLI does not predict the market. Your strategy supplies its expected edge. The guard answers a narrower, useful question:

Given the current visible Hyperliquid book, does this order still preserve enough of that edge to deserve being sent?

bot / strategy
      ↓  trade.json
Tereno Hyper CLI
      ↓  TRADE · REDUCE_TO · DON'T_TRADE
your existing Hyperliquid order flow

🚀 Install

Terminal

npm install -g tereno-hyper-cli
hlguard simulate trade.json

# Start the guided terminal
tereno

Or run it without a global install:

npx -y tereno-hyper-cli simulate trade.json

Bot / TypeScript

import { simulateExecution } from "tereno-hyper-cli";

const decision = await simulateExecution({
  coin: "ETH",
  side: "buy",
  size: "0.25",
  orderType: "ioc",
  expectedEdgeBps: 12,
  takerFeeBps: 4.5,
  safetyBufferBps: 0.5,
});

if (decision.decision !== "TRADE") {
  // Do not send the order.
}

For a machine-readable command response:

hlguard simulate trade.json --json

The --json mode prints no banner, so a bot receives JSON only.

📥 Trade input

{
  "coin": "ETH",
  "side": "buy",
  "size": "0.25",
  "orderType": "ioc",
  "expectedEdgeBps": 12,
  "takerFeeBps": 4.5,
  "builderFeeBps": 0,
  "safetyBufferBps": 0.5,
  "minimumNetEdgeBps": 0.5,
  "maxBookAgeMs": 1000
}

| Field | Meaning | |---|---| | expectedEdgeBps | The strategy's own expected edge. The guard does not manufacture alpha. | | takerFeeBps | Your actual expected exchange fee. Required: guessing a user's fee tier is dishonest. | | builderFeeBps | Optional additional builder fee. Set to 0 today. | | safetyBufferBps | Extra margin for the book moving between observation and fill. | | minimumNetEdgeBps | Minimum edge that must remain after all estimated costs. | | maxBookAgeMs | Maximum accepted age of the L2 snapshot; default is 1,000 ms. |

🧮 What it calculates

For a buy order:

mid             = (best bid + best ask) / 2
spread          = best ask - mid
book impact     = VWAP for your size - best ask
total cost      = spread + book impact + fees + safety buffer
net edge        = expected edge - total cost

The sell calculation is symmetric. Spread and impact are intentionally split so the same cost is not counted twice.

Example:

Expected edge:       +12.00 bp
Spread:              -0.26 bp
Book impact:         -0.00 bp
Trading fees:        -4.50 bp
Safety buffer:       -0.50 bp
Net expected edge:   +6.74 bp

Decision: TRADE

🚦 Decisions

| Decision | Meaning | |---|---| | TRADE | The supplied edge survives the estimated cost and policy buffer. | | REDUCE_TO | The requested size fails, but a smaller visible-book size passes. | | DON'T_TRADE | Estimated execution cost consumes the supplied edge. | | INSUFFICIENT_DATA | The book is stale or the order exceeds visible depth. The tool refuses to invent liquidity. |

🔐 Security & honest boundaries

• No wallet, private key, API key or signup is required.
• No order is signed, sent, modified or cancelled. Your bot and its wallet retain complete control.
• The CLI currently reads a public L2 snapshot. Hyperliquid exposes at most 20 displayed levels per side through this endpoint; the guard fails closed when requested size exceeds that visible depth.
• A passing decision means only that the order passed this bounded policy using the observed book. It is not a promise of fill, profit, safety, alpha or protection from future book changes, latency, funding, liquidation or MEV.
• expectedEdgeBps remains the strategy's claim. The guard measures execution cost; it does not prove that the strategy is correct.

Read the Hyperliquid L2 book API documentation for the underlying market-data contract.

💰 Builder fees and x402 — not enabled yet

This is an operating canary. It currently charges nothing.

If it proves that users save more execution cost than it adds, the intended commercial path is a small Hyperliquid builder fee on protected fills — not a fee for every rejected trade. That requires explicit user approval and a future order-flow integration; it is deliberately outside this first release.

x402 is separate: it may later charge a hosted decision API, but it is not a native Hyperliquid execution fee. The CLI remains free while the usefulness hypothesis is being tested.

🛠️ Develop locally

git clone https://github.com/tereno-xyz/hyper-cli.git
cd hyper-cli
npm install
npm test
node bin/hlguard.mjs simulate examples/trade.json

🤝 Support & community

• 💬 Questions / feedback → Tereno Discord
• 🐛 Bugs → GitHub issues
• 🔒 Vulnerabilities → report privately

tereno.xyz · Preserve the edge before the order reaches the book.