perp-cli 0.12.17 → 0.14.1

package/dist/mcp-server.js

@@ -2,149 +2,219 @@
 /**
  * MCP (Model Context Protocol) server for perp-cli.
  *
- * Read-only advisor mode: provides market data, account balance, and CLI command suggestions.
- * Does NOT execute trades directly — instead suggests CLI commands for the user to run.
- * Adapters are created lazily from environment variables.
+ * Market data, account reads, CLI command suggestions, and two WRITE tools (`trade_execute`,
+ * `trade_close`) that place real orders through the same safety path as `perp trade`
+ * (local risk gate — no force override over MCP —, quarantine reject, execution log).
+ * Network: PERP_NETWORK (mainnet | testnet, validated like `-n`); unset = mainnet, the
+ * documented default. Every result's meta carries `network`.
+ * Adapters are created lazily from the registered agent / OWS wallet / settings (no CLI flags).
  */
-import "dotenv/config";
+// SSOT Rule #3: load only ~/.perp/.env, like the CLI (src/index.ts) — never a .env in the CWD
+// (a project tree's leftover dev keys would silently become this server's credentials).
+import { setQuarantineNetwork } from "./bot/quarantine.js";
+import { config as loadDotenv } from "dotenv";
+import { resolve as resolvePath } from "node:path";
+loadDotenv({ path: resolvePath(process.env.HOME || "~", ".perp", ".env") });
+import { registerAdapterNetwork } from "./exchanges/adapter-network.js";
+import { builderPlanFor } from "./exchanges/builder-fee.js";
+import { resolveAdapterSlippage } from "./exchanges/slippage.js";
 import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { tryLoadPrivateKey, parseSolanaKeypair } from "./config.js";
-import { PacificaAdapter } from "./exchanges/pacifica.js";
-import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
-import { LighterAdapter } from "./exchanges/lighter.js";
-import { AsterAdapter } from "./exchanges/aster.js";
-import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, pingPacifica, pingHyperliquid, pingLighter, } from "./shared-api.js";
+import { hasCredentials, listConfiguredAccountVenues, resolveCredentials, NO_CLI_CREDENTIAL_OPTS } from "./config.js";
+import { getVenue, listVenues, listVenuesWithRole, networkConfig, READ_ONLY_CREDENTIALS, requireCapabilities } from "./exchanges/venue.js";
+import "./exchanges/venues/index.js";
+import { newVenueClientOrderId, placeAndConfirm, validateLegacyTif, validateOrderRequest } from "./exchanges/trading-v2.js";
+import { closePerpVerified, isOutcomeUnknown } from "./bot/perp-order.js";
+import { quarantineSymbol } from "./bot/quarantine.js";
+import { fillSizeString, sizeDecimalsOf } from "./exchanges/spot-result.js";
+import { tradingV2Of } from "./exchanges/legacy-trading-v2.js";
+import { PerpError, classifyError, extractErrorMessage, isDefiniteOrderFailure, orderOutcomeUnknown, parsePositiveDecimal } from "./errors.js";
+import { invalidateCache } from "./cache.js";
+import { pingPacifica, pingHyperliquid, pingLighter, } from "./shared-api.js";
 import { fetchAllFundingRates } from "./funding-rates.js";
 import { loadArbState } from "./arb/state.js";
 import { validateTrade } from "./trade-validator.js";
+import { orderResultJson, symbolMatch } from "./utils.js";
+import { logMcpExecution, mcpPreTradeGate, mcpReduceOnlyGate, resolveMcpNetwork } from "./mcp-trade-guard.js";
+import { setSharedApiNetwork } from "./api/public/urls.js";
+import { logClientId } from "./client-id-tracker.js";
+import { loadSettings } from "./settings.js";
+/**
+ * The one network this server serves: PERP_NETWORK, validated like `-n` (an invalid value
+ * makes the server refuse to start). Unset = mainnet, the documented default. Reported in
+ * every result's meta.network.
+ */
+const MCP_NETWORK = resolveMcpNetwork(process.env["PERP_NETWORK"]);
+// Quarantine entries are network-scoped; the MCP server trades only MCP_NETWORK.
+setQuarantineNetwork(MCP_NETWORK);
+setSharedApiNetwork(MCP_NETWORK);
 // ── Adapter cache & factory ──
+//
+// Same creation path and signer tiers as the CLI (agent → OWS master → PK;
+// design §9.1 #1, §10.2). The MCP server has no CLI flags, so credentials come
+// from the registered agent, settings.owsActiveWallet, and (legacy venues) env.
 const adapters = new Map();
+/** The network each adapter was created on (TradingV2 wrappers must use the same one). */
+const adapterNetworks = new WeakMap();
+function requireCreate(def) {
+    if (def.create === null) {
+        throw new PerpError("NOT_IMPLEMENTED", `${def.displayName} has no account/trading API`, {
+            remediation: `${def.id} is market-data only — use get_markets / funding tools`,
+        });
+    }
+    return def.create;
+}
 async function getOrCreateAdapter(exchange) {
-    const key = exchange.toLowerCase();
-    if (adapters.has(key))
-        return adapters.get(key);
-    const pk = await tryLoadPrivateKey(key);
-    if (!pk)
-        throw new Error(`No private key configured for ${exchange}. Run: perp setup`);
-    let adapter;
-    switch (key) {
-        case "pacifica": {
-            const keypair = parseSolanaKeypair(pk);
-            adapter = new PacificaAdapter(keypair);
-            break;
-        }
-        case "hyperliquid": {
-            const hl = new HyperliquidAdapter(pk);
-            await hl.init();
-            adapter = hl;
-            break;
-        }
-        case "lighter": {
-            const lt = new LighterAdapter(pk);
-            await lt.init();
-            adapter = lt;
-            break;
-        }
-        case "aster": {
-            const ast = new AsterAdapter(pk);
-            await ast.init();
-            adapter = ast;
-            break;
-        }
-        default:
-            throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter, aster`);
+    const def = getVenue(exchange);
+    const cached = adapters.get(def.id);
+    if (cached)
+        return cached;
+    const create = requireCreate(def);
+    if (!(await hasCredentials(def.id, NO_CLI_CREDENTIAL_OPTS))) {
+        throw new PerpError("NO_SIGNER_AVAILABLE", `No credentials configured for ${def.id}`, {
+            remediation: def.masterKeyKind === "none"
+                ? `Import an API key created on the ${def.displayName} website: perp wallet agent import ${def.id}`
+                : `Run: perp setup, or perp wallet agent approve ${def.id}`,
+        });
     }
-    adapters.set(key, adapter);
+    const network = MCP_NETWORK;
+    const adapter = await create({
+        network,
+        credentials: await resolveCredentials(def.id, NO_CLI_CREDENTIAL_OPTS, network),
+        noAgent: false,
+        hlDex: null,
+        readOnly: false,
+        // Builder fees follow settings.builder (user-configured, approval-confirmed); MCP has no per-call opt-out.
+        noBuilder: false,
+    });
+    adapters.set(def.id, adapter);
+    adapterNetworks.set(adapter, network);
+    registerAdapterNetwork(adapter, network);
     return adapter;
 }
-/** Try to get adapter, returns null if no key configured (for read-only fallback) */
+/** Signer-availability failures that route a read tool to the venue's public data path. */
+const PUBLIC_FALLBACK_CODES = new Set(["NO_SIGNER_AVAILABLE", "AGENT_NOT_REGISTERED", "KEY_NOT_FOUND"]);
+/**
+ * Adapter when credentials are configured and usable; null when there are none
+ * or adapter creation fails specifically for lack of a usable signer
+ * (NO_SIGNER_AVAILABLE / AGENT_NOT_REGISTERED / KEY_NOT_FOUND) — the caller then
+ * reads the venue's public data path. Every other creation error propagates.
+ */
 async function tryGetAdapter(exchange) {
-    const key = exchange.toLowerCase();
-    if (adapters.has(key))
-        return adapters.get(key);
+    const def = getVenue(exchange);
+    const cached = adapters.get(def.id);
+    if (cached)
+        return cached;
+    if (def.create === null || !(await hasCredentials(def.id, NO_CLI_CREDENTIAL_OPTS)))
+        return null;
     try {
-        return await getOrCreateAdapter(exchange);
+        return await getOrCreateAdapter(def.id);
     }
-    catch {
-        return null;
+    catch (e) {
+        if (e instanceof PerpError && PUBLIC_FALLBACK_CODES.has(e.structured.code))
+            return null;
+        throw e;
     }
 }
-/** Fetch markets using public API (no key needed) */
+/** Fetch markets using the venue's public data path (no key needed). */
 async function fetchMarketsPublic(exchange) {
-    const ex = exchange.toLowerCase();
-    if (ex === "pacifica" || ex === "pac") {
-        const data = await fetchPacificaPrices();
-        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.mark), indexPrice: String(d.mark), fundingRate: String(d.funding), volume24h: "0", openInterest: "0", maxLeverage: 10 }));
-    }
-    else if (ex === "hyperliquid" || ex === "hl") {
-        const data = await fetchHyperliquidMeta();
-        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.markPx), indexPrice: String(d.markPx), fundingRate: String(d.funding), volume24h: "0", openInterest: "0", maxLeverage: 50 }));
-    }
-    else if (ex === "lighter" || ex === "lt") {
-        const data = await fetchLighterOrderBookDetails();
-        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.lastTradePrice), indexPrice: String(d.lastTradePrice), fundingRate: "0", volume24h: "0", openInterest: "0", maxLeverage: 20 }));
-    }
-    else if (ex === "aster" || ex === "ast") {
-        // Aster has no shared-api helper; AsterAdapter.getMarkets() uses
-        // public-only endpoints (exchangeInfo + ticker/24hr + premiumIndex).
-        const ast = new AsterAdapter();
-        await ast.init();
-        return ast.getMarkets();
+    return getVenue(exchange).publicData.fetchMarkets(MCP_NETWORK);
+}
+/** One book level from a venue payload; a level without a string price / size is a payload error (never "0"). */
+function bookLevel(venue, symbol, price, size) {
+    if (typeof price !== "string" || typeof size !== "string") {
+        throw new PerpError("EXCHANGE_ERROR", `${venue} orderbook ${symbol}: level without price / size`, { exchange: venue });
     }
-    throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter, aster`);
+    return [price, size];
 }
-/** Fetch orderbook using public API (no key needed) */
+/**
+ * Fetch an orderbook without credentials. Hyperliquid (native perps) and the Lighter family are
+ * read straight from their public REST endpoints and validated (HTTP status, payload shape, unknown
+ * symbol); every other venue goes through its read-only adapter (no key material), the same path
+ * `perp market book` takes without credentials. A venue without an account/trading API throws
+ * NOT_IMPLEMENTED (requireCreate).
+ */
 async function fetchOrderbookPublic(exchange, symbol) {
-    const ex = exchange.toLowerCase();
-    if (ex === "hyperliquid" || ex === "hl") {
+    const def = getVenue(exchange);
+    const sym = symbol.toUpperCase();
+    if (def.id === "hyperliquid") {
         const { HYPERLIQUID_API_URL } = await import("./api/public/urls.js");
         const res = await fetch(HYPERLIQUID_API_URL, {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ type: "l2Book", coin: symbol.toUpperCase() }),
+            body: JSON.stringify({ type: "l2Book", coin: sym }),
         });
+        if (!res.ok)
+            throw new PerpError("EXCHANGE_ERROR", `${def.displayName} l2Book ${sym}: HTTP ${res.status}`, { exchange: def.id });
         const data = await res.json();
-        return {
-            bids: (data.levels?.[0] ?? []).map(l => [l.px, l.sz]),
-            asks: (data.levels?.[1] ?? []).map(l => [l.px, l.sz]),
-        };
-    }
-    else if (ex === "lighter" || ex === "lt") {
-        const { LIGHTER_API_URL } = await import("./api/public/urls.js");
-        const res = await fetch(`${LIGHTER_API_URL}/api/v1/orderBookOrders?market_id=0&limit=20`);
-        const data = await res.json();
-        return {
-            bids: (data.bids ?? []).map(l => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
-            asks: (data.asks ?? []).map(l => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
-        };
+        if (data === null) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `${def.displayName} has no native perp ${sym}`, {
+                exchange: def.id,
+                remediation: `List markets with get_markets (exchange: ${def.id}); HIP-3 dex markets are read with the CLI: perp -e hyperliquid --dex <name> market book ${sym}`,
+            });
+        }
+        const levels = data.levels;
+        if (!Array.isArray(levels) || levels.length !== 2 || !Array.isArray(levels[0]) || !Array.isArray(levels[1])) {
+            throw new PerpError("EXCHANGE_ERROR", `${def.displayName} l2Book ${sym}: unexpected payload (no [bids, asks] levels)`, { exchange: def.id });
+        }
+        const side = (ls) => ls.map(l => bookLevel(def.id, sym, l.px, l.sz));
+        return { bids: side(levels[0]), asks: side(levels[1]) };
     }
-    else if (ex === "pacifica" || ex === "pac") {
-        const { PACIFICA_API_URL } = await import("./api/public/urls.js");
-        const baseUrl = PACIFICA_API_URL.replace("/info/prices", "");
-        const res = await fetch(`${baseUrl}/info/l2Book?symbol=${symbol.toUpperCase()}`);
+    if (def.family === "lighter") {
+        const market = (await def.publicData.fetchMarkets(MCP_NETWORK)).find(m => m.symbol.toUpperCase() === sym);
+        if (!market) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `${def.displayName} has no market ${sym}`, { exchange: def.id, remediation: `List markets with get_markets (exchange: ${def.id})` });
+        }
+        const res = await fetch(`${networkConfig(def, MCP_NETWORK).restUrl}/api/v1/orderBookOrders?market_id=${market.venueSymbol}&limit=20`);
+        if (!res.ok)
+            throw new PerpError("EXCHANGE_ERROR", `${def.displayName} orderBookOrders ${sym}: HTTP ${res.status}`, { exchange: def.id });
         const data = await res.json();
-        return {
-            bids: (data.l?.[0] ?? []).map(e => [e.p, e.a]),
-            asks: (data.l?.[1] ?? []).map(e => [e.p, e.a]),
-        };
-    }
-    else if (ex === "aster" || ex === "ast") {
-        // AsterAdapter.getOrderbook() uses /fapi/v1/depth (public).
-        const ast = new AsterAdapter();
-        await ast.init();
-        return ast.getOrderbook(symbol);
+        if (!Array.isArray(data.bids) || !Array.isArray(data.asks)) {
+            throw new PerpError("EXCHANGE_ERROR", `${def.displayName} orderBookOrders ${sym}: unexpected payload (no bids / asks arrays)`, { exchange: def.id });
+        }
+        const side = (ls) => ls.map(l => {
+            const lv = l;
+            return bookLevel(def.id, sym, lv.price, lv.remaining_base_amount !== undefined ? lv.remaining_base_amount : lv.size);
+        });
+        return { bids: side(data.bids), asks: side(data.asks) };
     }
-    throw new Error(`Unknown exchange: ${exchange}`);
+    // Read-only adapter: no key material, public endpoints only.
+    const ro = await requireCreate(def)({ network: MCP_NETWORK, credentials: READ_ONLY_CREDENTIALS, noAgent: true, hlDex: null, readOnly: true, noBuilder: true });
+    return ro.getOrderbook(sym);
 }
 // ── JSON envelope helpers ──
 function ok(data, meta) {
-    return JSON.stringify({ ok: true, data, meta }, null, 2);
+    return JSON.stringify({ ok: true, data, meta: { ...meta, network: MCP_NETWORK } }, null, 2);
 }
-function err(error, meta) {
-    return JSON.stringify({ ok: false, error, meta }, null, 2);
+/**
+ * Error envelope from a thrown value: the STRUCTURED error (classifyError — a PerpError keeps its
+ * code / remediation / details verbatim), never just the message. An ORDER_PENDING order must
+ * reach the agent as code + "Do NOT resubmit" remediation, or it would retry and double-trade.
+ */
+function errOf(e, meta, top) {
+    const s = classifyError(e, typeof meta?.exchange === "string" ? meta.exchange : undefined);
+    return JSON.stringify({
+        ok: false,
+        error: s.message,
+        code: s.code,
+        retryable: s.retryable,
+        ...(s.remediation !== undefined ? { remediation: s.remediation } : {}),
+        ...(s.details !== undefined ? { details: s.details } : {}),
+        // Tool-specific top-level facts an agent must not miss (e.g. trade_execute executed:false / pending:true).
+        ...top,
+        meta: { ...meta, network: MCP_NETWORK },
+    }, null, 2);
 }
+/** Hyperliquid scope of every MCP tool: the server builds adapters with no HIP-3 dex (hlDex null). */
+const HL_SCOPE_NOTE = "Hyperliquid: native perps only (HIP-3 dexes via the CLI --dex).";
+/**
+ * Venues with a `perp funds deposit <venue>` command. lighter takes a route (ethereum | cctp <chain>);
+ * qfex takes no amount (it shows the deposit address). Tested against the real command tree.
+ */
+export const MCP_DEPOSIT_VENUES = ["pacifica", "hyperliquid", "lighter", "lighter-rh", "aster", "ondo", "qfex"];
+/** Venues with a `perp funds withdraw <venue>` command. Tested against the real command tree. */
+export const MCP_WITHDRAW_VENUES = ["pacifica", "hyperliquid", "lighter", "aster", "arcus"];
 // ── MCP Server ──
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../package.json");
@@ -152,7 +222,7 @@ const server = new McpServer({ name: "perp-cli", version: _pkg.version }, { capa
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================
-server.tool("get_markets", "Get all available perpetual futures markets on an exchange, including price, funding rate, volume, and max leverage. Works without API keys.", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
+server.tool("get_markets", `Get all available perpetual futures markets on an exchange, including price, funding rate, volume, and max leverage. Works without API keys (public market data). ${HL_SCOPE_NOTE}`, { exchange: z.string().describe(`Exchange name: ${listVenues().map(v => v.id).join(", ")} (aliases accepted)`) }, async ({ exchange }) => {
     try {
         // Try adapter first (richer data), fall back to public API (no key needed)
         const adapter = await tryGetAdapter(exchange);
@@ -164,11 +234,11 @@ server.tool("get_markets", "Get all available perpetual futures markets on an ex
         return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, source: "public" }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
     }
 });
-server.tool("get_orderbook", "Get the order book (bids and asks) for a symbol on an exchange. Works without API keys.", {
-    exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster"),
+server.tool("get_orderbook", `Get the order book (bids and asks) for a symbol on an exchange. Works without API keys on every venue with an account API (configured credentials → the account adapter; none → the public endpoint / read-only adapter); market-data-only venues have no orderbook path. ${HL_SCOPE_NOTE}`, {
+    exchange: z.string().describe(`Exchange name: ${listVenues().map(v => v.id).join(", ")} (aliases accepted)`),
     symbol: z.string().describe("Trading pair symbol, e.g. BTC, ETH, SOL"),
 }, async ({ exchange, symbol }) => {
     try {
@@ -182,10 +252,10 @@ server.tool("get_orderbook", "Get the order book (bids and asks) for a symbol on
         return { content: [{ type: "text", text: ok(book, { exchange, symbol, source: "public" }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange, symbol }) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange, symbol }) }], isError: true };
     }
 });
-server.tool("get_funding_rates", "Compare funding rates across all 4 exchanges (Pacifica, Hyperliquid, Lighter, Aster). Returns rates per symbol with spread analysis", {
+server.tool("get_funding_rates", "Compare funding rates across every market-data venue. Returns rates per symbol with spread analysis", {
     symbols: z
         .array(z.string())
         .optional()
@@ -202,105 +272,146 @@ server.tool("get_funding_rates", "Compare funding rates across all 4 exchanges (
         };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
-server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from all 4 exchanges for comparison", {
+server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from every market-data venue for comparison", {
     symbols: z
         .array(z.string())
         .optional()
         .describe("Symbols to fetch prices for (e.g. ['BTC','ETH']). Omit for top assets"),
 }, async ({ symbols }) => {
     try {
-        // Aster has no shared-api helper; use AsterAdapter.getMarkets() (public).
-        const asterMarkets = (async () => {
-            const ast = new AsterAdapter();
-            await ast.init();
-            return ast.getMarkets();
-        })();
-        const [pacifica, hl, lighter, aster] = await Promise.all([
-            fetchPacificaPrices(),
-            fetchHyperliquidMeta(),
-            fetchLighterOrderBookDetails(),
-            asterMarkets,
-        ]);
+        const venues = listVenuesWithRole("marketData").map(v => v.id);
+        const results = await Promise.allSettled(venues.map(ex => fetchMarketsPublic(ex)));
         const filter = symbols ? new Set(symbols.map(s => s.toUpperCase())) : null;
-        // Build symbol → exchange prices map
+        // Build symbol → exchange prices map; per-venue failures are reported in meta.errors
         const priceMap = new Map();
-        for (const p of pacifica) {
-            const sym = p.symbol.toUpperCase();
-            if (filter && !filter.has(sym))
-                continue;
-            if (!priceMap.has(sym))
-                priceMap.set(sym, {});
-            priceMap.get(sym).pacifica = p.mark;
-        }
-        for (const a of hl) {
-            const sym = a.symbol.toUpperCase();
-            if (filter && !filter.has(sym))
-                continue;
-            if (!priceMap.has(sym))
-                priceMap.set(sym, {});
-            priceMap.get(sym).hyperliquid = a.markPx;
-        }
-        for (const m of lighter) {
-            const sym = m.symbol.toUpperCase();
-            if (filter && !filter.has(sym))
-                continue;
-            if (!priceMap.has(sym))
-                priceMap.set(sym, {});
-            priceMap.get(sym).lighter = m.lastTradePrice;
-        }
-        for (const a of aster) {
-            const sym = a.symbol.toUpperCase();
-            if (filter && !filter.has(sym))
-                continue;
-            if (!priceMap.has(sym))
-                priceMap.set(sym, {});
-            priceMap.get(sym).aster = Number(a.markPrice);
-        }
+        const errors = {};
+        results.forEach((r, i) => {
+            const ex = venues[i];
+            if (r.status === "rejected") {
+                errors[ex] = r.reason instanceof Error ? r.reason.message : String(r.reason);
+                return;
+            }
+            for (const m of r.value) {
+                const sym = m.symbol.toUpperCase();
+                if (filter && !filter.has(sym))
+                    continue;
+                if (!priceMap.has(sym))
+                    priceMap.set(sym, {});
+                priceMap.get(sym)[ex] = Number(m.markPrice);
+            }
+        });
         const data = Array.from(priceMap.entries()).map(([symbol, prices]) => ({ symbol, prices }));
-        return { content: [{ type: "text", text: ok(data, { count: data.length }) }] };
+        return { content: [{ type: "text", text: ok(data, { count: data.length, errors }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
+    }
+});
+// ============================================================
+// 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, MCP_NETWORK === "testnet");
+        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: errOf(e) }], isError: true };
+    }
+});
+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, MCP_NETWORK === "testnet");
+        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: errOf(e, { outcome }) }], 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, MCP_NETWORK === "testnet");
+        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: errOf(e, { outcome, side }) }], isError: true };
     }
 });
 // ============================================================
 // Account tools (need private key)
 // ============================================================
-server.tool("get_balance", "Get account balance (equity, available margin, margin used, unrealized PnL) on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
+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)) {
+            throw new PerpError("CAPABILITY_UNSUPPORTED", "Outcome positions are Hyperliquid-only", { exchange: "hyperliquid" });
+        }
+        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: errOf(e, { exchange: "hyperliquid" }) }], isError: true };
+    }
+});
+server.tool("get_balance", `Get account balance (equity, available margin, margin used, unrealized PnL) on an exchange. ${HL_SCOPE_NOTE}`, { exchange: z.string().describe(`Exchange name: ${listVenues().map(v => v.id).join(", ")} (aliases accepted)`) }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const balance = await adapter.getBalance();
         return { content: [{ type: "text", text: ok(balance, { exchange }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
     }
 });
-server.tool("get_positions", "Get all open positions on an exchange, including size, entry price, PnL, leverage", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
+server.tool("get_positions", `Get all open positions on an exchange, including size, entry price, PnL, leverage. ${HL_SCOPE_NOTE}`, { exchange: z.string().describe(`Exchange name: ${listVenues().map(v => v.id).join(", ")} (aliases accepted)`) }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const positions = await adapter.getPositions();
         return { content: [{ type: "text", text: ok(positions, { exchange, count: positions.length }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
     }
 });
-server.tool("get_open_orders", "Get all open/pending orders on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
+server.tool("get_open_orders", `Get all open/pending orders on an exchange. ${HL_SCOPE_NOTE}`, { exchange: z.string().describe(`Exchange name: ${listVenues().map(v => v.id).join(", ")} (aliases accepted)`) }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const orders = await adapter.getOpenOrders();
         return { content: [{ type: "text", text: ok(orders, { exchange, count: orders.length }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
     }
 });
-server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions, and risk metrics across all 4 exchanges", {}, async () => {
-    const EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
+server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions, and risk metrics across all exchanges with configured credentials", {}, async () => {
+    const EXCHANGES = await listConfiguredAccountVenues();
     const snapshots = await Promise.all(EXCHANGES.map(async (name) => {
         try {
             const adapter = await getOrCreateAdapter(name);
@@ -375,21 +486,22 @@ server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions,
 // ============================================================
 server.tool("suggest_command", "Given a natural language trading goal, suggest the exact perp CLI commands to run. Does NOT execute anything — only returns commands for the user to review and run manually", {
     goal: z.string().describe("Natural language goal, e.g. 'buy 0.1 BTC on pacifica', 'close all positions', 'check funding arb opportunities'"),
-    exchange: z.string().optional().describe("Preferred exchange (default: pacifica). Options: pacifica, hyperliquid, lighter, aster"),
+    exchange: z.string().optional().describe(`Preferred exchange (default: settings.defaultExchange, else pacifica — the CLI's -e default). Options: ${listVenuesWithRole("trading").map(v => v.id).join(", ")}`),
 }, async ({ goal, exchange }) => {
     try {
-        const ex = exchange ?? "pacifica";
+        // Same default as the CLI's -e (src/index.ts): settings.defaultExchange, else pacifica. Aliases resolve; unknown names throw.
+        const ex = getVenue(exchange ?? (loadSettings().defaultExchange || "pacifica")).id;
         const g = goal.toLowerCase();
         const steps = [];
         if (g.includes("buy") || g.includes("long")) {
             const symbol = extractSymbol(g) || "BTC";
             const size = extractNumber(g) || "<size>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} buy ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} buy ${size}`, description: `Buy ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} buy ${size}`, description: "Pre-flight validation (read-only, sends nothing)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} buy ${size}`, description: `Buy ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
         }
         else if (g.includes("sell") || g.includes("short")) {
             const symbol = extractSymbol(g) || "BTC";
             const size = extractNumber(g) || "<size>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} sell ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} sell ${size}`, description: `Sell ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} sell ${size}`, description: "Pre-flight validation (read-only, sends nothing)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} sell ${size}`, description: `Sell ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
         }
         else if (g.includes("limit")) {
             const symbol = extractSymbol(g) || "BTC";
@@ -421,16 +533,16 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         }
         else if (g.includes("tpsl") || g.includes("tp/sl") || g.includes("tp sl") || (g.includes("take profit") && g.includes("stop loss"))) {
             const symbol = extractSymbol(g) || "<symbol>";
-            const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json trade tpsl ${symbol} ${side} --tp <price> --sl <price>`, description: "Set TP/SL bracket orders", dangerous: true }, { step: 3, command: `perp -e ${ex} --json account orders`, description: "Verify TP/SL orders placed" });
+            const side = g.includes("sell") || g.includes("short") ? "short" : "long";
+            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position (side and size)" }, { step: 2, command: `perp -e ${ex} --json trade tpsl ${symbol} ${side} --tp <price> --sl <price>`, description: "Set reduce-only TP/SL on the position (positionSide = long|short)", dangerous: true }, { step: 3, command: `perp -e ${ex} --json account orders`, description: "Verify TP/SL orders placed" });
         }
         else if (g.includes("trailing") || g.includes("trail")) {
             const symbol = extractSymbol(g) || "<symbol>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json trade trailing-stop ${symbol}`, description: "Set trailing stop order", dangerous: true });
+            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json strategy trailing-stop ${symbol} --trail <pct>`, description: "Run a client-side trailing stop (closes the position when the trail % is hit)", dangerous: true });
         }
         else if (g.includes("stop") || g.includes("sl") || g.includes("stop loss")) {
             const symbol = extractSymbol(g) || "<symbol>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json trade stop ${symbol} <side> <stopPrice> <size>`, description: "Place stop order", dangerous: true });
+            steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position" }, { step: 2, command: `perp -e ${ex} --json trade stop ${symbol} <side> <size> <stopPrice>`, description: "Place stop order", dangerous: true });
         }
         else if (g.includes("split") || g.includes("depth") || (g.includes("large") && (g.includes("order") || g.includes("buy") || g.includes("sell")))) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -450,7 +562,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json account positions`, description: "Check current position size" }, { step: 2, command: `perp -e ${ex} --json trade reduce ${symbol} ${pct}`, description: `Reduce ${symbol} position by ${pct}%`, dangerous: true });
         }
         else if (g.includes("edit") || g.includes("modify order")) {
-            steps.push({ step: 1, command: `perp -e ${ex} --json account orders`, description: "List open orders to find order ID" }, { step: 2, command: `perp -e ${ex} --json trade edit <symbol> <orderId> <newPrice> <newSize>`, description: "Modify the order", dangerous: true });
+            steps.push({ step: 1, command: `perp -e ${ex} --json account orders`, description: "List open orders to find order ID" }, { step: 2, command: `perp -e ${ex} --json trade edit <symbol> <orderId> <price> <size>`, description: "Modify the order", dangerous: true });
         }
         else if (g.includes("arb") || g.includes("arbitrage")) {
             steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan --gaps", description: "Check cross-exchange price gaps" }, { step: 3, command: "perp --json arb scan --hip3", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
@@ -466,7 +578,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         }
         else if (g.includes("bridge") || g.includes("transfer") || g.includes("cross-chain")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: "perp --json bridge chains", description: "List supported chains" }, { step: 2, command: `perp --json bridge quote --from <chain> --to <chain> --amount ${amount}`, description: "Get bridge quote with fees" }, { step: 3, command: `perp --json bridge send --from <chain> --to <chain> --amount ${amount}`, description: "Execute bridge transfer", dangerous: true }, { step: 4, command: "perp --json bridge status <orderId>", description: "Track bridge completion" });
+            steps.push({ step: 1, command: "perp --json funds bridge chains", description: "List supported chains" }, { step: 2, command: `perp --json funds bridge quote --from <chain> --to <chain> --amount ${amount}`, description: "Get bridge quote with fees" }, { step: 3, command: `perp --json funds bridge send --from <chain> --to <chain> --amount ${amount}`, description: "Execute bridge transfer", dangerous: true }, { step: 4, command: "perp --json funds bridge status <orderId>", description: "Track bridge completion" });
         }
         else if (g.includes("grid") || g.includes("dca") || g.includes("bot")) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -491,7 +603,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             }
         }
         else if (g.includes("setup") || g.includes("init") || g.includes("configure") || g.includes("connect") || g.includes("set key") || g.includes("set wallet") || g.includes("private key")) {
-            steps.push({ step: 1, command: "perp --json wallet show", description: "Check if any wallets are already configured" }, { step: 2, command: "perp --json wallet set <exchange> <privateKey>", description: "Set private key for exchange (exchange: pacifica, hyperliquid, lighter, or aliases: hl, pac, lt)" }, { step: 3, command: "perp --json wallet set <exchange> <privateKey> --default", description: "Set key + make it the default exchange" }, { step: 4, command: "perp --json wallet show", description: "Verify wallet is configured (shows public address)" });
+            steps.push({ step: 1, command: "perp --json wallet show", description: "Check if any wallets are already configured" }, { step: 2, command: "printf '%s' \"$KEY\" | OWS_PASSPHRASE=<pp> perp --json wallet set <exchange>", description: "Import the master key (stdin — never argv) into the OWS vault and make it the active wallet. wallet set takes pacifica, hyperliquid, lighter, aster (aliases: hl, pac, lt, ast); Lighter RH / Ondo / Arcus register with perp wallet agent approve <lighter-rh|ondo|arcus>, QFEX with perp wallet agent import qfex" }, { step: 3, command: "printf '%s' \"$KEY\" | OWS_PASSPHRASE=<pp> perp --json wallet set <exchange> --default", description: "Import key + make it the default exchange" }, { step: 4, command: "perp --json wallet show", description: "Verify wallet is configured (shows public address)" });
         }
         else if (g.includes("wallet") || g.includes("balance") || g.includes("on-chain")) {
             steps.push({ step: 1, command: "perp --json wallet show", description: "Show configured wallets with public addresses" }, { step: 2, command: "perp --json wallet balance", description: "Check on-chain balances" });
@@ -518,7 +630,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp --json arb scan --gaps", description: "Cross-exchange price gaps" }, { step: 2, command: "perp --json arb scan --gaps --live", description: "Live gap monitor" });
         }
         else if (g.includes("rebalance")) {
-            steps.push({ step: 1, command: "perp --json rebalance check", description: "Check balance distribution" }, { step: 2, command: "perp --json rebalance plan", description: "Generate rebalance plan" }, { step: 3, command: "perp --json rebalance execute", description: "Execute rebalance", dangerous: true });
+            steps.push({ step: 1, command: "perp --json funds rebalance check", description: "Check balance distribution" }, { step: 2, command: "perp --json funds rebalance plan", description: "Generate rebalance plan" }, { step: 3, command: "perp --json funds rebalance execute", description: "Execute rebalance", dangerous: true });
         }
         else if (g.includes("job") || g.includes("running") || g.includes("background")) {
             steps.push({ step: 1, command: "perp --json background list", description: "List running background jobs" });
@@ -534,11 +646,31 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         }
         else if (g.includes("deposit")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" }, { step: 2, command: `perp --json funds deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json portfolio`, description: "Verify deposit arrived" });
+            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" });
+            if (ex === "lighter") {
+                // Lighter deposits pick a route: ethereum (L1 bridge) or cctp <chain> (USDC via CCTP).
+                steps.push({ step: 2, command: `perp --json funds deposit lighter ethereum ${amount}`, description: `Deposit $${amount} to lighter from Ethereum L1 (or: perp --json funds deposit lighter cctp <chain> ${amount})`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json portfolio`, description: "Verify deposit arrived" });
+            }
+            else if (ex === "qfex") {
+                // QFEX: perp-cli shows the deposit address; the user sends USDC on Arbitrum One from their own wallet.
+                steps.push({ step: 2, command: "perp --json funds deposit qfex", description: "Show the QFEX USDC (Arbitrum One) deposit address — perp-cli sends nothing; transfer from your own wallet" }, { step: 3, command: `perp -e ${ex} --json portfolio`, description: "Verify deposit arrived" });
+            }
+            else if (MCP_DEPOSIT_VENUES.includes(ex)) {
+                steps.push({ step: 2, command: `perp --json funds deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json portfolio`, description: "Verify deposit arrived" });
+            }
+            else {
+                steps.push({ step: 2, command: "perp --json funds info", description: `${ex} has no CLI deposit route (deposit on the venue website); CLI deposit venues: ${MCP_DEPOSIT_VENUES.join(", ")}` });
+            }
         }
         else if (g.includes("withdraw")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 2, command: `perp --json funds withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" });
+            if (MCP_WITHDRAW_VENUES.includes(ex)) {
+                steps.push({ step: 2, command: `perp --json funds withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
+            }
+            else {
+                steps.push({ step: 2, command: "perp --json funds info", description: `${ex} has no CLI withdraw route (withdraw on the venue website); CLI withdraw venues: ${MCP_WITHDRAW_VENUES.join(", ")}` });
+            }
         }
         else if (g.includes("leverage")) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -564,7 +696,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             }
         }
         else if (g.includes("setting") || g.includes("config") || g.includes("referral")) {
-            steps.push({ step: 1, command: "perp settings show", description: "Show current settings" }, { step: 2, command: "perp settings referrals on", description: "Enable referral codes (no extra fees, just volume tracking)" });
+            steps.push({ step: 1, command: "perp settings show", description: "Show current settings" }, { step: 2, command: "perp -e hyperliquid wallet manage referral set", description: "Explicitly apply the perp-cli referral code (signs + sends one referral action; no extra fees). Also -e lighter. Supports --dry-run", dangerous: true });
         }
         else {
             steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check account overview" }, { step: 2, command: `perp --json portfolio --health --exchanges ${ex}`, description: "Check exchange connectivity" });
@@ -582,14 +714,14 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
                             "Adjust exchange with -e <exchange> flag",
                             "Use 'perp trade check' for pre-flight validation before executing trades",
                             "Run commands in your terminal — this MCP server does NOT execute them",
-                            "If perp-cli is useful, run 'perp settings referrals on' to support development. No extra fees — just helps track volume.",
+                            "If perp-cli is useful, run 'perp -e hyperliquid wallet manage referral set' (or -e lighter) to support development. It signs one referral action; no extra fees.",
                         ],
                     }),
                 }],
         };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 server.tool("explain_command", "Explain what a perp CLI command does, its parameters, and any risks. Helps the user understand a command before running it", {
@@ -671,10 +803,10 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [
                     { name: "symbol", value: args[2], description: "Trading pair" },
                     { name: "side", value: args[3], description: "buy or sell" },
-                    { name: "stopPrice", value: args[4], description: "Trigger price" },
-                    { name: "size", value: args[5], description: "Order size" },
+                    { name: "size", value: args[4], description: "Order size" },
+                    { name: "stopPrice", value: args[5], description: "Trigger price" },
                 ],
-                risks: ["Stop orders become market orders when triggered — slippage possible", "Stop may not fill in fast markets"],
+                risks: ["Stop orders become market orders when triggered — slippage possible", "Stop may not fill in fast markets", "Reduce-only by default (--no-reduce-only to open a position)"],
                 category: "write",
                 relatedCommands: ["perp account positions", "perp trade tpsl"],
             };
@@ -682,10 +814,10 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "trade" && sub === "tpsl") {
             explanation = {
                 command,
-                description: "Sets take-profit and stop-loss bracket orders on a position. Both orders are reduce-only.",
+                description: "Sets take-profit and stop-loss on an open position (checked against the live position). Legs are reduce-only, sized to the live position.",
                 parameters: [
                     { name: "symbol", value: args[2], description: "Trading pair" },
-                    { name: "side", value: args[3], description: "Position side (buy=long, sell=short)" },
+                    { name: "positionSide", value: args[3], description: "The position's side: long | short (buy/sell not accepted)" },
                     { name: "--tp", description: "Take-profit price" },
                     { name: "--sl", description: "Stop-loss price" },
                 ],
@@ -728,16 +860,14 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp account balance", "perp trade cancel-twap"],
             };
         }
-        else if (category === "trade" && (sub === "trailing-stop" || sub === "pnl-track")) {
+        else if (category === "trade" && sub === "pnl-track") {
             explanation = {
                 command,
-                description: sub === "trailing-stop"
-                    ? "Sets a trailing stop that follows the price by a callback percentage. Triggers a market close when price reverses."
-                    : "Starts real-time PnL tracking for open positions with visual updates",
-                parameters: [{ name: "symbol", value: args[2], description: "Trading pair" }],
-                risks: sub === "trailing-stop" ? ["Will close position when trailing stop is triggered"] : [],
-                category: sub === "trailing-stop" ? "write" : "read",
-                relatedCommands: ["perp account positions", "perp trade stop"],
+                description: "Starts real-time PnL tracking for open positions with visual updates",
+                parameters: [],
+                risks: [],
+                category: "read",
+                relatedCommands: ["perp account positions", "perp strategy trailing-stop <symbol> --trail <pct>"],
             };
         }
         else if (category === "trade" && (sub === "reduce" || sub === "flatten" || sub === "close-all")) {
@@ -853,7 +983,8 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp arb scan", "perp arb status", "perp arb scan --gaps"],
             };
         }
-        else if (category === "bridge") {
+        else if (category === "funds" && sub === "bridge") {
+            const bsub = args[2] ?? "";
             explanation = {
                 command,
                 description: {
@@ -862,10 +993,10 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                     send: "Executes a cross-chain USDC bridge transfer",
                     exchange: "Bridges USDC between exchange accounts",
                     status: "Checks the status of a bridge transfer",
-                }[sub] || `Bridge command: ${sub}`,
+                }[bsub] || `Bridge command: ${bsub}`,
                 parameters: [],
-                risks: sub === "send" || sub === "exchange" ? ["Transfers real funds cross-chain — verify addresses carefully"] : [],
-                category: sub === "send" || sub === "exchange" ? "write" : "read",
+                risks: bsub === "send" || bsub === "exchange" ? ["Transfers real funds cross-chain — verify addresses carefully"] : [],
+                category: bsub === "send" || bsub === "exchange" ? "write" : "read",
                 relatedCommands: ["perp funds bridge chains", "perp funds bridge quote"],
             };
         }
@@ -895,7 +1026,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 command,
                 description: `Automated strategy: ${sub}. Runs as a background job.`,
                 parameters: args.slice(2).map((a, i) => ({ name: `arg${i}`, value: a, description: "See --help" })),
-                risks: ["Runs automated trades — monitor with 'perp background list'", "Use --dry-run to simulate first"],
+                risks: ["Runs automated trades — monitor with 'perp background list'", "--dry-run runs it against a read-only adapter (no orders sent); strategies that cannot be simulated reject --dry-run"],
                 category: "write",
                 relatedCommands: ["perp background list", "perp background stop"],
             };
@@ -933,7 +1064,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "settings") {
             explanation = {
                 command,
-                description: { show: "Display current CLI settings", referrals: "Toggle referral codes on/off (no extra fees, helps track volume)", set: "Set a specific setting value" }[sub] || `Settings: ${sub}`,
+                description: { show: "Display current CLI settings", set: "Set a specific setting value" }[sub] || `Settings: ${sub}`,
                 parameters: [],
                 risks: [],
                 category: "read",
@@ -954,7 +1085,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         return { content: [{ type: "text", text: ok(explanation) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 // ── Helper functions for suggest_command ──
@@ -1013,39 +1144,53 @@ server.tool("arb_scan", "Scan for funding rate arbitrage opportunities across ex
         };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
-server.tool("health_check", "Ping all 4 exchanges and return connectivity status and latency", {}, async () => {
+server.tool("health_check", "Ping every registered venue on the server's network and return connectivity status and latency. Pacifica / Hyperliquid / Lighter / Aster / QFEX: REST ping (status = HTTP status, 0 = no response); every other venue: its public market-data read (status null). A failure carries its error message.", {}, async () => {
     try {
-        // Aster has no shared-api ping helper; ping /fapi/v1/time directly.
-        const pingAster = async () => {
+        const timed = async (probe, fn) => {
             const start = Date.now();
             try {
-                const res = await fetch("https://fapi.asterdex.com/fapi/v1/time");
-                return { ok: res.ok, latencyMs: Date.now() - start, status: res.status };
+                const r = await fn();
+                return { ok: r.ok, latencyMs: Date.now() - start, status: r.status, error: r.ok ? null : `HTTP ${r.status}`, probe };
             }
-            catch {
-                return { ok: false, latencyMs: Date.now() - start, status: 0 };
+            catch (e) {
+                return { ok: false, latencyMs: Date.now() - start, status: probe === "ping" ? 0 : null, error: extractErrorMessage(e), probe };
             }
         };
-        const [pacifica, hyperliquid, lighter, aster] = await Promise.all([
-            pingPacifica(),
-            pingHyperliquid(),
-            pingLighter(),
-            pingAster(),
-        ]);
-        const result = {
-            pacifica: { ...pacifica, statusText: pacifica.ok ? "healthy" : "unreachable" },
-            hyperliquid: { ...hyperliquid, statusText: hyperliquid.ok ? "healthy" : "unreachable" },
-            lighter: { ...lighter, statusText: lighter.ok ? "healthy" : "unreachable" },
-            aster: { ...aster, statusText: aster.ok ? "healthy" : "unreachable" },
-            allHealthy: pacifica.ok && hyperliquid.ok && lighter.ok && aster.ok,
+        const restPing = (url) => timed("ping", async () => {
+            const res = await fetch(url);
+            return { ok: res.ok, status: res.status };
+        });
+        // Shared-api helpers report a transport failure as status 0 (no message).
+        const helperPing = (fn) => async () => {
+            const r = await fn();
+            return { ...r, error: r.ok ? null : r.status === 0 ? "no response" : `HTTP ${r.status}`, probe: "ping" };
+        };
+        const pings = {
+            pacifica: helperPing(pingPacifica),
+            hyperliquid: helperPing(pingHyperliquid),
+            lighter: helperPing(pingLighter),
+            aster: () => restPing(`${networkConfig(getVenue("aster"), MCP_NETWORK).restUrl}/fapi/v1/time`),
+            // QFEX: public GET /refdata for one instrument on the server's network.
+            qfex: () => restPing(`${networkConfig(getVenue("qfex"), MCP_NETWORK).restUrl}/refdata?ticker=AAPL-USD`),
         };
+        const venues = listVenues();
+        const probes = await Promise.all(venues.map(v => {
+            const ping = pings[v.id];
+            return ping !== undefined
+                ? ping()
+                : timed("markets", async () => { await v.publicData.fetchMarkets(MCP_NETWORK); return { ok: true, status: null }; });
+        }));
+        const result = {};
+        venues.forEach((v, i) => { result[v.id] = { ...probes[i], statusText: probes[i].ok ? "healthy" : "unreachable" }; });
+        result.covered = venues.map(v => v.id);
+        result.allHealthy = probes.every(p => p.ok);
         return { content: [{ type: "text", text: ok(result) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 // ============================================================
@@ -1055,13 +1200,14 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
     const schema = {
         schemaVersion: "2.0",
         name: "perp",
-        description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter, Aster)",
-        exchanges: ["pacifica", "hyperliquid", "lighter", "aster"],
+        description: `Multi-DEX Perpetual Futures CLI (${listVenues().map(v => v.displayName).join(", ")})`,
+        exchanges: listVenues().map(v => ({ id: v.id, displayName: v.displayName, roles: v.roles })),
         globalFlags: [
-            { flag: "-e, --exchange <name>", description: "Exchange to use (pacifica, hyperliquid, lighter, aster)", default: "pacifica" },
+            { flag: "-e, --exchange <name>", description: `Exchange to use (${listVenues().map(v => v.id).join(", ")})`, default: "settings.defaultExchange, else pacifica" },
             { flag: "--json", description: "Output as JSON for structured parsing" },
-            { flag: "-n, --network <net>", description: "Network: mainnet or testnet", default: "mainnet" },
-            { flag: "--dry-run", description: "Simulate without executing (for trade commands)" },
+            { flag: "-n, --network <net>", description: "Network: mainnet or testnet (validated; a typo is a usage error)", default: "mainnet" },
+            { flag: "--dry-run", description: "Print the order/plan without sending anything (result has sent:false). Default-deny: commands that cannot honor it reject --dry-run instead of running live" },
+            { flag: "--dex <name>", description: "HIP-3 deployed dex name, Hyperliquid only (the MCP tools read/trade native Hyperliquid perps only). Example: perp -e hyperliquid --dex <name> market list" },
         ],
         commands: {
             market: {
@@ -1093,17 +1239,16 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 },
             },
             trade: {
-                description: "Trading commands (execute in terminal, use --dry-run to simulate)",
+                description: "Trading commands (execute in terminal; --dry-run prints the order without sending it)",
                 subcommands: {
                     market: { usage: "perp trade market <symbol> <buy|sell> <size>", description: "Market order" },
                     buy: { usage: "perp trade buy <symbol> <size>", description: "Shorthand market buy" },
                     sell: { usage: "perp trade sell <symbol> <size>", description: "Shorthand market sell" },
                     limit: { usage: "perp trade limit <symbol> <buy|sell> <price> <size>", description: "Limit order" },
-                    stop: { usage: "perp trade stop <symbol> <side> <stopPrice> <size>", description: "Stop order" },
-                    tpsl: { usage: "perp trade tpsl <symbol> <side> --tp <p> --sl <p>", description: "TP/SL bracket" },
+                    stop: { usage: "perp trade stop <symbol> <side> <size> <stopPrice>", description: "Stop order (reduce-only by default; --no-reduce-only to open)" },
+                    tpsl: { usage: "perp trade tpsl <symbol> <long|short> --tp <p> --sl <p>", description: "TP/SL on an open position (reduce-only)" },
                     "scale-tp": { usage: "perp trade scale-tp <symbol> --levels '<p>:<pct>,...'", description: "Scaled take-profit" },
                     "scale-in": { usage: "perp trade scale-in <symbol> <side> --levels '<p>:<size>,...'", description: "Scaled entry" },
-                    "trailing-stop": { usage: "perp trade trailing-stop <symbol>", description: "Trailing stop" },
                     twap: { usage: "perp trade twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
                     edit: { usage: "perp trade edit <symbol> <orderId> <price> <size>", description: "Modify existing order" },
                     cancel: { usage: "perp trade cancel <symbol> <orderId>", description: "Cancel order" },
@@ -1128,7 +1273,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 subcommands: {
                     scan: { usage: "perp arb scan --min <pct>", description: "Find arb opportunities (use --rates, --gaps, --hip3, --positions, --basis, --compare, --history, --live)" },
                     auto: { usage: "perp arb auto --min-spread <pct>", description: "Auto-execute funding arb" },
-                    exec: { usage: "perp arb exec <symbol> <longEx> <shortEx> <size>", description: "Execute arb trade on two exchanges" },
+                    exec: { usage: "perp arb exec <symbol> <longExch> <shortExch> <sizeUsd>", description: "Execute arb trade on two exchanges (sizeUsd = USD notional per leg)" },
                     status: { usage: "perp arb status", description: "Current arb positions" },
                     close: { usage: "perp arb close <symbol>", description: "Close arb position" },
                     "history|log": { usage: "perp arb history", description: "Arb execution history" },
@@ -1149,10 +1294,10 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 subcommands: {
                     start: { usage: "perp strategy start <config>", description: "Start bot from config file" },
                     twap: { usage: "perp strategy twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
-                    grid: { usage: "perp strategy grid <symbol> --range <pct> --grids <n> --size <usd>", description: "Grid trading bot" },
+                    grid: { usage: "perp strategy grid <symbol> --upper <price> --lower <price> --grids <n> --size <base>", description: "Grid trading bot" },
                     dca: { usage: "perp strategy dca <symbol> <side> <amount> <interval>", description: "DCA bot" },
                     "funding-arb": { usage: "perp strategy funding-arb", description: "Funding arb bot" },
-                    "trailing-stop": { usage: "perp strategy trailing-stop <symbol>", description: "Trailing stop bot" },
+                    "trailing-stop": { usage: "perp strategy trailing-stop <symbol> --trail <pct>", description: "Client-side trailing stop (closes the position when the trail % is hit)" },
                     "quick-grid": { usage: "perp strategy quick-grid <symbol>", description: "Quick grid bot" },
                     "quick-dca": { usage: "perp strategy quick-dca <symbol> <side> <amount> <interval>", description: "Quick DCA bot" },
                     "quick-arb": { usage: "perp strategy quick-arb", description: "Quick arb bot" },
@@ -1169,17 +1314,18 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 subcommands: {
                     show: { usage: "perp wallet show", description: "Show configured wallets with public addresses" },
                     list: { usage: "perp wallet list", description: "List all wallets (OWS vault + legacy)" },
-                    balance: { usage: "perp wallet balance [name]", description: "On-chain balances" },
+                    balance: { usage: "perp wallet balance [name]", description: "On-chain gas token + USDC/USDT on Arbitrum, Ethereum, Base, BNB Chain, Robinhood Chain (USDG) and Solana" },
                     generate: { usage: "perp wallet generate [name]", description: "Generate new OWS wallet (encrypted, multi-chain)" },
-                    import: { usage: "perp wallet import <privateKey>", description: "Import key into OWS vault" },
+                    import: { usage: "printf '%s' \"$KEY\" | OWS_PASSPHRASE=<pp> perp wallet import --name <name> [--chain evm|solana|dual]", description: "Import key into OWS vault (stdin / hidden prompt — never argv)" },
                     migrate: { usage: "perp wallet migrate", description: "Migrate legacy wallets to OWS vault" },
-                    set: { usage: "perp wallet set <exchange> <key>", description: "Set private key for exchange (legacy)" },
+                    set: { usage: "perp wallet set <exchange> [--name <n>]", description: "Import an exchange key (hidden prompt / stdin; argv key rejected) into the OWS vault → active wallet" },
                     use: { usage: "perp wallet use <name>", description: "Set active wallet (OWS or legacy)" },
                     remove: { usage: "perp wallet remove <name>", description: "Remove a wallet" },
                     rename: { usage: "perp wallet rename <oldName> <newName>", description: "Rename a wallet" },
                     policy: { usage: "perp wallet policy <create|list|show|delete>", description: "OWS signing policies (guardrails for agent signing)" },
                     key: { usage: "perp wallet key <create|list|revoke>", description: "OWS API keys (scoped agent access tokens)" },
                     agent: { usage: "perp wallet agent <approve|list|revoke|rotate|verify>", description: "DEX-side agent wallet delegation (per-exchange)" },
+                    builder: { usage: "perp wallet builder <status|approve|revoke>", description: "Builder fees (off by default): status / master-signed approve / revoke of the builder set in settings builder.<venue> (approve/revoke: --dry-run, --yes)" },
                     deposit: { usage: "perp wallet deposit <walletName>", description: "MoonPay multi-chain deposit (auto-converts to USDC)" },
                     setup: { usage: "perp wallet setup", description: "One-click: wallet + guardrail policy + agent API key" },
                     backup: { usage: "perp wallet backup", description: "Backup encrypted OWS vault" },
@@ -1224,8 +1370,10 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 usage: "perp funds <deposit|withdraw|transfer|bridge|rebalance|info> ...",
                 description: "Fund movement — deposit, withdraw, transfer, cross-chain bridge, inter-exchange rebalance",
                 subcommands: {
-                    "deposit <exchange> <amount>": "Deposit USDC to exchange (pacifica, hyperliquid, lighter)",
-                    "withdraw <exchange> <amount>": "Withdraw USDC from exchange (pacifica, hyperliquid, lighter)",
+                    [`deposit <${MCP_DEPOSIT_VENUES.filter(v => v !== "lighter" && v !== "qfex").join("|")}> <amount>`]: "Deposit USDC to an exchange account",
+                    "deposit qfex": "Show the QFEX USDC (Arbitrum One) deposit address — perp-cli sends nothing",
+                    "deposit lighter <ethereum|cctp> ...": "Deposit to Lighter: perp funds deposit lighter ethereum <amount> (L1 bridge) | perp funds deposit lighter cctp <chain> <amount> (CCTP)",
+                    [`withdraw <${MCP_WITHDRAW_VENUES.join("|")}> <amount>`]: "Withdraw USDC from an exchange account",
                     "transfer <amount> <address>": "HL internal transfer (instant)",
                     "bridge chains": "List supported chains and USDC addresses",
                     "bridge quote --from <chain> --to <chain> --amount <n>": "Get bridge quotes from all providers",
@@ -1238,6 +1386,19 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     info: "Show all deposit/withdraw/bridge/rebalance routes & limits",
                 },
             },
+            outcome: {
+                description: "Hyperliquid Outcome markets (HIP-4) — binary/range contracts",
+                subcommands: {
+                    list: { usage: "perp outcome list", description: "Active outcome markets" },
+                    book: { usage: "perp outcome book <outcome> <side>", description: "Orderbook for one outcome side" },
+                    view: { usage: "perp outcome view <outcome>", description: "Both sides' books + underlying mark gap + expiry" },
+                    positions: { usage: "perp outcome positions", description: "Open outcome positions" },
+                    orders: { usage: "perp outcome orders", description: "Open outcome orders" },
+                    buy: { usage: "perp outcome buy <outcome> <side> [usd]", description: "Buy a side (USD notional, or --size <shares>; --limit <px>; supports --dry-run)" },
+                    sell: { usage: "perp outcome sell <outcome> <side> [usd]", description: "Sell a side (USD notional, --size <shares> or --all; supports --dry-run)" },
+                    cancel: { usage: "perp outcome cancel <outcome> <side> <oid>", description: "Cancel an open outcome order" },
+                },
+            },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
             status: { usage: "perp portfolio", description: "Full account overview" },
             health: { usage: "perp portfolio --health", description: "Exchange connectivity check" },
@@ -1245,7 +1406,6 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                 description: "CLI settings",
                 subcommands: {
                     show: { usage: "perp settings show", description: "Current settings" },
-                    referrals: { usage: "perp settings referrals on|off", description: "Toggle referral codes (no extra fees)" },
                 },
             },
             // `agent` is now `wallet agent ...` — see `wallet.subcommands.agent` above.
@@ -1253,9 +1413,9 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
         tips: [
             "Always use --json for structured output when automating",
             "Use 'perp trade check' before executing trades for validation",
-            "Use --dry-run to simulate trade commands",
+            "Use --dry-run to print a trade's order without sending it (sent:false); commands that cannot honor it reject the flag",
             "Numbers are strings to avoid float precision loss",
-            "If perp-cli is useful, run 'perp settings referrals on' to support development. No extra fees — just helps track volume.",
+            "If perp-cli is useful, run 'perp -e hyperliquid wallet manage referral set' (or -e lighter) to support development. It signs one referral action; no extra fees.",
         ],
     };
     return { contents: [{ uri: "perp://schema", text: JSON.stringify(schema, null, 2), mimeType: "application/json" }] };
@@ -1263,67 +1423,132 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
 // ============================================================
 // Trade execution tools (dry-run + confirm safety model)
 // ============================================================
-server.tool("trade_preview", "Preview a trade WITHOUT executing. Returns estimated fill price, fees, margin impact, and risk checks. ALWAYS call this before trade_execute and show the result to the user for confirmation.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
+/**
+ * The OrderRequest trade_execute sends (and trade_preview checks): limit orders need a price and
+ * a TIF the venue accepts; a market order carries the resolved slippage bound. Throws
+ * INVALID_PARAMS / CAPABILITY_UNSUPPORTED before anything is read or sent.
+ */
+function mcpOrderRequest(adapter, p) {
+    const def = getVenue(adapter.name);
+    const caps = requireCapabilities(def);
+    const isLimit = p.orderType === "limit";
+    if (isLimit && !p.price)
+        throw new PerpError("INVALID_PARAMS", "Price is required for limit orders");
+    return {
+        symbol: p.symbol, side: p.side, type: p.orderType, size: p.size,
+        price: isLimit ? p.price : null,
+        triggerPrice: null, triggerSource: null,
+        tif: isLimit ? validateLegacyTif(def, caps, p.tif ?? "GTC") : null,
+        reduceOnly: p.reduceOnly,
+        clientOrderId: caps.clientOrderId && caps.orderAck === "async" ? newVenueClientOrderId(def) : null,
+        slippage: isLimit ? null : resolveAdapterSlippage(adapter, p.slippageBps ?? null),
+        tpsl: null,
+    };
+}
+server.tool("trade_preview", `Preview a trade WITHOUT executing. Runs trade_execute's pre-send checks read-only (size parse, order validation incl. TIF, quarantine, local risk limits — never forced) and reports any refusal as valid:false with its code + remediation; also returns the estimated fill price from the book, notional, margin impact, the builder fee the order would carry, and the existing position. Venue trading fees are NOT estimated. ALWAYS call this before trade_execute and show the result to the user for confirmation. ${HL_SCOPE_NOTE}`, {
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.create !== null).map(v => v.id).join(", ")} (aliases accepted)`),
     symbol: z.string().describe("Trading symbol (e.g., BTC, ETH, SOL)"),
     side: z.enum(["buy", "sell"]).describe("Order side"),
     size: z.string().describe("Order size (base currency units, e.g., '0.1' for 0.1 BTC)"),
     orderType: z.enum(["market", "limit"]).default("market").describe("Order type"),
     price: z.string().optional().describe("Limit price (required for limit orders)"),
-}, async ({ exchange, symbol, side, size, orderType, price }) => {
+    tif: z.string().optional().describe("Limit orders: GTC (default) | IOC | FOK | ALO (post-only); venue aliases GTT / GTX / TOB accepted — checked like trade_execute"),
+    reduceOnly: z.boolean().default(false).describe("Reduce-only order (close position only) — checked like trade_execute (quarantine applies only to non-reduce-only orders)"),
+}, async ({ exchange, symbol, side, size, orderType, price, tif, reduceOnly }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
+        const sym = symbol.toUpperCase();
+        const isLimit = orderType === "limit";
+        // trade_execute's pre-send checks, read-only. Each refusal keeps its code + remediation.
+        const refusals = [];
+        const refuse = (check, e) => {
+            const s = classifyError(e, adapter.name);
+            refusals.push({ check, code: s.code, message: s.message, remediation: s.remediation ?? null });
+        };
+        let parsedSize = null;
+        try {
+            parsedSize = parsePositiveDecimal(size, "size");
+        }
+        catch (e) {
+            refuse("size", e);
+        }
+        if (parsedSize !== null) {
+            try {
+                const req = mcpOrderRequest(adapter, { symbol: sym, side, size: parsedSize, orderType, price, tif, reduceOnly, slippageBps: undefined });
+                const def = getVenue(adapter.name);
+                validateOrderRequest(def, requireCapabilities(def), req);
+            }
+            catch (e) {
+                refuse("order", e);
+            }
+            try {
+                await mcpPreTradeGate(adapter, { symbol: sym, size: Number(parsedSize), price: isLimit && price ? Number(price) : null, reduceOnly }, (m) => process.stderr.write(`${m}\n`));
+            }
+            catch (e) {
+                refuse("gate", e);
+            }
+        }
         const [balance, positions, orderbook] = await Promise.all([
             adapter.getBalance(),
             adapter.getPositions(),
-            adapter.getOrderbook(symbol),
+            adapter.getOrderbook(sym),
         ]);
         // Estimate fill price from orderbook
         const bestBid = orderbook.bids[0]?.[0];
         const bestAsk = orderbook.asks[0]?.[0];
-        const estPrice = orderType === "limit" && price
+        const estPrice = isLimit && price
             ? price
             : side === "buy" ? bestAsk : bestBid;
-        const notional = estPrice ? Number(estPrice) * Number(size) : 0;
-        const existingPos = positions.find(p => p.symbol.toUpperCase().includes(symbol.toUpperCase()));
-        // Run validation
+        // Unknown (unparseable size / empty book side) = null, never 0.
+        const notional = estPrice && parsedSize !== null ? Number(estPrice) * Number(parsedSize) : null;
+        const existingPos = positions.find(p => symbolMatch(p.symbol, symbol));
         // SSOT rule #2: validation failure must surface as a structured invalid
-        // result, NOT be swallowed into a fake `{ valid: true }`. The previous
-        // shape silently green-lit trades when the underlying balance/orderbook
-        // fetches errored out.
+        // result, NOT be swallowed into a fake `{ valid: true }`.
         let validation;
         // For a preview the user has not yet committed leverage, so 1x is the
         // documented default exposed in the preview shape (no silent fallback —
         // the caller can override via existingPos.leverage when re-entering an
         // open position).
         const previewLeverage = existingPos?.leverage ?? 1;
-        try {
-            validation = await validateTrade(adapter, { symbol, side, size: Number(size), leverage: previewLeverage });
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            validation = {
-                valid: false,
-                checks: [{
-                        check: "symbol_valid",
-                        passed: false,
-                        message: `Validation could not run: ${msg}`,
-                    }],
-                warnings: [],
-            };
+        if (parsedSize === null) {
+            validation = { valid: false, checks: [{ check: "size", passed: false, message: refusals[0].message }], warnings: [] };
         }
+        else {
+            try {
+                validation = await validateTrade(adapter, {
+                    symbol: sym, side, size: Number(parsedSize), leverage: previewLeverage, type: orderType, reduceOnly,
+                    ...(isLimit && price ? { price: Number(price) } : {}),
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                validation = {
+                    valid: false,
+                    checks: [{
+                            check: "symbol_valid",
+                            passed: false,
+                            message: `Validation could not run: ${msg}`,
+                        }],
+                    warnings: [],
+                };
+            }
+        }
+        const builderPlan = await builderPlanFor(adapter, sym);
         const preview = {
-            order: { exchange, symbol, side, size, orderType, price: price ?? estPrice },
+            // false when trade_execute would refuse this order (see refusals) or the trade checks fail.
+            valid: refusals.length === 0 && validation.valid,
+            refusals,
+            order: { exchange, symbol, side, size, orderType, price: price ?? estPrice ?? null, tif: tif ?? null, reduceOnly },
             estimate: {
-                fillPrice: estPrice ?? "unknown",
-                notionalUsd: notional.toFixed(2),
-                spread: bestBid && bestAsk ? ((Number(bestAsk) - Number(bestBid)) / Number(bestBid) * 100).toFixed(4) + "%" : "unknown",
+                fillPrice: estPrice ?? null,
+                notionalUsd: notional !== null ? notional.toFixed(2) : null,
+                spread: bestBid && bestAsk ? ((Number(bestAsk) - Number(bestBid)) / Number(bestBid) * 100).toFixed(4) + "%" : null,
             },
             account: {
                 equity: balance.equity,
                 available: balance.available,
                 marginUsed: balance.marginUsed,
-                marginAfter: (Number(balance.marginUsed) + notional / (existingPos?.leverage ?? 1)).toFixed(2),
+                marginAfter: notional !== null ? (Number(balance.marginUsed) + notional / previewLeverage).toFixed(2) : null,
             },
             existingPosition: existingPos ? {
                 side: existingPos.side,
@@ -1332,66 +1557,238 @@ server.tool("trade_preview", "Preview a trade WITHOUT executing. Returns estimat
                 unrealizedPnl: existingPos.unrealizedPnl,
             } : null,
             validation,
+            // Builder fee the live order would carry (settings builder.<venue> + confirmed approval); null = none.
+            builderFee: builderPlan.applied,
+            builderNote: builderPlan.note,
             warning: "This is a PREVIEW only. Call trade_execute to place the order after user confirms.",
         };
         return { content: [{ type: "text", text: ok(preview, { exchange, type: "preview" }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange, symbol }) }], isError: true };
     }
 });
-server.tool("trade_execute", "Execute a trade. IMPORTANT: Always call trade_preview first and get explicit user confirmation before calling this tool. Supports market and limit orders.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
+/**
+ * Place one order through TradingV2 (native on ondo/arcus, legacy wrapper on the four
+ * pre-existing venues) and return OrderResult + execution (design §13.7). Pre-send
+ * validation failures stay definite; anything thrown after the request may have reached
+ * the venue becomes ORDER_PENDING ("do NOT resubmit", design §12.3).
+ */
+async function placeViaV2(adapter, req, what, remediation) {
+    const def = getVenue(adapter.name);
+    const caps = requireCapabilities(def);
+    validateOrderRequest(def, caps, req);
+    try {
+        const network = adapterNetworks.get(adapter);
+        if (network === undefined)
+            throw new PerpError("INVALID_PARAMS", `${def.displayName}: adapter network unknown — refusing to place`);
+        return await placeAndConfirm(tradingV2Of(adapter, network), caps, req);
+    }
+    catch (e) {
+        throw isDefiniteOrderFailure(e) ? e : orderOutcomeUnknown(adapter.name, what, e, remediation);
+    }
+}
+server.tool("trade_execute", `Execute a REAL trade on the server's network (meta.network; PERP_NETWORK, default mainnet). IMPORTANT: Always call trade_preview first and get explicit user confirmation before calling this tool. Refused with RISK_VIOLATION when the order breaches the local risk limits (perp risk set; there is no override over MCP) or when the symbol is quarantined (only reduce-only orders pass). Every order is written to the execution log. Supports market and limit orders. Returns the uniform OrderResult (status, finality, filledSize, execution: slippage / protection price / TIF sent) with the raw venue response under \`legacy\`, plus top-level filledSize / requestedSize / partial. Outcomes: an unknown outcome (transport failure after send, or a non-final venue ack) → ok:false, code ORDER_PENDING, executed:false, pending:true and a "do NOT resubmit" remediation — the symbol is quarantined for opening orders until a human clears it; a final rejection / cancel with nothing filled → ORDER_REJECTED, executed:false; a cancel after a partial fill → executed:true, partial:true with the real filledSize. ${HL_SCOPE_NOTE}`, {
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.create !== null).map(v => v.id).join(", ")} (aliases accepted)`),
     symbol: z.string().describe("Trading symbol (e.g., BTC, ETH, SOL)"),
     side: z.enum(["buy", "sell"]).describe("Order side"),
     size: z.string().describe("Order size (base currency units)"),
     orderType: z.enum(["market", "limit"]).default("market").describe("Order type"),
     price: z.string().optional().describe("Limit price (required for limit orders)"),
+    tif: z.string().optional().describe("Limit orders: GTC (default) | IOC | FOK | ALO (post-only); venue aliases GTT / GTX / TOB accepted"),
     reduceOnly: z.boolean().default(false).describe("Reduce-only order (close position only)"),
-}, async ({ exchange, symbol, side, size, orderType, price, reduceOnly }) => {
+    slippageBps: z.number().optional().describe("Market orders: slippage bound in bps (default: settings defaultSlippageBps)"),
+}, async ({ exchange, symbol, side, size: rawSize, orderType, price, tif, reduceOnly, slippageBps }) => {
     try {
+        // One parsed size for the risk gate and the order ("1,000" / "abc" refused before any read or send).
+        const size = parsePositiveDecimal(rawSize, "size");
         const adapter = await getOrCreateAdapter(exchange);
+        const def = getVenue(adapter.name);
+        const caps = requireCapabilities(def);
+        const sym = symbol.toUpperCase();
+        const isLimit = orderType === "limit";
+        const req = mcpOrderRequest(adapter, { symbol: sym, side, size, orderType, price, tif, reduceOnly, slippageBps });
+        // Same pre-send path as `perp trade`: request validation, quarantine (non-reduce-only),
+        // local risk limits (no force over MCP), then client-id + execution log around the send.
+        validateOrderRequest(def, caps, req);
+        await mcpPreTradeGate(adapter, { symbol: sym, size: Number(size), price: isLimit ? Number(price) : null, reduceOnly }, (m) => process.stderr.write(`${m}\n`));
+        const orderType_ = isLimit ? "limit" : "market";
+        const logType = isLimit ? "limit_order" : "market_order";
+        const cid = req.clientOrderId;
+        const nowIso = () => new Date().toISOString();
+        if (cid !== null) {
+            logClientId({ clientOrderId: cid, exchange: adapter.name, symbol: sym, side, size, ...(isLimit ? { price: price } : {}), type: orderType_, status: "pending", createdAt: nowIso(), updatedAt: nowIso() });
+        }
+        const logMeta = { reduceOnly, ...(cid !== null ? { clientOrderId: cid } : {}) };
+        const priceLog = isLimit ? { price: price } : {};
+        const errMeta = { exchange, symbol, type: "execution" };
+        const qLog = (m) => process.stderr.write(`${m}\n`);
+        const clearCmd = `${MCP_NETWORK === "testnet" ? "perp -n testnet" : "perp"} strategy quarantine-clear ${sym}`;
+        // An unknown outcome on an opening order quarantines the symbol: the gate then refuses a
+        // resubmit of the same order (only reduce-only orders pass) until a human clears it.
+        const quarantineUnknown = (why) => {
+            if (reduceOnly)
+                return;
+            quarantineSymbol("mcp-execute", sym, `trade_execute ${orderType} ${side} ${size} ${sym} on ${adapter.name}: ${why}`, `Check ${sym} on ${adapter.name} (get_open_orders / get_positions), resolve the order by hand, then: ${clearCmd}`, qLog);
+        };
         let result;
-        if (orderType === "limit") {
-            if (!price)
-                throw new Error("Price is required for limit orders");
-            result = await adapter.limitOrder(symbol, side, price, size, { reduceOnly });
+        try {
+            result = await placeViaV2(adapter, req, `${orderType} ${side} ${size} ${sym}`, `Do NOT resubmit — the order may have been placed. Call get_positions / get_open_orders for ${symbol} on ${exchange} first`);
+        }
+        catch (placeErr) {
+            const unknown = isOutcomeUnknown(placeErr);
+            logMcpExecution(MCP_NETWORK, { type: logType, exchange: adapter.name, symbol: sym, side, size, ...priceLog, status: unknown ? "unverified" : "failed", error: extractErrorMessage(placeErr), meta: logMeta });
+            // An unknown outcome stays "pending" in the client-id log (it may have been placed).
+            if (cid !== null && !unknown) {
+                logClientId({ clientOrderId: cid, exchange: adapter.name, symbol: sym, side, size, type: orderType_, status: "failed", createdAt: nowIso(), updatedAt: nowIso() });
+            }
+            if (unknown)
+                quarantineUnknown(`outcome unknown (${extractErrorMessage(placeErr)})`);
+            return { content: [{ type: "text", text: errOf(placeErr, errMeta, unknown ? { executed: false, pending: true } : { executed: false }) }], isError: true };
+        }
+        // Settle what the venue reported (mirrors the CLI scale path, src/commands/trade.ts placeScaleLevels):
+        //  - not final → outcome unknown: ORDER_PENDING, never "success";
+        //  - final rejected / cancelled with nothing filled → ORDER_REJECTED;
+        //  - final cancelled with an unreported fill → the fill is unknown: ORDER_PENDING;
+        //  - final rejected / cancelled with a fill → executed, reported as the partial fill it is.
+        const filled = result.filledSize === null ? null : Number(result.filledSize);
+        const terminal = result.status === "rejected" || result.status === "cancelled";
+        const fillUnknown = result.finality === "final" && result.status === "cancelled" && filled === null;
+        if (result.finality !== "final" || fillUnknown) {
+            const why = fillUnknown
+                ? `the venue cancelled the order without reporting its fill`
+                : `the venue acknowledged the order without a final status (${result.status})`;
+            logMcpExecution(MCP_NETWORK, { type: logType, exchange: adapter.name, symbol: sym, side, size, ...priceLog, status: "unverified", error: why, meta: logMeta });
+            quarantineUnknown(why);
+            const pe = new PerpError("ORDER_PENDING", `${adapter.name} ${orderType} ${side} ${size} ${sym}: outcome unknown — ${why}`, {
+                exchange: adapter.name,
+                remediation: result.remediation ?? `Do NOT resubmit — the order may have filled. Call get_open_orders / get_positions for ${symbol} on ${exchange} first`,
+            });
+            return { content: [{ type: "text", text: errOf(pe, errMeta, { executed: false, pending: true, result: orderResultJson(result) }) }], isError: true };
+        }
+        if (terminal && (filled === null || filled === 0)) {
+            const why = `the venue ${result.status} the order${result.orderId !== null ? ` ${result.orderId}` : ""}`;
+            logMcpExecution(MCP_NETWORK, { type: logType, exchange: adapter.name, symbol: sym, side, size, ...priceLog, status: "failed", error: why, meta: logMeta });
+            if (cid !== null) {
+                logClientId({ clientOrderId: cid, exchange: adapter.name, symbol: sym, side, size, type: orderType_, status: "failed", createdAt: nowIso(), updatedAt: nowIso() });
+            }
+            const pe = new PerpError("ORDER_REJECTED", `${adapter.name} ${orderType} ${side} ${size} ${sym}: ${why}; nothing filled`, { exchange: adapter.name });
+            return { content: [{ type: "text", text: errOf(pe, errMeta, { executed: false, result: orderResultJson(result) }) }], isError: true };
         }
-        else {
-            result = await adapter.marketOrder(symbol, side, size);
+        const partial = terminal; // a terminal status with a fill > 0 — the rest was cancelled / rejected
+        logMcpExecution(MCP_NETWORK, {
+            type: logType, exchange: adapter.name, symbol: sym, side, size: partial ? result.filledSize : size, ...priceLog, status: "success",
+            meta: { ...logMeta, ...(partial ? { partial: true, requested: size, venueStatus: result.status } : {}) },
+        });
+        if (cid !== null) {
+            logClientId({ clientOrderId: cid, exchange: adapter.name, symbol: sym, side, size, type: orderType_, status: "submitted", createdAt: nowIso(), updatedAt: nowIso() });
+        }
+        // The order is placed: a failed position read below must NOT turn it into an error
+        // (an agent would retry and double-trade). Report currentPosition: null + warning instead.
+        // Exact symbol match; "-PERP" suffix-insensitive; uncached read.
+        let currentPosition;
+        let warning = partial
+            ? `Partially filled: ${result.filledSize} of ${size} ${sym}; the rest was ${result.status} by the venue. Do NOT resubmit the full size`
+            : null;
+        try {
+            invalidateCache("acct");
+            const positions = await adapter.getPositions();
+            currentPosition = positions.find(p => symbolMatch(p.symbol, symbol)) ?? null;
+        }
+        catch (readErr) {
+            currentPosition = null;
+            const readWarning = `Order placed, but the post-order position read failed: ${extractErrorMessage(readErr)}. Do NOT resubmit — call get_positions for ${symbol} on ${exchange}`;
+            warning = warning === null ? readWarning : `${warning}. ${readWarning}`;
         }
-        // Fetch updated position
-        const positions = await adapter.getPositions();
-        const pos = positions.find(p => p.symbol.toUpperCase().includes(symbol.toUpperCase()));
         return {
             content: [{
                     type: "text",
                     text: ok({
                         executed: true,
-                        order: { exchange, symbol, side, size, orderType, price },
-                        result,
-                        currentPosition: pos ?? null,
+                        partial,
+                        // null = the venue did not report the fill (never "0" as a stand-in).
+                        filledSize: result.filledSize,
+                        requestedSize: size,
+                        order: { exchange, symbol, side, size, orderType, price, tif: req.tif },
+                        result: orderResultJson(result),
+                        currentPosition,
+                        ...(warning !== null ? { warning } : {}),
                     }, { exchange, type: "execution" }),
                 }],
         };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange, symbol, type: "execution" }) }], isError: true };
     }
 });
-server.tool("trade_close", "Close an existing position. IMPORTANT: Call trade_preview first with the opposite side to show impact, then get user confirmation.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
+server.tool("trade_close", `Close an existing position. IMPORTANT: Call trade_preview first with the opposite side to show impact, then get user confirmation. Verified close: \`closedSize\` is the measured / venue-final fill (one residual market close is attempted); a residual still open → ORDER_PARTIAL error (symbol quarantined). Includes the uniform OrderResult of the reduce-only market order. ${HL_SCOPE_NOTE}`, {
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.create !== null).map(v => v.id).join(", ")} (aliases accepted)`),
     symbol: z.string().describe("Symbol to close (e.g., BTC, ETH)"),
 }, async ({ exchange, symbol }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
+        const def = getVenue(adapter.name);
+        const caps = requireCapabilities(def);
+        // A venue whose reduce-only orders are gated refuses the close before any read.
+        mcpReduceOnlyGate(adapter);
+        // Size the reduce-only close from a fresh read, never a cached position.
+        invalidateCache("acct");
         const positions = await adapter.getPositions();
-        const pos = positions.find(p => p.symbol.toUpperCase().includes(symbol.toUpperCase()));
+        const pos = positions.find(p => symbolMatch(p.symbol, symbol));
         if (!pos || Number(pos.size) === 0) {
-            return { content: [{ type: "text", text: err(`No open position for ${symbol} on ${exchange}`) }], isError: true };
+            throw new PerpError("POSITION_NOT_FOUND", `No open position for ${symbol} on ${exchange}`, { exchange: adapter.name, remediation: `List open positions with get_positions (exchange: ${exchange})` });
         }
         const closeSide = pos.side === "long" ? "sell" : "buy";
-        const result = await adapter.marketOrder(symbol, closeSide, pos.size);
+        const closeSize = pos.size.replace(/^-/, "");
+        const req = {
+            symbol: pos.symbol, side: closeSide, type: "market", size: closeSize,
+            price: null, triggerPrice: null, triggerSource: null, tif: null, reduceOnly: true,
+            clientOrderId: caps.clientOrderId && caps.orderAck === "async" ? newVenueClientOrderId(def) : null,
+            slippage: resolveAdapterSlippage(adapter, null),
+            tpsl: null,
+        };
+        const holder = { placed: null };
+        const nowIso = () => new Date().toISOString();
+        const dec = sizeDecimalsOf(closeSize);
+        const qLog = (m) => process.stderr.write(`${m}\n`);
+        const remediation = `Check ${pos.symbol} on ${adapter.name} (get_positions), close any residual by hand, then: perp strategy quarantine-clear ${pos.symbol}`;
+        let c;
+        try {
+            // Verified close: the first leg is the TradingV2 reduce-only market order; the fill is
+            // measured / venue-final, and one residual market close is attempted (closePerpVerified).
+            c = await closePerpVerified(adapter, adapter.name, pos.symbol, closeSide, closeSize, {
+                decimals: dec,
+                slippage: req.slippage ?? undefined,
+                place: async () => {
+                    if (req.clientOrderId !== null)
+                        logClientId({ clientOrderId: req.clientOrderId, exchange: adapter.name, symbol: pos.symbol, side: closeSide, size: closeSize, type: "market", status: "pending", createdAt: nowIso(), updatedAt: nowIso() });
+                    holder.placed = await placeViaV2(adapter, req, `reduce-only close ${closeSide} ${closeSize} ${pos.symbol}`, `Do NOT resubmit — the close may have executed. Call get_positions for ${symbol} on ${exchange} first`);
+                    return holder.placed.venueRaw;
+                },
+            });
+        }
+        catch (e) {
+            // An unknown outcome keeps the client id "pending"; a definite failure marks it failed.
+            if (req.clientOrderId !== null && !isOutcomeUnknown(e))
+                logClientId({ clientOrderId: req.clientOrderId, exchange: adapter.name, symbol: pos.symbol, side: closeSide, size: closeSize, type: "market", status: "failed", createdAt: nowIso(), updatedAt: nowIso() });
+            if (isOutcomeUnknown(e))
+                quarantineSymbol("mcp-close", pos.symbol, `trade_close ${pos.symbol} on ${adapter.name}: outcome unknown (${extractErrorMessage(e)})`, remediation, qLog);
+            logMcpExecution(MCP_NETWORK, { type: "market_order", exchange: adapter.name, symbol: pos.symbol, side: closeSide, size: closeSize, status: isOutcomeUnknown(e) ? "unverified" : "failed", error: extractErrorMessage(e), meta: { reduceOnly: true, action: "close" } });
+            throw e;
+        }
+        const closedSize = fillSizeString(c.closed, dec);
+        const residual = fillSizeString(c.residual, dec);
+        if (req.clientOrderId !== null)
+            logClientId({ clientOrderId: req.clientOrderId, exchange: adapter.name, symbol: pos.symbol, side: closeSide, size: closeSize, type: "market", status: "submitted", createdAt: nowIso(), updatedAt: nowIso() });
+        logMcpExecution(MCP_NETWORK, { type: "market_order", exchange: adapter.name, symbol: pos.symbol, side: closeSide, size: closedSize, status: c.residual > 0 ? "failed" : "success", ...(c.residual > 0 ? { error: `residual ${residual} still open` } : {}), meta: { reduceOnly: true, action: "close", requested: closeSize } });
+        const closedPosition = { side: pos.side, size: pos.size, entryPrice: pos.entryPrice, unrealizedPnl: pos.unrealizedPnl };
+        const entryResult = holder.placed !== null ? orderResultJson(holder.placed) : null;
+        if (c.residual > 0) {
+            quarantineSymbol("mcp-close", pos.symbol, `trade_close ${pos.symbol} on ${adapter.name}: closed ${closedSize} of ${closeSize}, ${residual} still open${c.note !== null ? ` (${c.note})` : ""}`, remediation, qLog);
+            throw new PerpError("ORDER_PARTIAL", `${adapter.name} close ${pos.symbol}: closed ${closedSize} of ${closeSize}; ${residual} still open${c.note !== null ? ` (${c.note})` : ""}`, {
+                exchange: adapter.name, closedSize, residual, closedPosition, result: entryResult, remediation,
+            });
+        }
         return {
             content: [{
                     type: "text",
@@ -1399,14 +1796,16 @@ server.tool("trade_close", "Close an existing position. IMPORTANT: Call trade_pr
                         closed: true,
                         symbol,
                         exchange,
-                        closedPosition: { side: pos.side, size: pos.size, entryPrice: pos.entryPrice, unrealizedPnl: pos.unrealizedPnl },
-                        result,
+                        closedSize,
+                        residual,
+                        closedPosition,
+                        result: entryResult,
                     }, { exchange, type: "close" }),
                 }],
         };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e, { exchange, symbol, type: "close" }) }], isError: true };
     }
 });
 // ============================================================
@@ -1418,34 +1817,35 @@ server.tool("get_funding_analysis", "Analyze funding income across exchanges —
     symbol: z.string().optional().describe("Filter by symbol"),
 }, async ({ period, exchange: exFilter, symbol: symFilter }) => {
     try {
-        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter", "aster"];
+        const exchanges = exFilter ? [exFilter] : await listConfiguredAccountVenues();
         const periodMatch = period.match(/^(\d+)(d|w|m)$/);
         const sinceMs = periodMatch
             ? Date.now() - parseInt(periodMatch[1]) * ({ d: 86400000, w: 604800000, m: 2592000000 }[periodMatch[2]] ?? 86400000)
             : 0;
         const allFunding = [];
         const posNotionals = new Map();
-        await Promise.allSettled(exchanges.map(async (ex) => {
-            try {
-                const adapter = await getOrCreateAdapter(ex);
-                const [payments, positions] = await Promise.all([
-                    adapter.getFundingPayments(200),
-                    adapter.getPositions(),
-                ]);
-                for (const p of payments) {
-                    if (sinceMs && p.time < sinceMs)
-                        continue;
-                    if (symFilter && !p.symbol.toUpperCase().includes(symFilter.toUpperCase()))
-                        continue;
-                    allFunding.push({ exchange: ex, symbol: p.symbol, payment: Number(p.payment), time: p.time });
-                }
-                for (const p of positions) {
-                    if (Number(p.size) > 0)
-                        posNotionals.set(`${ex}:${p.symbol}`, Math.abs(Number(p.size) * Number(p.markPrice)));
-                }
+        // Per-venue failures are reported in meta.errors (never silently dropped from the totals).
+        const errors = {};
+        const settled = await Promise.allSettled(exchanges.map(async (ex) => {
+            const adapter = await getOrCreateAdapter(ex);
+            const [payments, positions] = await Promise.all([
+                adapter.getFundingPayments(200),
+                adapter.getPositions(),
+            ]);
+            for (const p of payments) {
+                if (sinceMs && p.time < sinceMs)
+                    continue;
+                if (symFilter && !p.symbol.toUpperCase().includes(symFilter.toUpperCase()))
+                    continue;
+                allFunding.push({ exchange: ex, symbol: p.symbol, payment: Number(p.payment), time: p.time });
+            }
+            for (const p of positions) {
+                if (Number(p.size) > 0)
+                    posNotionals.set(`${ex}:${p.symbol}`, Math.abs(Number(p.size) * Number(p.markPrice)));
             }
-            catch { /* skip */ }
         }));
+        settled.forEach((r, i) => { if (r.status === "rejected")
+            errors[exchanges[i]] = extractErrorMessage(r.reason); });
         allFunding.sort((a, b) => a.time - b.time);
         // Aggregate by exchange×symbol
         const byExSym = new Map();
@@ -1461,7 +1861,7 @@ server.tool("get_funding_analysis", "Analyze funding income across exchanges —
         const periodDays = sinceMs ? (Date.now() - sinceMs) / 86400000
             : allFunding.length > 1 ? (allFunding[allFunding.length - 1].time - allFunding[0].time) / 86400000 : 1;
         // Match to arb positions
-        const arbState = loadArbState();
+        const arbState = loadArbState(MCP_NETWORK);
         const arbPositions = (arbState?.positions ?? []).map(pos => {
             const lf = allFunding.filter(f => f.symbol === pos.symbol && f.exchange === pos.longExchange).reduce((s, f) => s + f.payment, 0);
             const sf = allFunding.filter(f => f.symbol === pos.symbol && f.exchange === pos.shortExchange).reduce((s, f) => s + f.payment, 0);
@@ -1477,10 +1877,10 @@ server.tool("get_funding_analysis", "Analyze funding income across exchanges —
             })),
             arbPositions,
         };
-        return { content: [{ type: "text", text: ok(data) }] };
+        return { content: [{ type: "text", text: ok(data, { errors }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 server.tool("get_pnl_analysis", "P&L analysis combining trading fees and funding income — shows net profit/loss by exchange with daily breakdown", {
@@ -1488,43 +1888,44 @@ server.tool("get_pnl_analysis", "P&L analysis combining trading fees and funding
     exchange: z.string().optional().describe("Filter by exchange"),
 }, async ({ period, exchange: exFilter }) => {
     try {
-        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter", "aster"];
+        const exchanges = exFilter ? [exFilter] : await listConfiguredAccountVenues();
         const periodMatch = period.match(/^(\d+)(d|w|m)$/);
         const sinceMs = periodMatch
             ? Date.now() - parseInt(periodMatch[1]) * ({ d: 86400000, w: 604800000, m: 2592000000 }[periodMatch[2]] ?? 86400000)
             : 0;
         const byExchange = new Map();
         const dailyMap = new Map();
-        await Promise.allSettled(exchanges.map(async (ex) => {
-            try {
-                const adapter = await getOrCreateAdapter(ex);
-                const [trades, funding] = await Promise.all([adapter.getTradeHistory(200), adapter.getFundingPayments(200)]);
-                const exData = byExchange.get(ex) ?? { trades: 0, volume: 0, fees: 0, funding: 0 };
-                for (const t of trades) {
-                    if (sinceMs && t.time < sinceMs)
-                        continue;
-                    const notional = Number(t.price) * Number(t.size);
-                    exData.trades++;
-                    exData.volume += notional;
-                    exData.fees += Number(t.fee);
-                    const day = new Date(t.time).toISOString().slice(0, 10);
-                    const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
-                    d.fees += Number(t.fee);
-                    dailyMap.set(day, d);
-                }
-                for (const f of funding) {
-                    if (sinceMs && f.time < sinceMs)
-                        continue;
-                    exData.funding += Number(f.payment);
-                    const day = new Date(f.time).toISOString().slice(0, 10);
-                    const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
-                    d.funding += Number(f.payment);
-                    dailyMap.set(day, d);
-                }
-                byExchange.set(ex, exData);
+        // Per-venue failures are reported in meta.errors (never silently dropped from the totals).
+        const errors = {};
+        const settled = await Promise.allSettled(exchanges.map(async (ex) => {
+            const adapter = await getOrCreateAdapter(ex);
+            const [trades, funding] = await Promise.all([adapter.getTradeHistory(200), adapter.getFundingPayments(200)]);
+            const exData = byExchange.get(ex) ?? { trades: 0, volume: 0, fees: 0, funding: 0 };
+            for (const t of trades) {
+                if (sinceMs && t.time < sinceMs)
+                    continue;
+                const notional = Number(t.price) * Number(t.size);
+                exData.trades++;
+                exData.volume += notional;
+                exData.fees += Number(t.fee);
+                const day = new Date(t.time).toISOString().slice(0, 10);
+                const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
+                d.fees += Number(t.fee);
+                dailyMap.set(day, d);
             }
-            catch { /* skip */ }
+            for (const f of funding) {
+                if (sinceMs && f.time < sinceMs)
+                    continue;
+                exData.funding += Number(f.payment);
+                const day = new Date(f.time).toISOString().slice(0, 10);
+                const d = dailyMap.get(day) ?? { fees: 0, funding: 0 };
+                d.funding += Number(f.payment);
+                dailyMap.set(day, d);
+            }
+            byExchange.set(ex, exData);
         }));
+        settled.forEach((r, i) => { if (r.status === "rejected")
+            errors[exchanges[i]] = extractErrorMessage(r.reason); });
         let totalFees = 0, totalFunding = 0, totalVolume = 0, totalTrades = 0;
         for (const d of byExchange.values()) {
             totalFees += d.fees;
@@ -1537,17 +1938,17 @@ server.tool("get_pnl_analysis", "P&L analysis combining trading fees and funding
             byExchange: Object.fromEntries([...byExchange.entries()].map(([ex, d]) => [ex, { ...d, netPnl: d.funding - d.fees }])),
             daily: [...dailyMap.entries()].sort().map(([date, d]) => ({ date, fees: d.fees, funding: d.funding, net: d.funding - d.fees })),
         };
-        return { content: [{ type: "text", text: ok(data) }] };
+        return { content: [{ type: "text", text: ok(data, { errors }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 server.tool("get_arb_compare", "Compare active arbitrage positions side by side — ROI, funding income, price PnL, and annualized returns for each position", {
     period: z.string().default("all").describe("Funding lookup period: 7d, 30d, 90d, or all"),
 }, async ({ period }) => {
     try {
-        const arbState = loadArbState();
+        const arbState = loadArbState(MCP_NETWORK);
         const positions = arbState?.positions ?? [];
         if (positions.length === 0) {
             return { content: [{ type: "text", text: ok({ positions: [], message: "No active arb positions" }) }] };
@@ -1563,38 +1964,53 @@ server.tool("get_arb_compare", "Compare active arbitrage positions side by side
         }
         const fundingByExSym = new Map();
         const currentPrices = new Map();
-        await Promise.allSettled([...exchangeSet].map(async (ex) => {
-            try {
-                const adapter = await getOrCreateAdapter(ex);
-                const [funding, livePos] = await Promise.all([adapter.getFundingPayments(200), adapter.getPositions()]);
-                for (const f of funding) {
-                    if (sinceMs && f.time < sinceMs)
-                        continue;
-                    const key = `${ex}:${f.symbol}`;
-                    fundingByExSym.set(key, (fundingByExSym.get(key) ?? 0) + Number(f.payment));
-                }
-                for (const p of livePos)
-                    currentPrices.set(`${ex}:${p.symbol}`, Number(p.markPrice));
+        // A venue whose reads failed has unknown funding / prices: its rows report null, the reason is in meta.errors.
+        const errors = {};
+        const venues = [...exchangeSet];
+        const settled = await Promise.allSettled(venues.map(async (ex) => {
+            const adapter = await getOrCreateAdapter(ex);
+            const [funding, livePos] = await Promise.all([adapter.getFundingPayments(200), adapter.getPositions()]);
+            for (const f of funding) {
+                if (sinceMs && f.time < sinceMs)
+                    continue;
+                const key = `${ex}:${f.symbol}`;
+                fundingByExSym.set(key, (fundingByExSym.get(key) ?? 0) + Number(f.payment));
             }
-            catch { /* skip */ }
+            for (const p of livePos)
+                currentPrices.set(`${ex}:${p.symbol}`, Number(p.markPrice));
         }));
-        const rows = positions.map(pos => {
+        settled.forEach((r, i) => { if (r.status === "rejected")
+            errors[venues[i]] = extractErrorMessage(r.reason); });
+        // Entries without a verified entry price have no price PnL: listed apart, never priced at a guess.
+        const priced = positions.filter((p) => p.entryLongPrice !== null && p.entryShortPrice !== null);
+        const unpricedPositions = positions.filter(p => p.entryLongPrice === null || p.entryShortPrice === null).map(p => p.symbol);
+        // Funding of a venue that answered: the sum of its payments (none = 0). A failed venue: unknown (null).
+        const fundingOf = (ex, sym) => (ex in errors ? null : fundingByExSym.get(`${ex}:${sym}`) ?? 0);
+        // Current mark price from the live position; none (failed read / no live leg) = unknown (null), never the entry price.
+        const priceOf = (ex, sym) => currentPrices.get(`${ex}:${sym}`) ?? null;
+        const rows = priced.map(pos => {
             const daysHeld = Math.max(1, Math.round((Date.now() - new Date(pos.entryTime).getTime()) / 86400000));
-            const funding = (fundingByExSym.get(`${pos.longExchange}:${pos.symbol}`) ?? 0) + (fundingByExSym.get(`${pos.shortExchange}:${pos.symbol}`) ?? 0);
-            const longPrice = currentPrices.get(`${pos.longExchange}:${pos.symbol}`) ?? pos.entryLongPrice;
-            const shortPrice = currentPrices.get(`${pos.shortExchange}:${pos.symbol}`) ?? pos.entryShortPrice;
-            const pricePnl = (longPrice - pos.entryLongPrice) * pos.longSize + (pos.entryShortPrice - shortPrice) * pos.shortSize;
-            const totalPnl = pricePnl + funding;
+            const lf = fundingOf(pos.longExchange, pos.symbol);
+            const sf = fundingOf(pos.shortExchange, pos.symbol);
+            const funding = lf !== null && sf !== null ? lf + sf : null;
+            const longPrice = priceOf(pos.longExchange, pos.symbol);
+            const shortPrice = priceOf(pos.shortExchange, pos.symbol);
+            const pricePnl = longPrice !== null && shortPrice !== null
+                ? (longPrice - pos.entryLongPrice) * pos.longSize + (pos.entryShortPrice - shortPrice) * pos.shortSize
+                : null;
+            const totalPnl = pricePnl !== null && funding !== null ? pricePnl + funding : null;
             const notional = pos.entryLongPrice * pos.longSize + pos.entryShortPrice * pos.shortSize;
-            const roi = notional > 0 ? (totalPnl / notional) * 100 : 0;
-            const fundingRoi = notional > 0 ? (funding / notional) * 100 : 0;
-            return { symbol: pos.symbol, mode: pos.mode ?? "perp-perp", longExchange: pos.longExchange, shortExchange: pos.shortExchange, daysHeld, funding, pricePnl, totalPnl, roi, annualizedRoi: daysHeld > 0 ? (fundingRoi / daysHeld) * 365 : 0 };
-        }).sort((a, b) => b.totalPnl - a.totalPnl);
-        const totals = { funding: rows.reduce((s, r) => s + r.funding, 0), pricePnl: rows.reduce((s, r) => s + r.pricePnl, 0), totalPnl: rows.reduce((s, r) => s + r.totalPnl, 0) };
-        return { content: [{ type: "text", text: ok({ period, positionCount: rows.length, positions: rows, totals }) }] };
+            const roi = totalPnl !== null && notional > 0 ? (totalPnl / notional) * 100 : null;
+            const fundingRoi = funding !== null && notional > 0 ? (funding / notional) * 100 : null;
+            return { symbol: pos.symbol, mode: pos.mode ?? "perp-perp", longExchange: pos.longExchange, shortExchange: pos.shortExchange, daysHeld, funding, pricePnl, totalPnl, roi, annualizedRoi: fundingRoi !== null ? (fundingRoi / daysHeld) * 365 : null };
+        }).sort((a, b) => (a.totalPnl === null ? 1 : b.totalPnl === null ? -1 : b.totalPnl - a.totalPnl));
+        // A total over rows with an unknown value is itself unknown (null).
+        const sumOrNull = (vals) => (vals.some(v => v === null) ? null : vals.reduce((s, v) => s + v, 0));
+        const totals = { funding: sumOrNull(rows.map(r => r.funding)), pricePnl: sumOrNull(rows.map(r => r.pricePnl)), totalPnl: sumOrNull(rows.map(r => r.totalPnl)) };
+        return { content: [{ type: "text", text: ok({ period, positionCount: rows.length, positions: rows, unpricedPositions, totals }, { errors }) }] };
     }
     catch (e) {
-        return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
+        return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
 // ============================================================
@@ -1602,27 +2018,28 @@ server.tool("get_arb_compare", "Compare active arbitrage positions side by side
 // ============================================================
 server.resource("market_prices", "market://prices", { mimeType: "application/json", description: "Live cross-exchange prices for all perpetual futures markets" }, async () => {
     const prices = {};
-    await Promise.allSettled(["pacifica", "hyperliquid", "lighter", "aster"].map(async (ex) => {
-        try {
-            const adapter = await getOrCreateAdapter(ex);
-            const markets = await adapter.getMarkets();
-            for (const m of markets) {
-                if (!prices[m.symbol])
-                    prices[m.symbol] = {};
-                prices[m.symbol][ex] = m.markPrice;
-            }
+    const venues = listVenuesWithRole("marketData").map(v => v.id);
+    // Per-venue failures are reported in meta.errors (like get_prices), never silently skipped.
+    const errors = {};
+    const settled = await Promise.allSettled(venues.map(async (ex) => {
+        const markets = await fetchMarketsPublic(ex);
+        for (const m of markets) {
+            if (!prices[m.symbol])
+                prices[m.symbol] = {};
+            prices[m.symbol][ex] = m.markPrice;
         }
-        catch { /* skip */ }
     }));
-    return { contents: [{ uri: "market://prices", text: JSON.stringify({ ok: true, data: prices, meta: { timestamp: new Date().toISOString() } }, null, 2), mimeType: "application/json" }] };
+    settled.forEach((r, i) => { if (r.status === "rejected")
+        errors[venues[i]] = extractErrorMessage(r.reason); });
+    return { contents: [{ uri: "market://prices", text: JSON.stringify({ ok: true, data: prices, meta: { timestamp: new Date().toISOString(), network: MCP_NETWORK, errors } }, null, 2), mimeType: "application/json" }] };
 });
 server.resource("funding_rates", "market://funding-rates", { mimeType: "application/json", description: "Current funding rates across all exchanges with spread analysis" }, async () => {
     try {
         const rates = await fetchAllFundingRates();
-        return { contents: [{ uri: "market://funding-rates", text: JSON.stringify({ ok: true, data: rates, meta: { timestamp: new Date().toISOString() } }, null, 2), mimeType: "application/json" }] };
+        return { contents: [{ uri: "market://funding-rates", text: JSON.stringify({ ok: true, data: rates, meta: { timestamp: new Date().toISOString(), network: MCP_NETWORK } }, null, 2), mimeType: "application/json" }] };
     }
     catch (e) {
-        return { contents: [{ uri: "market://funding-rates", text: JSON.stringify({ ok: false, error: String(e) }), mimeType: "application/json" }] };
+        return { contents: [{ uri: "market://funding-rates", text: errOf(e), mimeType: "application/json" }] };
     }
 });
 // ============================================================
@@ -1649,12 +2066,14 @@ server.prompt("trading-guide", "Step-by-step guide for trading with perp-cli via
 
 3. **Preview Before Executing**
    - ALWAYS use \`trade_preview\` before any trade
-   - Show the user: estimated price, fees, margin impact
+   - Show the user: estimated price, notional, margin impact, builder fee, and any refusal (valid:false + code / remediation)
+   - Venue trading fees are not estimated by the preview
    - Wait for explicit user confirmation
 
 4. **Execute with Confirmation**
    - Only call \`trade_execute\` after user says "yes" or "confirm"
    - Never execute trades without showing the preview first
+   - ORDER_PENDING (pending:true) means the outcome is unknown: do NOT resubmit — check \`get_open_orders\` / \`get_positions\` (the symbol is quarantined for opening orders until a human clears it)
 
 5. **Monitor After Execution**
    - Use \`get_positions\` to verify the trade went through
@@ -1666,11 +2085,10 @@ server.prompt("trading-guide", "Step-by-step guide for trading with perp-cli via
 - If the user asks to "buy" or "sell", preview first, then ask for confirmation
 - Warn about high-leverage trades or large position sizes
 
-## Supported Exchanges
-- **pacifica** (Solana) — SOL-based perpetual futures
-- **hyperliquid** (HyperEVM) — Low-fee perpetuals with HIP-3 DEXes
-- **lighter** (Ethereum) — Ethereum-based perpetual futures
-- **aster** (BNB Chain) — BNB Chain perpetual futures`,
+## Supported Exchanges (server network: ${MCP_NETWORK})
+${listVenues().map(v => `- **${v.id}** (${v.displayName}) — ${v.roles.join(", ")}`).join("\n")}
+
+${HL_SCOPE_NOTE}`,
             },
         }],
 }));