hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/live-dashboard.js

@@ -0,0 +1,245 @@
+import { HttpTransport, SubscriptionClient, WebSocketTransport } from "@nktkas/hyperliquid";
+import { dashboardOrders, dashboardPerps, dashboardSpot, loadAgentDashboard } from "./agent-dashboard.js";
+/** One read-only connection per linked account, never per browser tab. */
+export const openAccountFeed = (address, events, sharedTransport) => {
+    const transport = sharedTransport ?? new WebSocketTransport();
+    const client = new SubscriptionClient({ transport });
+    const abort = new AbortController();
+    let modeSeen = false;
+    let lastMode = null;
+    const connected = () => { modeSeen = false; events.connected(); };
+    const disconnected = () => events.disconnected();
+    transport.socket.addEventListener("open", connected);
+    transport.socket.addEventListener("close", disconnected);
+    const user = address;
+    const options = { signal: abort.signal, onError: () => events.failed() };
+    if (transport.socket.readyState === 1)
+        queueMicrotask(() => { if (!abort.signal.aborted)
+            connected(); });
+    const tasks = [
+        client.clearinghouseState({ user, dex: "" }, (event) => {
+            if (event.user.toLowerCase() === address && event.dex === "")
+                events.update("perps", dashboardPerps(event.clearinghouseState));
+        }, options),
+        client.spotState({ user }, (event) => {
+            if (event.user.toLowerCase() === address)
+                events.update("spot", dashboardSpot(event.spotState));
+        }, options),
+        client.openOrders({ user, dex: "" }, (event) => {
+            if (event.user.toLowerCase() === address && event.dex === "")
+                events.update("orders", dashboardOrders(event.orders));
+        }, options),
+        client.webData3({ user }, (event) => {
+            if (event.userState.user.toLowerCase() !== address)
+                return;
+            const mode = event.userState.abstraction ?? null;
+            // Omitted abstraction is unknown. Repair it once, not on every user event.
+            if (modeSeen && mode === lastMode)
+                return;
+            modeSeen = true;
+            lastMode = mode;
+            events.update("mode", { accountAbstraction: mode });
+        }, options),
+    ];
+    for (const task of tasks)
+        void task.catch(() => { if (!abort.signal.aborted)
+            events.failed(); });
+    return { async close() {
+            transport.socket.removeEventListener("open", connected);
+            transport.socket.removeEventListener("close", disconnected);
+            abort.abort();
+            if (!sharedTransport)
+                transport.close();
+            const subscriptions = await Promise.allSettled(tasks);
+            await Promise.allSettled(subscriptions.flatMap((result) => result.status === "fulfilled" ? [result.value.unsubscribe()] : []));
+        } };
+};
+const sections = ["perps", "spot", "orders", "mode"];
+/** Ephemeral latest-state projection, not a journal or reliable event queue. */
+export class LiveDashboards {
+    transport;
+    factory;
+    accounts = new Map();
+    stopped = false;
+    tasks = new Set();
+    constructor(transport = new HttpTransport(), factory = openAccountFeed) {
+        this.transport = transport;
+        this.factory = factory;
+    }
+    snapshot(address) {
+        return structuredClone(this.ensure(address.toLowerCase()).snapshot);
+    }
+    watch(address, signal, publish) {
+        if (signal.aborted)
+            return Promise.resolve();
+        const account = this.ensure(address.toLowerCase());
+        return new Promise((resolve) => {
+            const listener = () => publish(structuredClone(account.snapshot));
+            const finish = () => {
+                account.listeners.delete(listener);
+                signal.removeEventListener("abort", finish);
+                account.abort.signal.removeEventListener("abort", finish);
+                resolve();
+            };
+            account.listeners.add(listener);
+            signal.addEventListener("abort", finish, { once: true });
+            account.abort.signal.addEventListener("abort", finish, { once: true });
+            listener();
+        });
+    }
+    async reconcile(addresses) {
+        if (this.stopped)
+            return;
+        const wanted = new Set(addresses.map((address) => address.toLowerCase()));
+        for (const address of wanted)
+            this.ensure(address);
+        for (const [address, account] of this.accounts) {
+            if (wanted.has(address))
+                continue;
+            await this.stop(account);
+            this.accounts.delete(address);
+        }
+    }
+    ensure(address) {
+        if (this.stopped)
+            throw new Error("Live account service is closed");
+        const existing = this.accounts.get(address);
+        if (existing)
+            return existing;
+        const account = {
+            snapshot: {
+                address, accountAbstraction: null, fetchedAt: Date.now(), perpEquity: null, spotUsdc: null, positions: null, orders: null, errors: [],
+                live: { status: "connecting", sections: {
+                        perps: { updatedAt: null, fresh: false }, spot: { updatedAt: null, fresh: false }, orders: { updatedAt: null, fresh: false }, mode: { updatedAt: null, fresh: false },
+                    } },
+            },
+            listeners: new Set(), revision: { perps: 0, spot: 0, orders: 0, mode: 0 }, generation: 0, abort: new AbortController(),
+        };
+        this.accounts.set(address, account);
+        this.connect(account);
+        return account;
+    }
+    publish(account) {
+        for (const listener of account.listeners)
+            listener(account.snapshot);
+    }
+    connect(account) {
+        if (account.abort.signal.aborted)
+            return;
+        const generation = ++account.generation;
+        let epoch = 0;
+        let repairRunning = false;
+        let repairRequested = false;
+        const update = (section, patch) => {
+            const modeChanged = section === "mode" && patch.accountAbstraction !== account.snapshot.accountAbstraction;
+            if (modeChanged) {
+                // Balances observed before this boundary cannot establish current equity.
+                for (const balance of ["perps", "spot"]) {
+                    account.snapshot.live.sections[balance].fresh = false;
+                    account.revision[balance]++;
+                }
+            }
+            Object.assign(account.snapshot, patch);
+            account.revision[section]++;
+            const now = Date.now();
+            account.snapshot.fetchedAt = now;
+            account.snapshot.live.sections[section] = { updatedAt: now, fresh: section !== "mode" || account.snapshot.accountAbstraction !== null };
+            this.publish(account);
+            if (modeChanged || (section === "mode" && account.snapshot.accountAbstraction === null))
+                requestRepair();
+        };
+        const active = () => !account.abort.signal.aborted && generation === account.generation;
+        const requestRepair = () => {
+            repairRequested = true;
+            if (repairRunning || !active() || account.snapshot.live.status !== "connected")
+                return;
+            repairRequested = false;
+            repairRunning = true;
+            const connectionEpoch = epoch;
+            const revision = { ...account.revision };
+            const refresh = loadAgentDashboard(this.transport, account.snapshot.address, account.abort.signal).then((snapshot) => {
+                if (!active() || connectionEpoch !== epoch || account.snapshot.live.status !== "connected")
+                    return;
+                // Apply mode first. A changed mode invalidates this request's balances
+                // and schedules a post-boundary repair, even for an idle account.
+                if (account.revision.mode === revision.mode && snapshot.accountAbstraction !== null)
+                    update("mode", { accountAbstraction: snapshot.accountAbstraction });
+                for (const section of ["perps", "spot", "orders"]) {
+                    if (account.revision[section] !== revision[section])
+                        continue;
+                    if (section === "perps" && snapshot.perpEquity !== null && snapshot.positions !== null)
+                        update(section, { perpEquity: snapshot.perpEquity, positions: snapshot.positions });
+                    if (section === "spot" && snapshot.spotUsdc !== null)
+                        update(section, { spotUsdc: snapshot.spotUsdc, spotUsdcHold: snapshot.spotUsdcHold ?? null });
+                    if (section === "orders" && snapshot.orders !== null)
+                        update(section, { orders: snapshot.orders });
+                }
+                this.publish(account);
+            }).catch(() => { }).finally(() => {
+                repairRunning = false;
+                if (repairRequested && active() && account.snapshot.live.status === "connected")
+                    requestRepair();
+            });
+            this.track(refresh);
+        };
+        const invalidate = () => {
+            ++epoch;
+            account.snapshot.live.status = "reconnecting";
+            for (const section of sections)
+                account.snapshot.live.sections[section].fresh = false;
+            this.publish(account);
+        };
+        const failed = () => {
+            if (!active())
+                return;
+            ++account.generation;
+            invalidate();
+            const feed = account.feed;
+            account.feed = undefined;
+            if (feed)
+                this.track(feed.close());
+            account.retry = setTimeout(() => this.connect(account), 5_000);
+            account.retry.unref();
+        };
+        try {
+            account.feed = this.factory(account.snapshot.address, {
+                connected: () => {
+                    if (!active())
+                        return;
+                    account.snapshot.live.status = "connected";
+                    this.publish(account);
+                    // Only connection and mode events trigger HTTP repair; never polling.
+                    ++epoch;
+                    requestRepair();
+                },
+                disconnected: () => { if (active())
+                    invalidate(); },
+                update: (section, patch) => { if (active())
+                    update(section, patch); },
+                failed,
+            });
+        }
+        catch {
+            failed();
+        }
+    }
+    track(task) {
+        const tracked = task.finally(() => this.tasks.delete(tracked));
+        this.tasks.add(tracked);
+    }
+    async stop(account) {
+        clearTimeout(account.retry);
+        account.snapshot.live.status = "stopped";
+        for (const section of sections)
+            account.snapshot.live.sections[section].fresh = false;
+        this.publish(account);
+        account.abort.abort();
+        await account.feed?.close();
+    }
+    async close() {
+        this.stopped = true;
+        await Promise.all([...this.accounts.values()].map((account) => this.stop(account)));
+        this.accounts.clear();
+        await Promise.all(this.tasks);
+    }
+}

package/dist/hyperliquid/logo-cache.js

@@ -0,0 +1,27 @@
+import { SvgLogoCache } from "../cache/svg-logo-cache.js";
+import { isPerpetualLogoSymbol } from "./currency-logo.js";
+export function fallbackCurrencyLogo(symbol) {
+    // Only validated symbols may reach the SVG template.
+    if (!isPerpetualLogoSymbol(symbol))
+        throw new Error("Invalid currency symbol");
+    return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#18181b"/><text x="16" y="21" text-anchor="middle" font-family="sans-serif" font-size="${symbol.length <= 3 ? 11 : 8}" textLength="26" lengthAdjust="spacingAndGlyphs" fill="#fafafa">${symbol}</text></svg>`);
+}
+const source = {
+    directory: "hyperliquid/logos",
+    validate: isPerpetualLogoSymbol,
+    url: (symbol) => `https://app.hyperliquid.xyz/coins/${encodeURIComponent(symbol)}.svg`,
+    fallback: fallbackCurrencyLogo,
+};
+/** Caches Hyperliquid perpetual coin logos; see {@link SvgLogoCache} for mechanics. */
+export class CurrencyLogoCache {
+    cache;
+    constructor(root, fetcher = fetch) {
+        this.cache = new SvgLogoCache(root, source, fetcher);
+    }
+    get(symbol) {
+        return this.cache.get(symbol);
+    }
+    close() {
+        return this.cache.close();
+    }
+}

package/dist/hyperliquid/market-charts.js

@@ -0,0 +1,242 @@
+import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
+import { HyperliquidError } from "./errors.js";
+import { intervalMillis, isChartInterval, mergeChartCandles } from "./chart-contracts.js";
+const pageSize = 500;
+function normalize(raw, selection) {
+    const candles = [];
+    for (const row of raw) {
+        if (row.s !== selection.coin || row.i !== selection.interval)
+            continue;
+        const candle = { time: row.t / 1000, open: Number(row.o), high: Number(row.h), low: Number(row.l), close: Number(row.c), volume: Number(row.v) };
+        if (!Number.isSafeInteger(row.t) || row.t < 0 || row.t % intervalMillis[selection.interval] !== 0
+            || !Object.values(candle).every(Number.isFinite) || candle.volume < 0 || candle.low <= 0
+            || candle.low > Math.min(candle.open, candle.close) || candle.high < Math.max(candle.open, candle.close))
+            continue;
+        candles.push(candle);
+    }
+    return mergeChartCandles([], candles);
+}
+/** Cancelling a consumer must not cancel a shared public-market-data request. */
+function waitForSignal(task, signal) {
+    if (!signal)
+        return task;
+    if (signal.aborted) {
+        void task.catch(() => { }); // The abandoned caller must still observe rejection.
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+        signal.addEventListener("abort", abort, { once: true });
+        void task.then((value) => { signal.removeEventListener("abort", abort); resolve(value); }, (error) => { signal.removeEventListener("abort", abort); reject(error); });
+    });
+}
+/** Bounded ephemeral market data; history is shared across viewers, never persisted. */
+export class MarketCharts {
+    factory;
+    info;
+    abort = new AbortController();
+    feeds = new Map();
+    tasks = new Set();
+    cache = new Map();
+    researchCache = new Map();
+    universe;
+    constructor(transport, factory) {
+        this.factory = factory;
+        this.info = new InfoClient({ transport });
+    }
+    admit() { if (this.abort.signal.aborted)
+        throw new HyperliquidError("Market data service is closed", 503); }
+    track(task) {
+        this.tasks.add(task);
+        void task.finally(() => this.tasks.delete(task)).catch(() => { });
+        return task;
+    }
+    instruments() {
+        return this.instrumentDetails().then((items) => items.map((item) => item.symbol));
+    }
+    instrumentDetails() {
+        this.admit();
+        if (this.universe && this.universe.expires > Date.now())
+            return this.universe.task;
+        const task = this.track(this.info.meta({ dex: "" }, this.abort.signal).then((meta) => meta.universe.filter((asset) => !asset.isDelisted)
+            .map((asset) => ({ symbol: asset.name, sizeDecimals: asset.szDecimals })).sort((a, b) => a.symbol.localeCompare(b.symbol))));
+        this.universe = { expires: Date.now() + 60_000, task };
+        void task.catch(() => { if (this.universe?.task === task)
+            this.universe = undefined; });
+        return task;
+    }
+    async selection(coin, interval) {
+        this.admit();
+        if (!isChartInterval(interval) || !coin || coin.length > 64)
+            throw new HyperliquidError("Invalid chart selection");
+        if (!(await this.instruments()).includes(coin))
+            throw new HyperliquidError("Select an available perpetual instrument");
+        return { coin, interval };
+    }
+    async history(selection, before) {
+        this.admit();
+        if (before !== undefined && (!Number.isSafeInteger(before) || before <= 0 || before > Date.now() + intervalMillis[selection.interval]))
+            throw new HyperliquidError("Invalid history cursor");
+        const width = intervalMillis[selection.interval];
+        // The cursor is an exclusive candle-open timestamp, in milliseconds.
+        const endTime = before === undefined ? Math.floor(Date.now() / width) * width : Math.floor((before - 1) / width) * width;
+        const startTime = Math.max(0, endTime - (pageSize - 1) * width);
+        const key = `${selection.coin}/${selection.interval}/${endTime}`;
+        const cached = this.cache.get(key);
+        if (cached && cached.expires > Date.now())
+            return cached.task;
+        if (this.tasks.size >= 12)
+            throw new HyperliquidError("Market data is busy. Please retry.", 429);
+        const task = this.track(this.info.candleSnapshot({ ...selection, startTime, endTime }, this.abort.signal).then((raw) => {
+            const candles = normalize(raw, selection).filter((candle) => candle.time * 1000 >= startTime && candle.time * 1000 <= endTime).slice(-pageSize);
+            return { candles, hasMore: candles.length > 0 && startTime > 0 };
+        }));
+        if (this.cache.size >= 64)
+            this.cache.delete(this.cache.keys().next().value);
+        this.cache.set(key, { expires: Date.now() + (before === undefined ? 2_000 : 60_000), task });
+        void task.catch(() => { if (this.cache.get(key)?.task === task)
+            this.cache.delete(key); });
+        return task;
+    }
+    /** Research pages have a fixed exclusive end and never include forming candles.
+     * Hyperliquid retains only the most recent ~5,000 candles per instrument/interval.
+     */
+    async researchHistory(coin, interval, start, end, limit, cancellation) {
+        cancellation?.throwIfAborted();
+        const selection = await waitForSignal(this.selection(coin, interval), cancellation);
+        const width = intervalMillis[selection.interval];
+        if (![start, end, limit].every(Number.isSafeInteger) || start < 0 || end <= start || end > Date.now() || limit < 1 || limit > 5000)
+            throw new HyperliquidError("Invalid research candle range");
+        const boundary = Math.min(Math.floor(end / width) * width, Math.floor(Date.now() / width) * width);
+        const pageStart = Math.ceil(start / width) * width;
+        const pageEnd = Math.min(boundary, pageStart + limit * width);
+        const key = JSON.stringify([selection.coin, selection.interval, pageStart, pageEnd]);
+        let cached = this.researchCache.get(key);
+        if (!cached || cached.expires <= Date.now()) {
+            if (this.tasks.size >= 12)
+                throw new HyperliquidError("Market data is busy", 429);
+            const task = pageEnd <= pageStart ? Promise.resolve([]) : this.track(this.info.candleSnapshot({ ...selection, startTime: pageStart, endTime: pageEnd - 1 }, AbortSignal.any([this.abort.signal, AbortSignal.timeout(15_000)]))
+                .then((raw) => normalize(raw, selection).filter((row) => row.time * 1000 >= pageStart && row.time * 1000 + width <= pageEnd)));
+            if (this.researchCache.size >= 16)
+                this.researchCache.delete(this.researchCache.keys().next().value);
+            cached = { expires: Date.now() + 60_000, task };
+            this.researchCache.set(key, cached);
+            void task.catch(() => { if (this.researchCache.get(key)?.task === task)
+                this.researchCache.delete(key); });
+        }
+        const items = (await waitForSignal(cached.task, cancellation)).slice(0, limit).map((candle) => ({ ...candle }));
+        const expected = Math.max(0, (pageEnd - pageStart) / width);
+        return { coin, interval, start, end: boundary, pageEnd, candles: items, nextStart: pageEnd < boundary ? pageEnd : null,
+            coverage: { complete: items.length === expected, returned: items.length, expected, sourceLimit: "Hyperliquid retains approximately the latest 5,000 candles; empty/gapped data is not proof of no trading.", closedOnly: true } };
+    }
+    watch(selection, signal, publish) {
+        this.admit();
+        if (signal.aborted)
+            return Promise.resolve();
+        const key = `${selection.coin}/${selection.interval}`;
+        let feed = this.feeds.get(key);
+        if (!feed) {
+            if (this.feeds.size >= 40)
+                throw new HyperliquidError("Too many active charts. Please retry.", 429);
+            feed = { snapshot: { candles: [], status: "connecting" }, listeners: new Set(), abort: new AbortController(), updates: new Map(), generation: 0 };
+            this.feeds.set(key, feed);
+        }
+        const current = feed;
+        const task = new Promise((resolve) => {
+            const listener = (snapshot) => publish(structuredClone(snapshot));
+            const finish = () => {
+                current.listeners.delete(listener);
+                signal.removeEventListener("abort", finish);
+                current.abort.signal.removeEventListener("abort", finish);
+                if (!current.listeners.size && this.feeds.get(key) === current) {
+                    this.feeds.delete(key);
+                    void this.stop(current);
+                }
+                resolve();
+            };
+            current.listeners.add(listener);
+            signal.addEventListener("abort", finish, { once: true });
+            current.abort.signal.addEventListener("abort", finish, { once: true });
+            listener(current.snapshot);
+            if (!current.handle)
+                this.open(current, selection);
+        });
+        return task;
+    }
+    publish(feed) { for (const listener of feed.listeners)
+        listener(feed.snapshot); }
+    open(feed, selection) {
+        const generation = ++feed.generation;
+        feed.updates.clear();
+        const active = () => !feed.abort.signal.aborted && feed.generation === generation;
+        const repair = async () => {
+            const history = await this.history(selection);
+            if (!active())
+                return;
+            // HTTP must never overwrite newer websocket values for the forming candle.
+            feed.snapshot.candles = mergeChartCandles(history.candles, [...feed.updates.values()]).slice(-pageSize);
+            feed.snapshot.status = "live";
+            this.publish(feed);
+        };
+        const disconnected = () => { if (active()) {
+            ++feed.generation;
+            feed.snapshot.status = "reconnecting";
+            this.publish(feed);
+            this.retry(feed, selection);
+        } };
+        try {
+            feed.handle = this.factory(selection, {
+                connected: () => { if (active())
+                    void this.track(repair()).catch(disconnected); },
+                disconnected,
+                failed: disconnected,
+                update: (raw) => {
+                    if (!active())
+                        return;
+                    const candles = normalize([raw], selection);
+                    if (!candles.length)
+                        return;
+                    for (const candle of candles)
+                        feed.updates.set(candle.time, candle);
+                    if (feed.updates.size > pageSize)
+                        feed.updates.delete(feed.updates.keys().next().value);
+                    feed.snapshot.candles = mergeChartCandles(feed.snapshot.candles, candles).slice(-pageSize);
+                    this.publish(feed);
+                },
+            });
+        }
+        catch {
+            disconnected();
+        }
+    }
+    retry(feed, selection) {
+        if (feed.retry || feed.abort.signal.aborted)
+            return;
+        feed.retry = setTimeout(() => {
+            feed.retry = undefined;
+            const old = feed.handle;
+            feed.handle = undefined;
+            void this.track((async () => {
+                await old?.close();
+                if (!feed.abort.signal.aborted)
+                    this.open(feed, selection);
+            })()).catch(() => this.retry(feed, selection));
+        }, 3_000);
+        feed.retry.unref();
+    }
+    stop(feed) {
+        feed.abort.abort();
+        clearTimeout(feed.retry);
+        return this.track(feed.handle?.close() ?? Promise.resolve());
+    }
+    async close() {
+        this.abort.abort();
+        const feeds = [...this.feeds.values()];
+        this.feeds.clear();
+        for (const feed of feeds)
+            void this.stop(feed);
+        await Promise.allSettled(this.tasks);
+        this.cache.clear();
+        this.researchCache.clear();
+    }
+}

package/dist/hyperliquid/market-snapshot.js

@@ -0,0 +1,45 @@
+import { Type } from "@earendil-works/pi-ai";
+import { InfoClient } from "@nktkas/hyperliquid";
+import { HyperliquidError } from "./errors.js";
+import { amount } from "./journal-decimal.js";
+const decimal = Type.String({ pattern: "^-?[0-9]+(\\.[0-9]+)?$" });
+const nullableDecimal = Type.Union([decimal, Type.Null()]);
+export const MarketSnapshotSchema = Type.Object({
+    instrument: Type.String(), scope: Type.Literal("main-dex-perpetuals"),
+    source: Type.Literal("Hyperliquid metaAndAssetCtxs HTTP"), observedAt: Type.Integer(),
+    midPrice: nullableDecimal, markPrice: decimal, oraclePrice: decimal,
+    previousDayPrice: decimal, markChange24hPercent: nullableDecimal,
+    volume24hUsd: decimal, volume24hBase: decimal, fundingRateHourly: decimal,
+    openInterestBase: decimal, warning: Type.String(),
+});
+/** A single venue response keeps metadata and its index-aligned contexts together. */
+export async function loadMarketSnapshot(transport, instrument, signal) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/.test(instrument))
+        throw new HyperliquidError("Select a main-DEX perpetual instrument such as BTC.");
+    const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000);
+    requestSignal.throwIfAborted();
+    const [meta, contexts] = await new InfoClient({ transport }).metaAndAssetCtxs({ dex: "" }, requestSignal);
+    const observedAt = Date.now();
+    const index = meta.universe.findIndex((asset) => asset.name === instrument && !asset.isDelisted);
+    if (index < 0)
+        throw new HyperliquidError("Unknown or delisted main-DEX perpetual instrument.", 404);
+    const ctx = contexts[index];
+    if (!ctx || contexts.length !== meta.universe.length)
+        throw new HyperliquidError("Market snapshot context is unavailable.", 502);
+    // Reject malformed data, rather than silently turning missing values into zero.
+    const nonnegative = [ctx.markPx, ctx.oraclePx, ctx.prevDayPx, ctx.dayNtlVlm, ctx.dayBaseVlm, ctx.openInterest, ...(ctx.midPx === null ? [] : [ctx.midPx])];
+    if (nonnegative.some((value) => amount(value).sign < 0))
+        throw new HyperliquidError("Invalid market snapshot amounts.", 502);
+    amount(ctx.funding);
+    const previous = amount(ctx.prevDayPx);
+    return {
+        instrument, scope: "main-dex-perpetuals",
+        source: "Hyperliquid metaAndAssetCtxs HTTP", observedAt,
+        midPrice: ctx.midPx, markPrice: ctx.markPx, oraclePrice: ctx.oraclePx,
+        previousDayPrice: ctx.prevDayPx,
+        markChange24hPercent: previous.zero ? null : amount(ctx.markPx).sub(previous).mul(amount("100")).div(previous).toString(),
+        volume24hUsd: ctx.dayNtlVlm, volume24hBase: ctx.dayBaseVlm,
+        fundingRateHourly: ctx.funding, openInterestBase: ctx.openInterest,
+        warning: "Host observation time in UTC milliseconds, not a venue timestamp. Mid/mark/oracle prices are not executable quotes or last-trade prices. 24h change uses mark versus previous-day price; null means unavailable. Funding is an hourly decimal rate, not percent or APR. Volume is rolling 24h; open interest is base-asset quantity. Snapshot only, not candle/indicator research or trade authority.",
+    };
+}

package/dist/hyperliquid/orders/order-contracts.js

@@ -0,0 +1,42 @@
+import { Type } from "@earendil-works/pi-ai";
+const object = { additionalProperties: false };
+export const Decimal = Type.String({ pattern: "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", maxLength: 80, description: "Exact plain decimal string, never a JSON number or exponent." });
+export const OrderSize = { ...Decimal, description: "Exact positive base-asset quantity, NOT USD notional. Read list_instruments sizeDecimals/sizeStep first; do not guess precision or silently increase the user's size/budget. For a USD budget, choose an expressible base quantity consistent with that budget." };
+export const OrderPrice = { ...Decimal, description: "Exact positive price string. Read list_instruments: fractional prices must satisfy BOTH priceMaxDecimals and priceMaxSignificantFigures; positive integer prices are exempt from these precision limits." };
+export const RequestId = Type.String({ minLength: 1, maxLength: 120, pattern: "^[a-zA-Z0-9_-]+$", description: "Unique logical request ID. Reuse with identical arguments on retry; never issue a new ID to retry an unknown outcome." });
+const SymbolName = Type.String({ minLength: 1, maxLength: 30, pattern: "^[A-Za-z0-9_-]+$", description: "Exact main-DEX perpetual symbol from exchange metadata (e.g. BTC). No spot or HIP-3 symbols." });
+const Trigger = Type.Object({ trigger_price: OrderPrice, limit_price: Type.Optional(OrderPrice), size: Type.Optional(OrderSize) }, object);
+export const OrderInputSchema = Type.Object({
+    symbol: SymbolName, side: Type.Union([Type.Literal("buy"), Type.Literal("sell")]),
+    order_type: Type.Union([Type.Literal("limit"), Type.Literal("market"), Type.Literal("take_profit"), Type.Literal("stop_loss")], { description: 'Use "limit" with price, "market" for a 0.5%-guarded IOC (omit price/time_in_force), or "take_profit"/"stop_loss" for standalone reduce-only triggers with trigger_price. This is not the planner entry_style field.' }),
+    size: OrderSize, price: Type.Optional(OrderPrice), trigger_price: Type.Optional(OrderPrice),
+    time_in_force: Type.Optional(Type.Union([Type.Literal("gtc"), Type.Literal("ioc"), Type.Literal("alo")], { description: 'Limit orders only: "gtc" (default), "ioc", or "alo". Omit for market orders and standalone triggers.' })),
+    reduce_only: Type.Optional(Type.Boolean()),
+    take_profits: Type.Optional(Type.Array(Trigger, { maxItems: 1, description: "At most one attached native OCO take-profit. Use a standalone reduce-only trigger for position-level protection." })),
+    stop_losses: Type.Optional(Type.Array(Trigger, { maxItems: 1 })),
+}, object);
+export const SubmitSchema = Type.Object({ request_id: RequestId, decision_ref: Type.Optional(Type.String({ pattern: "^m[1-9][0-9]*$", maxLength: 17, description: "Optional reference to a decision that actually motivates this submission, for audit only, never trading authority. For a direct/manual user request with no memory-based rationale, omit this field; no research or decision memory is required. Do not attach an unrelated or previously blocked/skipped decision just to populate it." })), orders: Type.Array(OrderInputSchema, { minItems: 1, maxItems: 20 }) }, object);
+export const CancelInputSchema = Type.Object({ symbol: SymbolName, oid: Type.String({ pattern: "^[1-9][0-9]*$", maxLength: 16, description: "Exchange order ID as a decimal string." }) }, object);
+export const CancelSchema = Type.Object({ request_id: RequestId, orders: Type.Array(CancelInputSchema, { minItems: 1, maxItems: 100 }) }, object);
+export const CancelAllSchema = Type.Object({ request_id: RequestId, symbol: Type.Optional(SymbolName) }, object);
+export const ListSchema = Type.Object({
+    source: Type.Optional(Type.Union([Type.Literal("open"), Type.Literal("local")])), symbol: Type.Optional(SymbolName), status: Type.Optional(Type.String({ maxLength: 60 })),
+    limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })), offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 100000 })),
+}, object);
+export const GetSchema = Type.Object({ order_id: Type.String({ minLength: 1, maxLength: 80 }), include_events: Type.Optional(Type.Boolean()) }, object);
+const NullableString = Type.Union([Type.String(), Type.Null()]);
+export const OrderViewSchema = Type.Object({
+    id: Type.String(), requestId: NullableString, symbol: Type.String(), side: Type.String(), kind: Type.String(),
+    size: NullableString, price: NullableString, triggerPrice: NullableString, reduceOnly: Type.Boolean(),
+    cloid: NullableString, exchangeOid: NullableString,
+    commandStatus: Type.Union([Type.Literal("not_sent"), Type.Literal("accepted"), Type.Literal("rejected"), Type.Literal("unknown"), Type.Literal("reconciled")]),
+    orderStatus: Type.String(), filledSize: NullableString, averageFillPrice: NullableString,
+    updatedAt: Type.Number(), venueTimestamp: Type.Union([Type.Number(), Type.Null()]), source: Type.String(), error: NullableString,
+}, object);
+export const OperationSchema = Type.Object({
+    operationId: Type.String(), requestId: Type.String(), kind: Type.String(),
+    results: Type.Array(OrderViewSchema), uncertain: Type.Boolean(), warnings: Type.Array(Type.String()),
+}, object);
+export const EventSchema = Type.Object({ id: Type.Number(), source: Type.String(), time: Type.Number(), data: Type.String() }, object);
+export const GetResultSchema = Type.Object({ order: Type.Union([OrderViewSchema, Type.Null()]), events: Type.Array(EventSchema), error: NullableString, observedAt: Type.Number() }, object);
+export const ListResultSchema = Type.Object({ items: Type.Array(OrderViewSchema), source: Type.String(), observedAt: Type.Number(), nextOffset: Type.Union([Type.Number(), Type.Null()]), coverage: Type.String() }, object);