feat(outcome): MCP read-only tools + skill bundle docs

Wires the v0.13.0 outcome surface into the agent integration layer.

MCP server (3 new tools, 18 → 21 total):
- get_outcome_markets — list active outcome markets with parsed
  metadata (class/underlying/expiry/targetPrice/period) and per-side
  info (encoding, asset id, current mid). Public read.
- get_outcome_book — orderbook for one outcome side. Public read.
- get_outcome_positions — active account's outcome holdings (size,
  entry notional, mark, uPnL). Requires configured HL wallet/agent.

Per existing MCP design, server is advisor-only — no execution
endpoints. Agents pair these with the CLI for placing orders, which
gates on dry-run + explicit user confirmation.

Skill bundle:
- references/commands.md gains an "Outcome Markets (Hyperliquid HIP-4)"
  section: full command tree, identifier model (5 forms), enforced
  foot-guns (min notional / encoded-side mismatch / USDH balance /
  venue rejection), and a 6-step agent workflow.
- SKILL.md intro mentions HIP-4 support; reference list includes
  outcome; MCP tool count updated to 21 with public read-only tools
  enumerated.

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

Author: Hiksang

skills/perp-cli/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 # perp-cli
 
-Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain).
+Multi-DEX perpetual futures CLI + MCP server for Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum), and Aster (BNB Chain). v0.13.0+ also supports Hyperliquid Outcome markets (HIP-4) — fully-collateralized binary/range contracts quoted in USDH.
 
 ## Instructions
 
@@ -25,7 +25,7 @@ Activate whenever the user wants to do anything against perp-cli, including: sca
 
 This skill uses progressive disclosure. Read these on demand:
 
-- `references/commands.md` — full command tree for every group (market, account, trade, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
+- `references/commands.md` — full command tree for every group (market, account, trade, outcome, arb, funds, wallet, risk, history, strategy, background, alerts, settings, backtest)
 - `references/agent-operations.md` — non-interactive setup flows, idempotency rules, error codes, common mistakes
 - `references/strategies.md` — funding-arb decision framework + risk-management playbook (read before designing arb strategy)
 
@@ -320,7 +320,7 @@ When the user first sets up a wallet, ask:
 
 ## MCP Server
 
-The package also ships a 18-tool MCP server (no API keys required for read-only market data):
+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):
 
 ```json
 {

skills/perp-cli/references/commands.md

@@ -89,6 +89,75 @@ perp --json -e <EX> trade spot-balance
 perp --json trade multi <legs...>
 ```
 
+## Outcome Markets (Hyperliquid HIP-4)
+
+Fully-collateralized binary/range contracts on Hyperliquid. **Quote token: USDH (NOT USDC)**. No leverage / no liquidation. Min order $10 USDH (price × size ≥ 10). Currently 1 live market on mainnet (BTC binary daily settling at 06:00 UTC).
+
+```bash
+# List active outcome markets — parses the description string into
+# class / underlying / expiry / targetPrice / period and lists each side
+# 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).
+perp --json outcome book <outcome> <side> [--depth N=10]
+
+# Holdings + open orders.
+perp --json outcome positions
+perp --json outcome orders
+
+# Place orders. ALWAYS dry-run first.
+perp --json outcome buy  <outcome> <side> <usd> --dry-run
+perp --json outcome sell <outcome> <side> <usd> --dry-run
+
+# Live execution. --limit makes it GTC; without --limit it's IoC at top-of-book +/-5%.
+perp --json outcome buy  <outcome> <side> <usd> [--limit <px>] [--tif gtc|ioc|alo]
+perp --json outcome sell <outcome> <side> <usd> [--limit <px>] [--tif gtc|ioc|alo]
+
+# Cancel a resting order.
+perp --json outcome cancel <outcome> <side> <oid>
+```
+
+### Identifier model
+
+Same outcome side can be referenced 5 ways — the CLI normalises:
+
+| Form | Example (BTC daily Yes) |
+|---|---|
+| `<outcome>, <side>` integer | `1, 0` |
+| `<outcome>, <side>` name | `1, yes` |
+| `#<enc>` (l2Book / candle / allMids coin) | `#10` |
+| `+<enc>` (spotClearinghouseState balance coin) | `+10` |
+| asset id (HL `/exchange` payload) | `100000010` |
+
+Encoding formula: `enc = 10 * outcome + side`; asset id = `100,000,000 + enc`.
+
+### Foot-guns enforced (Rule #2)
+
+- **Min notional:** `price * size < 10 USDH` → `INVALID_PARAMS` with remediation. Enforced in dry-run too.
+- **Encoded-side mismatch:** `outcome buy 2 #10` (where `#10` decodes to outcome=1) → `INVALID_PARAMS`, never silently routes to outcome 2.
+- **Insufficient USDH:** pre-checked before order send → `INSUFFICIENT_BALANCE` with "bridge USDC→USDH" remediation. Resolves the user address through the OWS-stored agent meta when no master pk is configured.
+- **Venue rejection:** HL returns HTTP 200 with `statuses[0].error` even when an order is rejected; the adapter throws `EXCHANGE_ERROR` so a "placed" success message never masks a failure.
+
+### Agent workflow recommendation
+
+```
+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
+                                                  # validate notional, get user approval
+5. perp --json outcome buy <outcome> <side> <usd> [--limit <px>] [--tif ...]
+                                                  # execute (only after explicit user OK)
+6. perp --json outcome positions                  # confirm fill / monitor
+```
+
+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)
 
 All fund movement lives under `perp funds`.

src/mcp-server.ts

@@ -300,10 +300,76 @@ server.tool(
   },
 );
 
+// ============================================================
+// Outcome markets (Hyperliquid HIP-4) — public reads
+// ============================================================
+
+server.tool(
+  "get_outcome_markets",
+  "List active Hyperliquid Outcome markets (HIP-4). Each market has parsed metadata (underlying asset, target price, expiry, period) and per-side info (Yes/No name, encoding, asset id, current mid). Public read — no API key needed.",
+  {},
+  async () => {
+    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 markets = await out.getMarkets();
+      return { content: [{ type: "text", text: ok(markets, { count: markets.length, source: "outcomeMeta" }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+    }
+  },
+);
+
+server.tool(
+  "get_outcome_book",
+  "Get the orderbook for one outcome side. Public read — no API key needed.",
+  {
+    outcome: z.number().int().nonnegative().describe("Outcome id from outcomeMeta (e.g., 1 for the BTC binary daily)"),
+    side: z.number().int().min(0).max(9).describe("Side index within the outcome (0 = first sideSpecs entry like 'Yes', 1 = second like 'No')"),
+  },
+  async ({ outcome, side }) => {
+    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 book = await out.getOrderbook(outcome, side);
+      return { content: [{ type: "text", text: ok(book, { outcome, side, assetId: HyperliquidOutcomeAdapter.assetId(outcome, side) }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { outcome, side }) }], isError: true };
+    }
+  },
+);
+
 // ============================================================
 // Account tools (need private key)
 // ============================================================
 
+server.tool(
+  "get_outcome_positions",
+  "Get the active account's open outcome positions (size, entry notional, mark price, unrealized PnL). Requires a configured Hyperliquid wallet or agent.",
+  {},
+  async () => {
+    try {
+      const { HyperliquidAdapter } = await import("./exchanges/hyperliquid.js");
+      const { HyperliquidOutcomeAdapter } = await import("./exchanges/hyperliquid-outcome.js");
+      const adapter = await getOrCreateAdapter("hyperliquid");
+      if (!(adapter instanceof HyperliquidAdapter)) {
+        return { content: [{ type: "text", text: err("Outcome positions are Hyperliquid-only", { exchange: "hyperliquid" }) }], isError: true };
+      }
+      const out = new HyperliquidOutcomeAdapter(adapter);
+      const positions = await out.getPositions();
+      return { content: [{ type: "text", text: ok(positions, { count: positions.length }) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+    }
+  },
+);
+
 server.tool(
   "get_balance",
   "Get account balance (equity, available margin, margin used, unrealized PnL) on an exchange",