perp-cli 0.3.3

package/dist/dex-asset-map.d.ts

@@ -0,0 +1,80 @@
+/**
+ * HIP-3 Deployed Dex Asset Mapping.
+ *
+ * Maps assets across Hyperliquid deployed dexes to their common underlying.
+ * Assets with the same base name (e.g., xyz:TSLA and flx:TSLA) are auto-matched.
+ * Known aliases (e.g., CL = OIL = crude oil) are explicitly mapped.
+ *
+ * Verified mismatches (NOT the same asset despite similar names):
+ *   USAR ($17) ≠ US500 ($666) ≠ USA500 ($6646)
+ *   SEMI ($319) ≠ SEMIS ($381)
+ *   USOIL ($113) ≠ CL ($93)
+ *   GOLDJM ≠ GOLD (different products)
+ *   SILVERJM ≠ SILVER
+ *   URNM ≠ URANIUM
+ */
+export interface DexAsset {
+    /** Full symbol as returned by API (e.g., "xyz:TSLA") */
+    raw: string;
+    /** Base name without prefix (e.g., "TSLA") */
+    base: string;
+    /** Dex name (e.g., "xyz") or "hl" for native */
+    dex: string;
+    /** Mark price */
+    markPrice: number;
+    /** Raw funding rate */
+    fundingRate: number;
+    /** Max leverage */
+    maxLeverage: number;
+    /** Open interest (USD notional) */
+    openInterest: number;
+    /** 24h volume (USD) */
+    volume24h: number;
+    /** Size decimals for order precision */
+    szDecimals: number;
+}
+export interface DexArbPair {
+    /** Canonical underlying name */
+    underlying: string;
+    /** Long side (lower funding rate) */
+    long: DexAsset;
+    /** Short side (higher funding rate) */
+    short: DexAsset;
+    /** Annualized funding spread % */
+    annualSpread: number;
+    /** Mark price difference % between the two sides */
+    priceGapPct: number;
+    /** Min OI (USD) across both legs — practical cap on position size */
+    minOiUsd: number;
+    /** Min 24h volume (USD) across both legs — liquidity indicator */
+    minVolume24hUsd: number;
+    /** Viability grade: "A" (>$1M OI), "B" (>$100K), "C" (>$10K), "D" (<$10K) */
+    viability: "A" | "B" | "C" | "D";
+}
+/**
+ * Fetch all assets from all Hyperliquid dexes (native + deployed).
+ */
+export declare function fetchAllDexAssets(): Promise<DexAsset[]>;
+/**
+ * Find all cross-dex arb pairs.
+ *
+ * Groups assets by canonical underlying, then finds pairs across different dexes
+ * with a funding rate spread. Validates by checking mark price similarity (< maxGapPct).
+ */
+export declare function findDexArbPairs(assets: DexAsset[], opts?: {
+    /** Max price gap % to consider same underlying (default: 5%) */
+    maxPriceGapPct?: number;
+    /** Min annual spread % to include (default: 0 = all) */
+    minAnnualSpread?: number;
+    /** Include native HL perps in comparison? (default: true) */
+    includeNative?: boolean;
+}): DexArbPair[];
+/**
+ * Fetch and return arb opportunities across all HIP-3 dexes.
+ * Single convenience function for CLI commands.
+ */
+export declare function scanDexArb(opts?: {
+    minAnnualSpread?: number;
+    maxPriceGapPct?: number;
+    includeNative?: boolean;
+}): Promise<DexArbPair[]>;

package/dist/dex-asset-map.js

@@ -0,0 +1,201 @@
+/**
+ * HIP-3 Deployed Dex Asset Mapping.
+ *
+ * Maps assets across Hyperliquid deployed dexes to their common underlying.
+ * Assets with the same base name (e.g., xyz:TSLA and flx:TSLA) are auto-matched.
+ * Known aliases (e.g., CL = OIL = crude oil) are explicitly mapped.
+ *
+ * Verified mismatches (NOT the same asset despite similar names):
+ *   USAR ($17) ≠ US500 ($666) ≠ USA500 ($6646)
+ *   SEMI ($319) ≠ SEMIS ($381)
+ *   USOIL ($113) ≠ CL ($93)
+ *   GOLDJM ≠ GOLD (different products)
+ *   SILVERJM ≠ SILVER
+ *   URNM ≠ URANIUM
+ */
+const HL_INFO_URL = "https://api.hyperliquid.xyz/info";
+/** Known aliases: different symbol → same underlying */
+const ALIASES = {
+    // Crude oil (WTI benchmark)
+    "CL": "CRUDE_OIL_WTI",
+    "OIL": "CRUDE_OIL_WTI",
+    // Meme token denominations
+    "kPEPE": "1000PEPE",
+    "1000PEPE": "1000PEPE",
+    "kSHIB": "1000SHIB",
+    "kBONK": "1000BONK",
+    "kFLOKI": "1000FLOKI",
+    "kLUNC": "1000LUNC",
+    "kNEIRO": "1000NEIRO",
+    "kDOGS": "1000DOGS",
+};
+/** Verified price-mismatch pairs — NEVER match these */
+const BLACKLIST_PAIRS = new Set([
+    "USAR:US500", "USAR:USA500", "US500:USA500",
+    "SEMI:SEMIS",
+    "USOIL:CL", "USOIL:OIL",
+    "GOLDJM:GOLD", "GLDMINE:GOLD",
+    "SILVERJM:SILVER",
+    "URNM:URANIUM",
+    "NUCLEAR:ENERGY", "NUCLEAR:USENERGY",
+]);
+function isBlacklisted(a, b) {
+    const key1 = `${a}:${b}`;
+    const key2 = `${b}:${a}`;
+    return BLACKLIST_PAIRS.has(key1) || BLACKLIST_PAIRS.has(key2);
+}
+async function hlInfoPost(body) {
+    const res = await fetch(HL_INFO_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`HL API error: ${res.status}`);
+    return res.json();
+}
+/**
+ * Fetch all assets from all Hyperliquid dexes (native + deployed).
+ */
+export async function fetchAllDexAssets() {
+    const { withCache, TTL_MARKET } = await import("./cache.js");
+    return withCache("pub:hl:allDexAssets", TTL_MARKET, () => _fetchAllDexAssetsLive());
+}
+async function _fetchAllDexAssetsLive() {
+    const allMetas = await hlInfoPost({ type: "allPerpMetas" });
+    if (!Array.isArray(allMetas))
+        return [];
+    // Collect dex names (index 0 = native "hl", rest = deployed dexes)
+    const dexNames = [];
+    for (let i = 0; i < allMetas.length; i++) {
+        const universe = (allMetas[i].universe ?? []);
+        if (universe.length === 0) {
+            dexNames.push("");
+            continue;
+        }
+        if (i === 0) {
+            dexNames.push("hl");
+            continue;
+        }
+        const first = universe[0].name;
+        const colon = first.indexOf(":");
+        dexNames.push(colon > 0 ? first.slice(0, colon) : `dex-${i}`);
+    }
+    // Fetch metaAndAssetCtxs for each dex in batches of 3 to avoid 429 rate limits
+    const BATCH_SIZE = 3;
+    const allAssets = [];
+    const tasks = dexNames.map((dex, i) => ({ dex, i })).filter(t => t.dex !== "");
+    for (let b = 0; b < tasks.length; b += BATCH_SIZE) {
+        const batch = tasks.slice(b, b + BATCH_SIZE);
+        const results = await Promise.all(batch.map(async ({ dex, i }) => {
+            try {
+                const body = i === 0
+                    ? { type: "metaAndAssetCtxs" }
+                    : { type: "metaAndAssetCtxs", dex };
+                const data = await hlInfoPost(body);
+                const universe = data[0]?.universe ?? [];
+                const ctxs = data[1] ?? [];
+                return universe
+                    .map((asset, j) => {
+                    if (asset.isDelisted)
+                        return null;
+                    const ctx = ctxs[j];
+                    const raw = asset.name;
+                    const colon = raw.indexOf(":");
+                    return {
+                        raw,
+                        base: colon > 0 ? raw.slice(colon + 1) : raw,
+                        dex,
+                        markPrice: Number(ctx?.markPx ?? 0),
+                        fundingRate: Number(ctx?.funding ?? 0),
+                        maxLeverage: asset.maxLeverage,
+                        openInterest: Number(ctx?.openInterest ?? 0),
+                        volume24h: Number(ctx?.dayNtlVlm ?? 0),
+                        szDecimals: asset.szDecimals,
+                    };
+                })
+                    .filter((a) => a !== null && a.markPrice > 0);
+            }
+            catch {
+                return [];
+            }
+        }));
+        allAssets.push(...results.flat());
+    }
+    return allAssets;
+}
+/**
+ * Normalize a base name to its canonical underlying.
+ */
+function toCanonical(base) {
+    return ALIASES[base] ?? base;
+}
+/**
+ * Find all cross-dex arb pairs.
+ *
+ * Groups assets by canonical underlying, then finds pairs across different dexes
+ * with a funding rate spread. Validates by checking mark price similarity (< maxGapPct).
+ */
+export function findDexArbPairs(assets, opts = {}) {
+    const maxGap = opts.maxPriceGapPct ?? 5;
+    const minSpread = opts.minAnnualSpread ?? 0;
+    const includeNative = opts.includeNative ?? true;
+    // Group by canonical underlying
+    const groups = new Map();
+    for (const asset of assets) {
+        if (!includeNative && asset.dex === "hl")
+            continue;
+        const canonical = toCanonical(asset.base);
+        if (!groups.has(canonical))
+            groups.set(canonical, []);
+        groups.get(canonical).push(asset);
+    }
+    const pairs = [];
+    for (const [underlying, group] of groups) {
+        if (group.length < 2)
+            continue;
+        // Compare all combinations of different dexes
+        for (let i = 0; i < group.length; i++) {
+            for (let j = i + 1; j < group.length; j++) {
+                const a = group[i];
+                const b = group[j];
+                if (a.dex === b.dex)
+                    continue; // same dex, skip
+                // Blacklist check
+                if (isBlacklisted(a.base, b.base))
+                    continue;
+                // Price gap validation
+                const avgPrice = (a.markPrice + b.markPrice) / 2;
+                const gapPct = Math.abs(a.markPrice - b.markPrice) / avgPrice * 100;
+                if (gapPct > maxGap)
+                    continue;
+                // All dexes (including HIP-3 deployed) settle funding every 1h
+                const hourlyA = a.fundingRate;
+                const hourlyB = b.fundingRate;
+                const annualSpread = Math.abs(hourlyA - hourlyB) * 8760 * 100;
+                if (annualSpread < minSpread)
+                    continue;
+                // Long the lower-funding side, short the higher-funding side
+                const [long, short] = hourlyA < hourlyB ? [a, b] : [b, a];
+                // Liquidity metrics: OI in USD, min across both legs
+                const longOiUsd = long.openInterest * long.markPrice;
+                const shortOiUsd = short.openInterest * short.markPrice;
+                const minOiUsd = Math.min(longOiUsd, shortOiUsd);
+                const minVolume24hUsd = Math.min(long.volume24h, short.volume24h);
+                const viability = minOiUsd >= 1_000_000 ? "A" :
+                    minOiUsd >= 100_000 ? "B" :
+                        minOiUsd >= 10_000 ? "C" : "D";
+                pairs.push({ underlying, long, short, annualSpread, priceGapPct: gapPct, minOiUsd, minVolume24hUsd, viability });
+            }
+        }
+    }
+    return pairs.sort((a, b) => b.annualSpread - a.annualSpread);
+}
+/**
+ * Fetch and return arb opportunities across all HIP-3 dexes.
+ * Single convenience function for CLI commands.
+ */
+export async function scanDexArb(opts) {
+    const assets = await fetchAllDexAssets();
+    return findDexArbPairs(assets, opts);
+}

package/dist/errors.d.ts

@@ -0,0 +1,109 @@
+/** All structured error codes for the CLI */
+export declare const ERROR_CODES: {
+    readonly INVALID_PARAMS: {
+        readonly code: "INVALID_PARAMS";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly SYMBOL_NOT_FOUND: {
+        readonly code: "SYMBOL_NOT_FOUND";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly ORDER_NOT_FOUND: {
+        readonly code: "ORDER_NOT_FOUND";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly POSITION_NOT_FOUND: {
+        readonly code: "POSITION_NOT_FOUND";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly INSUFFICIENT_BALANCE: {
+        readonly code: "INSUFFICIENT_BALANCE";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly MARGIN_INSUFFICIENT: {
+        readonly code: "MARGIN_INSUFFICIENT";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly SIZE_TOO_SMALL: {
+        readonly code: "SIZE_TOO_SMALL";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly SIZE_TOO_LARGE: {
+        readonly code: "SIZE_TOO_LARGE";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly RISK_VIOLATION: {
+        readonly code: "RISK_VIOLATION";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly DUPLICATE_ORDER: {
+        readonly code: "DUPLICATE_ORDER";
+        readonly status: 409;
+        readonly retryable: false;
+    };
+    readonly EXCHANGE_UNREACHABLE: {
+        readonly code: "EXCHANGE_UNREACHABLE";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly RATE_LIMITED: {
+        readonly code: "RATE_LIMITED";
+        readonly status: 429;
+        readonly retryable: true;
+        readonly retryAfterMs: 1000;
+    };
+    readonly PRICE_STALE: {
+        readonly code: "PRICE_STALE";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly SIGNATURE_FAILED: {
+        readonly code: "SIGNATURE_FAILED";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+    readonly EXCHANGE_ERROR: {
+        readonly code: "EXCHANGE_ERROR";
+        readonly status: 502;
+        readonly retryable: true;
+    };
+    readonly TIMEOUT: {
+        readonly code: "TIMEOUT";
+        readonly status: 504;
+        readonly retryable: true;
+    };
+    readonly UNKNOWN: {
+        readonly code: "UNKNOWN";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+export interface StructuredError {
+    code: ErrorCode;
+    message: string;
+    status: number;
+    retryable: boolean;
+    retryAfterMs?: number;
+    exchange?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Classify an error from any exchange into a structured error code.
+ * Pattern-matches on error messages to detect known error types.
+ */
+export declare function classifyError(err: unknown, exchange?: string): StructuredError;
+/** Custom error class that carries a structured error code */
+export declare class PerpError extends Error {
+    readonly structured: StructuredError;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+}

package/dist/errors.js

@@ -0,0 +1,84 @@
+/** All structured error codes for the CLI */
+export const ERROR_CODES = {
+    // 4xx - Client / user errors
+    INVALID_PARAMS: { code: "INVALID_PARAMS", status: 400, retryable: false },
+    SYMBOL_NOT_FOUND: { code: "SYMBOL_NOT_FOUND", status: 404, retryable: false },
+    ORDER_NOT_FOUND: { code: "ORDER_NOT_FOUND", status: 404, retryable: false },
+    POSITION_NOT_FOUND: { code: "POSITION_NOT_FOUND", status: 404, retryable: false },
+    INSUFFICIENT_BALANCE: { code: "INSUFFICIENT_BALANCE", status: 400, retryable: false },
+    MARGIN_INSUFFICIENT: { code: "MARGIN_INSUFFICIENT", status: 400, retryable: false },
+    SIZE_TOO_SMALL: { code: "SIZE_TOO_SMALL", status: 400, retryable: false },
+    SIZE_TOO_LARGE: { code: "SIZE_TOO_LARGE", status: 400, retryable: false },
+    RISK_VIOLATION: { code: "RISK_VIOLATION", status: 403, retryable: false },
+    DUPLICATE_ORDER: { code: "DUPLICATE_ORDER", status: 409, retryable: false },
+    // 5xx - System / transient errors
+    EXCHANGE_UNREACHABLE: { code: "EXCHANGE_UNREACHABLE", status: 503, retryable: true },
+    RATE_LIMITED: { code: "RATE_LIMITED", status: 429, retryable: true, retryAfterMs: 1000 },
+    PRICE_STALE: { code: "PRICE_STALE", status: 503, retryable: true },
+    SIGNATURE_FAILED: { code: "SIGNATURE_FAILED", status: 500, retryable: false },
+    EXCHANGE_ERROR: { code: "EXCHANGE_ERROR", status: 502, retryable: true },
+    TIMEOUT: { code: "TIMEOUT", status: 504, retryable: true },
+    UNKNOWN: { code: "UNKNOWN", status: 500, retryable: false },
+};
+/**
+ * Classify an error from any exchange into a structured error code.
+ * Pattern-matches on error messages to detect known error types.
+ */
+export function classifyError(err, exchange) {
+    const message = err instanceof Error ? err.message : String(err);
+    const lower = message.toLowerCase();
+    // Margin-specific checks first (before generic "insufficient" catch)
+    if (lower.includes("margin") && (lower.includes("insufficient") || lower.includes("not enough"))) {
+        return { ...ERROR_CODES.MARGIN_INSUFFICIENT, message, exchange };
+    }
+    if (lower.includes("insufficient") || lower.includes("not enough") || lower.includes("balance")) {
+        return { ...ERROR_CODES.INSUFFICIENT_BALANCE, message, exchange };
+    }
+    if (lower.includes("rate limit") || lower.includes("429") || lower.includes("too many request")) {
+        return { ...ERROR_CODES.RATE_LIMITED, message, exchange };
+    }
+    if (lower.includes("econnrefused") || lower.includes("enotfound") || lower.includes("fetch failed") || lower.includes("network")) {
+        return { ...ERROR_CODES.EXCHANGE_UNREACHABLE, message, exchange };
+    }
+    if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("etimedout")) {
+        return { ...ERROR_CODES.TIMEOUT, message, exchange };
+    }
+    if (lower.includes("not found") && (lower.includes("symbol") || lower.includes("market") || lower.includes("asset"))) {
+        return { ...ERROR_CODES.SYMBOL_NOT_FOUND, message, exchange };
+    }
+    if (lower.includes("order") && lower.includes("not found")) {
+        return { ...ERROR_CODES.ORDER_NOT_FOUND, message, exchange };
+    }
+    if (lower.includes("position") && lower.includes("not found")) {
+        return { ...ERROR_CODES.POSITION_NOT_FOUND, message, exchange };
+    }
+    if (lower.includes("too small") || lower.includes("minimum") || lower.includes("below min")) {
+        return { ...ERROR_CODES.SIZE_TOO_SMALL, message, exchange };
+    }
+    if (lower.includes("too large") || lower.includes("maximum") || lower.includes("exceeds max")) {
+        return { ...ERROR_CODES.SIZE_TOO_LARGE, message, exchange };
+    }
+    if (lower.includes("signature") || lower.includes("signing") || lower.includes("sign")) {
+        return { ...ERROR_CODES.SIGNATURE_FAILED, message, exchange };
+    }
+    if (lower.includes("duplicate") || lower.includes("already exists")) {
+        return { ...ERROR_CODES.DUPLICATE_ORDER, message, exchange };
+    }
+    if (lower.includes("risk") || lower.includes("violation")) {
+        return { ...ERROR_CODES.RISK_VIOLATION, message, exchange };
+    }
+    // Default: exchange error if we know the exchange, unknown otherwise
+    if (exchange) {
+        return { ...ERROR_CODES.EXCHANGE_ERROR, message, exchange };
+    }
+    return { ...ERROR_CODES.UNKNOWN, message };
+}
+/** Custom error class that carries a structured error code */
+export class PerpError extends Error {
+    structured;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "PerpError";
+        this.structured = { ...ERROR_CODES[code], message, details };
+    }
+}

package/dist/event-stream.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Unified event streaming for agent consumption.
+ *
+ * Streams normalized account events as NDJSON (one JSON per line).
+ * Uses poll-based diffing for cross-exchange compatibility.
+ */
+import type { ExchangeAdapter } from "./exchanges/interface.js";
+export type EventType = "position_opened" | "position_closed" | "position_updated" | "order_placed" | "order_filled" | "order_cancelled" | "balance_update" | "liquidation_warning" | "margin_call" | "heartbeat" | "error";
+export interface StreamEvent {
+    type: EventType;
+    exchange: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+    riskLevel?: "normal" | "warning" | "critical";
+}
+/**
+ * Start polling-based event stream.
+ * Emits NDJSON events to the provided callback.
+ */
+export declare function startEventStream(adapter: ExchangeAdapter, opts: {
+    intervalMs?: number;
+    liquidationWarningPct?: number;
+    onEvent: (event: StreamEvent) => void;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/event-stream.js

@@ -0,0 +1,168 @@
+/**
+ * Unified event streaming for agent consumption.
+ *
+ * Streams normalized account events as NDJSON (one JSON per line).
+ * Uses poll-based diffing for cross-exchange compatibility.
+ */
+/**
+ * Start polling-based event stream.
+ * Emits NDJSON events to the provided callback.
+ */
+export async function startEventStream(adapter, opts) {
+    const intervalMs = opts.intervalMs ?? 5000;
+    const liqWarnPct = opts.liquidationWarningPct ?? 10; // warn when < 10% from liq price
+    const emit = opts.onEvent;
+    let prevPositions = new Map();
+    let prevOrders = new Map();
+    let prevBalance = null;
+    let cycle = 0;
+    const poll = async () => {
+        cycle++;
+        const ts = new Date().toISOString();
+        try {
+            const [positions, orders, balance] = await Promise.all([
+                adapter.getPositions(),
+                adapter.getOpenOrders(),
+                adapter.getBalance(),
+            ]);
+            // ── Position diffs ──
+            const currentPositions = new Map();
+            for (const p of positions) {
+                currentPositions.set(p.symbol, {
+                    symbol: p.symbol,
+                    side: p.side,
+                    size: p.size,
+                    entryPrice: p.entryPrice,
+                    unrealizedPnl: p.unrealizedPnl,
+                    liquidationPrice: p.liquidationPrice,
+                });
+            }
+            // New positions
+            for (const [sym, pos] of currentPositions) {
+                const prev = prevPositions.get(sym);
+                if (!prev) {
+                    emit({ type: "position_opened", exchange: adapter.name, timestamp: ts, data: { ...pos } });
+                }
+                else if (prev.size !== pos.size || prev.side !== pos.side) {
+                    emit({ type: "position_updated", exchange: adapter.name, timestamp: ts, data: { ...pos, prevSize: prev.size, prevSide: prev.side } });
+                }
+            }
+            // Closed positions
+            for (const [sym, prev] of prevPositions) {
+                if (!currentPositions.has(sym)) {
+                    emit({ type: "position_closed", exchange: adapter.name, timestamp: ts, data: { ...prev } });
+                }
+            }
+            // ── Liquidation warnings ──
+            for (const p of positions) {
+                const mark = Number(p.markPrice);
+                const liq = Number(p.liquidationPrice);
+                if (mark > 0 && liq > 0 && p.liquidationPrice !== "N/A") {
+                    const distancePct = Math.abs(mark - liq) / mark * 100;
+                    if (distancePct < 3) {
+                        emit({
+                            type: "margin_call",
+                            exchange: adapter.name,
+                            timestamp: ts,
+                            riskLevel: "critical",
+                            data: { symbol: p.symbol, side: p.side, markPrice: mark, liquidationPrice: liq, distancePct: +distancePct.toFixed(2) },
+                        });
+                    }
+                    else if (distancePct < liqWarnPct) {
+                        emit({
+                            type: "liquidation_warning",
+                            exchange: adapter.name,
+                            timestamp: ts,
+                            riskLevel: "warning",
+                            data: { symbol: p.symbol, side: p.side, markPrice: mark, liquidationPrice: liq, distancePct: +distancePct.toFixed(2) },
+                        });
+                    }
+                }
+            }
+            prevPositions = currentPositions;
+            // ── Order diffs ──
+            const currentOrders = new Map();
+            for (const o of orders) {
+                currentOrders.set(o.orderId, {
+                    orderId: o.orderId,
+                    symbol: o.symbol,
+                    side: o.side,
+                    price: o.price,
+                    size: o.size,
+                    status: o.status,
+                });
+            }
+            // New orders
+            for (const [id, order] of currentOrders) {
+                if (!prevOrders.has(id)) {
+                    emit({ type: "order_placed", exchange: adapter.name, timestamp: ts, data: { ...order } });
+                }
+            }
+            // Removed orders (filled or cancelled)
+            for (const [id, prev] of prevOrders) {
+                if (!currentOrders.has(id)) {
+                    // Can't distinguish filled vs cancelled from diff alone; mark as filled if position changed
+                    const posChanged = currentPositions.get(prev.symbol)?.size !== prevPositions.get(prev.symbol)?.size;
+                    const type = posChanged ? "order_filled" : "order_cancelled";
+                    emit({ type, exchange: adapter.name, timestamp: ts, data: { ...prev } });
+                }
+            }
+            prevOrders = currentOrders;
+            // ── Balance updates ──
+            if (prevBalance) {
+                const equityDelta = Math.abs(Number(balance.equity) - Number(prevBalance.equity));
+                const availDelta = Math.abs(Number(balance.available) - Number(prevBalance.available));
+                if (equityDelta > 0.01 || availDelta > 0.01) {
+                    emit({
+                        type: "balance_update",
+                        exchange: adapter.name,
+                        timestamp: ts,
+                        data: {
+                            equity: balance.equity,
+                            available: balance.available,
+                            marginUsed: balance.marginUsed,
+                            unrealizedPnl: balance.unrealizedPnl,
+                            prevEquity: prevBalance.equity,
+                            prevAvailable: prevBalance.available,
+                        },
+                    });
+                }
+            }
+            prevBalance = balance;
+            // Heartbeat every 12 cycles (~60s at 5s interval)
+            if (cycle % 12 === 0) {
+                emit({
+                    type: "heartbeat",
+                    exchange: adapter.name,
+                    timestamp: ts,
+                    data: {
+                        cycle,
+                        positions: positions.length,
+                        openOrders: orders.length,
+                        equity: balance.equity,
+                    },
+                });
+            }
+        }
+        catch (err) {
+            emit({
+                type: "error",
+                exchange: adapter.name,
+                timestamp: ts,
+                data: { message: err instanceof Error ? err.message : String(err), cycle },
+            });
+        }
+    };
+    // Initial poll
+    await poll();
+    // Polling loop
+    while (!opts.signal?.aborted) {
+        await new Promise((resolve) => {
+            const timer = setTimeout(resolve, intervalMs);
+            opts.signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+        });
+        if (opts.signal?.aborted)
+            break;
+        await poll();
+    }
+}