feat(outcome): add outcome view — symmetric Yes/No book + underlying gap

Outcome markets have a complementary Yes/No structure where Yes BID +
No ASK ≈ 1.0. Agents and humans need a single snapshot that exposes
both books plus directional context (current underlying mark vs the
binary's targetPrice) — not a multi-call combination of `book` +
`market mid`.

Adapter:
- HyperliquidOutcomeAdapter.getView(outcome, depth) fetches both sides'
  books in parallel via Promise.all + a single allMids round-trip. From
  allMids it derives:
  - per-side mid + impliedProb
  - midSum (deviation from 1.0 = arbitrage hint)
  - underlying perp mid (parsed from description.underlying — currently
    only HL native perps; HIP-3 dex perps not referenced by HIP-4 yet)
  - gap = mark - target, gapPct, in-the-money side (priceBinary only)
- New OutcomeView / OutcomeViewSide / OutcomeViewUnderlying types in
  outcome-interface.ts.

CLI:
- `perp outcome view <outcome> [--depth N=10]` (alias `status`)
- TTY: header (target / current / gap / inTheMoney / expiry / implied
  probabilities) followed by stacked Yes/No book tables.
- JSON: full OutcomeView struct.

MCP:
- new tool `get_outcome_view` (public read, no API key).
- Total tools: 21 → 22.

Skill bundle:
- references/commands.md highlights `outcome view` as the preferred
  agent entry point and shortens the recommended workflow from 6 steps
  to 5 (drops the separate `market mid` lookup).
- SKILL.md MCP tool count + tool name list updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Hiksang

skills/perp-cli/SKILL.md

@@ -320,7 +320,7 @@ When the user first sets up a wallet, ask:
 
 ## MCP Server
 
-The package also ships a 21-tool MCP server (no API keys required for read-only market data — `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `get_outcome_markets`, `get_outcome_book`, plus 15 account/advisor tools):
+The package also ships a 22-tool MCP server (no API keys required for read-only market data — `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `get_outcome_markets`, `get_outcome_view`, `get_outcome_book`, plus 15 account/advisor tools):
 
 ```json
 {

skills/perp-cli/references/commands.md

@@ -99,9 +99,16 @@ Fully-collateralized binary/range contracts on Hyperliquid. **Quote token: USDH
 # with mid + assetId.
 perp --json outcome list
 
-# Orderbook for one side. <side> accepts: 0/1, Yes/No, or #<enc> / +<enc>
-# (the encoded form must match the outcome arg — mismatch throws
-# INVALID_PARAMS).
+# COMBINED VIEW — all sides' books in parallel + underlying mark price
+# (HL perp mid for `description.underlying`) + gap vs targetPrice + ms
+# until expiry + per-side implied probability. For a binary market the
+# symmetric structure means Yes BID + No ASK ≈ 1.0; this is the
+# preferred entry point for agents that need a single snapshot.
+perp --json outcome view <outcome> [--depth N=10]
+
+# Orderbook for ONE side only (use `view` if you want both at once).
+# <side> accepts: 0/1, Yes/No, or #<enc> / +<enc> (the encoded form
+# must match the outcome arg — mismatch throws INVALID_PARAMS).
 perp --json outcome book <outcome> <side> [--depth N=10]
 
 # Holdings + open orders.
@@ -145,17 +152,18 @@ Encoding formula: `enc = 10 * outcome + side`; asset id = `100,000,000 + enc`.
 
 ```
 1. perp --json outcome list                       # discover markets, parse description
-2. perp --json -e hyperliquid market mid <UNDERLYING>
-                                                  # if class:priceBinary, compare against targetPrice
-3. perp --json outcome book <outcome> <side> --depth 10
-                                                  # check liquidity (single-MM mirror book risk)
-4. perp --json outcome buy <outcome> <side> <usd> --dry-run
+2. perp --json outcome view <outcome>             # full snapshot: both books +
+                                                  # underlying mark + gap vs target +
+                                                  # implied probabilities + time to expiry
+3. perp --json outcome buy <outcome> <side> <usd> --dry-run
                                                   # validate notional, get user approval
-5. perp --json outcome buy <outcome> <side> <usd> [--limit <px>] [--tif ...]
+4. perp --json outcome buy <outcome> <side> <usd> [--limit <px>] [--tif ...]
                                                   # execute (only after explicit user OK)
-6. perp --json outcome positions                  # confirm fill / monitor
+5. perp --json outcome positions                  # confirm fill / monitor
 ```
 
+`outcome view` replaces the old multi-call pattern (separate `book` + `market mid` lookups). One round-trip returns everything an agent needs to decide direction.
+
 Settlement at `expiryMs` is venue-side: winning side → 1 USDH per share, losing → 0. Decide before expiry whether to self-close or let the venue settle.
 
 ## Funds (deposit, withdraw, transfer, bridge, rebalance)

src/commands/outcome.ts

@@ -15,6 +15,7 @@ import type {
   OutcomeMarketInfo,
   OutcomePosition,
   OutcomeOrderbook,
+  OutcomeView,
 } from "../exchanges/outcome-interface.js";
 import { makeTable, printJson, jsonOk, jsonError, formatUsd } from "../utils.js";
 import { PerpError } from "../errors.js";
@@ -90,6 +91,26 @@ export function registerOutcomeCommands(
       printOutcomeBook(book, depth);
     });
 
+  // ── outcome view <outcome> ───────────────────────────────────────────────
+  // Symmetric Yes/No book + underlying gap + time to expiry. Single
+  // round-trip view for binary markets.
+  outcome
+    .command("view <outcome>")
+    .alias("status")
+    .description("Combined view: Yes/No books side-by-side + underlying mark gap + expiry")
+    .option("--depth <n>", "Number of levels per side", "10")
+    .action(async (outcomeArg: string, opts: { depth?: string }) => {
+      const adapter = await getOutcomeAdapter();
+      const outcomeId = Number(outcomeArg);
+      if (!Number.isInteger(outcomeId) || outcomeId < 0) {
+        throw new PerpError("INVALID_PARAMS", `Invalid outcome id: ${outcomeArg}`, {});
+      }
+      const depth = Math.max(1, Number(opts.depth ?? "10"));
+      const view = await adapter.getView(outcomeId, depth);
+      if (isJson()) return printJson(jsonOk(view));
+      printOutcomeView(view);
+    });
+
   // ── outcome positions ────────────────────────────────────────────────────
   outcome
     .command("positions")
@@ -288,6 +309,72 @@ async function resolveOutcomeSide(
   return { outcome: outcomeId, side };
 }
 
+function printOutcomeView(view: OutcomeView): void {
+  console.log(chalk.white.bold(`\n  Outcome #${view.outcome} — ${view.name}`));
+  console.log(chalk.gray(`  ${view.description}`));
+
+  // Header line: target / underlying mark / gap / expiry
+  if (view.underlying) {
+    const u = view.underlying;
+    const target = u.targetPrice !== undefined ? `$${u.targetPrice.toLocaleString()}` : "—";
+    const mark = u.markPrice !== undefined ? `$${Number(u.markPrice).toLocaleString()}` : chalk.gray("—");
+    const gapStr = u.gap !== undefined && u.gapPct !== undefined
+      ? (u.gap >= 0
+          ? chalk.green(`+$${Math.abs(u.gap).toFixed(2)} (+${u.gapPct.toFixed(2)}%)`)
+          : chalk.red(`-$${Math.abs(u.gap).toFixed(2)} (${u.gapPct.toFixed(2)}%)`))
+      : chalk.gray("—");
+    const itm = u.inTheMoney === "yes" ? chalk.green("Yes ITM")
+      : u.inTheMoney === "no" ? chalk.red("No ITM")
+      : chalk.gray("—");
+    console.log(`  ${u.symbol} target ${target}  current ${mark}  gap ${gapStr}  ${itm}`);
+  }
+  if (view.expiryMs !== undefined) {
+    const expiryStr = new Date(view.expiryMs).toISOString().replace("T", " ").slice(0, 16) + " UTC";
+    const ttx = view.msToExpiry !== undefined ? formatDuration(view.msToExpiry) : "—";
+    console.log(`  Expires: ${expiryStr}  (${ttx})`);
+  }
+  if (view.midSum !== undefined) {
+    const sumColor = Math.abs(view.midSum - 1) < 0.01 ? chalk.gray : chalk.yellow;
+    console.log(`  Implied probabilities (sum ${sumColor(view.midSum.toFixed(4))}):`);
+    for (const s of view.sides) {
+      const p = s.impliedProb !== undefined ? `${(s.impliedProb * 100).toFixed(1)}%` : "—";
+      console.log(`    ${s.name.padEnd(6)} ${p}`);
+    }
+  }
+
+  // One table per side. Stacked layout — readable on any terminal width
+  // and avoids the alignment quirks that come from padding ANSI strings.
+  console.log("");
+  for (const s of view.sides) {
+    console.log(`  ${chalk.white.bold(s.name)} book`);
+    const maxLevels = Math.max(s.bids.length, s.asks.length);
+    const rows: string[][] = [];
+    for (let i = 0; i < maxLevels; i++) {
+      const b = s.bids[i];
+      const a = s.asks[i];
+      rows.push([
+        b ? chalk.green(b[0]) : "",
+        b ? b[1] : "",
+        a ? chalk.red(a[0]) : "",
+        a ? a[1] : "",
+      ]);
+    }
+    console.log(makeTable(["bid", "size", "ask", "size"], rows));
+    console.log("");
+  }
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 0) return "expired";
+  const s = Math.floor(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (h > 24) return `${Math.floor(h / 24)}d ${h % 24}h ${m}m left`;
+  if (h > 0) return `${h}h ${m}m left`;
+  if (m > 0) return `${m}m ${s % 60}s left`;
+  return `${s}s left`;
+}
+
 function printOutcomeBook(book: OutcomeOrderbook, depth: number): void {
   console.log(chalk.white.bold(`\n  outcome=${book.outcome} side=${book.side}`));
   const bids = book.bids.slice(0, depth);

src/exchanges/hyperliquid-outcome.ts

@@ -19,6 +19,9 @@ import type {
   OutcomeOrderbook,
   OutcomePosition,
   OutcomeSideInfo,
+  OutcomeView,
+  OutcomeViewSide,
+  OutcomeViewUnderlying,
 } from "./outcome-interface.js";
 import type { HyperliquidAdapter } from "./hyperliquid.js";
 
@@ -194,6 +197,112 @@ export class HyperliquidOutcomeAdapter implements OutcomeAdapter {
     return positions;
   }
 
+  /**
+   * Assemble a combined view of one outcome: all sides' books in parallel,
+   * the underlying mark price (HL perp mid for `description.underlying`),
+   * gap vs targetPrice, time-to-expiry, and per-side implied probability.
+   *
+   * Outcome markets have a symmetric (Yes / No) structure where the prices
+   * sum to ~$1; this view exposes both sides in a single round-trip and
+   * also surfaces the directional context for binary markets — what BTC
+   * mark price would settle the contract right now.
+   */
+  async getView(outcome: number, depth: number = 10): Promise<OutcomeView> {
+    await this.init();
+    const meta = this._outcomeMeta?.outcomes.find((o) => o.outcome === outcome);
+    if (!meta) {
+      throw new PerpError("SYMBOL_NOT_FOUND", `Unknown outcome id: ${outcome}`, {
+        exchange: "hyperliquid",
+        remediation: "Run: perp outcome list",
+      });
+    }
+    const parsed = HyperliquidOutcomeAdapter.parseDescription(meta.description);
+
+    // Fetch books for every side in parallel + allMids once for mids and
+    // the underlying symbol's mark price.
+    const allMidsPromise = this._infoPost({ type: "allMids" }) as Promise<Record<string, string>>;
+    const bookPromises = meta.sideSpecs.map((_, i) => this.getOrderbook(outcome, i));
+    const [allMids, ...books] = await Promise.all([allMidsPromise, ...bookPromises]);
+
+    // Trim each book to `depth` levels and compute best bid/ask + implied prob.
+    const sides: OutcomeViewSide[] = meta.sideSpecs.map((spec, i) => {
+      const encoding = HyperliquidOutcomeAdapter.encoding(outcome, i);
+      const book = books[i];
+      const bids = book.bids.slice(0, depth);
+      const asks = book.asks.slice(0, depth);
+      const bestBid = bids[0]?.[0];
+      const bestAsk = asks[0]?.[0];
+      const mid = allMids[`#${encoding}`];
+      return {
+        side: i,
+        name: spec.name,
+        encoding,
+        assetId: OUTCOME_ASSET_OFFSET + encoding,
+        mid,
+        bids,
+        asks,
+        bestBid,
+        bestAsk,
+        impliedProb: mid !== undefined ? Number(mid) : undefined,
+      };
+    });
+
+    const midSum = sides.every((s) => s.impliedProb !== undefined)
+      ? sides.reduce((acc, s) => acc + (s.impliedProb ?? 0), 0)
+      : undefined;
+
+    // Underlying: HL perp mid for the parsed underlying symbol.
+    let underlying: OutcomeViewUnderlying | null = null;
+    if (parsed.underlying) {
+      const sym = parsed.underlying.toUpperCase();
+      // HL `allMids` keys perps by bare symbol (e.g. "BTC"). HIP-3 perps
+      // use "@dexIdx:SYMBOL" but those won't be referenced in HIP-4
+      // outcomes for now.
+      const markPrice = allMids[sym];
+      const target = parsed.targetPrice;
+      let gap: number | undefined;
+      let gapPct: number | undefined;
+      let inTheMoney: "yes" | "no" | null = null;
+      if (markPrice !== undefined && target !== undefined) {
+        gap = Number(markPrice) - target;
+        gapPct = (gap / target) * 100;
+        // For class:priceBinary the convention is Yes = "underlying >=
+        // target". When `class` is unknown or non-binary, leave inTheMoney
+        // as null rather than guessing.
+        if (parsed.class === "priceBinary" && Number.isFinite(gap)) {
+          inTheMoney = gap >= 0 ? "yes" : "no";
+        }
+      }
+      underlying = {
+        symbol: sym,
+        source: sym,
+        markPrice,
+        targetPrice: target,
+        gap,
+        gapPct,
+        inTheMoney,
+      };
+    }
+
+    const expiryMs = parsed.expiryMs;
+    const serverTime = Date.now();
+    const msToExpiry = expiryMs !== undefined ? expiryMs - serverTime : undefined;
+
+    return {
+      outcome,
+      name: meta.name,
+      description: meta.description,
+      class: parsed.class,
+      expiryMs,
+      msToExpiry,
+      period: parsed.period,
+      underlying,
+      sides,
+      midSum,
+      serverTime,
+    };
+  }
+
   async getOrderbook(outcome: number, side: number): Promise<OutcomeOrderbook> {
     await this.init();
     this._validateOutcomeSide(outcome, side);

src/exchanges/outcome-interface.ts

@@ -74,6 +74,47 @@ export interface OutcomeOrderbook {
   time: number;
 }
 
+export interface OutcomeViewSide extends OutcomeSideInfo {
+  bids: [string, string][];
+  asks: [string, string][];
+  bestBid?: string;
+  bestAsk?: string;
+  /** Implied probability of THIS side winning, derived from mid */
+  impliedProb?: number;
+}
+
+export interface OutcomeViewUnderlying {
+  /** Underlying symbol from description (e.g. "BTC") */
+  symbol: string;
+  /** Source perp symbol used to fetch mark (typically same as `symbol`, may include venue prefix) */
+  source: string;
+  markPrice?: string;
+  targetPrice?: number;
+  /** markPrice - targetPrice (USD) */
+  gap?: number;
+  /** (markPrice - targetPrice) / targetPrice * 100 */
+  gapPct?: number;
+  /** If markPrice were to settle now: which side is winning ("yes"|"no") or null when ambiguous */
+  inTheMoney?: "yes" | "no" | null;
+}
+
+export interface OutcomeView {
+  outcome: number;
+  name: string;
+  description: string;
+  class?: string;
+  expiryMs?: number;
+  /** ms until expiry; negative if already expired; undefined if expiry unknown */
+  msToExpiry?: number;
+  period?: string;
+  underlying: OutcomeViewUnderlying | null;
+  sides: OutcomeViewSide[];
+  /** Sum of side mids; ~1.0 for fair binary, deviation hints at arbitrage. */
+  midSum?: number;
+  /** Server time-ms when the view was assembled */
+  serverTime: number;
+}
+
 export interface OutcomeAdapter {
   readonly name: string;
   init(): Promise<void>;
@@ -83,6 +124,8 @@ export interface OutcomeAdapter {
   getPositions(): Promise<OutcomePosition[]>;
   /** L2 orderbook for one (outcome, side). */
   getOrderbook(outcome: number, side: number): Promise<OutcomeOrderbook>;
+  /** Combined view: all sides' books in parallel + underlying mark price gap + expiry. */
+  getView(outcome: number, depth?: number): Promise<OutcomeView>;
   /** Place a limit order. Throws INVALID_PARAMS if `price * size < 10` USDH. */
   placeOrder(opts: {
     outcome: number;

src/mcp-server.ts

@@ -323,6 +323,28 @@ server.tool(
   },
 );
 
+server.tool(
+  "get_outcome_view",
+  "Get a combined view of one outcome market: all sides' books in parallel + underlying mark price gap (vs targetPrice) + time to expiry + per-side implied probability (mid sum). For binary markets, the symmetric structure means Yes bid + No ask ≈ 1.0 — the view exposes both sides in a single round-trip and surfaces directional context (e.g., is BTC currently above the target). Public read.",
+  {
+    outcome: z.number().int().nonnegative().describe("Outcome id from outcomeMeta (e.g., 1 for the BTC binary daily)"),
+    depth: z.number().int().min(1).max(50).optional().default(10).describe("Number of book levels per side"),
+  },
+  async ({ outcome, depth }) => {
+    try {
+      const { HyperliquidAdapter } = await import("./exchanges/hyperliquid.js");
+      const { HyperliquidOutcomeAdapter } = await import("./exchanges/hyperliquid-outcome.js");
+      const hl = new HyperliquidAdapter(undefined, false);
+      await hl.init();
+      const out = new HyperliquidOutcomeAdapter(hl);
+      const view = await out.getView(outcome, depth);
+      return { content: [{ type: "text", text: ok(view, { outcome, depth }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { outcome }) }], isError: true };
+    }
+  },
+);
+
 server.tool(
   "get_outcome_book",
   "Get the orderbook for one outcome side. Public read — no API key needed.",