perp-cli 0.14.0 → 0.14.1

package/dist/exchanges/ondo/funds.d.ts

@@ -1,5 +1,5 @@
 /**
- * Ondo Perps funding (mainnet only) + withdrawal address book.
+ * Ondo Perps funding (mainnet only). Withdrawals are web-app only (the API cannot withdraw).
  *
  * Deposit = a plain ERC-20 transfer of USDC to the account's own funding address
  * (docs.ondoperps.xyz/funding-ondo-perps, api-reference/integration_guide "Deposit USDC").
@@ -13,12 +13,7 @@
  *   - With a probe amount the transfer is two-step: probe → wait until GET /v1/wallet/deposits
  *     shows it confirmed → remainder. A probe that is not credited within the window stops the
  *     flow (ORDER_PENDING with the probe tx hash); the remainder is NOT sent.
- *
- * Address book: withdrawals go only to addresses on the account's address book. An address is
- * added by signing a SIWE challenge with the account's wallet
- * (POST /v1/auth/erc-4361/address_book/get_challenge → personal_sign → …/complete_challenge).
  */
-import { PerpError } from "../../errors.js";
 import { type TxSigner } from "../../evm-master-tx.js";
 import type { Network } from "../venue-types.js";
 import { type OndoDepositChain } from "../venues/ondo.js";
@@ -98,25 +93,3 @@ export interface OndoDepositResult {
  * remainder is never sent while the probe is uncredited (the ORDER_PENDING carries `sent`).
  */
 export declare function executeOndoDeposit(plan: OndoDepositPlan, sign: TxSigner, readDeposits: () => Promise<unknown>, timing: PollTiming): Promise<OndoDepositResult>;
-/** Withdrawal addresses on the account's address book (GET /v1/wallet/address_book). */
-export declare function ondoAddressBook(client: OndoFundsClient): Promise<string[]>;
-/** Refusal for a withdraw destination that is not on the address book (nothing was sent). */
-export declare function ondoAddressNotOnBook(destination: string, book: readonly string[]): PerpError;
-/** A challenge the master key will sign must be about this address book entry — never an arbitrary message. */
-export declare function assertOndoAddressBookChallenge(message: string, wallet: string, withdrawalAddress: string, restUrl: string): void;
-export interface OndoAddressBookAddResult {
-    address: string;
-    alreadyListed: boolean;
-    listed: boolean;
-    challengeId: string | null;
-}
-/**
- * Add the signing wallet's own address to the address book: get_challenge → personal_sign
- * (EIP-191) with the wallet → complete_challenge. Challenge chainId "1" (enum: 1 | 43114).
- */
-export declare function addOndoAddressBookEntry(client: OndoFundsClient, p: {
-    wallet: string;
-    restUrl: string;
-    label: string | null;
-    signMessage: (message: string) => Promise<string>;
-}): Promise<OndoAddressBookAddResult>;

package/dist/exchanges/ondo/funds.js

@@ -1,5 +1,5 @@
 /**
- * Ondo Perps funding (mainnet only) + withdrawal address book.
+ * Ondo Perps funding (mainnet only). Withdrawals are web-app only (the API cannot withdraw).
  *
  * Deposit = a plain ERC-20 transfer of USDC to the account's own funding address
  * (docs.ondoperps.xyz/funding-ondo-perps, api-reference/integration_guide "Deposit USDC").
@@ -13,12 +13,8 @@
  *   - With a probe amount the transfer is two-step: probe → wait until GET /v1/wallet/deposits
  *     shows it confirmed → remainder. A probe that is not credited within the window stops the
  *     flow (ORDER_PENDING with the probe tx hash); the remainder is NOT sent.
- *
- * Address book: withdrawals go only to addresses on the account's address book. An address is
- * added by signing a SIWE challenge with the account's wallet
- * (POST /v1/auth/erc-4361/address_book/get_challenge → personal_sign → …/complete_challenge).
  */
-import { formatUnits, parseUnits, verifyMessage } from "ethers";
+import { formatUnits, parseUnits } from "ethers";
 import { PerpError } from "../../errors.js";
 import { ERC20, EVM_ADDRESS_RE, assertRpcChainId, erc20Balance, erc20Decimals, evmProvider, sameAddress, sendMasterTx, } from "../../evm-master-tx.js";
 import { unsupported } from "../trading-v2.js";
@@ -200,91 +196,3 @@ export async function executeOndoDeposit(plan, sign, readDeposits, timing) {
     }
     return { transfers, depositAddress: plan.depositAddress };
 }
-// ── Address book ──
-const ADDRESS_BOOK_UI = "add the address in the Ondo Perps web app (Withdraw → address book)";
-/** Withdrawal addresses on the account's address book (GET /v1/wallet/address_book). */
-export async function ondoAddressBook(client) {
-    const res = await client.get("/v1/wallet/address_book", null);
-    if (!Array.isArray(res.addressBook))
-        throw venueError("GET /v1/wallet/address_book returned no addressBook list");
-    return res.addressBook.map(e => {
-        if (typeof e?.withdrawalAddress !== "string")
-            throw venueError("address book entry has no withdrawalAddress");
-        return e.withdrawalAddress;
-    });
-}
-/** Refusal for a withdraw destination that is not on the address book (nothing was sent). */
-export function ondoAddressNotOnBook(destination, book) {
-    return new PerpError("INVALID_PARAMS", `${destination} is not on the Ondo Perps withdrawal address book (${book.length === 0 ? "the book is empty" : `listed: ${book.join(", ")}`}) — nothing was sent`, {
-        exchange: "ondo",
-        remediation: `Ondo only withdraws to address-book entries. An entry is added by signing a SIWE challenge with the account's wallet (api-reference/auth/get-siwe-address-book-challenge + complete). For the master wallet's own address run: perp funds address-book add ondo ${destination} — otherwise ${ADDRESS_BOOK_UI}`,
-    });
-}
-/** A challenge the master key will sign must be about this address book entry — never an arbitrary message. */
-export function assertOndoAddressBookChallenge(message, wallet, withdrawalAddress, restUrl) {
-    const refuse = (why) => {
-        throw new PerpError("POLICY_DENIED", `Ondo address-book challenge refused: ${why}. Nothing was signed.`, {
-            exchange: "ondo", challenge: message.slice(0, 600), remediation: `If this message is expected, ${ADDRESS_BOOK_UI}`,
-        });
-    };
-    if (!message.toLowerCase().includes(withdrawalAddress.toLowerCase()))
-        refuse(`the message does not name the withdrawal address ${withdrawalAddress}`);
-    // The endpoint is POST /v1/auth/erc-4361/address_book/get_challenge — "Get a Sign-In with Ethereum
-    // challenge for adding a withdrawal address" (Ondo REST spec). ERC-4361 shape:
-    // "<domain> wants you to sign in with your Ethereum account:\n<address>\n…". Any other message
-    // is refused: the master key never signs free-form text.
-    const siwe = /^(\S+) wants you to sign in with your Ethereum account:\n(0x[0-9a-fA-F]{40})\n/.exec(message);
-    if (siwe === null)
-        return refuse("the message is not a Sign-In with Ethereum (ERC-4361) message");
-    const venueHost = new URL(restUrl).hostname.split(".").slice(-2).join(".");
-    const domain = siwe[1].replace(/^[a-z]+:\/\//, "").split(":")[0];
-    if (domain !== venueHost && !domain.endsWith(`.${venueHost}`))
-        refuse(`its domain "${siwe[1]}" is not ${venueHost}`);
-    if (!sameAddress(siwe[2], wallet))
-        refuse(`it is addressed to ${siwe[2]}, not the signing wallet ${wallet}`);
-}
-/** A venue refusal of the SIWE address-book endpoints, re-raised with the web-app route. */
-function addressBookAuthError(e, step) {
-    if (!(e instanceof PerpError) || e.structured.code === "ORDER_PENDING")
-        return e;
-    return new PerpError(e.structured.code, `${e.message} — Ondo refused the address-book ${step} with API-key auth`, {
-        ...e.structured.details, exchange: "ondo",
-        remediation: `These endpoints may need a wallet (SIWE/JWT) session instead of an API key: ${ADDRESS_BOOK_UI}`,
-    });
-}
-/**
- * Add the signing wallet's own address to the address book: get_challenge → personal_sign
- * (EIP-191) with the wallet → complete_challenge. Challenge chainId "1" (enum: 1 | 43114).
- */
-export async function addOndoAddressBookEntry(client, p) {
-    const before = await ondoAddressBook(client);
-    if (before.some(a => sameAddress(a, p.wallet)))
-        return { address: p.wallet, alreadyListed: true, listed: true, challengeId: null };
-    let challenge;
-    try {
-        challenge = await client.post("/v1/auth/erc-4361/address_book/get_challenge", {
-            walletAddress: p.wallet, chainId: "1", withdrawalAddress: p.wallet,
-        });
-    }
-    catch (e) {
-        throw addressBookAuthError(e, "challenge");
-    }
-    if (typeof challenge.id !== "string" || typeof challenge.message !== "string" || challenge.message === "") {
-        throw venueError("address_book/get_challenge returned no id / message");
-    }
-    assertOndoAddressBookChallenge(challenge.message, p.wallet, p.wallet, p.restUrl);
-    const signature = await p.signMessage(challenge.message);
-    if (!sameAddress(verifyMessage(challenge.message, signature), p.wallet)) {
-        throw new PerpError("SIGNATURE_FAILED", `The address-book challenge signature does not recover to ${p.wallet} — nothing was submitted`, { exchange: "ondo" });
-    }
-    try {
-        await client.postNoResult("/v1/auth/erc-4361/address_book/complete_challenge", {
-            id: challenge.id, signature, ...(p.label !== null ? { addressLabel: p.label } : {}),
-        });
-    }
-    catch (e) {
-        throw addressBookAuthError(e, "completion");
-    }
-    const after = await ondoAddressBook(client);
-    return { address: p.wallet, alreadyListed: false, listed: after.some(a => sameAddress(a, p.wallet)), challengeId: challenge.id };
-}

package/dist/exchanges/pacifica.d.ts

@@ -375,6 +375,11 @@ export declare class PacificaAdapter implements ExchangeAdapter {
         price: string | null;
     }[]>;
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    /**
+     * Recent orders, newest first (GET /orders/history; PacificaClient.get already unwraps the
+     * `{success, data}` envelope, so the list is the result itself). A non-list or a row without a
+     * readable field → EXCHANGE_ERROR, never an empty list or a placeholder value.
+     */
     getOrderHistory(limit?: number): Promise<ExchangeOrder[]>;
     getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
     getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;

package/dist/exchanges/pacifica.js

@@ -1340,24 +1340,41 @@ export class PacificaAdapter {
             trades: k.n,
         }));
     }
+    /**
+     * Recent orders, newest first (GET /orders/history; PacificaClient.get already unwraps the
+     * `{success, data}` envelope, so the list is the result itself). A non-list or a row without a
+     * readable field → EXCHANGE_ERROR, never an empty list or a placeholder value.
+     */
     async getOrderHistory(limit = 30) {
         if (!this._hasRealKey)
             throw new Error("No private key configured — account data unavailable. Run: perp setup");
-        const result = await this.client.getOrderHistory(this.account);
-        const data = (result.data ?? result.orders ?? []);
-        if (!Array.isArray(data))
-            return [];
-        return data.slice(0, limit).map((o) => ({
-            orderId: String(o.order_id ?? ""),
-            symbol: String(o.symbol ?? ""),
-            side: String(o.side) === "bid" ? "buy" : "sell",
-            price: String(o.initial_price ?? o.price ?? "0"),
-            size: String(o.amount ?? o.initial_amount ?? ""),
-            filled: String(o.filled_amount ?? "0"),
-            status: String(o.order_status ?? "done"),
-            type: String(o.order_type ?? ""),
-            triggerPrice: Number(o.stop_price) > 0 ? String(o.stop_price) : null,
-        }));
+        const rows = await this.client.getOrderHistory(this.account, { limit });
+        if (!Array.isArray(rows)) {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica /orders/history returned no order list (${JSON.stringify(rows).slice(0, 120)})`, { exchange: "pacifica" });
+        }
+        const field = (o, k) => {
+            const v = o[k];
+            if ((typeof v === "string" && v !== "") || typeof v === "number")
+                return String(v);
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica order-history row without a readable ${k}: ${JSON.stringify(o).slice(0, 160)}`, { exchange: "pacifica" });
+        };
+        return rows.slice(0, limit).map((o) => {
+            const side = field(o, "side");
+            if (side !== "bid" && side !== "ask") {
+                throw new PerpError("EXCHANGE_ERROR", `Pacifica order-history row with unknown side "${side}"`, { exchange: "pacifica" });
+            }
+            return {
+                orderId: field(o, "order_id"),
+                symbol: field(o, "symbol"),
+                side: side === "bid" ? "buy" : "sell",
+                price: field(o, "initial_price"),
+                size: field(o, "amount"),
+                filled: field(o, "filled_amount"),
+                status: field(o, "order_status"),
+                type: field(o, "order_type"),
+                triggerPrice: Number(o.stop_price) > 0 ? String(o.stop_price) : null,
+            };
+        });
     }
     async getTradeHistory(limit = 30) {
         if (!this._hasRealKey)

package/dist/exchanges/qfex/adapter.js

@@ -47,7 +47,7 @@ import { alignProtectionPrice, floorSize, requireOnTick, slippagePrice, subDecim
 import { unsupported, validateLegacyTif, validateOrderRequest } from "../trading-v2.js";
 import { requireCapabilities } from "../venue.js";
 import { parseOrderRef, toLegacyMarketInfo } from "../venue-types.js";
-import { QFEX_BANKER_NETWORK, QFEX_ENDPOINTS } from "../venues/qfex.js";
+import { QFEX_BANKER_NETWORK, QFEX_ENDPOINTS, QFEX_WITHDRAW_DISABLED, QFEX_WITHDRAW_ENABLED } from "../venues/qfex.js";
 import { loadQfexCredentials, QFEX_IMPORT_REMEDIATION } from "./agent.js";
 import { QfexClient } from "./client.js";
 import { qfexStatusClass } from "./errors.js";
@@ -1319,6 +1319,9 @@ export class QfexAdapter {
      * `available_balance` is a different quantity — the venue's own 400 is the answer.
      */
     async withdraw(amount, destination, opts) {
+        if (!QFEX_WITHDRAW_ENABLED) {
+            throw unsupported("QFEX", "withdraw", QFEX_WITHDRAW_DISABLED.reason, QFEX_WITHDRAW_DISABLED.remediation);
+        }
         const meta = this.requireMeta();
         if (opts?.assetId !== undefined || opts?.routeType !== undefined) {
             throw new PerpError("INVALID_PARAMS", "QFEX withdraw takes no assetId/routeType (USDC on Arbitrum One only)");

package/dist/exchanges/venues/ondo.d.ts

@@ -7,11 +7,6 @@
  * Not registered here; the registry module owns registerVenue().
  */
 import type { VenueDefinition } from "../venue.js";
-/**
- * Chain Ondo Perps withdrawals are paid out on (POST /v1/withdraw `network`).
- * The venue settles off-chain (settlementChain "offchain"); USDC leaves on Ethereum.
- */
-export declare const ONDO_WITHDRAW_NETWORK = "ethereum";
 /** Chains the CLI funds an Ondo Perps account from (`funds deposit ondo --chain`). */
 export type OndoDepositChain = "arbitrum" | "ethereum";
 export interface OndoDepositChainPins {

package/dist/exchanges/venues/ondo.js

@@ -16,11 +16,6 @@ const publicData = {
         return (await import("../ondo/public.js")).ondoPublicData.fetchMarkets(net);
     },
 };
-/**
- * Chain Ondo Perps withdrawals are paid out on (POST /v1/withdraw `network`).
- * The venue settles off-chain (settlementChain "offchain"); USDC leaves on Ethereum.
- */
-export const ONDO_WITHDRAW_NETWORK = "ethereum";
 /**
  * PINNED USDC token addresses for Ondo Perps funding (mainnet). Funding is a plain ERC-20
  * transfer of USDC to the account's own funding address (docs.ondoperps.xyz/funding-ondo-perps:
@@ -103,7 +98,8 @@ export const ondoVenue = {
         amend: "cancelReplace",
         batchPlaceMax: 20,
         marginModes: ["cross"],
-        withdrawAssets: ["USDC"],
+        // The API does not allow withdrawals (web app only) — OndoAdapter.withdraw refuses.
+        withdrawAssets: null,
     },
     rateLimit: { capacity: 1, refillPerSec: 1, weights: null },
     // Docs (account-set-up, about): "outside the U.S., Panama and other prohibited

package/dist/exchanges/venues/qfex.d.ts

@@ -23,6 +23,17 @@ export declare const QFEX_ENDPOINTS: Readonly<Record<Network, {
 }>>;
 /** Chain QFEX USDC deposits / withdrawals use in perp-cli (banker network ARBITRUM_ONE). */
 export declare const QFEX_WITHDRAW_NETWORK = "arbitrum";
+/**
+ * API withdrawals are switched off (owner decision 2026-10-13): `funds withdraw qfex` and
+ * QfexAdapter.withdraw refuse with CAPABILITY_UNSUPPORTED. The implementation (banker POST
+ * /withdraw behind settings.withdraw.qfex) is kept; flip this to re-enable it.
+ */
+export declare const QFEX_WITHDRAW_ENABLED: boolean;
+/** The uniform refusal while QFEX_WITHDRAW_ENABLED is false. */
+export declare const QFEX_WITHDRAW_DISABLED: {
+    readonly reason: "QFEX withdrawals are disabled in perp-cli for now";
+    readonly remediation: "Withdraw from the QFEX web app";
+};
 /** Banker `network` value for QFEX_WITHDRAW_NETWORK. */
 export declare const QFEX_BANKER_NETWORK = "ARBITRUM_ONE";
 export declare const qfexVenue: VenueDefinition;

package/dist/exchanges/venues/qfex.js

@@ -21,6 +21,14 @@ export const QFEX_ENDPOINTS = {
 };
 /** Chain QFEX USDC deposits / withdrawals use in perp-cli (banker network ARBITRUM_ONE). */
 export const QFEX_WITHDRAW_NETWORK = "arbitrum";
+/**
+ * API withdrawals are switched off (owner decision 2026-10-13): `funds withdraw qfex` and
+ * QfexAdapter.withdraw refuse with CAPABILITY_UNSUPPORTED. The implementation (banker POST
+ * /withdraw behind settings.withdraw.qfex) is kept; flip this to re-enable it.
+ */
+export const QFEX_WITHDRAW_ENABLED = false;
+/** The uniform refusal while QFEX_WITHDRAW_ENABLED is false. */
+export const QFEX_WITHDRAW_DISABLED = { reason: "QFEX withdrawals are disabled in perp-cli for now", remediation: "Withdraw from the QFEX web app" };
 /** Banker `network` value for QFEX_WITHDRAW_NETWORK. */
 export const QFEX_BANKER_NETWORK = "ARBITRUM_ONE";
 /** Lazy: public.ts (and `ws`) is only loaded when market data is actually requested. */
@@ -92,8 +100,8 @@ export const qfexVenue = {
         amend: QFEX_MODIFY_KEEPS_CLIENT_ID === true ? "native" : null,
         batchPlaceMax: null,
         marginModes: ["cross"],
-        // TRON USDT and USD bank rails are out of scope.
-        withdrawAssets: ["USDC"],
+        // TRON USDT and USD bank rails are out of scope. API withdrawals are off (QFEX_WITHDRAW_ENABLED).
+        withdrawAssets: QFEX_WITHDRAW_ENABLED ? ["USDC"] : null,
     },
     // Venue budget: 12,000 weight / 60 s per USER across all connections and keys (general and
     // cancel buckets separate). This process takes 25% (50/s, burst 100); the rest is left to the

package/dist/mcp-server.js

@@ -214,7 +214,7 @@ const HL_SCOPE_NOTE = "Hyperliquid: native perps only (HIP-3 dexes via the CLI -
  */
 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", "ondo", "arcus", "qfex"];
+export const MCP_WITHDRAW_VENUES = ["pacifica", "hyperliquid", "lighter", "aster", "arcus"];
 // ── MCP Server ──
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../package.json");
@@ -1314,7 +1314,7 @@ 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: "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" },

package/dist/onchain-balances.d.ts

@@ -0,0 +1,40 @@
+export interface OnchainBalance {
+    /** Chain id in perp-cli terms (arbitrum, ethereum, base, bsc, robinhood, solana, …). */
+    chain: string;
+    token: string;
+    kind: "stable" | "native";
+    /** Decimal string; null = the read failed (see `error`). */
+    balance: string | null;
+    /** Stablecoins at $1; native tokens at the Hyperliquid mid; null when unknown. */
+    usdValue: number | null;
+    /** Why the balance read failed (balance null). */
+    error: string | null;
+    /** Why a native token's usdValue is null although its balance was read. */
+    priceError: string | null;
+}
+interface TokenPin {
+    symbol: string;
+    address: string;
+    decimals: number;
+}
+interface EvmChainPin {
+    label: string;
+    chainId: number;
+    rpcUrl: string;
+    native: string;
+    tokens: TokenPin[];
+}
+/** Mainnet EVM chains, in display order. */
+export declare function mainnetEvmChains(): Record<string, EvmChainPin>;
+/** Per-request timeout of every read here: a stuck public RPC becomes a per-row error, not a hang. */
+export declare const ONCHAIN_READ_TIMEOUT_MS = 10000;
+/** Gas token + stablecoins on every EVM chain (mainnet), or Arbitrum Sepolia (testnet). `only` limits the chains. */
+export declare function evmOnchainBalances(address: string, testnet: boolean, only?: readonly string[]): Promise<OnchainBalance[]>;
+/** SOL + USDC / USDT (mainnet) or USDP (devnet) of a Solana address. */
+export declare function solanaOnchainBalances(address: string, testnet: boolean): Promise<OnchainBalance[]>;
+/** Sum of the stablecoin balances that were read (failed reads are excluded and listed in `errors`). */
+export declare function stableTotal(rows: readonly OnchainBalance[]): {
+    usd: number;
+    errors: string[];
+};
+export {};

package/dist/onchain-balances.js

@@ -0,0 +1,173 @@
+/**
+ * On-chain wallet balances (`perp wallet balance`): the gas token plus the USD stablecoins
+ * (USDC / USDT; USDG on Robinhood Chain) on every chain perp-cli moves funds on.
+ *
+ * Token pins come from the registries the fund-movement code already uses (RELAY_CHAINS,
+ * ONDO_DEPOSIT_CHAINS); the two not in them are Tether's Ethereum USDT and Solana USDT
+ * (tether.to/en/supported-protocols). A read that fails is reported per token
+ * (balance null + error) — never shown as 0.
+ */
+import { HYPERLIQUID_API_URL } from "./api/public/urls.js";
+import { ONDO_DEPOSIT_CHAINS } from "./exchanges/venues/ondo.js";
+import { RELAY_CHAINS } from "./relay-swap.js";
+const relayToken = (chain, symbol) => {
+    const a = RELAY_CHAINS[chain]?.assets[symbol];
+    if (a === undefined)
+        throw new Error(`RELAY_CHAINS has no ${symbol} on ${chain}`);
+    return { symbol, address: a.address, decimals: a.decimals };
+};
+const relayRpc = (chain) => {
+    const url = RELAY_CHAINS[chain]?.rpcUrl;
+    if (url === null || url === undefined)
+        throw new Error(`RELAY_CHAINS has no RPC for ${chain}`);
+    return url;
+};
+/** Mainnet EVM chains, in display order. */
+export function mainnetEvmChains() {
+    return {
+        arbitrum: {
+            label: "Arbitrum", chainId: 42161, rpcUrl: relayRpc("arbitrum"), native: "ETH",
+            tokens: [relayToken("arbitrum", "USDC"), relayToken("arbitrum", "USDT")],
+        },
+        ethereum: {
+            label: "Ethereum", chainId: 1, rpcUrl: ONDO_DEPOSIT_CHAINS.ethereum.rpcUrl, native: "ETH",
+            tokens: [
+                { symbol: "USDC", address: ONDO_DEPOSIT_CHAINS.ethereum.usdc, decimals: 6 },
+                { symbol: "USDT", address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", decimals: 6 },
+            ],
+        },
+        base: {
+            label: "Base", chainId: 8453, rpcUrl: relayRpc("base"), native: "ETH",
+            tokens: [relayToken("base", "USDC")],
+        },
+        bsc: {
+            label: "BNB Chain", chainId: 56, rpcUrl: relayRpc("bsc"), native: "BNB",
+            tokens: [relayToken("bsc", "USDT"), relayToken("bsc", "USDC")],
+        },
+        robinhood: {
+            label: "Robinhood Chain", chainId: 4663, rpcUrl: relayRpc("robinhood"), native: "ETH",
+            tokens: [relayToken("robinhood", "USDG")],
+        },
+    };
+}
+const TESTNET_EVM_CHAINS = {
+    "arbitrum-sepolia": {
+        label: "Arbitrum Sepolia", chainId: 421614, rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc", native: "ETH",
+        tokens: [{ symbol: "USDC", address: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", decimals: 6 }],
+    },
+};
+/** Built on use (not at import) so a registry change can only break `wallet balance`, never startup. */
+function solanaPins(testnet) {
+    return testnet
+        ? { rpcUrl: "https://api.devnet.solana.com", tokens: [{ symbol: "USDP", address: "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM", decimals: 6 }] }
+        : {
+            rpcUrl: "https://api.mainnet-beta.solana.com",
+            tokens: [
+                { symbol: "USDC", address: relayToken("solana", "USDC").address, decimals: 6 },
+                { symbol: "USDT", address: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", decimals: 6 },
+            ],
+        };
+}
+/** Per-request timeout of every read here: a stuck public RPC becomes a per-row error, not a hang. */
+export const ONCHAIN_READ_TIMEOUT_MS = 10_000;
+const timedFetch = (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(ONCHAIN_READ_TIMEOUT_MS) });
+const errText = (e) => (e instanceof Error ? e.message : String(e)).slice(0, 160);
+/**
+ * USD mids of the native gas tokens from Hyperliquid allMids. A failed / missing price leaves the
+ * native row's usdValue null and names the reason in `priceError`; balances are unaffected.
+ */
+async function nativePrices() {
+    const px = new Map();
+    try {
+        const res = await timedFetch(HYPERLIQUID_API_URL, {
+            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "allMids" }),
+        });
+        if (!res.ok)
+            return { px, error: `Hyperliquid allMids HTTP ${res.status}` };
+        const mids = await res.json();
+        for (const sym of ["ETH", "BNB", "SOL"]) {
+            const v = Number(mids[sym]);
+            if (typeof mids[sym] === "string" && Number.isFinite(v) && v > 0)
+                px.set(sym, v);
+        }
+        return { px, error: null };
+    }
+    catch (e) {
+        return { px, error: `Hyperliquid allMids: ${errText(e)}` };
+    }
+}
+function row(chain, token, kind, balance, prices, error) {
+    let usdValue = null;
+    let priceError = null;
+    if (balance !== null) {
+        if (kind === "stable")
+            usdValue = Number(balance);
+        else if (prices.px.has(token))
+            usdValue = Number(balance) * prices.px.get(token);
+        else
+            priceError = prices.error ?? `no Hyperliquid mid for ${token}`;
+    }
+    return { chain, token, kind, balance, usdValue, error, priceError };
+}
+async function evmChainBalances(ethers, chain, pin, address, prices) {
+    const req = new ethers.FetchRequest(pin.rpcUrl);
+    req.timeout = ONCHAIN_READ_TIMEOUT_MS;
+    // batchMaxCount 1: one plain JSON-RPC call per read (not every public RPC accepts batches).
+    const provider = new ethers.JsonRpcProvider(req, pin.chainId, { staticNetwork: true, batchMaxCount: 1 });
+    const native = provider.getBalance(address)
+        .then(b => row(chain, pin.native, "native", ethers.formatEther(b), prices, null))
+        .catch(e => row(chain, pin.native, "native", null, prices, errText(e)));
+    const tokens = pin.tokens.map(t => {
+        const c = new ethers.Contract(t.address, ["function balanceOf(address) view returns (uint256)"], provider);
+        return c.balanceOf(address)
+            .then(b => row(chain, t.symbol, "stable", ethers.formatUnits(b, t.decimals), prices, null))
+            .catch(e => row(chain, t.symbol, "stable", null, prices, errText(e)));
+    });
+    return Promise.all([native, ...tokens]);
+}
+/** Gas token + stablecoins on every EVM chain (mainnet), or Arbitrum Sepolia (testnet). `only` limits the chains. */
+export async function evmOnchainBalances(address, testnet, only) {
+    const chains = testnet ? TESTNET_EVM_CHAINS : mainnetEvmChains();
+    const selected = Object.entries(chains).filter(([id]) => only === undefined || only.includes(id));
+    const [{ ethers }, prices] = await Promise.all([import("ethers"), nativePrices()]);
+    return (await Promise.all(selected.map(([id, pin]) => evmChainBalances(ethers, id, pin, address, prices)))).flat();
+}
+/** SOL + USDC / USDT (mainnet) or USDP (devnet) of a Solana address. */
+export async function solanaOnchainBalances(address, testnet) {
+    const { Connection, PublicKey } = await import("@solana/web3.js");
+    const cfg = solanaPins(testnet);
+    const chain = testnet ? "solana-devnet" : "solana";
+    const connection = new Connection(cfg.rpcUrl, { fetch: timedFetch });
+    const owner = new PublicKey(address);
+    const prices = await nativePrices();
+    const sol = connection.getBalance(owner)
+        .then(l => row(chain, "SOL", "native", (l / 1e9).toFixed(9).replace(/\.?0+$/, ""), prices, null))
+        .catch(e => row(chain, "SOL", "native", null, prices, errText(e)));
+    const tokens = cfg.tokens.map(t => connection.getParsedTokenAccountsByOwner(owner, { mint: new PublicKey(t.address) })
+        .then(res => {
+        let raw = 0n;
+        for (const { account } of res.value) {
+            const amount = account.data.parsed?.info?.tokenAmount?.amount;
+            if (typeof amount !== "string")
+                throw new Error(`token account without a raw amount for ${t.symbol}`);
+            raw += BigInt(amount);
+        }
+        const s = raw.toString().padStart(t.decimals + 1, "0");
+        const dec = `${s.slice(0, -t.decimals)}.${s.slice(-t.decimals)}`.replace(/\.?0+$/, "");
+        return row(chain, t.symbol, "stable", dec, prices, null);
+    })
+        .catch(e => row(chain, t.symbol, "stable", null, prices, errText(e))));
+    return Promise.all([sol, ...tokens]);
+}
+/** Sum of the stablecoin balances that were read (failed reads are excluded and listed in `errors`). */
+export function stableTotal(rows) {
+    let usd = 0;
+    const errors = [];
+    for (const r of rows) {
+        if (r.error !== null)
+            errors.push(`${r.chain} ${r.token}: ${r.error}`);
+        else if (r.kind === "stable")
+            usd += Number(r.balance);
+    }
+    return { usd, errors };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster, Lighter RH, Ondo Perps, Arcus",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: "Bash(perp:*), Bash(npx -y perp-cli:*), Bash(bash scripts/preflig
 compatibility: "Requires Node.js 20 or newer and the perp-cli npm package (global install or npx). Network access required for exchange APIs and bridge providers. Mutating commands need a wallet key imported into the OWS vault via 'perp wallet set EXCHANGE' (key on stdin or hidden prompt — never argv). Skill is portable across Claude Code, Claude.ai, Cursor, Codex, and Gemini CLI — no platform-specific features."
 metadata:
   author: hypurrquant
-  version: "0.14.0"
+  version: "0.14.1"
 ---
 
 # perp-cli
@@ -46,7 +46,7 @@ Also bundled under `scripts/`: `preflight.sh`, `arb-monitor.sh`, `funding-analys
 ### Step 1: Verify install + version
 
 ```bash
-perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.0
+perp --version 2>/dev/null || npx -y perp-cli@latest --version   # must be >= 0.14.1
 ```
 
 If it is missing or older, ask the user before installing/upgrading (`npm install -g perp-cli@latest`) — never install on your own. If `perp` is not on PATH, prefix every command with `npx -y perp-cli@latest`.
@@ -94,7 +94,7 @@ Imported keys trade; `funds deposit|withdraw|transfer|bridge`, `wallet manage re
 - Limit GTC / ALO returns `status: accepted, finality: pending` after the ACK; `open` only via `perp --json trade status c:<id> --symbol <S> -e qfex`.
 - `ORDER_PENDING` = outcome unknown: NEVER resubmit; check with the `c:<id>` in the remediation.
 - Funding rates on QFEX are unverified: excluded everywhere unless `perp --json arb scan --rates --include-unverified` (display only).
-- Withdrawals need `settings.withdraw.qfex` (allowlist + limits), which only the user can set in an interactive terminal — an agent cannot set or change it. `perp --json --dry-run funds withdraw qfex <amt> --to <addr>` shows the gate verdict.
+- Withdrawals are disabled in perp-cli for now: `funds withdraw qfex` → `CAPABILITY_UNSUPPORTED` (also under `--dry-run`). Withdraw in the QFEX web app. Ondo Perps has no API withdrawals either.
 
 Venue rules for these: `trade limit` defaults to `--tif GTC` on every venue (arcus maps it to GTT; ondo offers GTC|IOC|ALO; FOK is never emulated → `CAPABILITY_UNSUPPORTED` where not offered); market orders on every venue are bounded by `--slippage-bps <n>` → `settings.slippageBps.<venue>` → `settings.defaultSlippageBps` (shipped default 50). Ondo (US, PA) and Arcus (US, CA, GB) print a one-time restricted-region notice on stderr when used with credentials (warn only, never blocks).
 
@@ -116,6 +116,23 @@ perp --json arb scan --live --interval 60         # continuous monitoring
 
 Common knobs: `--min <pct>`, `--top <n>`, `--hold-days <n>`, `--bridge-cost <usd>`, `--size <usd>`.
 
+#### HIP-3 dexes (part of Hyperliquid, not a separate venue)
+
+HIP-3 dexes are selected on the Hyperliquid venue with the root `--dex <name>` flag; every market / account / trade command works the same way. Same account and wallet as native Hyperliquid perps.
+
+```bash
+perp --json -e hyperliquid market hip3                               # list deployed dexes (name, markets)
+perp --json -e hyperliquid --dex xyz market list                     # markets on dex "xyz"
+perp --json -e hyperliquid --dex xyz market info GOLD                # symbols WITHOUT the "xyz:" prefix
+perp --json -e hyperliquid --dex xyz account positions               # positions on that dex only
+perp --json -e hyperliquid --dex xyz --dry-run trade market GOLD buy 0.01
+```
+
+- `--dex` with any other `-e` venue → `INVALID_PARAMS` (never ignored).
+- A dex symbol without `--dex` (e.g. `-e hyperliquid market mid xyz:GOLD`) → `SYMBOL_NOT_FOUND` with remediation `--dex xyz`; it is never read from the native dex.
+- `portfolio --dexes xyz,…` adds HIP-3 dex balances; builder fees are never attached on HIP-3.
+- MCP tools cover native Hyperliquid perps only — use the CLI for HIP-3.
+
 ### Step 4: Validate before mutating
 
 For arb: