perp-cli 0.14.3 → 0.16.0

package/dist/mcp-server.js

@@ -23,8 +23,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 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 { getVenue, listPublicBalanceVenues, listPublicPositionVenues, listVenues, listVenuesWithRole, networkConfig, READ_ONLY_CREDENTIALS, requireCapabilities, roleUnsupported } from "./exchanges/venue.js";
 import "./exchanges/venues/index.js";
+import { venueMarketRow } from "./exchanges/venue-types.js";
+import { lighterFundingStatsWarning } from "./exchanges/lighter-public.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";
@@ -32,8 +34,11 @@ 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 { probeVenueHealth } from "./venue-health.js";
+import { getOptionsVenue, listOptionsVenueIds } from "./exchanges/options-venues.js";
+import { fetchAllFundingRates, isRankedComparison } from "./funding-rates.js";
+import { readPositionsByAddress } from "./positions-by-address.js";
+import { readBalanceByAddress, readBalanceByAddressAll } from "./balance-by-address.js";
 import { loadArbState } from "./arb/state.js";
 import { validateTrade } from "./trade-validator.js";
 import { orderResultJson, symbolMatch } from "./utils.js";
@@ -41,6 +46,7 @@ import { logMcpExecution, mcpPreTradeGate, mcpReduceOnlyGate, resolveMcpNetwork
 import { setSharedApiNetwork } from "./api/public/urls.js";
 import { logClientId } from "./client-id-tracker.js";
 import { loadSettings } from "./settings.js";
+import { registerPacificaEarnMcpTools } from "./mcp-pacifica-earn.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
@@ -52,8 +58,8 @@ 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
+// Same creation path and signer tiers as the CLI (agent → OWS master → PK).
+// 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). */
@@ -71,6 +77,9 @@ async function getOrCreateAdapter(exchange) {
     const cached = adapters.get(def.id);
     if (cached)
         return cached;
+    // Market-data-only venue (TxFlow: unofficial read-only API): every account / trading tool refuses here.
+    if (!def.roles.includes("account"))
+        throw roleUnsupported(def, "account");
     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}`, {
@@ -118,9 +127,58 @@ async function tryGetAdapter(exchange) {
         throw e;
     }
 }
-/** Fetch markets using the venue's public data path (no key needed). */
+/**
+ * Fetch markets using the venue's public data path (no key needed). Unofficial-API rows carry
+ * venueApi; rows of a venue whose funding is unverified (QFEX, GRVT, TxFlow) carry fundingVerified false.
+ */
 async function fetchMarketsPublic(exchange) {
-    return getVenue(exchange).publicData.fetchMarkets(MCP_NETWORK);
+    return labelMarketRows(exchange, await getVenue(exchange).publicData.fetchMarkets(MCP_NETWORK));
+}
+/**
+ * meta.warnings when a venue's rows carry fundingRate null for a known reason (Lighter: the
+ * settled-rate snapshot could not be read) — the reason reaches the agent, not only stderr.
+ */
+function fundingWarningMeta(exchange, rows) {
+    const id = getVenue(exchange).id;
+    if (id !== "lighter" && id !== "lighter-rh")
+        return {};
+    // Tied to the rows served: only when they actually carry a null rate (cached rows that have
+    // rates never get a stale warning; null rows always say why when the reason is known).
+    if (!rows.some(r => r.fundingRate === null))
+        return {};
+    const w = lighterFundingStatsWarning(id, MCP_NETWORK);
+    return w === null ? {} : { warnings: [w] };
+}
+/**
+ * Keyless get_markets rows: the public directory's VenueMarket rows in the CLI market-row shape
+ * (venueMarketRow — the mapper the VenueMarket CLI adapters use), the VenueMarket fields kept
+ * (venueSymbol, canonical, assetClass, fundingRateBasis, tickSize, …) and the MCP labels added.
+ */
+async function fetchMarketRowsPublic(exchange) {
+    const markets = await getVenue(exchange).publicData.fetchMarkets(MCP_NETWORK);
+    return labelMarketRows(exchange, markets.map(m => ({ ...m, ...venueMarketRow(m) })));
+}
+/**
+ * The one row label for market rows of any source (public data path or a credentialed adapter):
+ * every row carries fundingVerified (true or false — as `perp market list`), unofficial-API rows venueApi.
+ */
+function labelMarketRows(exchange, rows) {
+    const def = getVenue(exchange);
+    const labelled = rows.map(r => ({ ...r, fundingVerified: def.fundingVerified }));
+    return def.apiStatus.kind === "unofficial" ? labelled.map(r => ({ ...r, venueApi: "unofficial" })) : labelled;
+}
+/**
+ * meta fields every market-data tool adds for its venue: apiStatus, the note for an unofficial API,
+ * and fundingVerified false (with a note) when the venue's funding rate is unverified.
+ */
+function apiMeta(exchange) {
+    const def = getVenue(exchange);
+    if (def.apiStatus.kind === "unofficial") {
+        return { apiStatus: "unofficial", apiNote: `${def.displayName}: UNOFFICIAL API — ${def.apiStatus.note}`, fundingVerified: def.fundingVerified };
+    }
+    return def.fundingVerified
+        ? { apiStatus: "official" }
+        : { apiStatus: "official", fundingVerified: false, fundingNote: `${def.displayName}: funding rate UNVERIFIED (not confirmed against settled payments) — display only, never a basis for trading` };
 }
 /** 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) {
@@ -219,6 +277,8 @@ export const MCP_WITHDRAW_VENUES = ["pacifica", "hyperliquid", "lighter", "aster
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../package.json");
 const server = new McpServer({ name: "perp-cli", version: _pkg.version }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+// Pacifica Print + vaults: read-only tools (src/mcp-pacifica-earn.ts).
+registerPacificaEarnMcpTools(server, MCP_NETWORK, ok, errOf);
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================
@@ -227,11 +287,14 @@ server.tool("get_markets", `Get all available perpetual futures markets on an ex
         // Try adapter first (richer data), fall back to public API (no key needed)
         const adapter = await tryGetAdapter(exchange);
         if (adapter) {
-            const markets = await adapter.getMarkets();
-            return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length }) }] };
-        }
-        const markets = await fetchMarketsPublic(exchange);
-        return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, source: "public" }) }] };
+            const markets = labelMarketRows(exchange, await adapter.getMarkets());
+            return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, ...apiMeta(exchange), ...fundingWarningMeta(exchange, markets) }) }] };
+        }
+        // No credentials: the venue's public directory — price-only on GRVT (no 184-request
+        // margin_rules fan-out per call) — in the CLI market-row shape (venueMarketRow), with the
+        // same market set as `perp market list` (the venue's shared eligibility / listing rule).
+        const markets = await fetchMarketRowsPublic(exchange);
+        return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, source: "public", ...apiMeta(exchange), ...fundingWarningMeta(exchange, markets) }) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
@@ -246,24 +309,25 @@ server.tool("get_orderbook", `Get the order book (bids and asks) for a symbol on
         const adapter = await tryGetAdapter(exchange);
         if (adapter) {
             const book = await adapter.getOrderbook(symbol);
-            return { content: [{ type: "text", text: ok(book, { exchange, symbol }) }] };
+            return { content: [{ type: "text", text: ok(book, { exchange, symbol, ...apiMeta(exchange) }) }] };
         }
         const book = await fetchOrderbookPublic(exchange, symbol);
-        return { content: [{ type: "text", text: ok(book, { exchange, symbol, source: "public" }) }] };
+        return { content: [{ type: "text", text: ok(book, { exchange, symbol, source: "public", ...apiMeta(exchange) }) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: errOf(e, { exchange, symbol }) }], isError: true };
     }
 });
-server.tool("get_funding_rates", "Compare funding rates across every market-data venue. Returns rates per symbol with spread analysis", {
+server.tool("get_funding_rates", "Compare funding rates across every market-data venue whose funding rate is verified. Returns rates per symbol with spread analysis. includeUnverified also returns venues whose rate is unverified (QFEX; TxFlow — unofficial API; Variational — a predicted rate not checked against settled payments; GRVT — indicative rate; Extended — not checked against settled payments), each row tagged fundingVerified / apiStatus — display only, never a basis for trading (mirrors the CLI `arb scan --include-unverified`).", {
     symbols: z
         .array(z.string())
         .optional()
         .describe("Filter to specific symbols (e.g. ['BTC','ETH']). Omit for all available"),
     minSpread: z.number().optional().describe("Minimum annualized spread % to include (default: 0)"),
-}, async ({ symbols, minSpread }) => {
+    includeUnverified: z.boolean().optional().describe("Also include venues whose funding rate is unverified (default false); rows carry fundingVerified:false / apiStatus"),
+}, async ({ symbols, minSpread, includeUnverified }) => {
     try {
-        const snapshot = await fetchAllFundingRates({ symbols, minSpread });
+        const snapshot = await fetchAllFundingRates({ symbols, minSpread, includeUnverified: includeUnverified === true });
         return {
             content: [{
                     type: "text",
@@ -275,7 +339,7 @@ server.tool("get_funding_rates", "Compare funding rates across every market-data
         return { content: [{ type: "text", text: errOf(e) }], isError: true };
     }
 });
-server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from every market-data venue for comparison", {
+server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from every market-data venue for comparison; a venue appears in a row only when it lists that symbol (e.g. QFEX lists no BTC). Each row's unofficialApiVenues names the venues in it read through an undocumented API (TxFlow) — like get_markets' venueApi tag.", {
     symbols: z
         .array(z.string())
         .optional()
@@ -295,6 +359,10 @@ server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark p
                 return;
             }
             for (const m of r.value) {
+                // An ambiguous ticker (SPX6900 vs the S&P 500) names different instruments per venue:
+                // never grouped by symbol across venues.
+                if (m.assetClass === "unclassified")
+                    continue;
                 const sym = m.symbol.toUpperCase();
                 if (filter && !filter.has(sym))
                     continue;
@@ -303,8 +371,13 @@ server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark p
                 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, errors }) }] };
+        const unofficial = listVenuesWithRole("marketData").filter(v => v.apiStatus.kind === "unofficial").map(v => v.id);
+        const data = Array.from(priceMap.entries()).map(([symbol, prices]) => ({
+            symbol,
+            prices,
+            unofficialApiVenues: Object.keys(prices).filter(ex => unofficial.includes(ex)),
+        }));
+        return { content: [{ type: "text", text: ok(data, { count: data.length, errors, unofficialApiVenues: unofficial }) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: errOf(e) }], isError: true };
@@ -362,6 +435,44 @@ server.tool("get_outcome_book", "Get the orderbook for one outcome side. Public
     }
 });
 // ============================================================
+// Options market data (read-only, keyless; venues: src/exchanges/options-venues.ts)
+// ============================================================
+const OPTIONS_VENUE_ARG = z.string().describe(`Options venue: ${listOptionsVenueIds().join(", ")}`);
+server.tool("get_option_expiries", "List the active option expiries of an underlying on an options venue (Derive): per expiry the UTC date (YYYY-MM-DD), expiry ms, strike and instrument counts, soonest first. Public read — no API key needed.", { venue: OPTIONS_VENUE_ARG, underlying: z.string().describe("Underlying, e.g. ETH, BTC") }, async ({ venue, underlying }) => {
+    try {
+        const data = await (await getOptionsVenue(venue, MCP_NETWORK)).listExpiries(underlying);
+        return { content: [{ type: "text", text: ok(data, { venue, count: data.expiries.length }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: errOf(e, { venue, underlying }) }], isError: true };
+    }
+});
+server.tool("get_option_chain", "Option chain for one expiry (Derive): rows per strike with call and put quotes — bid / ask (price + size; null = empty side), mark, index, forward, IV (mark / bid / ask; null = not computable), greeks (delta, gamma, theta, vega, rho), open interest, 24h volume — plus the ATM strike. Decimals are strings. One venue request per expiry. Public read.", {
+    venue: OPTIONS_VENUE_ARG,
+    underlying: z.string().describe("Underlying, e.g. ETH, BTC"),
+    expiry: z.string().optional().describe("Expiry date YYYY-MM-DD (UTC); omit for the nearest active expiry (result expirySelection: \"nearest\")"),
+    strikes: z.number().int().min(1).optional().describe("Only the N strikes closest to the ATM reference (forward, else index); omit for all strikes"),
+}, async ({ venue, underlying, expiry, strikes }) => {
+    try {
+        const chain = await (await getOptionsVenue(venue, MCP_NETWORK)).getChain({
+            underlying, expiry: expiry === undefined ? null : expiry, strikesAroundAtm: strikes === undefined ? null : strikes,
+        });
+        return { content: [{ type: "text", text: ok(chain, { venue, expiry: chain.expiry, rows: chain.rows.length }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: errOf(e, { venue, underlying }) }], isError: true };
+    }
+});
+server.tool("get_option_quote", "Quote one option instrument (Derive name, e.g. ETH-20261225-3500-P): bid / ask (price + size), mark, index, forward, IV, greeks, open interest, 24h stats. Unknown instrument → SYMBOL_NOT_FOUND. Public read.", { venue: OPTIONS_VENUE_ARG, instrument: z.string().describe("Venue instrument name, e.g. ETH-20261225-3500-P") }, async ({ venue, instrument }) => {
+    try {
+        const q = await (await getOptionsVenue(venue, MCP_NETWORK)).getQuote(instrument);
+        return { content: [{ type: "text", text: ok(q, { venue, instrument: q.instrument }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: errOf(e, { venue, instrument }) }], isError: true };
+    }
+});
+// ============================================================
 // Account tools (need private key)
 // ============================================================
 server.tool("get_outcome_positions", "Get the active account's open outcome positions (size, entry notional, mark price, unrealized PnL). Requires a configured Hyperliquid wallet or agent.", {}, async () => {
@@ -400,6 +511,49 @@ server.tool("get_positions", `Get all open positions on an exchange, including s
         return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
     }
 });
+server.tool("get_positions_by_address", `Open positions of ANY account by its public address — keyless, read-only (public venue data; nothing is signed, no key is needed). Venues: ${listPublicPositionVenues().map(v => `${v.id} (${v.publicData.addressKind === "solana" ? "base58 Solana address" : "0x address"})`).join(", ")}. Hyperliquid reads the native dex and every HIP-3 dex (rows carry dex: null | "<dex>"; a dex that fails is listed in meta.errors / meta.warnings — its rows are missing, not absent); Lighter reads every account of the address (rows carry accountIndex; accountIndex narrows). Other venues: CAPABILITY_UNSUPPORTED; a wrong address format: INVALID_PARAMS. Same rows as \`perp -e <venue> account positions --address <addr>\`.`, {
+    exchange: z.string().describe(`Exchange: ${listPublicPositionVenues().map(v => v.id).join(", ")} (aliases accepted)`),
+    address: z.string().describe("Public account address (0x… for hyperliquid / lighter / lighter-rh; base58 Solana for pacifica)"),
+    symbol: z.string().optional().describe("Only this market (plain asset, e.g. BTC)"),
+    accountIndex: z.number().int().nonnegative().optional().describe("Lighter only: one account (sub-account) of the address"),
+}, async ({ exchange, address, symbol, accountIndex }) => {
+    try {
+        const r = await readPositionsByAddress(exchange, MCP_NETWORK, address, { symbol, accountIndex });
+        return { content: [{ type: "text", text: ok(r.positions, {
+                        exchange: r.venue, address, source: "public", count: r.positions.length,
+                        ...(r.warnings.length > 0 ? { warnings: r.warnings, errors: r.errors } : {}),
+                        ...(r.notes.length > 0 ? { notes: r.notes } : {}),
+                    }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
+    }
+});
+server.tool("get_balance_by_address", `Balances of ANY account by its public address — keyless, read-only (public venue data; nothing is signed, no key is needed). Venues: ${listPublicBalanceVenues().map(v => `${v.id} (${v.publicData.addressKind === "solana" ? "base58 Solana address" : "0x address"})`).join(", ")}; omit exchange to read every one of them (a venue that fails, address format included, is listed in data.errors). data: { balance (equity / available / marginUsed / unrealizedPnl + venue extras; null on Lighter), spot (token balances; null where the venue does not publish them), accounts (Lighter: one row per account of the address; accountIndex narrows), dexes + accountMode (Hyperliquid: HIP-3 dexes with a non-zero account value; a dex that fails is in meta.errors / meta.warnings — unknown, not zero) }. Other venues: CAPABILITY_UNSUPPORTED; a wrong address format: INVALID_PARAMS. Same data as \`perp [-e <venue>] account balance --address <addr>\`.`, {
+    exchange: z.string().optional().describe(`Exchange: ${listPublicBalanceVenues().map(v => v.id).join(", ")} (aliases accepted); omit for every one`),
+    address: z.string().describe("Public account address (0x… for hyperliquid / lighter / lighter-rh / risex; base58 Solana for pacifica)"),
+    accountIndex: z.number().int().nonnegative().optional().describe("Lighter only: one account (sub-account) of the address"),
+}, async ({ exchange, address, accountIndex }) => {
+    try {
+        if (exchange === undefined) {
+            const all = await readBalanceByAddressAll(MCP_NETWORK, address, { accountIndex });
+            return { content: [{ type: "text", text: ok({
+                            venues: all.venues,
+                            ...(Object.keys(all.errors).length > 0 ? { errors: all.errors } : {}),
+                            ...(Object.keys(all.notes).length > 0 ? { notes: all.notes } : {}),
+                        }, { address, source: "public", ...(all.warnings.length > 0 ? { warnings: all.warnings } : {}) }) }] };
+        }
+        const r = await readBalanceByAddress(exchange, MCP_NETWORK, address, { accountIndex });
+        return { content: [{ type: "text", text: ok({ exchange: r.venue, address, ...r.data }, {
+                        exchange: r.venue, address, source: "public",
+                        ...(r.warnings.length > 0 ? { warnings: r.warnings, errors: r.errors } : {}),
+                        ...(r.notes.length > 0 ? { notes: r.notes } : {}),
+                    }) }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: errOf(e, { exchange }) }], isError: true };
+    }
+});
 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);
@@ -433,6 +587,9 @@ server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions,
             };
         }
     }));
+    // Totals are null (unknown) when no account balance was read — no configured credentials, or
+    // every venue failed — never 0 (QA 0.15.0: totalEquity 0 without credentials).
+    const read = snapshots.filter(s => s.balance !== null);
     let totalEquity = 0;
     let totalAvailable = 0;
     let totalMarginUsed = 0;
@@ -468,16 +625,21 @@ server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions,
         pct: totalEquity > 0 ? (Number(s.balance.equity) / totalEquity) * 100 : 0,
     }))
         .sort((a, b) => b.pct - a.pct);
+    const known = read.length > 0;
     const summary = {
-        totalEquity,
-        totalAvailable,
-        totalMarginUsed,
-        totalUnrealizedPnl,
+        /** "noAccount" = no venue has credentials; "unread" = credentials exist but no balance was read. */
+        accountState: EXCHANGES.length === 0 ? "noAccount" : known ? "ok" : "unread",
+        /** Venues whose balances the totals cover. */
+        totalsCover: read.map(s => s.exchange),
+        totalEquity: known ? totalEquity : null,
+        totalAvailable: known ? totalAvailable : null,
+        totalMarginUsed: known ? totalMarginUsed : null,
+        totalUnrealizedPnl: known ? totalUnrealizedPnl : null,
         totalPositions,
         totalOpenOrders,
         exchanges: snapshots,
         positions: allPositions,
-        riskMetrics: { marginUtilization, largestPosition, exchangeConcentration },
+        riskMetrics: { marginUtilization: known ? marginUtilization : null, largestPosition, exchangeConcentration },
     };
     return { content: [{ type: "text", text: ok(summary) }] };
 });
@@ -1121,10 +1283,14 @@ server.tool("arb_scan", "Scan for funding rate arbitrage opportunities across ex
             symbols,
             minSpread: minSpread ?? 5,
         });
-        const opportunities = snapshot.symbols.map(s => ({
+        const opportunities = snapshot.symbols.filter(isRankedComparison).map(s => ({
             symbol: s.symbol,
             maxSpreadAnnual: `${s.maxSpreadAnnual.toFixed(2)}%`,
             strategy: `Long ${s.longExchange} / Short ${s.shortExchange}`,
+            // false = a leg is on a read-only venue (RISEx in this release): data only, not tradable here.
+            executable: s.executable,
+            readOnlyLegs: s.readOnlyLegs,
+            unverifiedLegs: s.unverifiedLegs,
             estHourlyIncomePerK: `$${s.estHourlyIncomeUsd.toFixed(4)}`,
             rates: s.rates.map(r => ({
                 exchange: r.exchange,
@@ -1149,44 +1315,17 @@ server.tool("arb_scan", "Scan for funding rate arbitrage opportunities across ex
 });
 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 {
-        const timed = async (probe, fn) => {
-            const start = Date.now();
-            try {
-                const r = await fn();
-                return { ok: r.ok, latencyMs: Date.now() - start, status: r.status, error: r.ok ? null : `HTTP ${r.status}`, probe };
-            }
-            catch (e) {
-                return { ok: false, latencyMs: Date.now() - start, status: probe === "ping" ? 0 : null, error: extractErrorMessage(e), probe };
-            }
-        };
-        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 health = await probeVenueHealth(MCP_NETWORK);
         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);
+        for (const { venue, ...p } of health.probes)
+            result[venue] = { ...p, statusText: p.ok ? "healthy" : "unreachable" };
+        result.covered = health.probes.map(p => p.venue);
+        // A venue without an environment on the server's network (TxFlow has no testnet) is not probed.
+        result.skipped = health.skipped;
+        // Same two verdicts as `perp health --json`: healthy = every OFFICIAL-API venue is up (an
+        // unofficial API being down does not make perp-cli unhealthy); allHealthy includes them.
+        result.healthy = health.probes.filter(p => p.apiStatus === "official").every(p => p.ok);
+        result.allHealthy = health.allHealthy;
         return { content: [{ type: "text", text: ok(result) }] };
     }
     catch (e) {
@@ -1446,7 +1585,7 @@ function mcpOrderRequest(adapter, p) {
     };
 }
 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)`),
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.roles.includes("trading")).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)"),
@@ -1456,6 +1595,8 @@ server.tool("trade_preview", `Preview a trade WITHOUT executing. Runs trade_exec
     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 {
+        // No trading role (TxFlow, release-gated RISEx) → CAPABILITY_UNSUPPORTED before any credential.
+        requireCapabilities(getVenue(exchange));
         const adapter = await getOrCreateAdapter(exchange);
         const sym = symbol.toUpperCase();
         const isLimit = orderType === "limit";
@@ -1570,9 +1711,9 @@ server.tool("trade_preview", `Preview a trade WITHOUT executing. Runs trade_exec
 });
 /**
  * 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
+ * pre-existing venues) and return OrderResult + execution. 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).
+ * the venue becomes ORDER_PENDING ("do NOT resubmit").
  */
 async function placeViaV2(adapter, req, what, remediation) {
     const def = getVenue(adapter.name);
@@ -1589,7 +1730,7 @@ async function placeViaV2(adapter, req, what, 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)`),
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.roles.includes("trading")).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)"),
@@ -1602,6 +1743,7 @@ server.tool("trade_execute", `Execute a REAL trade on the server's network (meta
     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");
+        requireCapabilities(getVenue(exchange)); // trading role first, before any credential
         const adapter = await getOrCreateAdapter(exchange);
         const def = getVenue(adapter.name);
         const caps = requireCapabilities(def);
@@ -1722,10 +1864,11 @@ server.tool("trade_execute", `Execute a REAL trade on the server's network (meta
     }
 });
 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)`),
+    exchange: z.string().describe(`Exchange: ${listVenues().filter(v => v.roles.includes("trading")).map(v => v.id).join(", ")} (aliases accepted)`),
     symbol: z.string().describe("Symbol to close (e.g., BTC, ETH)"),
 }, async ({ exchange, symbol }) => {
     try {
+        requireCapabilities(getVenue(exchange)); // trading role first, before any credential
         const adapter = await getOrCreateAdapter(exchange);
         const def = getVenue(adapter.name);
         const caps = requireCapabilities(def);

package/dist/pacifica/client.d.ts

@@ -1,13 +1,23 @@
 import { type Network } from "./constants.js";
-import type { MarketInfo, PriceInfo, Orderbook, Trade, Kline, KlineInterval, AggLevel, AccountInfo, AccountSettings, Position, OrderInfo, MarketOrderParams, LimitOrderParams, StopOrderParams, EditOrderParams, CancelOrderParams, CancelAllOrdersParams, TWAPParams, CancelTWAPParams, TPSLParams, UpdateLeverageParams, WithdrawParams, TransferFundsParams, BatchAction, CreateLakeParams, LakeDepositParams, LakeWithdrawParams } from "./types/index.js";
+import { requireSolanaAddress } from "../exchanges/address.js";
+import type { MarketInfo, PriceInfo, Orderbook, Trade, Kline, KlineInterval, AggLevel, AccountInfo, AccountSettings, Position, OrderInfo, MarketOrderParams, LimitOrderParams, StopOrderParams, EditOrderParams, CancelOrderParams, CancelAllOrdersParams, TWAPParams, CancelTWAPParams, TPSLParams, UpdateLeverageParams, WithdrawParams, TransferFundsParams, BatchAction, BatchActionType, CreateLakeParams, LakeDepositParams, LakeWithdrawParams } from "./types/index.js";
 type SignMessageFn = (message: Uint8Array) => Promise<Uint8Array>;
 /** Per-request timeout of a POST (fetch + body read). */
 export declare const PACIFICA_POST_TIMEOUT_MS = 15000;
+/**
+ * Credits ×10 reserved for one POST /orders/batch. The docs (api/rate-limits "Credit Costs") price
+ * a "Standard request/action" at 1 credit and an "Order cancellation" at 0.5 and say nothing
+ * batch-specific (batch-order page: no cost); every action is individually signed and processed,
+ * so the batch is reserved per ACTION — the conservative reading (over-reserving only throttles
+ * earlier; the venue's ratelimit headers on the response settle the real count).
+ */
+export declare function pacificaBatchCost(types: readonly BatchActionType[]): number;
 export interface PacificaClientConfig {
     network?: Network;
     baseUrl?: string;
     apiKey?: string;
 }
+export { requireSolanaAddress };
 export declare class PacificaClient {
     private baseUrl;
     private apiKey?;
@@ -18,6 +28,10 @@ export declare class PacificaClient {
      * against the agent key. Undefined for master/PK signers.
      */
     private requestAgentWallet?;
+    /** Credit-quota state for this base URL + key tier (rate-limit.ts; process-local): unsigned GETs (IP quota) … */
+    private readonly rate;
+    /** … and signed POSTs (may report the account's quota) kept apart. */
+    private readonly signedRate;
     /** Attach (or clear) the agent wallet used for subsequent signed requests. */
     setRequestAgentWallet(agentWallet?: string): void;
     /** Build a signed POST body, attaching agent_wallet when an agent is the active signer. */
@@ -31,8 +45,12 @@ export declare class PacificaClient {
      * outcome unknown → ORDER_PENDING (sendFailure), never a retryable network error. No connection
      * at all → not sent. A 4xx is the venue's refusal and keeps the plain `POST <path> failed
      * (<status>): <body>` error the adapters map (422 business codes) — except on
-     * DEFINITE_4XX_PATHS, where it is a definite ACTION_REJECTED (429 stays the plain error →
-     * RATE_LIMITED). A fetch timeout (PACIFICA_POST_TIMEOUT_MS) on a write is ORDER_PENDING too;
+     * DEFINITE_4XX_PATHS, where it is a definite ACTION_REJECTED. HTTP 429 → RATE_LIMITED
+     * (details.sent === false, retryAfterMs) — never retried, a write is never resubmitted.
+     * "429 = not executed" is our reading of the docs ("When credits are exhausted, requests return
+     * HTTP 429"), not an explicit Pacifica statement. Before sending, the credit throttle may wait up
+     * to PACIFICA_SIGNED_MAX_WAIT_MS (the body is already signed) or fail fast with RATE_LIMITED
+     * (nothing sent). A write needs only its own cost, never the read reserve. A fetch timeout (PACIFICA_POST_TIMEOUT_MS) on a write is ORDER_PENDING too;
    * on a listing read a timeout is TIMEOUT and any other transport failure EXCHANGE_UNREACHABLE.
      */
     private post;
@@ -119,6 +137,27 @@ export declare class PacificaClient {
     createLake(params: CreateLakeParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     depositToLake(params: LakeDepositParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
     withdrawFromLake(params: LakeWithdrawParams, account: string, signMessage: SignMessageFn): Promise<unknown>;
+    /**
+     * Unauthenticated GET that keeps the whole {success, data, has_more, next_cursor} envelope.
+     * Same credit limiter as get() (unsigned IP quota, PACIFICA_READ_NEED: may wait for the window,
+     * else RATE_LIMITED sent:false); the response headers are recorded; HTTP 429 → RATE_LIMITED
+     * (structural, never retried). Timeout → TIMEOUT, transport failure → EXCHANGE_UNREACHABLE,
+     * non-JSON / non-object body → EXCHANGE_ERROR (a read: nothing can have changed).
+     */
+    getEnvelope(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
+    /**
+     * POST a body the caller already built and signed (Print / vault writes sign their own canonical
+     * message so `--dry-run` can show the exact body). Same unknown-outcome rules as every write.
+     */
+    postPresigned(path: "/game/deposit" | "/game/end" | "/lake/deposit" | "/lake/withdraw", body: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Pre-sign credit wait for a pre-signed write (same rule as signedBody / amend): call BEFORE
+     * building + signing, so the post-sign wait in post() (≤ PACIFICA_SIGNED_MAX_WAIT_MS, inside the
+     * 5 s expiry_window) finds credits. Cost: the docs' rate-limits table lists no Print / vault
+     * entry — "Standard request/action: 1 credit" applies (end_game is not an order cancellation).
+     * Fail-fast RATE_LIMITED here sent and signed nothing (details.sent === false).
+     */
+    awaitPresignedCapacity(operationType: string): Promise<void>;
     approveBuilderCode(params: {
         builder_code: string;
         max_fee_rate: string;
@@ -137,6 +176,31 @@ export declare class PacificaClient {
     claimReferralCode(params: {
         code: string;
     }, account: string, signMessage: SignMessageFn): Promise<unknown>;
-    batchOrders(actions: BatchAction[]): Promise<unknown>;
+    /**
+     * POST /orders/batch with the per-action cost (pacificaBatchCost) reserved. `maxWaitMs` caps the
+     * post-sign throttle wait (default PACIFICA_SIGNED_MAX_WAIT_MS, never more): a caller with a
+     * tighter signature deadline passes what is left of it, so a wait can never send an expired batch
+     * — a longer wait fails fast with RATE_LIMITED (sent: false, nothing sent).
+     */
+    batchOrders(actions: BatchAction[], opts?: {
+        maxWaitMs?: number;
+    }): Promise<unknown>;
+    /**
+     * Pre-sign throttle for a batch (like signedBody does for single writes): wait — up to
+     * PACIFICA_MAX_THROTTLE_WAIT_MS, else RATE_LIMITED with nothing signed or sent — until the
+     * batch's whole cost fits, so the post-sign acquire in batchOrders normally finds the credits.
+     */
+    awaitBatchCapacity(types: readonly BatchActionType[]): Promise<void>;
+    /**
+     * One signed batch action body (docs rest-api/orders/batch-order: "Batch orders are not signed
+     * as a whole, but rather by its individual actions components"; each action's `data` carries the
+     * fields of its standalone endpoint, signed with that endpoint's operation type). Nothing is sent.
+     * `header` fixes the signed timestamp / expiry window, so every action of one batch can share
+     * one timestamp. agent_wallet is attached when an agent is the active signer. A signing failure
+     * → ORDER_REJECTED (orderNotSent).
+     */
+    signBatchAction(operationType: string, payload: Record<string, unknown>, account: string, signMessage: SignMessageFn, header: {
+        timestamp: number;
+        expiry_window: number;
+    }): Promise<Record<string, unknown>>;
 }
-export {};