perp-cli 0.15.0 → 0.16.0

package/dist/funding/rates.d.ts

@@ -12,6 +12,7 @@
  */
 import { type HistoricalAverages } from "./history.js";
 import { type VenueDefinition } from "../exchanges/venue.js";
+import type { FundingRateKind } from "../exchanges/interface.js";
 import { type FundingRateBasis, type Network, type VenueId } from "../exchanges/venue-types.js";
 export interface ExchangeFundingRate {
     exchange: VenueId;
@@ -30,27 +31,61 @@ export interface ExchangeFundingRate {
     fundingVerified: boolean;
     /** How the row was read: "unofficial" = an undocumented venue API (VenueDefinition.apiStatus) — may change without notice. */
     apiStatus: "official" | "unofficial";
+    /**
+     * Which rate `fundingRate` is (the venue market row's rate — arb compares those, never a
+     * predicted next-period rate unless the venue only publishes that): "lastSettled" | "accruing" |
+     * "predicted", null = not verified (fundingRateKindOf).
+     */
+    rateKind: FundingRateKind | null;
 }
 export interface SymbolFundingComparison {
     /** Canonical symbol shared by every row. */
     symbol: string;
     rates: ExchangeFundingRate[];
-    maxSpreadAnnual: number;
-    longExchange: string;
-    shortExchange: string;
+    /**
+     * Ranking is over VERIFIED rows only (VenueDefinition.fundingVerified): an unverified row
+     * (`--include-unverified`) is shown in `rates` but is never the long or short leg nor part of
+     * the spread. Fewer than two verified rows → no ranked pair: longExchange / shortExchange /
+     * maxSpreadAnnual / estHourlyIncomeUsd are null (a display-only row).
+     */
+    maxSpreadAnnual: number | null;
+    longExchange: string | null;
+    shortExchange: string | null;
     bestMarkPrice: number;
-    estHourlyIncomeUsd: number;
+    estHourlyIncomeUsd: number | null;
     /**
      * false = a leg of the long/short pair sits on a venue without the trading role (RISEx while its
      * trading is gated in this release): the spread is data only — `arb exec` refuses it.
      */
     executable: boolean;
+    /**
+     * true = the row's rates are of different kinds (e.g. Lighter lastSettled vs Hyperliquid
+     * accruing) — the perp-ws comparator's `mixedKinds`: the spread compares unlike quantities.
+     */
+    mixedKinds: boolean;
     /** Venues of the long/short pair that perp-cli cannot trade (read-only); [] when executable. */
     readOnlyLegs: string[];
+    /**
+     * Venues of the long/short pair whose funding is unverified (VenueDefinition.fundingVerified
+     * false, e.g. QFEX — shown only with --include-unverified, display only); such a pair is never
+     * executable. [] when both legs are verified.
+     */
+    unverifiedLegs: string[];
 }
+/** A comparison with a ranked pair (≥ 2 verified rows): long / short / spread / income are set. */
+export type RankedFundingComparison = SymbolFundingComparison & {
+    maxSpreadAnnual: number;
+    longExchange: string;
+    shortExchange: string;
+    estHourlyIncomeUsd: number;
+};
+export declare function isRankedComparison(c: SymbolFundingComparison): c is RankedFundingComparison;
 export interface FundingRateSnapshot {
     timestamp: string;
     symbols: SymbolFundingComparison[];
+    /** The minSpread applied (annualized %) and how many ranked pairs it hid (spread below it). */
+    minSpread: number;
+    belowMinSpread: number;
     exchangeStatus: Record<string, "ok" | "error">;
     /** Error message per venue whose status is "error". */
     exchangeErrors: Record<string, string>;
@@ -68,6 +103,16 @@ export declare function fetchVenuesRates(venues: VenueDefinition[], net: Network
     exchangeStatus: Record<string, "ok" | "error">;
     exchangeErrors: Record<string, string>;
 }>;
+/**
+ * Same canonical ticker on two venues is not proof of the same asset (e.g. two
+ * unrelated tokens both listed as "PRL"). Within a canonical group, drop any
+ * venue whose mark price deviates more than MAX_PRICE_DEVIATION_PCT from the
+ * group median, with a one-time stderr warning per (symbol, venue).
+ */
+export declare function dropPriceOutliers<T extends {
+    exchange: VenueId;
+    markPrice: number;
+}>(canonical: string, list: T[], tag?: string): T[];
 export interface VenuePrice {
     exchange: VenueId;
     /** Venue display symbol. */
@@ -94,10 +139,14 @@ export declare function fetchCanonicalPriceGroups(venues: VenueDefinition[], opt
     network?: Network;
     tag?: string;
 }): Promise<PriceGroupSnapshot>;
-/** Whether perp-cli can trade both legs of a long/short pair (the trading role), and which it cannot. */
+/**
+ * Whether a long/short pair can be traded as a funding arb: both legs need the trading role AND
+ * verified funding (an unverified-funding venue is display only — never ranked for trading).
+ */
 export declare function pairExecutability(longExchange: string, shortExchange: string): {
     executable: boolean;
     readOnlyLegs: string[];
+    unverifiedLegs: string[];
 };
 /**
  * Fetch funding rates from every market-data venue in parallel, normalize, and compare.

package/dist/funding/rates.js

@@ -14,10 +14,15 @@ import { annualizeHourlyRate, estimateHourlyFundingFromHourly } from "./normaliz
 import { getHistoricalAverages } from "./history.js";
 import { SPOT_PERP_TOKEN_MAP, MAX_PRICE_DEVIATION_PCT } from "../exchanges/index.js";
 import { getVenue, listVenuesWithRole, READ_ONLY_CREDENTIALS } from "../exchanges/venue.js";
-import { rateToHourly } from "../exchanges/venue-types.js";
+import { fundingRateKindOf, rateToHourly } from "../exchanges/venue-types.js";
 import { ensureVenuesRegistered } from "../exchanges/venues/index.js";
 import { sharedApiNetwork } from "../api/public/urls.js";
 import { PerpError } from "../errors.js";
+import { canonicalQuerySymbol } from "../exchanges/canonical-symbols.js";
+export function isRankedComparison(c) {
+    // estHourlyIncomeUsd is set together with the pair (null exactly when the pair is).
+    return c.longExchange !== null && c.shortExchange !== null && c.maxSpreadAnnual !== null;
+}
 // ── Default top symbols to track ──
 export const TOP_SYMBOLS = [
     "BTC", "ETH", "SOL", "DOGE", "SUI", "AVAX", "LINK", "ARB",
@@ -55,13 +60,17 @@ async function fetchVenueRates(def, net) {
     for (const r of rows) {
         if (r.canonical === null)
             continue; // not matchable across venues
+        // Outside its funding hours (QFEX market_hours) a market has no rate: never ranked, snapshotted
+        // (saveFundingSnapshot) or averaged as a 0.
+        if (r.rate === null || r.marketClosed === true)
+            continue;
         const markRaw = r.markPrice !== null ? r.markPrice : markBySymbol?.get(r.venueSymbol);
         const markPrice = markRaw === undefined ? NaN : Number(markRaw);
         if (!Number.isFinite(markPrice) || markPrice <= 0) {
             unpriced.push(r.symbol);
             continue;
         }
-        out.push(toExchangeRate(r, r.canonical, markPrice, def.fundingVerified, def.apiStatus.kind));
+        out.push(toExchangeRate({ ...r, rate: r.rate }, r.canonical, markPrice, def.fundingVerified, def.apiStatus.kind));
     }
     if (unpriced.length > 0) {
         console.warn(`[${def.id}] excluded ${unpriced.length} funding row(s) without a mark price: ${unpriced.join(", ")}`);
@@ -87,6 +96,7 @@ function toExchangeRate(r, canonical, markPrice, fundingVerified, apiStatus) {
         historicalAvg: null,
         fundingVerified,
         apiStatus,
+        rateKind: fundingRateKindOf(r.venue, r.rate),
     };
 }
 /**
@@ -122,7 +132,7 @@ const _warnedPriceMismatch = new Set();
  * venue whose mark price deviates more than MAX_PRICE_DEVIATION_PCT from the
  * group median, with a one-time stderr warning per (symbol, venue).
  */
-function dropPriceOutliers(canonical, list, tag = "funding") {
+export function dropPriceOutliers(canonical, list, tag = "funding") {
     if (list.length < 2)
         return list;
     const sorted = list.map(r => r.markPrice).sort((x, y) => x - y);
@@ -173,7 +183,7 @@ function groupByCanonical(rates, symbols, tag = "funding") {
 export async function fetchCanonicalPriceGroups(venues, opts) {
     ensureVenuesRegistered();
     const net = opts?.network ?? sharedApiNetwork();
-    const settled = await Promise.allSettled(venues.map(v => v.publicData.fetchMarkets(net)));
+    const settled = await Promise.allSettled(venues.map(v => v.publicData.fetchMarkets(net, { funding: false })));
     const exchangeStatus = {};
     const exchangeErrors = {};
     const prices = [];
@@ -196,10 +206,15 @@ export async function fetchCanonicalPriceGroups(venues, opts) {
     });
     return { groups: groupByCanonical(prices, opts?.symbols, opts?.tag ?? "prices"), exchangeStatus, exchangeErrors };
 }
-/** Whether perp-cli can trade both legs of a long/short pair (the trading role), and which it cannot. */
+/**
+ * Whether a long/short pair can be traded as a funding arb: both legs need the trading role AND
+ * verified funding (an unverified-funding venue is display only — never ranked for trading).
+ */
 export function pairExecutability(longExchange, shortExchange) {
-    const readOnlyLegs = [...new Set([longExchange, shortExchange])].filter(v => !getVenue(v).roles.includes("trading"));
-    return { executable: readOnlyLegs.length === 0, readOnlyLegs };
+    const legs = [...new Set([longExchange, shortExchange])];
+    const readOnlyLegs = legs.filter(v => !getVenue(v).roles.includes("trading"));
+    const unverifiedLegs = legs.filter(v => !getVenue(v).fundingVerified);
+    return { executable: readOnlyLegs.length === 0 && unverifiedLegs.length === 0, readOnlyLegs, unverifiedLegs };
 }
 function bestMarkPrice(rates) {
     const rank = (id) => MARK_PRICE_PREFERENCE.indexOf(id);
@@ -226,14 +241,28 @@ export async function fetchAllFundingRates(opts) {
     }
     const comparisons = [];
     const minSpread = opts?.minSpread ?? 0;
+    let belowMinSpread = 0;
     for (const [symbol, rates] of rateMap) {
         // Need at least 2 exchanges to compare
         if (rates.length < 2)
             continue;
         // Sort by hourly rate (ascending)
         rates.sort((a, b) => a.hourlyRate - b.hourlyRate);
-        const lowest = rates[0];
-        const highest = rates[rates.length - 1];
+        // The long / short legs and the spread come from verified rows only: an unverified rate is
+        // display data (--include-unverified), never ranked. < 2 verified rows → a display-only row.
+        const ranked = rates.filter(r => r.fundingVerified);
+        if (ranked.length < 2) {
+            const unverifiedLegs = [...new Set(rates.filter(r => !r.fundingVerified).map(r => r.exchange))];
+            comparisons.push({
+                symbol, rates, maxSpreadAnnual: null, longExchange: null, shortExchange: null,
+                bestMarkPrice: bestMarkPrice(rates), estHourlyIncomeUsd: null,
+                executable: false, readOnlyLegs: [], unverifiedLegs,
+                mixedKinds: new Set(rates.map(r => r.rateKind)).size > 1,
+            });
+            continue;
+        }
+        const lowest = ranked[0];
+        const highest = ranked[ranked.length - 1];
         // The median filter alone lets a 2-venue group through at up to 2 × MAX_PRICE_DEVIATION_PCT
         // apart (each side deviates half the gap): the CHOSEN pair must itself agree on price.
         const pairGapPct = Math.abs(lowest.markPrice - highest.markPrice) / ((lowest.markPrice + highest.markPrice) / 2) * 100;
@@ -246,8 +275,10 @@ export async function fetchAllFundingRates(opts) {
             continue;
         }
         const maxSpreadAnnual = annualizeHourlyRate(highest.hourlyRate - lowest.hourlyRate);
-        if (maxSpreadAnnual < minSpread)
+        if (maxSpreadAnnual < minSpread) {
+            belowMinSpread++;
             continue;
+        }
         // Estimate hourly income for $1000 notional arb
         const notional = 1000;
         const longIncome = estimateHourlyFundingFromHourly(lowest.hourlyRate, notional, "long");
@@ -262,13 +293,16 @@ export async function fetchAllFundingRates(opts) {
             bestMarkPrice: bestMarkPrice(rates),
             estHourlyIncomeUsd,
             ...pairExecutability(lowest.exchange, highest.exchange),
+            mixedKinds: new Set(rates.map(r => r.rateKind)).size > 1,
         });
     }
-    // Sort by spread descending
-    comparisons.sort((a, b) => b.maxSpreadAnnual - a.maxSpreadAnnual);
+    // Sort by spread descending; display-only rows (no ranked pair) last
+    comparisons.sort((a, b) => (b.maxSpreadAnnual ?? -Infinity) - (a.maxSpreadAnnual ?? -Infinity));
     return {
         timestamp: new Date().toISOString(),
         symbols: comparisons,
+        minSpread,
+        belowMinSpread,
         exchangeStatus,
         exchangeErrors,
     };
@@ -277,7 +311,9 @@ export async function fetchAllFundingRates(opts) {
  * Fetch rates for a single (canonical) symbol across all exchanges.
  */
 export async function fetchSymbolFundingRates(symbol, includeUnverified = false) {
-    const snapshot = await fetchAllFundingRates({ symbols: [symbol.toUpperCase()], includeUnverified });
+    // The comparison groups by canonical key: a venue ticker / denomination alias (kPEPE) is
+    // looked up under its canonical symbol (1000PEPE), never as-is.
+    const snapshot = await fetchAllFundingRates({ symbols: [canonicalQuerySymbol(symbol)], includeUnverified });
     return snapshot.symbols[0] ?? null;
 }
 /**

package/dist/liquidity.d.ts

@@ -26,7 +26,9 @@ export declare function computeExecutableSize(levels: [string, string][], reques
  * Check liquidity on both sides for an arb entry.
  * Returns adjusted size or 0 if not viable.
  */
-export declare function checkArbLiquidity(longAdapter: ExchangeAdapter, shortAdapter: ExchangeAdapter, symbol: string, sizeUsd: number, maxSlippagePct?: number, log?: (msg: string) => void): Promise<{
+export declare function checkArbLiquidity(longAdapter: ExchangeAdapter, shortAdapter: ExchangeAdapter, symbol: string, sizeUsd: number, maxSlippagePct?: number, log?: (msg: string) => void, 
+/** The short venue's own symbol when it differs (kPEPE ↔ 1000PEPE); default `symbol`. */
+shortSymbol?: string): Promise<{
     viable: boolean;
     adjustedSizeUsd: number;
     longSlippage: number;

package/dist/liquidity.js

@@ -1,3 +1,4 @@
+import { classifyError } from "./errors.js";
 /**
  * Walk through orderbook levels and compute how much can be filled
  * within the given slippage tolerance.
@@ -63,11 +64,13 @@ export function computeExecutableSize(levels, requestedSizeUsd, maxSlippagePct =
  * Check liquidity on both sides for an arb entry.
  * Returns adjusted size or 0 if not viable.
  */
-export async function checkArbLiquidity(longAdapter, shortAdapter, symbol, sizeUsd, maxSlippagePct = 0.5, log) {
+export async function checkArbLiquidity(longAdapter, shortAdapter, symbol, sizeUsd, maxSlippagePct = 0.5, log, 
+/** The short venue's own symbol when it differs (kPEPE ↔ 1000PEPE); default `symbol`. */
+shortSymbol = symbol) {
     try {
         const [longOB, shortOB] = await Promise.all([
             longAdapter.getOrderbook(symbol),
-            shortAdapter.getOrderbook(symbol),
+            shortAdapter.getOrderbook(shortSymbol),
         ]);
         // For long entry we consume asks, for short entry we consume bids
         const longCheck = computeExecutableSize(longOB.asks, sizeUsd, maxSlippagePct);
@@ -145,8 +148,9 @@ export async function checkSpotPerpLiquidity(spotAdapter, perpAdapter, spotSymbo
             perpSlippage: perpCheck.slippagePct,
         };
     }
-    catch {
-        log?.(`[LIQ] spot-perp ${spotSymbol}: orderbook fetch failed`);
+    catch (e) {
+        const c = classifyError(e);
+        log?.(`[LIQ] spot-perp ${spotSymbol}: orderbook fetch failed (${c.code}: ${c.message})`);
         return { viable: false, adjustedSizeUsd: 0, spotSlippage: 0, perpSlippage: 0 };
     }
 }

package/dist/mcp-pacifica-earn.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { PacificaClient } from "./pacifica/client.js";
+import { PacificaClient, requireSolanaAddress } from "./pacifica/client.js";
 import { fetchPrintGames, fetchPrintHistory, fetchPrintMarket, fetchPrintPositions, findPrintGame, quotePrintOrder } from "./exchanges/pacifica-print.js";
-import { DEPOSIT_WHITELIST_API_STATUS, fetchDepositWhitelist, fetchVaults, findVault, heldShares, withdrawWindowAt } from "./exchanges/pacifica-vaults.js";
+import { DEPOSIT_WHITELIST_API_STATUS, readDepositWhitelist, fetchVaults, findVault, heldShares, withdrawWindowAt } from "./exchanges/pacifica-vaults.js";
 export function registerPacificaEarnMcpTools(server, network, ok, errOf) {
     const client = () => new PacificaClient({ network });
     const run = async (meta, f) => {
@@ -12,7 +12,13 @@ export function registerPacificaEarnMcpTools(server, network, ok, errOf) {
             return { content: [{ type: "text", text: errOf(e, meta) }], isError: true };
         }
     };
-    const address = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/, "base58 Solana address");
+    const address = z.string().refine((v) => { try {
+        requireSolanaAddress(v);
+        return true;
+    }
+    catch {
+        return false;
+    } }, "base58 Solana address (32-byte public key; not an EVM address)");
     server.tool("pacifica_print_products", "Pacifica Print products (read-only): game id (e.g. BTC_24H, BTC_7D, BTC_1M), cycle length in days, max leverage, deposit caps, allowed target distance from mark. Print = a strike order that earns a premium each cycle; while resting it fills / is liquidated only at a cycle checkpoint, after a fill it is an ordinary perp position (continuous liquidation).", {}, async () => run({ exchange: "pacifica" }, async () => fetchPrintGames(client())));
     server.tool("pacifica_print_quote", "Validate a Pacifica Print order and preview it (read-only, nothing signed): notional, size on fill, docs-formula liquidation price (an outer bound — a liquidation was observed earlier in one live case; venue trigger unpublished), max loss (deposit + premiums), lock period. The premium is not quoted (the venue's preview is a signed request). Placing the order is CLI-only: perp -e pacifica print deposit … (supports --dry-run).", {
         game: z.string().describe("Print product, e.g. BTC_24H"),
@@ -46,12 +52,12 @@ export function registerPacificaEarnMcpTools(server, network, ok, errOf) {
         if (vault === undefined)
             return vaults;
         const v = findVault(vaults, vault);
-        const [acct, positions, whitelist] = await Promise.all([c.getAccount(v.address), c.getPositions(v.address), fetchDepositWhitelist(c, v.address).catch(() => null)]);
+        const [acct, positions, whitelist] = await Promise.all([c.getAccount(v.address), c.getPositions(v.address), readDepositWhitelist(c, v.address)]);
         return {
             ...v,
             ...(account !== undefined ? { holding: heldShares(v, account) } : {}),
             live: { accountEquity: acct.account_equity ?? null, availableToWithdraw: acct.available_to_withdraw ?? null, positions: positions.map((p) => ({ symbol: p.symbol, side: p.side, amount: p.amount, entryPrice: p.entry_price })) },
-            depositWhitelist: { apiStatus: DEPOSIT_WHITELIST_API_STATUS, addresses: whitelist },
+            depositWhitelist: { apiStatus: DEPOSIT_WHITELIST_API_STATUS, addresses: whitelist.addresses, error: whitelist.error },
             withdrawWindow: withdrawWindowAt(v.config, Date.now()),
         };
     }));

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, roleUnsupported } 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";
@@ -34,7 +36,9 @@ import { PerpError, classifyError, extractErrorMessage, isDefiniteOrderFailure,
 import { invalidateCache } from "./cache.js";
 import { probeVenueHealth } from "./venue-health.js";
 import { getOptionsVenue, listOptionsVenueIds } from "./exchanges/options-venues.js";
-import { fetchAllFundingRates } from "./funding-rates.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";
@@ -130,15 +134,38 @@ async function tryGetAdapter(exchange) {
 async function fetchMarketsPublic(exchange) {
     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):
- * unofficial-API rows carry venueApi + fundingVerified; unverified-funding rows carry fundingVerified false.
+ * every row carries fundingVerified (true or false — as `perp market list`), unofficial-API rows venueApi.
  */
 function labelMarketRows(exchange, rows) {
     const def = getVenue(exchange);
-    if (def.apiStatus.kind === "unofficial")
-        return rows.map(r => ({ ...r, venueApi: "unofficial", fundingVerified: def.fundingVerified }));
-    return def.fundingVerified ? rows : rows.map(r => ({ ...r, fundingVerified: false }));
+    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,
@@ -261,10 +288,13 @@ server.tool("get_markets", `Get all available perpetual futures markets on an ex
         const adapter = await tryGetAdapter(exchange);
         if (adapter) {
             const markets = labelMarketRows(exchange, await adapter.getMarkets());
-            return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, ...apiMeta(exchange) }) }] };
+            return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, ...apiMeta(exchange), ...fundingWarningMeta(exchange, markets) }) }] };
         }
-        const markets = await fetchMarketsPublic(exchange);
-        return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, source: "public", ...apiMeta(exchange) }) }] };
+        // 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 };
@@ -329,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;
@@ -477,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);
@@ -510,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;
@@ -545,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) }] };
 });
@@ -1198,13 +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,
@@ -1236,6 +1322,9 @@ server.tool("health_check", "Ping every registered venue on the server's network
         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) }] };
     }

package/dist/pacifica/client.d.ts

@@ -1,4 +1,5 @@
 import { type Network } from "./constants.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). */
@@ -16,6 +17,7 @@ export interface PacificaClientConfig {
     baseUrl?: string;
     apiKey?: string;
 }
+export { requireSolanaAddress };
 export declare class PacificaClient {
     private baseUrl;
     private apiKey?;
@@ -202,4 +204,3 @@ export declare class PacificaClient {
         expiry_window: number;
     }): Promise<Record<string, unknown>>;
 }
-export {};

package/dist/pacifica/client.js

@@ -2,6 +2,7 @@ import { getNetworkConfig } from "./constants.js";
 import { buildSignedRequest, buildAgentSignedRequest, signWithWallet } from "./signing.js";
 import { PerpError, extractErrorMessage, orderNotSent, orderOutcomeUnknown, sendFailure } from "../errors.js";
 import { invalidateCache } from "../cache.js";
+import { requireSolanaAddress } from "../exchanges/address.js";
 import { PACIFICA_COST_CANCEL, PACIFICA_COST_STANDARD, PACIFICA_MAX_THROTTLE_WAIT_MS, PACIFICA_READ_NEED, PACIFICA_SIGNED_MAX_WAIT_MS, pacificaRateLimiter, } from "./rate-limit.js";
 /** Per-request timeout of a POST (fetch + body read). */
 export const PACIFICA_POST_TIMEOUT_MS = 15_000;
@@ -38,6 +39,14 @@ function writeNeed(cancel, maxWaitMs) {
 export function pacificaBatchCost(types) {
     return types.reduce((a, t) => a + (t === "Cancel" || t === "CancelStopOrder" ? PACIFICA_COST_CANCEL : PACIFICA_COST_STANDARD), 0);
 }
+/** Query parameters that carry a Solana address (account reads, Print orders, vaults). */
+const ADDRESS_PARAMS = new Set(["account", "game_account", "lake"]);
+export { requireSolanaAddress };
+function checkAddressParams(params) {
+    for (const [k, v] of Object.entries(params ?? {}))
+        if (ADDRESS_PARAMS.has(k) && v !== undefined && v !== null)
+            requireSolanaAddress(v, k);
+}
 export class PacificaClient {
     baseUrl;
     apiKey;
@@ -87,6 +96,7 @@ export class PacificaClient {
         return h;
     }
     async get(path, params) {
+        checkAddressParams(params);
         const url = new URL(`${this.baseUrl}${path}`);
         if (params) {
             Object.entries(params).forEach(([k, v]) => {
@@ -445,6 +455,7 @@ export class PacificaClient {
      * non-JSON / non-object body → EXCHANGE_ERROR (a read: nothing can have changed).
      */
     async getEnvelope(path, params = {}) {
+        checkAddressParams(params);
         const url = new URL(`${this.baseUrl}${path}`);
         for (const [k, v] of Object.entries(params))
             url.searchParams.set(k, v);

package/dist/positions-by-address.d.ts

@@ -0,0 +1,34 @@
+import { type Network, type PublicPosition } from "./exchanges/venue.js";
+export interface AddressPositions {
+    venue: string;
+    positions: PublicPosition[];
+    /** Sub-reads that failed (Hyperliquid HIP-3 dex), keyed "hip3:<dex>". */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    notes: string[];
+    /** One human line per failed sub-read: its rows are unknown, not absent. */
+    warnings: string[];
+}
+export interface AddressPositionsOptions {
+    accountIndex?: number;
+    symbol?: string;
+}
+/** Rows of `symbol` (plain asset; HIP-3 "xyz:GOLD" also matches "GOLD"; "BTC-PERP" matches "BTC"). */
+export declare function filterPositionsBySymbol<T extends {
+    symbol: string;
+}>(rows: T[], symbol: string | undefined): T[];
+export declare function readPositionsByAddress(venue: string, net: Network, address: string, opts?: AddressPositionsOptions): Promise<AddressPositions>;
+export interface AddressPositionsFanOut {
+    venues: Record<string, PublicPosition[]>;
+    /** A venue that failed (`<venue>`) or a failed sub-read of a venue (`<venue>:hip3:<dex>`). */
+    errors: Record<string, {
+        code: string;
+        message: string;
+    }>;
+    notes: Record<string, string[]>;
+    warnings: string[];
+}
+/** Every venue that reads positions by address; a venue that fails (address format included) is an `errors` entry. */
+export declare function readPositionsByAddressAll(net: Network, address: string, opts?: AddressPositionsOptions): Promise<AddressPositionsFanOut>;