hypervibes 0.0.0-stage → 0.4.0

package/dist/gateway/telegram/transport.js

@@ -0,0 +1,96 @@
+import { Bot, GrammyError } from "grammy";
+import { NotificationDeliveryError } from "../../notifications/delivery.js";
+import { chunkText } from "../handlers.js";
+/** Telegram caps one message at 4096 characters. */
+export const TELEGRAM_MESSAGE_MAX_CHARS = 4096;
+/** Validates a bot token with Telegram and returns the bot's own username. */
+export async function fetchBotUsername(token) {
+    const bot = new Bot(token);
+    await bot.init();
+    return bot.botInfo.username;
+}
+/** Uses the existing bot's HTTP API without starting another polling endpoint. */
+export async function sendTelegramNotification(token, chatId, text, signal) {
+    try {
+        const bot = new Bot(token, { client: { timeoutSeconds: 15 } });
+        // grammY's Node declarations use abort-controller's older signal type;
+        // its HTTP client accepts the native signal's standard abort interface.
+        const cancellation = signal;
+        return (await bot.api.sendMessage(chatId, text, { link_preview_options: { is_disabled: true } }, cancellation)).message_id;
+    }
+    catch (error) {
+        if (error instanceof GrammyError) {
+            if (error.error_code === 429)
+                throw new NotificationDeliveryError("Telegram rate limit; retrying", false, (error.parameters.retry_after ?? 1) * 1000);
+            throw new NotificationDeliveryError(`Telegram rejected delivery (${error.error_code})`, error.error_code >= 400 && error.error_code < 500);
+        }
+        throw new NotificationDeliveryError("Telegram is unreachable; retrying");
+    }
+}
+/** One grammY long-polling bot: routes messages and sends on behalf of the bridge. */
+export function grammyEndpoint(token, onMessage, logger) {
+    // Leave room for grammY's default 30-second long poll, but bound its
+    // final, unsignalled offset acknowledgement during stop.
+    const bot = new Bot(token, { client: { timeoutSeconds: 45 } });
+    const lifetime = new AbortController();
+    let polling;
+    let stopping;
+    const cancellation = (signal) => {
+        const combined = signal ? AbortSignal.any([lifetime.signal, signal]) : lifetime.signal;
+        combined.throwIfAborted();
+        // grammY uses abort-controller's older declarations, but accepts native signals.
+        return combined;
+    };
+    bot.on("message", (ctx) => {
+        const text = ctx.msg.text?.trim();
+        const chatId = ctx.chat?.id;
+        if (text && chatId !== undefined)
+            onMessage({ chatId, text, ...(ctx.from?.username ? { fromUsername: ctx.from.username } : {}) });
+    });
+    // One failing update must not stop polling for the whole bot.
+    bot.catch((error) => logger?.warn("Telegram update handling failed", error.error));
+    return {
+        start(onStarted) {
+            if (lifetime.signal.aborted)
+                return Promise.resolve();
+            polling ??= (async () => {
+                try {
+                    // bot.start creates its polling controller only after starting init.
+                    // Initialize explicitly so stop can cancel that first request and retries.
+                    await bot.init(cancellation());
+                    if (lifetime.signal.aborted)
+                        return;
+                    await bot.start({ allowed_updates: ["message"], ...(onStarted ? { onStart: onStarted } : {}) });
+                }
+                catch (error) {
+                    if (!lifetime.signal.aborted)
+                        throw error;
+                }
+            })();
+            return polling;
+        },
+        stop() {
+            stopping ??= (async () => {
+                lifetime.abort();
+                try {
+                    // Keep grammY's final offset acknowledgement: skipping it can replay
+                    // the last delivered update when the next endpoint starts.
+                    await bot.stop();
+                }
+                finally {
+                    // stop does not join start, including its middleware and retry delay.
+                    // grammY's polling-error sleep is not cancellable; this join can wait
+                    // for retry_after even though its HTTP requests have been cancelled.
+                    await polling?.catch(() => undefined);
+                }
+            })();
+            return stopping;
+        },
+        async sendText(chatId, text, signal) {
+            for (const chunk of chunkText(text, TELEGRAM_MESSAGE_MAX_CHARS)) {
+                await bot.api.sendMessage(chatId, chunk, {}, cancellation(signal));
+            }
+        },
+        async sendTyping(chatId, signal) { await bot.api.sendChatAction(chatId, "typing", {}, cancellation(signal)); },
+    };
+}

package/dist/hyperliquid/account-info.js

@@ -0,0 +1,117 @@
+import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { compareDecimals, parseDecimal } from "./decimal.js";
+export function accountModeMessage(mode) {
+    switch (mode) {
+        case "unified": return "";
+        case "unregistered":
+            return "This wallet is not registered with Hyperliquid yet. Register it before setting up a trading signer, approving a builder fee, transferring funds, or creating agents.";
+        case "unsupported":
+            return "HyperVibes currently supports Unified Accounts only. Enable Unified Account in Hyperliquid before transferring or creating agents.";
+        case "unavailable":
+            return "Hyperliquid account mode could not be verified. Transfers are temporarily unavailable.";
+    }
+}
+export function accountModeError(mode) {
+    return mode === "unified" ? null : accountModeMessage(mode);
+}
+function usdcBalance(balances) {
+    const balance = balances.find((entry) => entry.coin.toLowerCase() === "usdc");
+    // A registered account simply not holding USDC is zero, not unavailable.
+    if (!balance)
+        return "0";
+    if (typeof balance.total !== "string")
+        return null;
+    const value = parseDecimal(balance.total);
+    if (!value || value.negative)
+        return null;
+    return balance.total;
+}
+/** Sub-account capacity follows Hyperliquid's volume-based schedule, capped at 50. */
+function subaccountCapacity(cumulativeVolume, existing) {
+    const comparison = compareDecimals(cumulativeVolume, "100000");
+    if (comparison === null)
+        return null;
+    if (comparison < 0)
+        return "0 remaining of 0 total";
+    // One additional account per $100M of volume above the first $100k.
+    const additional = wholeQuotientMinus(cumulativeVolume);
+    const limit = Math.min(10 + additional, 50);
+    const remaining = Math.max(limit - existing, 0);
+    return `${remaining} remaining of ${limit} total`;
+}
+function wholeQuotientMinus(volume) {
+    const separator = volume.indexOf(".");
+    const whole = separator === -1 ? volume : volume.slice(0, separator);
+    const base = BigInt(whole) - 100000n;
+    if (base < 0n)
+        return 0;
+    return Number(base / 100000000n);
+}
+/**
+ * Loads the wallet's main account and owned sub-accounts with their spot USDC
+ * balances, mirroring the legacy application's unified-account checks.
+ */
+export async function loadOwnedTradingAccounts(transport, walletAddress, options = {}) {
+    const mainAddress = walletAddress.toLowerCase();
+    const info = new InfoClient({ transport });
+    const checkMode = options.checkMode ?? true;
+    const [spotState, subaccountsResult, userRole, abstraction] = await Promise.all([
+        info.spotClearinghouseState({ user: mainAddress }).then((state) => ({ ok: true, state }), (error) => ({ ok: false, error })),
+        info.subAccounts({ user: mainAddress }).then((accounts) => ({ ok: true, accounts }), (error) => ({ ok: false, error })),
+        checkMode
+            ? info.userRole({ user: mainAddress }).then((role) => ({ ok: true, role }), (error) => ({ ok: false, error }))
+            : Promise.resolve({ ok: true, role: { role: "user" } }),
+        checkMode
+            ? info.userAbstraction({ user: mainAddress }).then((mode) => ({ ok: true, mode }), (error) => ({ ok: false, error }))
+            : Promise.resolve({ ok: true, mode: "unifiedAccount" }),
+    ]);
+    const mainBalance = spotState.ok ? usdcBalance(spotState.state.balances) : null;
+    const accountMode = userRole.ok && userRole.role.role === "missing"
+        ? "unregistered"
+        : abstraction.ok && abstraction.mode === "unifiedAccount"
+            ? "unified"
+            : abstraction.ok
+                ? "unsupported"
+                : "unavailable";
+    let subaccounts = [];
+    let subaccountLookupError = null;
+    if (subaccountsResult.ok) {
+        subaccounts = (subaccountsResult.accounts ?? [])
+            .filter((account) => account.master.toLowerCase() === mainAddress)
+            .map((account) => ({
+            name: account.name || null,
+            address: account.subAccountUser.toLowerCase(),
+            // Hyperliquid omits spotState entirely for never-funded sub-accounts.
+            balance: usdcBalance(account.spotState?.balances ?? []),
+        }));
+    }
+    else {
+        subaccountLookupError = "Hyperliquid sub-account data is temporarily unavailable.";
+    }
+    const lookupError = accountMode === "unregistered"
+        ? null
+        : spotState.ok || mainBalance !== null
+            ? subaccountLookupError
+            : "Hyperliquid account data is temporarily unavailable.";
+    let subaccountCapacityText = null;
+    if (options.includeCapacity && accountMode === "unified") {
+        try {
+            const rateLimit = await info.userRateLimit({ user: mainAddress });
+            subaccountCapacityText = subaccountCapacity(rateLimit.cumVlm, subaccounts.length);
+        }
+        catch { /* Capacity is advisory; the page still renders without it. */ }
+    }
+    return {
+        mainAddress,
+        mainBalance,
+        subaccounts,
+        subaccountCapacity: subaccountCapacityText,
+        lookupError,
+        accountMode,
+    };
+}
+/** Looks up the current builder-fee maximum for a user, in tenths of a bp. */
+export async function maxBuilderFee(transport, user, builder, signal) {
+    const info = new InfoClient({ transport });
+    return info.maxBuilderFee({ user: user, builder: builder }, signal);
+}

package/dist/hyperliquid/account-status.js

@@ -0,0 +1,64 @@
+import { InfoClient } from "@nktkas/hyperliquid";
+import { dashboardOrders, dashboardPerps, dashboardSpot } from "./agent-dashboard.js";
+function perpetualOrder(coin) { return !coin.startsWith("@") && !coin.includes("/"); }
+/** A bounded-age read of the shared feed, repaired without modifying its state. */
+export async function loadAccountStatus(transport, address, cached, cancellation) {
+    const now = Date.now();
+    const result = {
+        address, scope: "main-dex-perpetuals-and-spot-usdc", observedAt: now, accountAbstraction: null,
+        perpEquity: cached?.perpEquity ?? null, positions: cached?.positions ?? null,
+        spotUsdc: cached?.spotUsdc ?? null, spotUsdcHold: cached?.spotUsdcHold ?? null,
+        orders: cached?.orders?.filter((order) => perpetualOrder(order.coin)) ?? null,
+        sections: {
+            perps: { updatedAt: null, fresh: false, source: "unavailable" },
+            spot: { updatedAt: null, fresh: false, source: "unavailable" },
+            orders: { updatedAt: null, fresh: false, source: "unavailable" },
+            mode: { updatedAt: null, fresh: false, source: "unavailable" },
+        }, errors: [],
+    };
+    if (!address) {
+        result.errors.push("No trading account is assigned to this Agent.");
+        return result;
+    }
+    for (const section of ["perps", "spot", "orders"]) {
+        const state = cached?.live?.sections[section];
+        if (state?.updatedAt !== null && state?.updatedAt !== undefined) {
+            const complete = section === "perps" ? result.perpEquity !== null && result.positions !== null
+                : section === "spot" ? result.spotUsdc !== null && result.spotUsdcHold !== null : result.orders !== null;
+            result.sections[section] = { updatedAt: state.updatedAt, fresh: complete && state.fresh && cached?.live?.status === "connected" && now - state.updatedAt <= 30_000, source: "live" };
+        }
+    }
+    const client = new InfoClient({ transport });
+    const user = address;
+    const signal = AbortSignal.any([AbortSignal.timeout(8_000), ...(cancellation ? [cancellation] : [])]);
+    const errors = {
+        perps: "Perpetual balances and positions are unavailable; any retained values are stale.",
+        spot: "Spot USDC balance and holds are unavailable; any retained values are stale.",
+        orders: "Open perpetual orders are unavailable; any retained values are stale.",
+        mode: "Account mode is unavailable. Do not infer collateral availability from balances or the raw perp summary.",
+    };
+    await Promise.all(["perps", "spot", "orders", "mode"].map(async (section) => {
+        if (result.sections[section].fresh)
+            return;
+        try {
+            if (section === "perps")
+                Object.assign(result, dashboardPerps(await client.clearinghouseState({ user, dex: "" }, signal)));
+            else if (section === "spot")
+                Object.assign(result, dashboardSpot(await client.spotClearinghouseState({ user }, signal)));
+            else if (section === "mode")
+                result.accountAbstraction = await client.userAbstraction({ user }, signal);
+            else {
+                const orders = await client.frontendOpenOrders({ user, dex: "" }, signal);
+                result.orders = dashboardOrders(orders.filter((order) => perpetualOrder(order.coin))).orders;
+            }
+            result.sections[section] = { updatedAt: Date.now(), fresh: true, source: "http" };
+        }
+        catch {
+            if (cancellation?.aborted)
+                throw new Error("Account status request aborted");
+            result.errors.push(errors[section]);
+        }
+    }));
+    result.observedAt = Date.now();
+    return result;
+}

package/dist/hyperliquid/agent-dashboard.js

@@ -0,0 +1,56 @@
+import { InfoClient } from "@nktkas/hyperliquid";
+import { compareDecimals } from "./decimal.js";
+export function dashboardPerps(state) {
+    return {
+        perpEquity: state.marginSummary.accountValue,
+        positions: state.assetPositions.filter(({ position }) => {
+            const size = compareDecimals(position.szi, "0");
+            return size !== null && size !== 0;
+        }).map(({ position: p }) => ({ coin: p.coin, size: p.szi, entryPrice: p.entryPx, unrealizedPnl: p.unrealizedPnl, liquidationPrice: p.liquidationPx, leverage: p.leverage.value })),
+    };
+}
+export function dashboardSpot(state) {
+    const usdc = state.balances.find((balance) => balance.coin === "USDC");
+    return { spotUsdc: usdc?.total ?? "0", spotUsdcHold: usdc ? usdc.hold ?? null : "0" };
+}
+export function dashboardOrders(orders) {
+    const convert = (order) => ({ id: order.oid, coin: order.coin, side: order.side === "B" ? "Buy" : "Sell", size: order.sz, price: order.limitPx, type: order.orderType,
+        ...(Number.isFinite(order.timestamp) ? { timestamp: order.timestamp } : {}),
+        ...(order.isTrigger ? { triggerPrice: order.triggerPx } : {}), ...(order.isPositionTpsl ? { positionTpsl: true } : {}),
+        ...(order.children?.length ? { children: order.children.map(convert) } : {}), });
+    return { orders: orders.map(convert) };
+}
+/** Read-only main-DEX snapshots. No signer, persistence, or trading authority. */
+export async function loadAgentDashboard(transport, address, cancellation) {
+    const result = { address, accountAbstraction: null, fetchedAt: Date.now(), perpEquity: null, spotUsdc: null, positions: null, orders: null, errors: [] };
+    if (!address)
+        return result;
+    const client = new InfoClient({ transport });
+    const user = address;
+    const signal = AbortSignal.any([AbortSignal.timeout(8_000), ...(cancellation ? [cancellation] : [])]);
+    const [perps, spot, orders, mode] = await Promise.allSettled([
+        client.clearinghouseState({ user }, signal),
+        client.spotClearinghouseState({ user }, signal),
+        client.frontendOpenOrders({ user }, signal),
+        client.userAbstraction({ user }, signal),
+    ]);
+    if (perps.status === "fulfilled") {
+        Object.assign(result, dashboardPerps(perps.value));
+    }
+    else
+        result.errors.push("Perpetual balances and positions are temporarily unavailable.");
+    if (spot.status === "fulfilled")
+        Object.assign(result, dashboardSpot(spot.value));
+    else
+        result.errors.push("Spot USDC balance is temporarily unavailable.");
+    if (orders.status === "fulfilled")
+        Object.assign(result, dashboardOrders(orders.value));
+    else
+        result.errors.push("Open orders are temporarily unavailable.");
+    if (mode.status === "fulfilled")
+        result.accountAbstraction = mode.value;
+    else
+        result.errors.push("Account mode is temporarily unavailable; total equity cannot be determined.");
+    result.fetchedAt = Date.now();
+    return result;
+}

package/dist/hyperliquid/chart-contracts.js

@@ -0,0 +1,9 @@
+export const chartIntervals = ["1m", "5m", "15m", "1h", "4h", "1d"];
+export const intervalMillis = { "1m": 60_000, "5m": 300_000, "15m": 900_000, "1h": 3_600_000, "4h": 14_400_000, "1d": 86_400_000 };
+export function isChartInterval(value) { return chartIntervals.some((interval) => interval === value); }
+export function mergeChartCandles(previous, incoming) {
+    const values = new Map(previous.map((candle) => [candle.time, candle]));
+    for (const candle of incoming)
+        values.set(candle.time, candle);
+    return [...values.values()].sort((a, b) => a.time - b.time);
+}

package/dist/hyperliquid/constants.js

@@ -0,0 +1,25 @@
+/** Mainnet-only Hyperliquid constants shared by server code and templates. */
+/** The only builder fee recipient the server accepts and submits. */
+export const BUILDER_RECIPIENT = "0x2ebba955c61116e1c249efb1e39d25cb4a79ea05";
+/** Builder fee limits in whole basis points, stored as tenths of a basis point. */
+export const MIN_BUILDER_FEE_BPS = 1;
+export const MAX_BUILDER_FEE_BPS = 10;
+export const DEFAULT_BUILDER_FEE_BPS = 5;
+export const BUILDER_FEE_BPS_TO_TENTHS = 10;
+/** The maximum builder fee Hyperliquid allows this builder, in tenths of a bp. */
+export const MAX_BUILDER_FEE_TENTHS_OF_BP = MAX_BUILDER_FEE_BPS * BUILDER_FEE_BPS_TO_TENTHS;
+/** The maxFeeRate string that revokes the builder fee approval. */
+export const REVOKED_BUILDER_FEE_RATE = "0.00%";
+/** Name recorded with Hyperliquid for every HyperVibes trading signer. */
+export const USER_API_WALLET_NAME = "HyperVibes";
+/** Arbitrum One: the chain every Hyperliquid action signature must target. */
+export const SIGNATURE_CHAIN_ID = 42_161;
+export const SIGNATURE_CHAIN_HEX = "0xa4b1";
+/** Hyperliquid mainnet API endpoints. */
+export const HYPERLIQUID_API_URL = "https://api.hyperliquid.xyz";
+/** Approvals of trading signers expire on Hyperliquid after 180 days. */
+export const API_WALLET_APPROVAL_MS = 180 * 24 * 60 * 60 * 1000;
+/** `vt-` prefix plus at most 13 characters keeps subaccount names within Hyperliquid's limit. */
+export function agentSubaccountName(displayName) {
+    return `vt-${displayName.trim().slice(0, 13).trimEnd()}`;
+}

package/dist/hyperliquid/crypto.js

@@ -0,0 +1,29 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const NONCE_LENGTH = 12;
+const TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+/** Generates a fresh secp256k1 private key in Hyperliquid's `0x…` hex form. */
+export function generateWalletPrivateKey() {
+    return `0x${randomBytes(KEY_LENGTH).toString("hex")}`;
+}
+/** Encrypts a secret with AES-256-GCM: `nonce ‖ ciphertext ‖ tag`. */
+export function encryptSecret(key, plaintext) {
+    const nonce = randomBytes(NONCE_LENGTH);
+    const cipher = createCipheriv("aes-256-gcm", key.bytes, nonce);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return new Uint8Array(Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]));
+}
+/**
+ * Decrypts an AES-256-GCM secret. Throws on truncation, tampering or a
+ * mismatched key so callers never silently accept corrupted credentials.
+ */
+export function decryptSecret(key, sealed) {
+    if (sealed.length < NONCE_LENGTH + TAG_LENGTH)
+        throw new Error("Encrypted secret is truncated");
+    const decipher = createDecipheriv("aes-256-gcm", key.bytes, sealed.subarray(0, NONCE_LENGTH));
+    decipher.setAuthTag(sealed.subarray(sealed.length - TAG_LENGTH));
+    return Buffer.concat([
+        decipher.update(sealed.subarray(NONCE_LENGTH, sealed.length - TAG_LENGTH)),
+        decipher.final(),
+    ]).toString("utf8");
+}

package/dist/hyperliquid/currency-logo.js

@@ -0,0 +1,7 @@
+/** Spot identifiers are intentionally not resolved by the perpetual logo feature. */
+export function isPerpetualLogoSymbol(symbol) {
+    return symbol.length <= 64 && /^(?:[A-Za-z0-9_-]+:)?[A-Za-z0-9_-]+$/.test(symbol);
+}
+export function currencyLogoUrl(symbol) {
+    return isPerpetualLogoSymbol(symbol) ? `/currency/${encodeURIComponent(symbol)}.svg` : null;
+}

package/dist/hyperliquid/decimal.js

@@ -0,0 +1,98 @@
+/**
+ * Minimal string-decimal helpers for display-only exchange amounts. Values
+ * arriving from Hyperliquid are kept as strings and combined with integer
+ * arithmetic; these are never used for signed amounts or order placement.
+ */
+/** Splits a plain decimal string like `-12.3400`; returns null when malformed. */
+export function parseDecimal(value) {
+    if (!/^-?\d+(?:\.\d+)?$/.test(value) || value.includes("e") || value.includes("E"))
+        return null;
+    const negative = value.startsWith("-");
+    const unsigned = negative ? value.slice(1) : value;
+    const separator = unsigned.indexOf(".");
+    const whole = separator === -1 ? unsigned : unsigned.slice(0, separator);
+    const fraction = separator === -1 ? "" : unsigned.slice(separator + 1);
+    return { negative, whole: BigInt(whole), fraction };
+}
+/** Scales two parsed decimals to a common denominator and returns the parts. */
+function commonScale(left, right) {
+    const scale = Math.max(left.fraction.length, right.fraction.length);
+    const scaleUp = (part) => BigInt(part.negative ? -1 : 1) * (part.whole * 10n ** BigInt(scale) + BigInt(part.fraction.padEnd(scale, "0") || "0"));
+    return { leftScaled: scaleUp(left), rightScaled: scaleUp(right), scale };
+}
+/** Adds two plain decimal strings; returns null when either is malformed. */
+export function addDecimals(left, right) {
+    const parsedLeft = parseDecimal(left);
+    const parsedRight = parseDecimal(right);
+    if (!parsedLeft || !parsedRight)
+        return null;
+    const { leftScaled, rightScaled, scale } = commonScale(parsedLeft, parsedRight);
+    const total = leftScaled + rightScaled;
+    return formatScaled(total, scale);
+}
+function formatScaled(scaled, scale) {
+    const negative = scaled < 0n;
+    const absolute = negative ? -scaled : scaled;
+    const denominator = 10n ** BigInt(scale);
+    const whole = absolute / denominator;
+    const fraction = (absolute % denominator).toString().padStart(scale, "0");
+    const canonical = fraction.replace(/0+$/, "");
+    const body = canonical ? `${whole}.${canonical}` : `${whole}`;
+    return negative && absolute !== 0n ? `-${body}` : body;
+}
+/** Compares two plain decimal strings; null when either is malformed. */
+export function compareDecimals(left, right) {
+    const parsedLeft = parseDecimal(left);
+    const parsedRight = parseDecimal(right);
+    if (!parsedLeft || !parsedRight)
+        return null;
+    const { leftScaled, rightScaled } = commonScale(parsedLeft, parsedRight);
+    return leftScaled === rightScaled ? 0 : leftScaled < rightScaled ? -1 : 1;
+}
+/**
+ * Formats a plain decimal string with fixed precision (4 places by default),
+ * half-up rounding, thousands separators and negatives in parentheses.
+ */
+export function formatMoneyText(value, decimalPlaces = 4) {
+    if (!value)
+        return "-";
+    const parsed = parseDecimal(value);
+    if (!parsed)
+        return "-";
+    // Keep one guard digit for exact half-up rounding at the requested precision.
+    const guard = BigInt(decimalPlaces + 1);
+    const scale = 10n ** guard;
+    const scaled = parsed.whole * scale
+        + BigInt(parsed.fraction.padEnd(Number(guard), "0").slice(0, Number(guard)) || "0");
+    const rounded = (scaled + 5n) / 10n;
+    const denominator = 10n ** BigInt(decimalPlaces);
+    const whole = rounded / denominator;
+    const fraction = (rounded % denominator).toString().padStart(decimalPlaces, "0");
+    const grouped = whole.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const formatted = `${grouped}.${fraction}`;
+    return parsed.negative && rounded !== 0n ? `(${formatted})` : formatted;
+}
+/** Formats an exchange amount for display: exact fraction preserved (padded to
+ * at least 2 decimals), thousands separators on the whole part, and negatives in
+ * parentheses. Never rounds; prices and sizes are exchange-exact. */
+export function formatAmountText(value) {
+    if (!value)
+        return "-";
+    const parsed = parseDecimal(value);
+    if (!parsed)
+        return "-";
+    const fraction = parsed.fraction.length < 2 ? parsed.fraction.padEnd(2, "0") : parsed.fraction;
+    const grouped = parsed.whole.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const body = `${grouped}.${fraction}`;
+    return parsed.negative ? `(${body})` : body;
+}
+/** Splits formatted money into the whole part and optional decimals. */
+export function moneyParts(value) {
+    if (!value)
+        return { whole: "-", decimals: null };
+    const separator = value.indexOf(".");
+    return {
+        whole: separator === -1 ? value : value.slice(0, separator),
+        decimals: separator === -1 ? null : value.slice(separator + 1),
+    };
+}

package/dist/hyperliquid/durable-extension.js

@@ -0,0 +1,39 @@
+import { Type } from "@earendil-works/pi-ai";
+import { createOrderTools, toolResult } from "./orders/order-tools.js";
+import { MarketSnapshotSchema } from "./market-snapshot.js";
+import { defineExtension, defineTool, section } from "@earendil-works/pi-durable";
+const nullable = Type.Union([Type.String(), Type.Null()]);
+const freshness = Type.Object({ updatedAt: Type.Union([Type.Number(), Type.Null()]), fresh: Type.Boolean(), source: Type.Union([Type.Literal("live"), Type.Literal("http"), Type.Literal("unavailable")]) });
+const AccountStatusSchema = Type.Object({
+    address: nullable, scope: Type.Literal("main-dex-perpetuals-and-spot-usdc"), observedAt: Type.Number(),
+    accountAbstraction: Type.Union([Type.Literal("unifiedAccount"), Type.Literal("portfolioMargin"), Type.Literal("disabled"), Type.Literal("default"), Type.Null()]),
+    perpEquity: nullable, spotUsdc: nullable, spotUsdcHold: nullable,
+    positions: Type.Union([Type.Array(Type.Object({ coin: Type.String(), size: Type.String(), entryPrice: Type.String(), unrealizedPnl: Type.String(), liquidationPrice: nullable, leverage: Type.Number() })), Type.Null()]),
+    orders: Type.Union([Type.Array(Type.Object({ id: Type.Number(), coin: Type.String(), side: Type.String(), size: Type.String(), price: Type.String(), type: Type.String() })), Type.Null()]),
+    sections: Type.Object({ perps: freshness, spot: freshness, orders: freshness, mode: freshness }), errors: Type.Array(Type.String()),
+});
+/** Trusted host binding: the model cannot choose an account or supply credentials. */
+export function createHyperliquidExtension(service, userId, agentId, orders) {
+    return defineExtension({
+        name: "hyperliquid",
+        sections: [section("hyperliquid", () => "When get_market_snapshot is selected, fetch fresh data before answering current price/market questions. Report its source and observation time, distinguish mid/mark/oracle from executable quotes, and distinguish this snapshot from older stored research. Missing data is unknown, not zero. Use analyst workers for deeper candle/indicator research, not basic price lookups. Use get_account to read this Agent's assigned Hyperliquid account: main-DEX perpetual positions/orders, spot USDC total and holds, and accountAbstraction (queried for this exact account). Decimal strings preserve exchange precision. Check each section's freshness, timestamps, and errors; null/stale data is not zero or an empty account. In unifiedAccount mode, spot USDC is the single shared balance collateralizing USDC-settled cross-margin perps and used for spot trading; individual perp-DEX balance summaries are not meaningful account equity. In portfolioMargin mode, eligible spot assets and perps share portfolio collateral, but this tool only includes spot USDC, not the whole portfolio. Never conclude the account has zero collateral from perpEquity=0 in either mode. In standard/manual mode, spot and perp balances are separate; do not assume spot USDC automatically collateralizes perps. Do not infer the mode from the application's supported/default mode, or guess if mode lookup failed. Spot total is not available buying power: holds, existing positions, margin requirements, and exposure on other DEXs may constrain it. Do not add spotUsdc and perpEquity into a total in unified/portfolio mode or double-count shared collateral. Report spot USDC explicitly when summarizing the account. Other spot tokens, spot orders, and other DEX positions/orders are outside this view. Order tools place/cancel real orders autonomously on this Agent's assigned account only. Use exact decimal strings and stable unique request_id values. Size is base-asset quantity, not a USDC amount. Main-DEX perps require a minimum order notional of $10 (size × price), in addition to exchange size/tick precision. Check intended notional before submitting; never silently increase the user's intended exposure to satisfy the minimum. Exchange validation is authoritative, including any reduce-only/closing exceptions; do not assume an exception or retry a rejected order unchanged. Reuse the same ID and identical arguments after an interruption; never use a new ID to retry an unknown outcome. Query get_order_request/get_order to reconcile. Unknown/not-found is not rejection or cancellation. Inspect every leg: accepted is not filled; a rejected TP/SL can leave exposure unprotected. Market entries are 0.5%-guarded IOC and can partially fill. Native attached TP/SL activates only on full parent fill (or certain venue margin-cancel paths); manually canceling a partially filled parent also cancels its protection. Triggers use mark prices; market triggers use a 10% guard and may not fully fill. Standalone triggers are fixed-size reduce-only. Cancel-all can remove protective stops and does not close positions. No transfers, leverage changes, or trading on other accounts/DEXs are exposed. Reference: https://hyperliquid.gitbook.io/hyperliquid-docs/trading/account-abstraction-modes")],
+        tools: [defineTool({
+                name: "get_account",
+                description: "Read this Agent's own Hyperliquid account mode, spot USDC total/holds, main-DEX perpetual positions/orders, and raw perp equity summary with per-section freshness. Unified/portfolio accounts use spot collateral; raw perp equity is not account equity. Reuses the live feed with HTTP repair.",
+                parameters: Type.Object({}, { additionalProperties: false }),
+                replay: "safe",
+                structuredOutputSchema: AccountStatusSchema,
+                execute: async (_args, _api, context) => {
+                    const status = await service.agentAccountStatus(userId, agentId, context.abortSignal);
+                    return toolResult(status);
+                },
+            }), defineTool({
+                name: "get_market_snapshot",
+                description: "Read a fresh public Hyperliquid main-DEX perpetual snapshot for one instrument (exact venue symbol, e.g. BTC): mid/mark/oracle prices, mark-based 24h change, volumes, hourly funding and open interest. Read-only; independent of trading permissions. Includes host observation time, not a venue timestamp. Not an executable quote, last trade, or technical-analysis report.",
+                parameters: Type.Object({ instrument: Type.String({ minLength: 1, maxLength: 32 }) }, { additionalProperties: false }),
+                replay: "safe",
+                structuredOutputSchema: MarketSnapshotSchema,
+                execute: async (args, _api, context) => toolResult(await service.marketSnapshot(args.instrument, context.abortSignal)),
+            }), ...createOrderTools(orders, userId, agentId)],
+    });
+}

package/dist/hyperliquid/errors.js

@@ -0,0 +1,8 @@
+/** Public exchange errors surfaced to users with their HTTP status. Browser-safe. */
+export class HyperliquidError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}