@livo-build/runtime 0.2.4 → 0.2.6

package/dist/hyperliquid.d.ts

@@ -0,0 +1,360 @@
+import { ExchangeClient, InfoClient } from "@nktkas/hyperliquid";
+import { type Hex } from "./hex.js";
+export interface HyperliquidOptions {
+    /** Signing key. Default: env.HYPERLIQUID_PRIVATE_KEY, then env.RELAYER_PRIVATE_KEY. */
+    privateKey?: string;
+    /** Env var name to read the key from. Default: "HYPERLIQUID_PRIVATE_KEY". */
+    privateKeySecret?: string;
+    /** Use testnet endpoints. Default: truthy env.HYPERLIQUID_TESTNET. */
+    testnet?: boolean;
+    /**
+     * Which HIP-3 builder dexes to resolve symbols for: an array of dex names, or
+     * true for all of them. Default true — so "xyz:TSLA" & friends just work.
+     */
+    dexs?: string[] | boolean;
+    /**
+     * Master secret for deriving per-user AGENT keys (see `forUser`/`agentAddress`).
+     * Default: env.HL_AGENT_SECRET, then env.RELAYER_PRIVATE_KEY. Keep it stable —
+     * changing it changes every user's agent address (they'd have to re-approve).
+     */
+    agentSecret?: string;
+}
+export type Tif = "Gtc" | "Ioc" | "Alo";
+export type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M";
+export interface CandlesOptions {
+    /** Window start (ms epoch). Default: endTime − lookbackMs. */
+    startTime?: number;
+    /** Window end (ms epoch). Default: now. */
+    endTime?: number;
+    /** How far back from endTime to start. Default: 24h. */
+    lookbackMs?: number;
+}
+/** Live per-coin context: prices, funding, and open interest. */
+export interface AssetContext {
+    coin: string;
+    markPx: number;
+    midPx: number | null;
+    oraclePx: number;
+    /** Current hourly funding rate (fraction, e.g. 0.0000125). */
+    funding: number;
+    openInterest: number;
+    prevDayPx: number;
+    /** 24h notional volume (USDC). */
+    dayNtlVlm: number;
+}
+/** Perp account summary. */
+export interface AccountBalance {
+    accountValue: number;
+    withdrawable: number;
+    totalMarginUsed: number;
+    totalNtlPos: number;
+}
+export interface PlaceOrderOptions {
+    /** Reduce-only (close, never flip). Default false. */
+    reduceOnly?: boolean;
+    /** Time-in-force for limit orders. Default "Gtc". */
+    tif?: Tif;
+}
+export interface MarketOrderOptions {
+    /** Reduce-only (close, never flip). Default false. */
+    reduceOnly?: boolean;
+    /** Max slippage from mid for the protective limit price (0.05 = 5%). Default 0.05. */
+    slippage?: number;
+}
+interface MinimalEnv {
+    [key: string]: unknown;
+}
+export declare class Hyperliquid {
+    /** True when pointed at testnet. */
+    readonly testnet: boolean;
+    /** The signer's address (null when no key is configured → read-only). */
+    readonly address: Hex | null;
+    private readonly env;
+    private readonly transport;
+    private readonly _info;
+    private readonly privateKey?;
+    private readonly dexOption;
+    private readonly agentSecret?;
+    private readAddressOverride?;
+    private _exchange?;
+    private _converter?;
+    private _meta?;
+    constructor(env: MinimalEnv | undefined, options?: HyperliquidOptions);
+    /** Raw @nktkas InfoClient (all read endpoints). */
+    get info(): InfoClient;
+    /** Raw @nktkas ExchangeClient (all signed endpoints). Throws if no key is set. */
+    get exchange(): ExchangeClient;
+    /**
+     * All mid prices for a dex, keyed by coin. With no arg → the main perp dex
+     * (e.g. { BTC: "95000.0" }). Pass a builder-dex name for equities/commodities
+     * (e.g. mids("xyz") → { "xyz:TSLA": "399.8", "xyz:GOLD": "4160.3", … }).
+     */
+    mids(dex?: string): Promise<Record<string, string>>;
+    /**
+     * Mid price of one coin as a number. Accepts a main-dex perp ("BTC") or a
+     * builder-dex asset ("xyz:TSLA") — the right dex is queried automatically.
+     * Throws if the coin isn't listed (try `findAsset` to resolve a bare ticker).
+     */
+    mid(coin: string): Promise<number>;
+    /** L2 order book for a coin (main-dex "BTC" or builder-dex "xyz:TSLA"). */
+    book(coin: string): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").L2BookResponse>;
+    /** Perp account state (positions, margin, withdrawable) for an address (default: the signer). */
+    positions(user?: string): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").ClearinghouseStateResponse>;
+    /** Resting open orders for an address (default: the signer). */
+    openOrders(user?: string): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").OpenOrdersResponse>;
+    /** Main perp-dex metadata (universe of coins + szDecimals + maxLeverage). Cached. */
+    meta(): Promise<{
+        universe: Array<{
+            name: string;
+            szDecimals: number;
+            maxLeverage: number;
+        }>;
+    }>;
+    /** The HIP-3 builder-deployed perp dexes (name + fullName + deployer). */
+    dexs(): Promise<{
+        name: string;
+        fullName?: string;
+    }[]>;
+    /**
+     * Resolve a bare ticker to its full Hyperliquid coin name. "BTC" → "BTC" (main
+     * dex); "TSLA" → "xyz:TSLA" (a builder dex). Returns null if nothing matches.
+     * Use the result with mid/book/limit/market/etc.
+     */
+    findAsset(symbol: string): Promise<string | null>;
+    /** The integer asset id Hyperliquid uses in orders for a coin (main, spot, or builder dex). */
+    assetId(coin: string): Promise<number>;
+    /** Perp account summary (value, withdrawable, margin) for an address (default: the signer). */
+    balance(user?: string): Promise<AccountBalance>;
+    /** Spot token balances for an address (default: the signer). */
+    spotBalances(user?: string): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").SpotClearinghouseStateResponse>;
+    /** Recent fills (trade history) for an address (default: the signer). */
+    fills(user?: string): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").UserFillsResponse>;
+    /** Live context for a coin — mark/mid/oracle price, funding rate, open interest, 24h volume. */
+    assetCtx(coin: string): Promise<AssetContext>;
+    /** OHLCV candles for charting. `interval` default "1h"; window defaults to the last 24h. */
+    candles(coin: string, interval?: CandleInterval, opts?: CandlesOptions): Promise<import("file:///home/runner/work/hyperliquid/hyperliquid/src/mod.ts").CandleSnapshotResponse>;
+    /** Raw order passthrough (the @nktkas `order` shape) for full control. */
+    order(params: Parameters<ExchangeClient["order"]>[0]): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    /** Place a limit order. `price`/`size` are numbers; we format to HL's precision. */
+    limit(coin: string, isBuy: boolean, size: number, price: number, opts?: PlaceOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    limitBuy(coin: string, size: number, price: number, opts?: PlaceOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    limitSell(coin: string, size: number, price: number, opts?: PlaceOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    /**
+     * Market order — an IOC limit priced `slippage` past the current mid so it
+     * crosses immediately. Returns the @nktkas order response.
+     */
+    market(coin: string, isBuy: boolean, size: number, opts?: MarketOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    marketBuy(coin: string, size: number, opts?: MarketOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    marketSell(coin: string, size: number, opts?: MarketOrderOptions): Promise<{
+        status: "ok";
+        response: {
+            type: "order";
+            data: {
+                statuses: ({
+                    resting: {
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | {
+                    filled: {
+                        totalSz: string;
+                        avgPx: string;
+                        oid: number;
+                        cloid?: `0x${string}`;
+                    };
+                } | "waitingForFill" | "waitingForTrigger")[];
+            };
+        };
+    }>;
+    /**
+     * Market-close the entire open position in `coin` (reduce-only). Reads the
+     * current size and crosses the opposite side. No-op (returns closed:false) if flat.
+     */
+    closePosition(coin: string, opts?: {
+        slippage?: number;
+    }): Promise<{
+        closed: false;
+        side?: undefined;
+        size?: undefined;
+        result?: undefined;
+    } | {
+        closed: true;
+        side: string;
+        size: number;
+        result: {
+            status: "ok";
+            response: {
+                type: "order";
+                data: {
+                    statuses: ({
+                        resting: {
+                            oid: number;
+                            cloid?: `0x${string}`;
+                        };
+                    } | {
+                        filled: {
+                            totalSz: string;
+                            avgPx: string;
+                            oid: number;
+                            cloid?: `0x${string}`;
+                        };
+                    } | "waitingForFill" | "waitingForTrigger")[];
+                };
+            };
+        };
+    }>;
+    /** Cancel a resting order by its order id (oid). */
+    cancel(coin: string, oid: number): Promise<{
+        status: "ok";
+        response: {
+            type: "cancel";
+            data: {
+                statuses: "success"[];
+            };
+        };
+    }>;
+    /** Set leverage for a coin (cross by default). */
+    updateLeverage(coin: string, leverage: number, opts?: {
+        cross?: boolean;
+    }): Promise<{
+        status: "ok";
+        response: {
+            type: "default";
+        };
+    }>;
+    private symbols;
+    private lookup;
+    private requireUser;
+    /** The per-user agent PRIVATE key (deterministic from the agent secret + userId; never stored). */
+    agentKey(userId: string): Hex;
+    /** The agent ADDRESS the user must approve (show this in your connect/approve UI). */
+    agentAddress(userId: string): Hex;
+    /**
+     * A Hyperliquid bound to one end-user: it SIGNS orders with that user's agent key
+     * and READS/attributes to their `master` account. Use after the user has approved
+     * `agentAddress(userId)`. Trading methods (marketBuy/limit/closePosition/cancel/…)
+     * then act on the user's account; positions()/balance() default to `master`.
+     */
+    forUser(userId: string, master: string): Hyperliquid;
+}
+export {};