hypervibes 0.0.0-stage → 0.4.0-beta

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;
+    }
+}

package/dist/hyperliquid/exchange.js

@@ -0,0 +1,118 @@
+import { ApiRequestError, ExchangeClient, HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { privateKeyToAccount } from "viem/accounts";
+import { HYPERLIQUID_API_URL } from "./constants.js";
+/** Splits a 65-byte secp256k1 signature into Hyperliquid's `r`/`s`/`v` fields. */
+export function signatureParts(signature) {
+    const raw = signature.slice(2);
+    if (!/^[0-9a-fA-F]{130}$/.test(raw))
+        throw new Error("Invalid signature");
+    return {
+        r: `0x${raw.slice(0, 64)}`,
+        s: `0x${raw.slice(64, 128)}`,
+        v: Number.parseInt(raw.slice(128, 130), 16),
+    };
+}
+/** An exchange response succeeded only when Hyperliquid reports `status: "ok"`. */
+export function exchangeSuccess(response) {
+    return typeof response === "object" && response !== null
+        && response.status === "ok";
+}
+/** The message Hyperliquid attached to a rejected exchange response. */
+export function exchangeErrorMessage(response) {
+    if (typeof response !== "object" || response === null)
+        return "Hyperliquid rejected the request.";
+    const inner = response.response;
+    const nested = typeof inner === "object" && inner !== null ? inner.data?.status?.error : undefined;
+    const message = typeof nested === "string" ? nested
+        : typeof inner === "string" ? inner
+            : typeof response.message === "string" ? response.message
+                : undefined;
+    return message ?? "Hyperliquid rejected the request.";
+}
+/**
+ * Relays a browser-signed action to the exchange endpoint unchanged. The
+ * caller has already validated the action object and recovered its signer.
+ */
+export async function relaySignedAction(transport, action, signature) {
+    const nonce = action.nonce;
+    if (typeof nonce !== "number" || !Number.isSafeInteger(nonce))
+        throw new Error("Invalid action nonce");
+    const response = await fetch(`${HYPERLIQUID_API_URL}/exchange`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ action, nonce, signature: signatureParts(signature) }),
+    });
+    if (!response.ok)
+        throw new Error("Hyperliquid exchange unavailable");
+    return response.json();
+}
+/**
+ * Serializes creation for each owner and remembers uncertain submissions for
+ * the lifetime of the service. A cancelled request also remains uncertain.
+ */
+export class SubaccountCreator {
+    transport;
+    nonceManager;
+    owners = new Map();
+    constructor(transport, nonceManager) {
+        this.transport = transport;
+        this.nonceManager = nonceManager;
+    }
+    async discover(owner, name) {
+        const info = new InfoClient({ transport: this.transport });
+        const accounts = await info.subAccounts({ user: owner });
+        return accounts?.find((account) => account.master.toLowerCase() === owner && account.name === name)
+            ?.subAccountUser.toLowerCase() ?? null;
+    }
+    async create(owner, name, privateKey) {
+        const state = this.owners.get(owner) ?? { pending: new Set(), queue: Promise.resolve() };
+        this.owners.set(owner, state);
+        const attempt = state.queue.then(() => this.attempt(state, owner, name, privateKey));
+        state.queue = attempt.then(() => { }, () => { });
+        return attempt;
+    }
+    async attempt(state, owner, name, privateKey) {
+        let existing;
+        try {
+            existing = await this.discover(owner, name);
+        }
+        catch {
+            return state.pending.has(name)
+                ? { ok: false, failure: { kind: "unconfirmed" } }
+                : { ok: false, failure: { kind: "lookup-unavailable" } };
+        }
+        if (existing) {
+            state.pending.delete(name);
+            return { ok: true, subaccount: { address: existing, created: false } };
+        }
+        if (state.pending.has(name))
+            return { ok: false, failure: { kind: "unconfirmed" } };
+        // Record the name before awaiting submission so a cancelled request cannot
+        // enable another request to blindly submit the same creation.
+        state.pending.add(name);
+        try {
+            const wallet = privateKeyToAccount(privateKey);
+            const exchange = new ExchangeClient({ transport: this.transport, wallet, nonceManager: this.nonceManager });
+            const response = await exchange.createSubAccount({ name });
+            state.pending.delete(name);
+            const address = typeof response.response?.data === "string" ? response.response.data.toLowerCase() : null;
+            if (!address)
+                return { ok: false, failure: { kind: "unconfirmed" } };
+            return { ok: true, subaccount: { address, created: true } };
+        }
+        catch (error) {
+            if (error instanceof ApiRequestError) {
+                // An explicit exchange rejection definitively means nothing was created.
+                state.pending.delete(name);
+                return { ok: false, failure: { kind: "rejected", message: error.message } };
+            }
+            // Transport or unexpected failures are uncertain; reconcile by discovery.
+            const reconciled = await this.discover(owner, name).catch(() => null);
+            if (reconciled) {
+                state.pending.delete(name);
+                return { ok: true, subaccount: { address: reconciled, created: true } };
+            }
+            return { ok: false, failure: { kind: "unconfirmed" } };
+        }
+    }
+}

package/dist/hyperliquid/journal-decimal.js

@@ -0,0 +1,48 @@
+/** Exact finite-decimal accounting. Division alone rounds half-even at 28 places.
+ * Split fees use subtraction for the remainder, preserving the source total. */
+export class Amount {
+    units;
+    scale;
+    constructor(units, scale) {
+        this.units = units;
+        this.scale = scale;
+    }
+    static from(value) {
+        if (value.length > 200 || !/^-?\d+(?:\.\d+)?$/.test(value))
+            throw new Error("Invalid journal decimal");
+        const [whole, fraction = ""] = value.split(".");
+        return new Amount(BigInt(`${whole}${fraction}`), fraction.length);
+    }
+    align(other) {
+        const scale = Math.max(this.scale, other.scale);
+        return { a: this.units * 10n ** BigInt(scale - this.scale), b: other.units * 10n ** BigInt(scale - other.scale), scale };
+    }
+    add(other) { const { a, b, scale } = this.align(other); return new Amount(a + b, scale); }
+    sub(other) { return this.add(other.neg()); }
+    neg() { return new Amount(-this.units, this.scale); }
+    abs() { return this.units < 0n ? this.neg() : this; }
+    mul(other) { return new Amount(this.units * other.units, this.scale + other.scale); }
+    div(other) {
+        if (other.units === 0n)
+            throw new Error("Division by zero");
+        const numerator = this.units * 10n ** BigInt(other.scale + 28);
+        const denominator = other.units * 10n ** BigInt(this.scale);
+        const negative = (numerator < 0n) !== (denominator < 0n);
+        const n = numerator < 0n ? -numerator : numerator;
+        const d = denominator < 0n ? -denominator : denominator;
+        let result = n / d;
+        const remainder = n % d;
+        if (remainder * 2n > d || (remainder * 2n === d && result % 2n !== 0n))
+            result++;
+        return new Amount(negative ? -result : result, 28);
+    }
+    cmp(other) { const { a, b } = this.align(other); return a < b ? -1 : a > b ? 1 : 0; }
+    get zero() { return this.units === 0n; }
+    get sign() { return this.units < 0n ? -1 : this.units > 0n ? 1 : 0; }
+    toString() {
+        const raw = (this.units < 0n ? -this.units : this.units).toString().padStart(this.scale + 1, "0");
+        const body = this.scale ? `${raw.slice(0, -this.scale)}.${raw.slice(-this.scale)}`.replace(/\.?0+$/, "") : raw;
+        return `${this.units < 0n ? "-" : ""}${body}`;
+    }
+}
+export const amount = Amount.from;