@pgnio/helios-mcp 0.4.0 → 0.5.0

package/README.md

@@ -20,7 +20,7 @@ https://helios.pgn.io/?connect=ai.
 | URL (hosted) | `HELIOS_MCP_PROFILE` (local) | Tools | For |
 | --- | --- | --- | --- |
 | `/mcp` | `lean` (default) | `sm_board`, `sm_moves`, `sm_coin`, `market`, `account`, `trades`, `trade`, `protect`, `candles` | Most agents, and small local models |
-| `/mcp/signals` | `signals` | the reads above, no `trade` or `protect` | Agents that watch but never trade |
+| `/mcp/signals` | `signals` | the same; `trade` and `protect` on the practice account only | Agents that watch or practice, never trade for real |
 | `/mcp/full` | `full` | lean plus the full ~50-column snapshot, symbol detail with raw indicators, fills and the indicator docs | Strong models doing their own analysis |
 
 Every lean answer is short text (a first line that answers, then one line per row) plus the same data as structured

package/dist/{chunk-5LIHYXEF.mjs → chunk-XM257Y63.mjs}

@@ -578,7 +578,13 @@ var agentMarketRowSchema = z2.object({
   volUsd: z2.number().nullable(),
   fundAprPct: z2.number().nullable(),
   oiUsd: z2.number().nullable(),
-  setup: agentSetupSchema.nullable()
+  setup: agentSetupSchema.nullable(),
+  /** Coin limits and the book; absent from older data-bridges. */
+  maxLev: z2.number().nullish(),
+  spreadBps: z2.number().nullish(),
+  slip10kBps: z2.number().nullish(),
+  slip100kBps: z2.number().nullish(),
+  depth1pctUsd: z2.number().nullish()
 });
 var agentMarketSchema = z2.object({
   asOf: z2.string().nullable(),
@@ -2703,6 +2709,7 @@ function renderCoin(c, you, now = Date.now()) {
     const vs = sm?.side ? entryText(sm.side, sm.edgePct) : null;
     lines.push(`price | ${price(mk.px)}${vs ? ` (${vs})` : ""} \xB7 15m ${pct(mk.r15m)} \xB7 1h ${pct(mk.r1h)} \xB7 24h ${pct(mk.r24h)}`);
     lines.push(`setup | ${mk.setup ?? "n/a"} \xB7 funding ${pct(mk.fundAprPct, 0)} APR \xB7 open interest ${usd(mk.oiUsd)} \xB7 vol ${usd(mk.volUsd)}`);
+    lines.push(tradingLine(mk, now));
   } else lines.push("price | no market data for this coin");
   if (sm && sm.flow1hUsd !== 0) lines.push(`flow | ${usd(Math.abs(sm.flow1hUsd))} net toward ${sm.flow1hUsd > 0 ? "long" : "short"} in the last hour`);
   if (sm?.pileIn) lines.push(`pile-in | ${pileText(sm.pileIn, now)}`);
@@ -2717,6 +2724,20 @@ function renderCoin(c, you, now = Date.now()) {
   if (c.note) lines.push(c.note);
   return lines.join("\n");
 }
+var MIN_ORDER_USD = 10;
+var bps = (v) => v === null || v === void 0 || !Number.isFinite(v) ? "n/a" : `${trim(v, 2)} bps`;
+function tradingLine(mk, now = Date.now()) {
+  const parts = [`max ${mk.maxLev ? `${trim(mk.maxLev, 0)}x` : "n/a"}`, `min order $${MIN_ORDER_USD}`];
+  if (mk.spreadBps !== null && mk.spreadBps !== void 0) parts.push(`spread ${bps(mk.spreadBps)}`);
+  if (mk.slip10kBps !== null && mk.slip10kBps !== void 0) parts.push(`$10k market order slips ${bps(mk.slip10kBps)}, $100k ${bps(mk.slip100kBps)}`);
+  if (mk.depth1pctUsd !== null && mk.depth1pctUsd !== void 0) parts.push(`${usd(mk.depth1pctUsd)} within 1%`);
+  if (mk.fundAprPct !== null) {
+    const hourly = mk.fundAprPct / (24 * 365);
+    const mins = Math.max(1, Math.ceil((36e5 - now % 36e5) / 6e4));
+    parts.push(`funding ${hourly > 0 ? "+" : ""}${hourly.toFixed(4)}%/h (${hourly >= 0 ? "longs pay" : "shorts pay"}), next in ${mins}m`);
+  }
+  return `trading | ${parts.join(" \xB7 ")}`;
+}
 function renderAccount(p, orders, summary) {
   const lines = [
     `account \xB7 value ${usd(p.totalBalance)} \xB7 free ${usd(p.availableBalance)} \xB7 margin used ${usd(p.totalMargin)} \xB7 open PnL ${usd(p.unrealizedPnl, true)}`
@@ -3252,13 +3273,15 @@ function createLeanToolDefinitions(services) {
   }
   async function protectionFor(input) {
     if (input.side === "short" && (input.tp_pct ?? 0) >= 100) throw new Error("A short can gain at most 100%: tp_pct must be under 100");
+    const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 })).catch(() => null);
+    if (m && !m.ok) return { pending: m.pending };
+    const row = m?.value?.rows?.find((r) => sameCoinName(r.coin, input.coin)) ?? null;
+    if (row?.maxLev && input.leverage && input.leverage > row.maxLev)
+      throw new Error(`${input.coin} allows at most ${row.maxLev}x on Hyperliquid: lower leverage. Nothing was sent.`);
+    if (input.leverage && input.margin_usd && input.margin_usd * input.leverage < MIN_ORDER_USD)
+      throw new Error(`Order value $${(input.margin_usd * input.leverage).toFixed(2)} is under Hyperliquid's $${MIN_ORDER_USD} minimum (margin x leverage). Nothing was sent.`);
     if (!input.sl_pct && !input.tp_pct) return { value: void 0 };
-    let ref = input.limit_px ?? null;
-    if (ref === null) {
-      const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 }));
-      if (!m.ok) return { pending: m.pending };
-      ref = m.value.rows[0]?.px ?? null;
-    }
+    const ref = input.limit_px ?? row?.px ?? null;
     if (ref === null) throw new Error(`No price for ${input.coin} to place the stop from; trade without sl_pct/tp_pct, then use protect`);
     const long = input.side === "long";
     const at = (p, away) => Number((p * (1 + away / 100)).toPrecision(6));
@@ -3271,9 +3294,16 @@ function createLeanToolDefinitions(services) {
   }
   return { smBoard, smMoves, smCoin, market, account, trade, protect, trades, candles };
 }
+function practiceOnly(tool) {
+  return {
+    ...tool,
+    description: `Practice account only on this link (no real money). ${tool.description}`,
+    execute: (input) => tool.execute({ ...input, paper: true })
+  };
+}
 function leanToolsFor(tools, profile) {
   const reads = [tools.smBoard, tools.smMoves, tools.smCoin, tools.market];
-  const list = profile === "signals" ? [...reads, tools.account, tools.trades, tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
+  const list = profile === "signals" ? [...reads, tools.account, tools.trades, practiceOnly(tools.trade), practiceOnly(tools.protect), tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
   return list;
 }
 
@@ -4083,7 +4113,7 @@ async function createHeliosAgentMcpServer(options) {
   const server = new McpServer(
     {
       name: "helios",
-      version: "0.4.0"
+      version: "0.5.0"
     },
     // Caps the array elements plus object keys one tools/call may carry (GHSA-46jr-4wx8-v453: without it, one request
     // under the body size limit could run the hosted server out of memory while validating). The largest real input is
@@ -4241,6 +4271,8 @@ export {
   renderBoard,
   renderMoves,
   renderCoin,
+  MIN_ORDER_USD,
+  tradingLine,
   renderAccount,
   positionLine,
   renderTrades,
@@ -4258,6 +4290,7 @@ export {
   candlesInputSchema,
   wrongSideTpSl,
   createLeanToolDefinitions,
+  practiceOnly,
   leanToolsFor,
   createHeliosDocsToolDefinitions,
   createHeliosAuthToolDefinitions,

package/dist/cli.js

@@ -594,7 +594,13 @@ var agentMarketRowSchema = import_zod3.z.object({
   volUsd: import_zod3.z.number().nullable(),
   fundAprPct: import_zod3.z.number().nullable(),
   oiUsd: import_zod3.z.number().nullable(),
-  setup: agentSetupSchema.nullable()
+  setup: agentSetupSchema.nullable(),
+  /** Coin limits and the book; absent from older data-bridges. */
+  maxLev: import_zod3.z.number().nullish(),
+  spreadBps: import_zod3.z.number().nullish(),
+  slip10kBps: import_zod3.z.number().nullish(),
+  slip100kBps: import_zod3.z.number().nullish(),
+  depth1pctUsd: import_zod3.z.number().nullish()
 });
 var agentMarketSchema = import_zod3.z.object({
   asOf: import_zod3.z.string().nullable(),
@@ -2689,6 +2695,7 @@ function renderCoin(c, you, now = Date.now()) {
     const vs = sm?.side ? entryText(sm.side, sm.edgePct) : null;
     lines.push(`price | ${price(mk.px)}${vs ? ` (${vs})` : ""} \xB7 15m ${pct(mk.r15m)} \xB7 1h ${pct(mk.r1h)} \xB7 24h ${pct(mk.r24h)}`);
     lines.push(`setup | ${mk.setup ?? "n/a"} \xB7 funding ${pct(mk.fundAprPct, 0)} APR \xB7 open interest ${usd(mk.oiUsd)} \xB7 vol ${usd(mk.volUsd)}`);
+    lines.push(tradingLine(mk, now));
   } else lines.push("price | no market data for this coin");
   if (sm && sm.flow1hUsd !== 0) lines.push(`flow | ${usd(Math.abs(sm.flow1hUsd))} net toward ${sm.flow1hUsd > 0 ? "long" : "short"} in the last hour`);
   if (sm?.pileIn) lines.push(`pile-in | ${pileText(sm.pileIn, now)}`);
@@ -2703,6 +2710,20 @@ function renderCoin(c, you, now = Date.now()) {
   if (c.note) lines.push(c.note);
   return lines.join("\n");
 }
+var MIN_ORDER_USD = 10;
+var bps = (v) => v === null || v === void 0 || !Number.isFinite(v) ? "n/a" : `${trim(v, 2)} bps`;
+function tradingLine(mk, now = Date.now()) {
+  const parts = [`max ${mk.maxLev ? `${trim(mk.maxLev, 0)}x` : "n/a"}`, `min order $${MIN_ORDER_USD}`];
+  if (mk.spreadBps !== null && mk.spreadBps !== void 0) parts.push(`spread ${bps(mk.spreadBps)}`);
+  if (mk.slip10kBps !== null && mk.slip10kBps !== void 0) parts.push(`$10k market order slips ${bps(mk.slip10kBps)}, $100k ${bps(mk.slip100kBps)}`);
+  if (mk.depth1pctUsd !== null && mk.depth1pctUsd !== void 0) parts.push(`${usd(mk.depth1pctUsd)} within 1%`);
+  if (mk.fundAprPct !== null) {
+    const hourly = mk.fundAprPct / (24 * 365);
+    const mins = Math.max(1, Math.ceil((36e5 - now % 36e5) / 6e4));
+    parts.push(`funding ${hourly > 0 ? "+" : ""}${hourly.toFixed(4)}%/h (${hourly >= 0 ? "longs pay" : "shorts pay"}), next in ${mins}m`);
+  }
+  return `trading | ${parts.join(" \xB7 ")}`;
+}
 function renderAccount(p, orders, summary) {
   const lines = [
     `account \xB7 value ${usd(p.totalBalance)} \xB7 free ${usd(p.availableBalance)} \xB7 margin used ${usd(p.totalMargin)} \xB7 open PnL ${usd(p.unrealizedPnl, true)}`
@@ -3236,13 +3257,15 @@ function createLeanToolDefinitions(services) {
   }
   async function protectionFor(input) {
     if (input.side === "short" && (input.tp_pct ?? 0) >= 100) throw new Error("A short can gain at most 100%: tp_pct must be under 100");
+    const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 })).catch(() => null);
+    if (m && !m.ok) return { pending: m.pending };
+    const row = m?.value?.rows?.find((r) => sameCoinName(r.coin, input.coin)) ?? null;
+    if (row?.maxLev && input.leverage && input.leverage > row.maxLev)
+      throw new Error(`${input.coin} allows at most ${row.maxLev}x on Hyperliquid: lower leverage. Nothing was sent.`);
+    if (input.leverage && input.margin_usd && input.margin_usd * input.leverage < MIN_ORDER_USD)
+      throw new Error(`Order value $${(input.margin_usd * input.leverage).toFixed(2)} is under Hyperliquid's $${MIN_ORDER_USD} minimum (margin x leverage). Nothing was sent.`);
     if (!input.sl_pct && !input.tp_pct) return { value: void 0 };
-    let ref = input.limit_px ?? null;
-    if (ref === null) {
-      const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 }));
-      if (!m.ok) return { pending: m.pending };
-      ref = m.value.rows[0]?.px ?? null;
-    }
+    const ref = input.limit_px ?? row?.px ?? null;
     if (ref === null) throw new Error(`No price for ${input.coin} to place the stop from; trade without sl_pct/tp_pct, then use protect`);
     const long = input.side === "long";
     const at = (p, away) => Number((p * (1 + away / 100)).toPrecision(6));
@@ -3255,9 +3278,16 @@ function createLeanToolDefinitions(services) {
   }
   return { smBoard, smMoves, smCoin, market, account, trade, protect, trades, candles };
 }
+function practiceOnly(tool) {
+  return {
+    ...tool,
+    description: `Practice account only on this link (no real money). ${tool.description}`,
+    execute: (input) => tool.execute({ ...input, paper: true })
+  };
+}
 function leanToolsFor(tools, profile) {
   const reads = [tools.smBoard, tools.smMoves, tools.smCoin, tools.market];
-  const list = profile === "signals" ? [...reads, tools.account, tools.trades, tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
+  const list = profile === "signals" ? [...reads, tools.account, tools.trades, practiceOnly(tools.trade), practiceOnly(tools.protect), tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
   return list;
 }
 
@@ -3804,7 +3834,7 @@ async function createHeliosAgentMcpServer(options) {
   const server = new McpServer(
     {
       name: "helios",
-      version: "0.4.0"
+      version: "0.5.0"
     },
     // Caps the array elements plus object keys one tools/call may carry (GHSA-46jr-4wx8-v453: without it, one request
     // under the body size limit could run the hosted server out of memory while validating). The largest real input is

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   DEFAULT_HELIOS_BASE_URL,
   MCP_PROFILES,
   createHeliosAgentMcpServer
-} from "./chunk-5LIHYXEF.mjs";
+} from "./chunk-XM257Y63.mjs";
 
 // src/cli.ts
 async function main() {

package/dist/index.d.mts

@@ -675,6 +675,11 @@ declare const agentMarketSchema: z.ZodObject<{
             "stretched down": "stretched down";
             neutral: "neutral";
         }>>;
+        maxLev: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        spreadBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip10kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip100kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        depth1pctUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         sm: z.ZodNullable<z.ZodObject<{
             side: z.ZodNullable<z.ZodEnum<{
                 long: "long";
@@ -901,6 +906,11 @@ declare const smartMoneyCoinSchema: z.ZodObject<{
             "stretched down": "stretched down";
             neutral: "neutral";
         }>>;
+        maxLev: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        spreadBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip10kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip100kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        depth1pctUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
     moves: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1646,7 +1656,7 @@ declare class HeliosAgentMcpTradingService {
  * Which tools a server lists (Mario 2026-10-26, the lean MCP):
  * - lean: the 9 smart-money-first tools (reads, your trades, trade, protect, candles) with short text answers, for small models (Qwen 27B
  *   at 32k) and most agents;
- * - signals: the reads of lean only (no trade or protect), for agents that should watch but never trade;
+ * - signals: the reads of lean, with trade and protect on the practice account only, for agents that watch or practice;
  * - full: lean plus the depth reads (the ~50-column snapshot, symbol detail with raw indicators, fills, the
  *   indicator docs), for strong models that do their own analysis.
  */
@@ -2838,6 +2848,13 @@ interface CoinYou {
     availableBalance: number;
 }
 declare function renderCoin(c: SmartMoneyCoin, you: CoinYou | null, now?: number): string;
+/** Minimum order value on Hyperliquid (notional = margin x leverage). */
+declare const MIN_ORDER_USD = 10;
+/**
+ * What it costs to trade the coin now: max leverage, spread, the slippage of a $10k and $100k market order (worse
+ * side), USD resting within 1% (thinner side), and the next funding payment (Hyperliquid pays every hour on the hour).
+ */
+declare function tradingLine(mk: SmartMoneyCoin['market'] & object, now?: number): string;
 declare function renderAccount(p: PortfolioSnapshot, orders: OpenOrder[] | null, summary: LedgerSummary | null): string;
 /** "long 0.5 BTC @ 67,420 · mark 67,900 · open PnL +$240 · 10x · liquidation 61,200". */
 declare function positionLine(pos: PortfolioSnapshot['positions'][number]): string;
@@ -3063,6 +3080,14 @@ declare function createLeanToolDefinitions(services: LeanServices): {
 };
 type LeanTools = ReturnType<typeof createLeanToolDefinitions>;
 /** The tool sets per profile, in the order they are listed (smart money first, so it is what a model reaches for). */
+/**
+ * A write tool for Watch only links (Mario 2026-11-08: they may paper trade): the same tool on the practice account
+ * only, whatever `paper` says. data-bridge holds the same line (paper.ts paperWriter): a watch-only token may change
+ * the agent practice account and nothing else.
+ */
+declare function practiceOnly<T extends {
+    paper?: boolean;
+}>(tool: LeanToolDefinition<T>): LeanToolDefinition<T>;
 declare function leanToolsFor(tools: LeanTools, profile: 'lean' | 'signals' | 'full'): LeanToolDefinition<never>[];
 
-export { type ActiveProviderView, type AgentMcpSessionStore, type CancelOrderToolResult, type ClosePositionToolResult, type CoinYou, type CreateHeliosAgentMcpServerOptions, DEFAULT_HELIOS_BASE_URL, DEFAULT_HELIOS_SESSION_ISSUER, DEFAULT_SNAPSHOT_FIELDS, DEFAULT_SNAPSHOT_TOP, type DeleteTpSlToolResult, type EnsureLoginOptions, type EnsureLoginResult, FileAgentSessionStore, type FileAgentSessionStoreOptions, type GetHeliosAgentMcpDocumentInput, HOSTED_RECONNECT_MESSAGE, HeliosAgentMcpAccountService, type HeliosAgentMcpAccountServiceOptions, HeliosAgentMcpAuthService, type HeliosAgentMcpAuthServiceOptions, type HeliosAgentMcpDocsIndex, type HeliosAgentMcpDocsIndexEntry, HeliosAgentMcpDocsService, type HeliosAgentMcpDocsServiceOptions, type HeliosAgentMcpDocument, HeliosAgentMcpLedgerService, type HeliosAgentMcpLedgerServiceOptions, HeliosAgentMcpMarketService, type HeliosAgentMcpMarketServiceOptions, HeliosAgentMcpProviderService, type HeliosAgentMcpProviderServiceOptions, HeliosAgentMcpTradingService, type HeliosAgentMcpTradingServiceOptions, type HeliosMcpToolDefinition, type HeliosMcpToolResult, type LeanServices, type LeanToolDefinition, type LeanToolResult, type LeanTools, type LedgerFillsResult, type LedgerSummaryResult, MAX_TOOL_INPUT_ELEMENTS, MCP_PROFILES, type MarketSnapshotChunkResult, type MarketSnapshotResult, type MarketSymbolDetailResult, type McpProfile, MemoryAgentMcpSessionStore, type OpenOrdersToolResult, type OpenPositionsResult, type PendingAgentLogin, type PendingLoginResult, type PollLoginResult, type PortfolioResult, type SetTpSlToolResult, type StartLoginResult, TRADE_KEY_WINDOW_SECONDS, type TradeIntentAction, type TradeIntentActionInput, type TradeIntentActionResult, type WalletStateResult, accountInputSchema, ago, assertHeliosBaseUrl, candlesInputSchema, compactSymbolDetail, createHeliosAccountToolDefinitions, createHeliosAgentMcpServer, createHeliosAuthToolDefinitions, createHeliosDocsToolDefinitions, createHeliosLedgerToolDefinitions, createHeliosMarketToolDefinitions, createHeliosProviderToolDefinitions, createHeliosTradingToolDefinitions, createLeanToolDefinitions, entryText, formatHeliosLoginPrompt, getDefaultHeliosAgentMcpDocsRoot, getDefaultHeliosAgentMcpSessionPath, isSameHeliosIssuer, leanToolsFor, marketInputSchema, moveText, pct, pendingAgentLoginSchema, positionLine, price, protectInputSchema, renderAccount, renderBoard, renderCandles, renderCoin, renderMarket, renderMoves, renderTrades, retryAfterUnauthorizedRefresh, smBoardInputSchema, smCoinInputSchema, smMovesInputSchema, toolAnnotations, topOfSnapshot, tradeInputSchema, tradeKeyFor, trader, tradesInputSchema, usd, withDataText, withSnapshotDefaults, wrongSideTpSl };
+export { type ActiveProviderView, type AgentMcpSessionStore, type CancelOrderToolResult, type ClosePositionToolResult, type CoinYou, type CreateHeliosAgentMcpServerOptions, DEFAULT_HELIOS_BASE_URL, DEFAULT_HELIOS_SESSION_ISSUER, DEFAULT_SNAPSHOT_FIELDS, DEFAULT_SNAPSHOT_TOP, type DeleteTpSlToolResult, type EnsureLoginOptions, type EnsureLoginResult, FileAgentSessionStore, type FileAgentSessionStoreOptions, type GetHeliosAgentMcpDocumentInput, HOSTED_RECONNECT_MESSAGE, HeliosAgentMcpAccountService, type HeliosAgentMcpAccountServiceOptions, HeliosAgentMcpAuthService, type HeliosAgentMcpAuthServiceOptions, type HeliosAgentMcpDocsIndex, type HeliosAgentMcpDocsIndexEntry, HeliosAgentMcpDocsService, type HeliosAgentMcpDocsServiceOptions, type HeliosAgentMcpDocument, HeliosAgentMcpLedgerService, type HeliosAgentMcpLedgerServiceOptions, HeliosAgentMcpMarketService, type HeliosAgentMcpMarketServiceOptions, HeliosAgentMcpProviderService, type HeliosAgentMcpProviderServiceOptions, HeliosAgentMcpTradingService, type HeliosAgentMcpTradingServiceOptions, type HeliosMcpToolDefinition, type HeliosMcpToolResult, type LeanServices, type LeanToolDefinition, type LeanToolResult, type LeanTools, type LedgerFillsResult, type LedgerSummaryResult, MAX_TOOL_INPUT_ELEMENTS, MCP_PROFILES, MIN_ORDER_USD, type MarketSnapshotChunkResult, type MarketSnapshotResult, type MarketSymbolDetailResult, type McpProfile, MemoryAgentMcpSessionStore, type OpenOrdersToolResult, type OpenPositionsResult, type PendingAgentLogin, type PendingLoginResult, type PollLoginResult, type PortfolioResult, type SetTpSlToolResult, type StartLoginResult, TRADE_KEY_WINDOW_SECONDS, type TradeIntentAction, type TradeIntentActionInput, type TradeIntentActionResult, type WalletStateResult, accountInputSchema, ago, assertHeliosBaseUrl, candlesInputSchema, compactSymbolDetail, createHeliosAccountToolDefinitions, createHeliosAgentMcpServer, createHeliosAuthToolDefinitions, createHeliosDocsToolDefinitions, createHeliosLedgerToolDefinitions, createHeliosMarketToolDefinitions, createHeliosProviderToolDefinitions, createHeliosTradingToolDefinitions, createLeanToolDefinitions, entryText, formatHeliosLoginPrompt, getDefaultHeliosAgentMcpDocsRoot, getDefaultHeliosAgentMcpSessionPath, isSameHeliosIssuer, leanToolsFor, marketInputSchema, moveText, pct, pendingAgentLoginSchema, positionLine, practiceOnly, price, protectInputSchema, renderAccount, renderBoard, renderCandles, renderCoin, renderMarket, renderMoves, renderTrades, retryAfterUnauthorizedRefresh, smBoardInputSchema, smCoinInputSchema, smMovesInputSchema, toolAnnotations, topOfSnapshot, tradeInputSchema, tradeKeyFor, trader, tradesInputSchema, tradingLine, usd, withDataText, withSnapshotDefaults, wrongSideTpSl };

package/dist/index.d.ts

@@ -675,6 +675,11 @@ declare const agentMarketSchema: z.ZodObject<{
             "stretched down": "stretched down";
             neutral: "neutral";
         }>>;
+        maxLev: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        spreadBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip10kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip100kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        depth1pctUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         sm: z.ZodNullable<z.ZodObject<{
             side: z.ZodNullable<z.ZodEnum<{
                 long: "long";
@@ -901,6 +906,11 @@ declare const smartMoneyCoinSchema: z.ZodObject<{
             "stretched down": "stretched down";
             neutral: "neutral";
         }>>;
+        maxLev: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        spreadBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip10kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        slip100kBps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        depth1pctUsd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, z.core.$strip>>;
     moves: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -1646,7 +1656,7 @@ declare class HeliosAgentMcpTradingService {
  * Which tools a server lists (Mario 2026-10-26, the lean MCP):
  * - lean: the 9 smart-money-first tools (reads, your trades, trade, protect, candles) with short text answers, for small models (Qwen 27B
  *   at 32k) and most agents;
- * - signals: the reads of lean only (no trade or protect), for agents that should watch but never trade;
+ * - signals: the reads of lean, with trade and protect on the practice account only, for agents that watch or practice;
  * - full: lean plus the depth reads (the ~50-column snapshot, symbol detail with raw indicators, fills, the
  *   indicator docs), for strong models that do their own analysis.
  */
@@ -2838,6 +2848,13 @@ interface CoinYou {
     availableBalance: number;
 }
 declare function renderCoin(c: SmartMoneyCoin, you: CoinYou | null, now?: number): string;
+/** Minimum order value on Hyperliquid (notional = margin x leverage). */
+declare const MIN_ORDER_USD = 10;
+/**
+ * What it costs to trade the coin now: max leverage, spread, the slippage of a $10k and $100k market order (worse
+ * side), USD resting within 1% (thinner side), and the next funding payment (Hyperliquid pays every hour on the hour).
+ */
+declare function tradingLine(mk: SmartMoneyCoin['market'] & object, now?: number): string;
 declare function renderAccount(p: PortfolioSnapshot, orders: OpenOrder[] | null, summary: LedgerSummary | null): string;
 /** "long 0.5 BTC @ 67,420 · mark 67,900 · open PnL +$240 · 10x · liquidation 61,200". */
 declare function positionLine(pos: PortfolioSnapshot['positions'][number]): string;
@@ -3063,6 +3080,14 @@ declare function createLeanToolDefinitions(services: LeanServices): {
 };
 type LeanTools = ReturnType<typeof createLeanToolDefinitions>;
 /** The tool sets per profile, in the order they are listed (smart money first, so it is what a model reaches for). */
+/**
+ * A write tool for Watch only links (Mario 2026-11-08: they may paper trade): the same tool on the practice account
+ * only, whatever `paper` says. data-bridge holds the same line (paper.ts paperWriter): a watch-only token may change
+ * the agent practice account and nothing else.
+ */
+declare function practiceOnly<T extends {
+    paper?: boolean;
+}>(tool: LeanToolDefinition<T>): LeanToolDefinition<T>;
 declare function leanToolsFor(tools: LeanTools, profile: 'lean' | 'signals' | 'full'): LeanToolDefinition<never>[];
 
-export { type ActiveProviderView, type AgentMcpSessionStore, type CancelOrderToolResult, type ClosePositionToolResult, type CoinYou, type CreateHeliosAgentMcpServerOptions, DEFAULT_HELIOS_BASE_URL, DEFAULT_HELIOS_SESSION_ISSUER, DEFAULT_SNAPSHOT_FIELDS, DEFAULT_SNAPSHOT_TOP, type DeleteTpSlToolResult, type EnsureLoginOptions, type EnsureLoginResult, FileAgentSessionStore, type FileAgentSessionStoreOptions, type GetHeliosAgentMcpDocumentInput, HOSTED_RECONNECT_MESSAGE, HeliosAgentMcpAccountService, type HeliosAgentMcpAccountServiceOptions, HeliosAgentMcpAuthService, type HeliosAgentMcpAuthServiceOptions, type HeliosAgentMcpDocsIndex, type HeliosAgentMcpDocsIndexEntry, HeliosAgentMcpDocsService, type HeliosAgentMcpDocsServiceOptions, type HeliosAgentMcpDocument, HeliosAgentMcpLedgerService, type HeliosAgentMcpLedgerServiceOptions, HeliosAgentMcpMarketService, type HeliosAgentMcpMarketServiceOptions, HeliosAgentMcpProviderService, type HeliosAgentMcpProviderServiceOptions, HeliosAgentMcpTradingService, type HeliosAgentMcpTradingServiceOptions, type HeliosMcpToolDefinition, type HeliosMcpToolResult, type LeanServices, type LeanToolDefinition, type LeanToolResult, type LeanTools, type LedgerFillsResult, type LedgerSummaryResult, MAX_TOOL_INPUT_ELEMENTS, MCP_PROFILES, type MarketSnapshotChunkResult, type MarketSnapshotResult, type MarketSymbolDetailResult, type McpProfile, MemoryAgentMcpSessionStore, type OpenOrdersToolResult, type OpenPositionsResult, type PendingAgentLogin, type PendingLoginResult, type PollLoginResult, type PortfolioResult, type SetTpSlToolResult, type StartLoginResult, TRADE_KEY_WINDOW_SECONDS, type TradeIntentAction, type TradeIntentActionInput, type TradeIntentActionResult, type WalletStateResult, accountInputSchema, ago, assertHeliosBaseUrl, candlesInputSchema, compactSymbolDetail, createHeliosAccountToolDefinitions, createHeliosAgentMcpServer, createHeliosAuthToolDefinitions, createHeliosDocsToolDefinitions, createHeliosLedgerToolDefinitions, createHeliosMarketToolDefinitions, createHeliosProviderToolDefinitions, createHeliosTradingToolDefinitions, createLeanToolDefinitions, entryText, formatHeliosLoginPrompt, getDefaultHeliosAgentMcpDocsRoot, getDefaultHeliosAgentMcpSessionPath, isSameHeliosIssuer, leanToolsFor, marketInputSchema, moveText, pct, pendingAgentLoginSchema, positionLine, price, protectInputSchema, renderAccount, renderBoard, renderCandles, renderCoin, renderMarket, renderMoves, renderTrades, retryAfterUnauthorizedRefresh, smBoardInputSchema, smCoinInputSchema, smMovesInputSchema, toolAnnotations, topOfSnapshot, tradeInputSchema, tradeKeyFor, trader, tradesInputSchema, usd, withDataText, withSnapshotDefaults, wrongSideTpSl };
+export { type ActiveProviderView, type AgentMcpSessionStore, type CancelOrderToolResult, type ClosePositionToolResult, type CoinYou, type CreateHeliosAgentMcpServerOptions, DEFAULT_HELIOS_BASE_URL, DEFAULT_HELIOS_SESSION_ISSUER, DEFAULT_SNAPSHOT_FIELDS, DEFAULT_SNAPSHOT_TOP, type DeleteTpSlToolResult, type EnsureLoginOptions, type EnsureLoginResult, FileAgentSessionStore, type FileAgentSessionStoreOptions, type GetHeliosAgentMcpDocumentInput, HOSTED_RECONNECT_MESSAGE, HeliosAgentMcpAccountService, type HeliosAgentMcpAccountServiceOptions, HeliosAgentMcpAuthService, type HeliosAgentMcpAuthServiceOptions, type HeliosAgentMcpDocsIndex, type HeliosAgentMcpDocsIndexEntry, HeliosAgentMcpDocsService, type HeliosAgentMcpDocsServiceOptions, type HeliosAgentMcpDocument, HeliosAgentMcpLedgerService, type HeliosAgentMcpLedgerServiceOptions, HeliosAgentMcpMarketService, type HeliosAgentMcpMarketServiceOptions, HeliosAgentMcpProviderService, type HeliosAgentMcpProviderServiceOptions, HeliosAgentMcpTradingService, type HeliosAgentMcpTradingServiceOptions, type HeliosMcpToolDefinition, type HeliosMcpToolResult, type LeanServices, type LeanToolDefinition, type LeanToolResult, type LeanTools, type LedgerFillsResult, type LedgerSummaryResult, MAX_TOOL_INPUT_ELEMENTS, MCP_PROFILES, MIN_ORDER_USD, type MarketSnapshotChunkResult, type MarketSnapshotResult, type MarketSymbolDetailResult, type McpProfile, MemoryAgentMcpSessionStore, type OpenOrdersToolResult, type OpenPositionsResult, type PendingAgentLogin, type PendingLoginResult, type PollLoginResult, type PortfolioResult, type SetTpSlToolResult, type StartLoginResult, TRADE_KEY_WINDOW_SECONDS, type TradeIntentAction, type TradeIntentActionInput, type TradeIntentActionResult, type WalletStateResult, accountInputSchema, ago, assertHeliosBaseUrl, candlesInputSchema, compactSymbolDetail, createHeliosAccountToolDefinitions, createHeliosAgentMcpServer, createHeliosAuthToolDefinitions, createHeliosDocsToolDefinitions, createHeliosLedgerToolDefinitions, createHeliosMarketToolDefinitions, createHeliosProviderToolDefinitions, createHeliosTradingToolDefinitions, createLeanToolDefinitions, entryText, formatHeliosLoginPrompt, getDefaultHeliosAgentMcpDocsRoot, getDefaultHeliosAgentMcpSessionPath, isSameHeliosIssuer, leanToolsFor, marketInputSchema, moveText, pct, pendingAgentLoginSchema, positionLine, practiceOnly, price, protectInputSchema, renderAccount, renderBoard, renderCandles, renderCoin, renderMarket, renderMoves, renderTrades, retryAfterUnauthorizedRefresh, smBoardInputSchema, smCoinInputSchema, smMovesInputSchema, toolAnnotations, topOfSnapshot, tradeInputSchema, tradeKeyFor, trader, tradesInputSchema, tradingLine, usd, withDataText, withSnapshotDefaults, wrongSideTpSl };

package/dist/index.js

@@ -47,6 +47,7 @@ __export(index_exports, {
   HeliosAgentMcpTradingService: () => HeliosAgentMcpTradingService,
   MAX_TOOL_INPUT_ELEMENTS: () => MAX_TOOL_INPUT_ELEMENTS,
   MCP_PROFILES: () => MCP_PROFILES,
+  MIN_ORDER_USD: () => MIN_ORDER_USD,
   MemoryAgentMcpSessionStore: () => MemoryAgentMcpSessionStore,
   TRADE_KEY_WINDOW_SECONDS: () => TRADE_KEY_WINDOW_SECONDS,
   accountInputSchema: () => accountInputSchema,
@@ -74,6 +75,7 @@ __export(index_exports, {
   pct: () => pct,
   pendingAgentLoginSchema: () => pendingAgentLoginSchema2,
   positionLine: () => positionLine,
+  practiceOnly: () => practiceOnly,
   price: () => price,
   protectInputSchema: () => protectInputSchema,
   renderAccount: () => renderAccount,
@@ -93,6 +95,7 @@ __export(index_exports, {
   tradeKeyFor: () => tradeKeyFor,
   trader: () => trader,
   tradesInputSchema: () => tradesInputSchema,
+  tradingLine: () => tradingLine,
   usd: () => usd,
   withDataText: () => withDataText,
   withSnapshotDefaults: () => withSnapshotDefaults,
@@ -634,7 +637,13 @@ var agentMarketRowSchema = import_zod3.z.object({
   volUsd: import_zod3.z.number().nullable(),
   fundAprPct: import_zod3.z.number().nullable(),
   oiUsd: import_zod3.z.number().nullable(),
-  setup: agentSetupSchema.nullable()
+  setup: agentSetupSchema.nullable(),
+  /** Coin limits and the book; absent from older data-bridges. */
+  maxLev: import_zod3.z.number().nullish(),
+  spreadBps: import_zod3.z.number().nullish(),
+  slip10kBps: import_zod3.z.number().nullish(),
+  slip100kBps: import_zod3.z.number().nullish(),
+  depth1pctUsd: import_zod3.z.number().nullish()
 });
 var agentMarketSchema = import_zod3.z.object({
   asOf: import_zod3.z.string().nullable(),
@@ -2798,6 +2807,7 @@ function renderCoin(c, you, now = Date.now()) {
     const vs = sm?.side ? entryText(sm.side, sm.edgePct) : null;
     lines.push(`price | ${price(mk.px)}${vs ? ` (${vs})` : ""} \xB7 15m ${pct(mk.r15m)} \xB7 1h ${pct(mk.r1h)} \xB7 24h ${pct(mk.r24h)}`);
     lines.push(`setup | ${mk.setup ?? "n/a"} \xB7 funding ${pct(mk.fundAprPct, 0)} APR \xB7 open interest ${usd(mk.oiUsd)} \xB7 vol ${usd(mk.volUsd)}`);
+    lines.push(tradingLine(mk, now));
   } else lines.push("price | no market data for this coin");
   if (sm && sm.flow1hUsd !== 0) lines.push(`flow | ${usd(Math.abs(sm.flow1hUsd))} net toward ${sm.flow1hUsd > 0 ? "long" : "short"} in the last hour`);
   if (sm?.pileIn) lines.push(`pile-in | ${pileText(sm.pileIn, now)}`);
@@ -2812,6 +2822,20 @@ function renderCoin(c, you, now = Date.now()) {
   if (c.note) lines.push(c.note);
   return lines.join("\n");
 }
+var MIN_ORDER_USD = 10;
+var bps = (v) => v === null || v === void 0 || !Number.isFinite(v) ? "n/a" : `${trim(v, 2)} bps`;
+function tradingLine(mk, now = Date.now()) {
+  const parts = [`max ${mk.maxLev ? `${trim(mk.maxLev, 0)}x` : "n/a"}`, `min order $${MIN_ORDER_USD}`];
+  if (mk.spreadBps !== null && mk.spreadBps !== void 0) parts.push(`spread ${bps(mk.spreadBps)}`);
+  if (mk.slip10kBps !== null && mk.slip10kBps !== void 0) parts.push(`$10k market order slips ${bps(mk.slip10kBps)}, $100k ${bps(mk.slip100kBps)}`);
+  if (mk.depth1pctUsd !== null && mk.depth1pctUsd !== void 0) parts.push(`${usd(mk.depth1pctUsd)} within 1%`);
+  if (mk.fundAprPct !== null) {
+    const hourly = mk.fundAprPct / (24 * 365);
+    const mins = Math.max(1, Math.ceil((36e5 - now % 36e5) / 6e4));
+    parts.push(`funding ${hourly > 0 ? "+" : ""}${hourly.toFixed(4)}%/h (${hourly >= 0 ? "longs pay" : "shorts pay"}), next in ${mins}m`);
+  }
+  return `trading | ${parts.join(" \xB7 ")}`;
+}
 function renderAccount(p, orders, summary) {
   const lines = [
     `account \xB7 value ${usd(p.totalBalance)} \xB7 free ${usd(p.availableBalance)} \xB7 margin used ${usd(p.totalMargin)} \xB7 open PnL ${usd(p.unrealizedPnl, true)}`
@@ -3345,13 +3369,15 @@ function createLeanToolDefinitions(services) {
   }
   async function protectionFor(input) {
     if (input.side === "short" && (input.tp_pct ?? 0) >= 100) throw new Error("A short can gain at most 100%: tp_pct must be under 100");
+    const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 })).catch(() => null);
+    if (m && !m.ok) return { pending: m.pending };
+    const row = m?.value?.rows?.find((r) => sameCoinName(r.coin, input.coin)) ?? null;
+    if (row?.maxLev && input.leverage && input.leverage > row.maxLev)
+      throw new Error(`${input.coin} allows at most ${row.maxLev}x on Hyperliquid: lower leverage. Nothing was sent.`);
+    if (input.leverage && input.margin_usd && input.margin_usd * input.leverage < MIN_ORDER_USD)
+      throw new Error(`Order value $${(input.margin_usd * input.leverage).toFixed(2)} is under Hyperliquid's $${MIN_ORDER_USD} minimum (margin x leverage). Nothing was sent.`);
     if (!input.sl_pct && !input.tp_pct) return { value: void 0 };
-    let ref = input.limit_px ?? null;
-    if (ref === null) {
-      const m = await withSession(auth, READ, (token) => dataBridge.getAgentMarket(token, { coins: [input.coin], limit: 1 }));
-      if (!m.ok) return { pending: m.pending };
-      ref = m.value.rows[0]?.px ?? null;
-    }
+    const ref = input.limit_px ?? row?.px ?? null;
     if (ref === null) throw new Error(`No price for ${input.coin} to place the stop from; trade without sl_pct/tp_pct, then use protect`);
     const long = input.side === "long";
     const at = (p, away) => Number((p * (1 + away / 100)).toPrecision(6));
@@ -3364,9 +3390,16 @@ function createLeanToolDefinitions(services) {
   }
   return { smBoard, smMoves, smCoin, market, account, trade, protect, trades, candles };
 }
+function practiceOnly(tool) {
+  return {
+    ...tool,
+    description: `Practice account only on this link (no real money). ${tool.description}`,
+    execute: (input) => tool.execute({ ...input, paper: true })
+  };
+}
 function leanToolsFor(tools, profile) {
   const reads = [tools.smBoard, tools.smMoves, tools.smCoin, tools.market];
-  const list = profile === "signals" ? [...reads, tools.account, tools.trades, tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
+  const list = profile === "signals" ? [...reads, tools.account, tools.trades, practiceOnly(tools.trade), practiceOnly(tools.protect), tools.candles] : [...reads, tools.account, tools.trades, tools.trade, tools.protect, tools.candles];
   return list;
 }
 
@@ -4176,7 +4209,7 @@ async function createHeliosAgentMcpServer(options) {
   const server = new McpServer(
     {
       name: "helios",
-      version: "0.4.0"
+      version: "0.5.0"
     },
     // Caps the array elements plus object keys one tools/call may carry (GHSA-46jr-4wx8-v453: without it, one request
     // under the body size limit could run the hosted server out of memory while validating). The largest real input is
@@ -4314,6 +4347,7 @@ function registerTool(server, tool) {
   HeliosAgentMcpTradingService,
   MAX_TOOL_INPUT_ELEMENTS,
   MCP_PROFILES,
+  MIN_ORDER_USD,
   MemoryAgentMcpSessionStore,
   TRADE_KEY_WINDOW_SECONDS,
   accountInputSchema,
@@ -4341,6 +4375,7 @@ function registerTool(server, tool) {
   pct,
   pendingAgentLoginSchema,
   positionLine,
+  practiceOnly,
   price,
   protectInputSchema,
   renderAccount,
@@ -4360,6 +4395,7 @@ function registerTool(server, tool) {
   tradeKeyFor,
   trader,
   tradesInputSchema,
+  tradingLine,
   usd,
   withDataText,
   withSnapshotDefaults,

package/dist/index.mjs

@@ -14,6 +14,7 @@ import {
   HeliosAgentMcpTradingService,
   MAX_TOOL_INPUT_ELEMENTS,
   MCP_PROFILES,
+  MIN_ORDER_USD,
   MemoryAgentMcpSessionStore,
   TRADE_KEY_WINDOW_SECONDS,
   accountInputSchema,
@@ -41,6 +42,7 @@ import {
   pct,
   pendingAgentLoginSchema,
   positionLine,
+  practiceOnly,
   price,
   protectInputSchema,
   renderAccount,
@@ -60,11 +62,12 @@ import {
   tradeKeyFor,
   trader,
   tradesInputSchema,
+  tradingLine,
   usd,
   withDataText,
   withSnapshotDefaults,
   wrongSideTpSl
-} from "./chunk-5LIHYXEF.mjs";
+} from "./chunk-XM257Y63.mjs";
 export {
   DEFAULT_HELIOS_BASE_URL,
   DEFAULT_HELIOS_SESSION_ISSUER,
@@ -81,6 +84,7 @@ export {
   HeliosAgentMcpTradingService,
   MAX_TOOL_INPUT_ELEMENTS,
   MCP_PROFILES,
+  MIN_ORDER_USD,
   MemoryAgentMcpSessionStore,
   TRADE_KEY_WINDOW_SECONDS,
   accountInputSchema,
@@ -108,6 +112,7 @@ export {
   pct,
   pendingAgentLoginSchema,
   positionLine,
+  practiceOnly,
   price,
   protectInputSchema,
   renderAccount,
@@ -127,6 +132,7 @@ export {
   tradeKeyFor,
   trader,
   tradesInputSchema,
+  tradingLine,
   usd,
   withDataText,
   withSnapshotDefaults,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgnio/helios-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Helios MCP server: connect an AI agent to your Helios account to follow the top Hyperliquid traders, read markets and your portfolio, and trade. Most apps can use the hosted URL https://helios.pgn.io/mcp instead.",
   "license": "UNLICENSED",
   "homepage": "https://helios.pgn.io/?connect=ai",