perp-cli 0.4.2 → 0.4.9

package/dist/config.js

@@ -3,7 +3,27 @@ import bs58 from "bs58";
 import chalk from "chalk";
 import { resolve } from "path";
 import { existsSync, readFileSync } from "fs";
-export async function loadPrivateKey(exchange, pkOverride) {
+/**
+ * Try to load a private key without throwing if none is found.
+ * Returns null if no key is configured.
+ */
+export async function tryLoadPrivateKey(exchange, pkOverride, walletName) {
+    try {
+        return await loadPrivateKey(exchange, pkOverride, walletName);
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadPrivateKey(exchange, pkOverride, walletName) {
+    // 0. Wallet name override (--wallet flag)
+    if (walletName) {
+        const { getWalletKeyByName } = await import("./commands/wallet.js");
+        const key = getWalletKeyByName(walletName);
+        if (!key)
+            throw new Error(`Wallet "${walletName}" not found. Run: perp wallet list`);
+        return key;
+    }
     // 1. CLI flag
     if (pkOverride)
         return pkOverride;

package/dist/dashboard/ws-feeds.js

@@ -569,7 +569,7 @@ class LighterFeed extends ExchangeWsFeed {
                         liquidationPrice: String(p.liquidation_price || "N/A"),
                         unrealizedPnl: String(p.unrealized_pnl ?? "0"),
                         leverage: Number(p.initial_margin_fraction ?? 0) > 0
-                            ? Math.round(100 / Number(p.initial_margin_fraction))
+                            ? Math.round(10000 / Number(p.initial_margin_fraction))
                             : 1,
                     };
                 });

package/dist/equity-tracker.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Equity Tracker — time-series equity snapshots for PnL analysis.
+ *
+ * Stores snapshots in ~/.perp/equity-history/YYYY-MM.jsonl (monthly files).
+ * Computes daily PnL, Sharpe ratio, max drawdown, win/loss stats.
+ */
+export interface EquitySnapshot {
+    ts: string;
+    exchange: string;
+    equity: number;
+    available: number;
+    marginUsed: number;
+    unrealizedPnl: number;
+    positionCount: number;
+}
+export interface DailyPnl {
+    date: string;
+    exchange: string;
+    startEquity: number;
+    endEquity: number;
+    pnl: number;
+    pnlPct: number;
+}
+export interface PnlMetrics {
+    totalReturn: number;
+    totalReturnPct: number;
+    dailyReturns: DailyPnl[];
+    sharpeRatio: number;
+    maxDrawdown: number;
+    maxDrawdownPct: number;
+    winDays: number;
+    lossDays: number;
+    winRate: number;
+    peakEquity: number;
+    currentDrawdown: number;
+    currentDrawdownPct: number;
+    bestDay: DailyPnl | null;
+    worstDay: DailyPnl | null;
+    avgDailyPnl: number;
+    period: {
+        from: string;
+        to: string;
+        days: number;
+    };
+}
+export declare function saveEquitySnapshot(snap: EquitySnapshot): void;
+export declare function readEquityHistory(opts?: {
+    exchange?: string;
+    since?: Date;
+    until?: Date;
+}): EquitySnapshot[];
+/** Group snapshots by date, take first and last per day for daily PnL. */
+export declare function computeDailyPnl(snapshots: EquitySnapshot[], exchange?: string): DailyPnl[];
+/** Compute comprehensive PnL metrics from equity snapshots. */
+export declare function computePnlMetrics(snapshots: EquitySnapshot[], exchange?: string): PnlMetrics;
+/** Compute weekly PnL from daily PnL data. */
+export declare function aggregateWeekly(daily: DailyPnl[]): DailyPnl[];

package/dist/equity-tracker.js

@@ -0,0 +1,209 @@
+/**
+ * Equity Tracker — time-series equity snapshots for PnL analysis.
+ *
+ * Stores snapshots in ~/.perp/equity-history/YYYY-MM.jsonl (monthly files).
+ * Computes daily PnL, Sharpe ratio, max drawdown, win/loss stats.
+ */
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, appendFileSync, existsSync, readdirSync, readFileSync } from "fs";
+const BASE_DIR = join(homedir(), ".perp", "equity-history");
+// ── Storage ──
+function getFilePath(date) {
+    const ym = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+    return join(BASE_DIR, `${ym}.jsonl`);
+}
+export function saveEquitySnapshot(snap) {
+    mkdirSync(BASE_DIR, { recursive: true });
+    const file = getFilePath(new Date(snap.ts));
+    appendFileSync(file, JSON.stringify(snap) + "\n");
+}
+export function readEquityHistory(opts) {
+    if (!existsSync(BASE_DIR))
+        return [];
+    const files = readdirSync(BASE_DIR)
+        .filter(f => f.endsWith(".jsonl"))
+        .sort();
+    const results = [];
+    for (const file of files) {
+        // Skip files clearly before range by filename (YYYY-MM.jsonl)
+        if (opts?.since) {
+            const ym = file.replace(".jsonl", "");
+            const fileMonth = new Date(ym + "-01");
+            const sinceMonth = new Date(opts.since.getFullYear(), opts.since.getMonth(), 1);
+            if (fileMonth < sinceMonth)
+                continue;
+        }
+        const content = readFileSync(join(BASE_DIR, file), "utf-8");
+        for (const line of content.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const snap = JSON.parse(line);
+                if (opts?.exchange && snap.exchange !== opts.exchange)
+                    continue;
+                const ts = new Date(snap.ts);
+                if (opts?.since && ts < opts.since)
+                    continue;
+                if (opts?.until && ts > opts.until)
+                    continue;
+                results.push(snap);
+            }
+            catch { /* skip malformed lines */ }
+        }
+    }
+    return results;
+}
+// ── Analysis ──
+/** Group snapshots by date, take first and last per day for daily PnL. */
+export function computeDailyPnl(snapshots, exchange) {
+    // If exchange filter provided, apply it
+    const filtered = exchange
+        ? snapshots.filter(s => s.exchange === exchange)
+        : snapshots;
+    // Aggregate across exchanges if no specific exchange requested
+    const byTimestamp = new Map();
+    for (const s of filtered) {
+        const key = s.ts;
+        byTimestamp.set(key, (byTimestamp.get(key) ?? 0) + s.equity);
+    }
+    // Group by date
+    const byDate = new Map();
+    for (const s of filtered) {
+        const date = s.ts.slice(0, 10); // YYYY-MM-DD
+        const eq = exchange ? s.equity : (byTimestamp.get(s.ts) ?? s.equity);
+        const existing = byDate.get(date);
+        if (!existing) {
+            byDate.set(date, { first: { ts: s.ts, eq }, last: { ts: s.ts, eq } });
+        }
+        else {
+            if (s.ts < existing.first.ts)
+                existing.first = { ts: s.ts, eq };
+            if (s.ts > existing.last.ts)
+                existing.last = { ts: s.ts, eq };
+        }
+    }
+    const daily = [];
+    const dates = [...byDate.keys()].sort();
+    for (let i = 0; i < dates.length; i++) {
+        const date = dates[i];
+        const day = byDate.get(date);
+        // Use previous day's end as start, or this day's first if no prev
+        const startEquity = i > 0 ? byDate.get(dates[i - 1]).last.eq : day.first.eq;
+        const endEquity = day.last.eq;
+        const pnl = endEquity - startEquity;
+        const pnlPct = startEquity > 0 ? (pnl / startEquity) * 100 : 0;
+        daily.push({
+            date,
+            exchange: exchange ?? "all",
+            startEquity,
+            endEquity,
+            pnl,
+            pnlPct,
+        });
+    }
+    return daily;
+}
+/** Compute comprehensive PnL metrics from equity snapshots. */
+export function computePnlMetrics(snapshots, exchange) {
+    const daily = computeDailyPnl(snapshots, exchange);
+    if (daily.length === 0) {
+        return {
+            totalReturn: 0, totalReturnPct: 0, dailyReturns: [],
+            sharpeRatio: 0, maxDrawdown: 0, maxDrawdownPct: 0,
+            winDays: 0, lossDays: 0, winRate: 0,
+            peakEquity: 0, currentDrawdown: 0, currentDrawdownPct: 0,
+            bestDay: null, worstDay: null, avgDailyPnl: 0,
+            period: { from: "", to: "", days: 0 },
+        };
+    }
+    const firstEquity = daily[0].startEquity;
+    const lastEquity = daily[daily.length - 1].endEquity;
+    const totalReturn = lastEquity - firstEquity;
+    const totalReturnPct = firstEquity > 0 ? (totalReturn / firstEquity) * 100 : 0;
+    // Win/loss stats
+    const winDays = daily.filter(d => d.pnl > 0).length;
+    const lossDays = daily.filter(d => d.pnl < 0).length;
+    const winRate = daily.length > 0 ? (winDays / daily.length) * 100 : 0;
+    // Best/worst day
+    const bestDay = daily.reduce((a, b) => (b.pnl > a.pnl ? b : a), daily[0]);
+    const worstDay = daily.reduce((a, b) => (b.pnl < a.pnl ? b : a), daily[0]);
+    // Average daily PnL
+    const avgDailyPnl = daily.reduce((sum, d) => sum + d.pnl, 0) / daily.length;
+    // Sharpe ratio (annualized, assuming 365 trading days for crypto)
+    const dailyReturns = daily.map(d => d.pnlPct / 100);
+    const meanReturn = dailyReturns.reduce((s, r) => s + r, 0) / dailyReturns.length;
+    const variance = dailyReturns.reduce((s, r) => s + (r - meanReturn) ** 2, 0) / dailyReturns.length;
+    const stdDev = Math.sqrt(variance);
+    const sharpeRatio = stdDev > 0 ? (meanReturn / stdDev) * Math.sqrt(365) : 0;
+    // Max drawdown
+    let peakEquity = 0;
+    let maxDrawdown = 0;
+    let maxDrawdownPct = 0;
+    for (const d of daily) {
+        if (d.endEquity > peakEquity)
+            peakEquity = d.endEquity;
+        const dd = peakEquity - d.endEquity;
+        const ddPct = peakEquity > 0 ? (dd / peakEquity) * 100 : 0;
+        if (dd > maxDrawdown) {
+            maxDrawdown = dd;
+            maxDrawdownPct = ddPct;
+        }
+    }
+    const currentDrawdown = peakEquity - lastEquity;
+    const currentDrawdownPct = peakEquity > 0 ? (currentDrawdown / peakEquity) * 100 : 0;
+    return {
+        totalReturn,
+        totalReturnPct,
+        dailyReturns: daily,
+        sharpeRatio,
+        maxDrawdown,
+        maxDrawdownPct,
+        winDays,
+        lossDays,
+        winRate,
+        peakEquity,
+        currentDrawdown,
+        currentDrawdownPct,
+        bestDay,
+        worstDay,
+        avgDailyPnl,
+        period: {
+            from: daily[0].date,
+            to: daily[daily.length - 1].date,
+            days: daily.length,
+        },
+    };
+}
+/** Compute weekly PnL from daily PnL data. */
+export function aggregateWeekly(daily) {
+    if (daily.length === 0)
+        return [];
+    const weeks = new Map();
+    for (const d of daily) {
+        // ISO week start (Monday)
+        const dt = new Date(d.date);
+        const day = dt.getDay();
+        const monday = new Date(dt);
+        monday.setDate(dt.getDate() - ((day + 6) % 7));
+        const weekKey = monday.toISOString().slice(0, 10);
+        const existing = weeks.get(weekKey);
+        if (!existing) {
+            weeks.set(weekKey, { start: d, end: d });
+        }
+        else {
+            if (d.date < existing.start.date)
+                existing.start = d;
+            if (d.date > existing.end.date)
+                existing.end = d;
+        }
+    }
+    return [...weeks.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([weekStart, { start, end }]) => ({
+        date: weekStart,
+        exchange: start.exchange,
+        startEquity: start.startEquity,
+        endEquity: end.endEquity,
+        pnl: end.endEquity - start.startEquity,
+        pnlPct: start.startEquity > 0 ? ((end.endEquity - start.startEquity) / start.startEquity) * 100 : 0,
+    }));
+}

package/dist/exchanges/hyperliquid-spot.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Hyperliquid Spot Adapter.
+ *
+ * Uses the same exchange.placeOrder() endpoint as perps — the only difference
+ * is the asset index: spot assets use `10000 + spotIndex`.
+ *
+ * Composes with HyperliquidAdapter for signing and API access.
+ */
+import type { SpotAdapter, SpotMarketInfo, SpotBalance } from "./spot-interface.js";
+import type { HyperliquidAdapter } from "./hyperliquid.js";
+export declare class HyperliquidSpotAdapter implements SpotAdapter {
+    readonly name = "hyperliquid";
+    private _hl;
+    private _spotAssetMap;
+    private _spotAssetReverse;
+    private _spotDecimals;
+    private _initialized;
+    private _cachedMetaCtx;
+    constructor(hlAdapter: HyperliquidAdapter);
+    /** Load spot metadata from the Hyperliquid spot API */
+    init(): Promise<void>;
+    private _loadSpotMeta;
+    getSpotMarkets(): Promise<SpotMarketInfo[]>;
+    getSpotOrderbook(symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getSpotBalances(): Promise<SpotBalance[]>;
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string): Promise<unknown>;
+    spotLimitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
+        tif?: string;
+    }): Promise<unknown>;
+    spotCancelOrder(symbol: string, orderId: string): Promise<unknown>;
+    /**
+     * Transfer USDC between perp and spot accounts.
+     * HL uses separate balances — spot buys require USDC in the spot account.
+     * Uses SDK's transferBetweenSpotAndPerp (userSignedAction, not L1 action).
+     */
+    transferUsdcToSpot(amount: number): Promise<unknown>;
+    transferUsdcToPerp(amount: number): Promise<unknown>;
+    /** Get the spot asset index (without the 10000 offset) */
+    getSpotIndex(base: string): number | undefined;
+    /** Get spot size decimals for a base token */
+    getSpotDecimals(base: string): {
+        size: number;
+        price: number;
+    };
+    /**
+     * Resolve a symbol to its actual spot base token and index.
+     * Handles U-token mapping: "BTC" → "UBTC" (Unit protocol bridged token).
+     * Throws if no mapping found.
+     */
+    private _resolveBase;
+    /**
+     * Get the perp symbol for a spot token.
+     * e.g., "UBTC" → "BTC", "ETH" → "ETH"
+     */
+    getUnderlying(spotBase: string): string;
+    /**
+     * Validate that an order actually filled.
+     * HL API returns status "ok" even for 0-fill IoC orders.
+     * Response shape: { status: "ok", response: { type: "order", data: { statuses: [...] } } }
+     * Each status is one of: { filled: { totalSz, avgPx, oid } }, { resting: { oid } }, { error: "msg" }
+     */
+    private _validateOrderFill;
+    private _rawPlaceSpotOrder;
+    private _signAndSendAction;
+    private _infoPost;
+}

package/dist/exchanges/hyperliquid-spot.js

@@ -0,0 +1,309 @@
+/**
+ * Hyperliquid Spot Adapter.
+ *
+ * Uses the same exchange.placeOrder() endpoint as perps — the only difference
+ * is the asset index: spot assets use `10000 + spotIndex`.
+ *
+ * Composes with HyperliquidAdapter for signing and API access.
+ */
+import { PERP_TO_SPOT_MAP, SPOT_PERP_TOKEN_MAP } from "./spot-interface.js";
+/** HL official price rounding: 5 significant figures, max 8 decimals for spot */
+function hlRoundPrice(px, szDecimals) {
+    const MAX_DECIMALS = 8; // spot uses 8 (perp uses 6)
+    if (px > 100_000)
+        return String(Math.round(px));
+    const sig5 = Number(px.toPrecision(5));
+    const priceDec = Math.max(0, MAX_DECIMALS - szDecimals);
+    return Number(sig5.toFixed(priceDec)).toString();
+}
+/** HL official size rounding */
+function hlRoundSize(sz, szDecimals) {
+    return sz.toFixed(szDecimals);
+}
+export class HyperliquidSpotAdapter {
+    name = "hyperliquid";
+    _hl;
+    _spotAssetMap = new Map(); // "ETH" → spotIndex (not +10000)
+    _spotAssetReverse = new Map(); // spotIndex → "ETH"
+    _spotDecimals = new Map();
+    _initialized = false;
+    _cachedMetaCtx = null;
+    constructor(hlAdapter) {
+        this._hl = hlAdapter;
+    }
+    /** Load spot metadata from the Hyperliquid spot API */
+    async init() {
+        if (this._initialized)
+            return;
+        await this._loadSpotMeta();
+        this._initialized = true;
+    }
+    async _loadSpotMeta() {
+        try {
+            // Single API call — spotMetaAndAssetCtxs includes all data from spotMeta
+            const metaCtx = await this._infoPost({ type: "spotMetaAndAssetCtxs" });
+            if (!metaCtx?.[0]?.universe)
+                return;
+            this._cachedMetaCtx = metaCtx;
+            const meta = metaCtx[0];
+            // Token index → name map
+            const tokenNames = new Map();
+            for (const t of meta.tokens ?? []) {
+                tokenNames.set(t.index, t.name);
+            }
+            // Find USDC token index for filtering
+            const usdcTokenIndex = meta.tokens?.find(t => t.name === "USDC")?.index ?? 0;
+            for (const u of meta.universe) {
+                const baseToken = tokenNames.get(u.tokens[0]) ?? "";
+                if (!baseToken)
+                    continue;
+                const key = baseToken.toUpperCase();
+                const isUsdcPair = u.tokens[1] === usdcTokenIndex;
+                if (this._spotAssetMap.has(key) && !isUsdcPair)
+                    continue;
+                this._spotAssetMap.set(key, u.index);
+                this._spotAssetReverse.set(u.index, key);
+                this._spotDecimals.set(key, {
+                    size: u.szDecimals ?? 2,
+                    price: 6,
+                });
+            }
+        }
+        catch (e) {
+            console.error("[hl-spot] Failed to load spot meta:", e instanceof Error ? e.message : e);
+        }
+    }
+    async getSpotMarkets() {
+        await this.init();
+        try {
+            // Reuse cached metaCtx from init, or fetch fresh if cache expired
+            const metaCtx = this._cachedMetaCtx
+                ?? await this._infoPost({ type: "spotMetaAndAssetCtxs" });
+            if (!metaCtx?.[0]?.universe)
+                return [];
+            const tokenNames = new Map();
+            for (const t of metaCtx[0].tokens ?? []) {
+                tokenNames.set(t.index, t.name);
+            }
+            const ctxs = metaCtx[1] ?? [];
+            const markets = [];
+            for (let i = 0; i < metaCtx[0].universe.length; i++) {
+                const u = metaCtx[0].universe[i];
+                const ctx = ctxs[i] ?? {};
+                const baseToken = tokenNames.get(u.tokens[0]) ?? "";
+                const quoteToken = tokenNames.get(u.tokens[1]) ?? "USDC";
+                if (!baseToken)
+                    continue;
+                markets.push({
+                    symbol: `${baseToken}/USDC`,
+                    baseToken,
+                    quoteToken,
+                    markPrice: String(ctx.markPx ?? ctx.midPx ?? "0"),
+                    volume24h: String(ctx.dayNtlVlm ?? "0"),
+                    sizeDecimals: u.szDecimals ?? 2,
+                    priceDecimals: 6,
+                });
+            }
+            return markets;
+        }
+        catch {
+            return [];
+        }
+    }
+    async getSpotOrderbook(symbol) {
+        await this.init();
+        const { spotIndex } = this._resolveBase(symbol);
+        // HL spot L2 book uses the universe name, which is like "ETH/USDC" internally
+        // But the API takes coin=<name>, where name is from spotMeta universe
+        const book = await this._infoPost({
+            type: "l2Book",
+            coin: `@${spotIndex}`,
+        });
+        const levels = book?.levels ?? [[], []];
+        return {
+            bids: (levels[0] ?? []).map((l) => [
+                String(l.px ?? "0"),
+                String(l.sz ?? "0"),
+            ]),
+            asks: (levels[1] ?? []).map((l) => [
+                String(l.px ?? "0"),
+                String(l.sz ?? "0"),
+            ]),
+        };
+    }
+    async getSpotBalances() {
+        try {
+            const state = await this._hl.client.info.spot.getSpotClearinghouseState(this._hl.address);
+            const balances = state?.balances ?? [];
+            return balances.map((b) => ({
+                token: String(b.coin ?? ""),
+                total: String(b.total ?? "0"),
+                available: String(Number(b.total ?? 0) - Number(b.hold ?? 0)),
+                held: String(b.hold ?? "0"),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    async spotMarketOrder(symbol, side, size) {
+        await this.init();
+        const { base, spotIndex } = this._resolveBase(symbol);
+        const assetIndex = 10000 + spotIndex;
+        // Get mid price for slippage calculation
+        const book = await this.getSpotOrderbook(symbol);
+        const bestAsk = book.asks.length > 0 ? Number(book.asks[0][0]) : 0;
+        const bestBid = book.bids.length > 0 ? Number(book.bids[0][0]) : 0;
+        const midPrice = (bestAsk + bestBid) / 2;
+        if (midPrice <= 0)
+            throw new Error(`Cannot get price for spot ${base}`);
+        // 5% slippage for market orders
+        const slippage = 0.05;
+        const isBuy = side === "buy";
+        const slippagePrice = isBuy ? midPrice * (1 + slippage) : midPrice * (1 - slippage);
+        const dec = this._spotDecimals.get(base);
+        const szDec = dec?.size ?? 2;
+        const result = await this._rawPlaceSpotOrder({
+            assetIndex,
+            isBuy,
+            price: hlRoundPrice(slippagePrice, szDec),
+            size: hlRoundSize(Number(size), szDec),
+            orderType: { limit: { tif: "Ioc" } },
+        });
+        // Validate fill — HL returns status "ok" even for 0-fill IoC orders
+        this._validateOrderFill(result, base, side, size);
+        return result;
+    }
+    async spotLimitOrder(symbol, side, price, size, opts) {
+        await this.init();
+        const { base, spotIndex } = this._resolveBase(symbol);
+        const assetIndex = 10000 + spotIndex;
+        const rawTif = opts?.tif ?? "Gtc";
+        const tifMap = { IOC: "Ioc", GTC: "Gtc", ALO: "Alo" };
+        const tif = tifMap[rawTif.toUpperCase()] ?? rawTif;
+        const dec = this._spotDecimals.get(base);
+        const szDec = dec?.size ?? 2;
+        return this._rawPlaceSpotOrder({
+            assetIndex,
+            isBuy: side === "buy",
+            price: hlRoundPrice(Number(price), szDec),
+            size: hlRoundSize(Number(size), szDec),
+            orderType: { limit: { tif } },
+        });
+    }
+    async spotCancelOrder(symbol, orderId) {
+        await this.init();
+        const { spotIndex } = this._resolveBase(symbol);
+        const assetIndex = 10000 + spotIndex;
+        return this._signAndSendAction({
+            type: "cancel",
+            cancels: [{ a: assetIndex, o: parseInt(orderId) }],
+        });
+    }
+    /**
+     * Transfer USDC between perp and spot accounts.
+     * HL uses separate balances — spot buys require USDC in the spot account.
+     * Uses SDK's transferBetweenSpotAndPerp (userSignedAction, not L1 action).
+     */
+    async transferUsdcToSpot(amount) {
+        return this._hl.client.exchange.transferBetweenSpotAndPerp(amount, false);
+    }
+    async transferUsdcToPerp(amount) {
+        return this._hl.client.exchange.transferBetweenSpotAndPerp(amount, true);
+    }
+    /** Get the spot asset index (without the 10000 offset) */
+    getSpotIndex(base) {
+        return this._spotAssetMap.get(base.toUpperCase());
+    }
+    /** Get spot size decimals for a base token */
+    getSpotDecimals(base) {
+        return this._spotDecimals.get(base.toUpperCase()) ?? { size: 2, price: 6 };
+    }
+    /**
+     * Resolve a symbol to its actual spot base token and index.
+     * Handles U-token mapping: "BTC" → "UBTC" (Unit protocol bridged token).
+     * Throws if no mapping found.
+     */
+    _resolveBase(symbol) {
+        const raw = symbol.split("/")[0].toUpperCase();
+        // 1. Direct match (e.g., "ETH" → ETH spot, or "UBTC" → UBTC spot)
+        const directIndex = this._spotAssetMap.get(raw);
+        if (directIndex !== undefined)
+            return { base: raw, spotIndex: directIndex };
+        // 2. U-token mapping: "BTC" → "UBTC" (perp name → spot token name)
+        const uToken = PERP_TO_SPOT_MAP[raw];
+        if (uToken) {
+            const mappedIndex = this._spotAssetMap.get(uToken);
+            if (mappedIndex !== undefined)
+                return { base: uToken, spotIndex: mappedIndex };
+        }
+        throw new Error(`Unknown HL spot asset: ${raw} (no direct match or U-token mapping)`);
+    }
+    /**
+     * Get the perp symbol for a spot token.
+     * e.g., "UBTC" → "BTC", "ETH" → "ETH"
+     */
+    getUnderlying(spotBase) {
+        const upper = spotBase.toUpperCase();
+        return SPOT_PERP_TOKEN_MAP[upper] ?? upper;
+    }
+    // ── Private helpers ──
+    /**
+     * Validate that an order actually filled.
+     * HL API returns status "ok" even for 0-fill IoC orders.
+     * Response shape: { status: "ok", response: { type: "order", data: { statuses: [...] } } }
+     * Each status is one of: { filled: { totalSz, avgPx, oid } }, { resting: { oid } }, { error: "msg" }
+     */
+    _validateOrderFill(result, base, side, requestedSize) {
+        const r = result;
+        const statuses = r?.response?.data?.statuses;
+        if (!statuses || statuses.length === 0) {
+            throw new Error(`Spot ${side} ${base}: no order status in response`);
+        }
+        const st = statuses[0];
+        if (st.error) {
+            throw new Error(`Spot ${side} ${base}: ${st.error}`);
+        }
+        const filled = st.filled;
+        if (!filled || Number(filled.totalSz ?? 0) === 0) {
+            // Resting or 0-fill → for IoC market orders this means no fill
+            throw new Error(`Spot ${side} ${base}: order not filled (0 of ${requestedSize} ${base}). Check price/liquidity.`);
+        }
+    }
+    async _rawPlaceSpotOrder(opts) {
+        const trimZeros = (s) => {
+            if (!s.includes("."))
+                return s;
+            const n = s.replace(/\.?0+$/, "");
+            return n === "-0" ? "0" : n;
+        };
+        const orderWire = {
+            a: opts.assetIndex,
+            b: opts.isBuy,
+            p: trimZeros(opts.price),
+            s: trimZeros(opts.size),
+            r: false,
+            t: opts.orderType,
+        };
+        const action = {
+            type: "order",
+            orders: [orderWire],
+            grouping: "na",
+        };
+        return this._signAndSendAction(action);
+    }
+    async _signAndSendAction(action) {
+        return this._hl.exchangeAction(action);
+    }
+    async _infoPost(body) {
+        const baseUrl = this._hl.isTestnet
+            ? "https://api.hyperliquid-testnet.xyz"
+            : "https://api.hyperliquid.xyz";
+        const res = await fetch(`${baseUrl}/info`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return res.json();
+    }
+}