openbroker 1.3.1 → 1.4.0

package/dist/core/client.d.ts

@@ -0,0 +1,684 @@
+import type { OpenBrokerConfig, BuilderInfo, OrderResponse, CancelResponse, MetaAndAssetCtxs, ClearinghouseState, OpenOrder, OutcomeMetaResponse, OutcomeMarket } from './types.js';
+export declare class HyperliquidClient {
+    private config;
+    private account;
+    private transport;
+    private info;
+    private exchange;
+    private meta;
+    private assetMap;
+    private szDecimalsMap;
+    /** Maps coin name → dex info for HIP-3 assets. Main dex assets have dexName=null */
+    private coinDexMap;
+    /** Cache of perpDexs list */
+    private perpDexsCache;
+    /** Whether HIP-3 assets have been loaded into maps */
+    private hip3Loaded;
+    /** Whether API wallet setup has been validated */
+    private apiWalletValidated;
+    /** Set of HIP-3 dex names that have been loaded (for testnet on-demand loading) */
+    private loadedHip3Dexes;
+    /** HIP-3 assets that have had isolated margin set this session */
+    private hip3IsolatedSet;
+    /** Cached maxLeverage for HIP-3 assets */
+    private hip3MaxLeverageMap;
+    /** Cached account abstraction mode: 'standard' | 'unified' | 'portfolio' | 'dexAbstraction' */
+    private accountMode;
+    /** Spot asset index map: coin name → 10000 + spotMeta.universe[i].index */
+    private spotAssetMap;
+    /** Spot market key map: coin name → pair.name (e.g. "@230", "PURR/USDC") */
+    private spotPairNameMap;
+    /** Spot szDecimals map: coin name → base token szDecimals */
+    private spotSzDecimalsMap;
+    /** Whether spot metadata has been loaded */
+    private spotMetaLoaded;
+    /** HIP-4 outcome metadata cache */
+    private outcomeMeta;
+    verbose: boolean;
+    constructor(config?: OpenBrokerConfig);
+    private log;
+    private describeError;
+    /** Retry an async operation on transient failures (fetch failed, ECONNRESET, etc.) */
+    private withRetry;
+    private getTransportContext;
+    private postInfo;
+    /** The address we're trading on behalf of (may be different from wallet if using API wallet) */
+    get address(): string;
+    /** The address of the signing wallet (derived from private key) */
+    get walletAddress(): string;
+    /** Whether we're using an API wallet (signing wallet differs from trading account) */
+    get isApiWallet(): boolean;
+    get builderInfo(): BuilderInfo;
+    get builderAddress(): string;
+    get builderFeeBps(): number;
+    /** Whether client is in read-only mode (no trading capability) */
+    get isReadOnly(): boolean;
+    /** Whether connected to testnet (HIP-3 dexes not auto-loaded) */
+    get isTestnet(): boolean;
+    /**
+     * Returns vaultAddress param for SDK exchange calls.
+     * Only used for vault trading (HYPERLIQUID_VAULT_ADDRESS set explicitly).
+     * Standard API wallets (agents) do NOT need this — the API maps agent → master automatically.
+     */
+    private get vaultParam();
+    /** Throw error if trying to trade in read-only mode. Validates API wallet on first call. */
+    private requireTrading;
+    getMetaAndAssetCtxs(): Promise<MetaAndAssetCtxs>;
+    /**
+     * Load HIP-3 perp dex assets into the asset/szDecimals maps.
+     * Asset index formula: 100000 + dexIdx * 10000 + assetIdx
+     * Coins are keyed as "dexName:COIN" (e.g., "xyz:CL")
+     */
+    /** Max concurrent HIP-3 API requests to avoid rate limiting */
+    private static readonly HIP3_CONCURRENCY;
+    /**
+     * Like Promise.allSettled but with a concurrency limit.
+     * Processes tasks in batches to avoid hitting API rate limits.
+     */
+    private batchSettled;
+    /**
+     * Load HIP-3 perp dex assets into the asset/szDecimals maps.
+     * On testnet: skips auto-loading (too many junk dexes). Use loadSingleHip3Dex() on demand.
+     * On mainnet: loads all dexes with concurrency limit.
+     */
+    private loadHip3Assets;
+    /**
+     * Load a single HIP-3 dex by name (on-demand, e.g. when user references "felix:BTC").
+     * No-op if already loaded.
+     */
+    loadSingleHip3Dex(dexName: string): Promise<boolean>;
+    /**
+     * Get HIP-3 dexes to iterate over for bulk queries.
+     * Mainnet: all dexes. Testnet: only explicitly loaded dexes.
+     */
+    private getIterableHip3Dexs;
+    /** Register a fetched HIP-3 dex's assets into lookup maps */
+    private registerHip3Dex;
+    getAllMids(): Promise<Record<string, string>>;
+    /**
+     * Get all perpetual DEXs (including HIP-3 builder-deployed markets)
+     * Returns array where index 0 is null (main dex), others are HIP-3 dexs
+     */
+    getPerpDexs(): Promise<Array<{
+        name: string;
+        fullName: string;
+        deployer: string;
+    } | null>>;
+    /**
+     * Get all perp markets including HIP-3 dexs
+     * Returns array of [meta, assetCtxs] for each dex
+     */
+    getAllPerpMetas(): Promise<Array<{
+        dexName: string | null;
+        meta: {
+            universe: Array<{
+                name: string;
+                szDecimals: number;
+                maxLeverage: number;
+                onlyIsolated?: boolean;
+            }>;
+        };
+        assetCtxs: Array<{
+            funding: string;
+            openInterest: string;
+            markPx: string;
+            midPx: string | null;
+            oraclePx: string;
+            prevDayPx: string;
+            dayNtlVlm: string;
+        }>;
+    }>>;
+    /**
+     * Get spot market metadata
+     */
+    getSpotMeta(): Promise<{
+        tokens: Array<{
+            name: string;
+            szDecimals: number;
+            weiDecimals: number;
+            index: number;
+            tokenId: string;
+            isCanonical: boolean;
+            fullName: string | null;
+        }>;
+        universe: Array<{
+            name: string;
+            tokens: [number, number];
+            index: number;
+            isCanonical: boolean;
+        }>;
+    }>;
+    /**
+     * Get spot metadata with asset contexts (prices, volumes)
+     */
+    getSpotMetaAndAssetCtxs(): Promise<{
+        meta: {
+            tokens: Array<{
+                name: string;
+                szDecimals: number;
+                weiDecimals: number;
+                index: number;
+                tokenId: string;
+                isCanonical: boolean;
+            }>;
+            universe: Array<{
+                name: string;
+                tokens: [number, number];
+                index: number;
+                isCanonical: boolean;
+            }>;
+        };
+        assetCtxs: Array<{
+            coin?: string;
+            dayNtlVlm: string;
+            markPx: string;
+            midPx: string;
+            prevDayPx: string;
+        }>;
+    }>;
+    private parseOutcomeDescription;
+    private normalizeOutcomeSide;
+    getOutcomeEncoding(outcome: number, side: 0 | 1): number;
+    getOutcomeCoin(outcome: number, side: 0 | 1): string;
+    getOutcomeAssetId(outcome: number, side: 0 | 1): number;
+    resolveOutcomeRef(ref: string | number, side?: string | number): {
+        outcome: number;
+        side: 0 | 1;
+        encoding: number;
+        coin: string;
+        tokenName: string;
+        assetId: number;
+    };
+    getOutcomeMeta(): Promise<OutcomeMetaResponse>;
+    private getOutcomeCtxMap;
+    getOutcomeMarkets(): Promise<OutcomeMarket[]>;
+    getOutcomeMarket(outcomeId: number): Promise<OutcomeMarket | null>;
+    getOutcomeSzDecimals(outcome: number, side: 0 | 1): Promise<number>;
+    getOutcomeMidPrice(outcome: number, side: 0 | 1): Promise<number>;
+    /**
+     * Load spot metadata into lookup maps.
+     * Spot asset index for orders = 10000 + universe[i].index
+     * Uses the base token's szDecimals for size rounding.
+     */
+    private loadSpotMeta;
+    /** Get the spot asset index for a coin, or undefined if not a spot asset */
+    getSpotAssetIndex(coin: string): number | undefined;
+    /** Get the preferred spot market key for a coin (e.g. "@230", "PURR/USDC") */
+    getSpotMarketKey(coin: string): string | undefined;
+    /** Get spot szDecimals for a coin */
+    getSpotSzDecimals(coin: string): number | undefined;
+    /** Get all loaded spot asset names */
+    getSpotAssetNames(): string[];
+    /**
+     * Get user's spot token balances
+     */
+    getSpotBalances(user?: string): Promise<{
+        balances: Array<{
+            coin: string;
+            token: number;
+            hold: string;
+            total: string;
+            entryNtl: string;
+        }>;
+    }>;
+    /**
+     * Get token details by token ID
+     */
+    getTokenDetails(tokenId: string): Promise<{
+        name: string;
+        maxSupply: string;
+        totalSupply: string;
+        circulatingSupply: string;
+        szDecimals: number;
+        weiDecimals: number;
+        midPx: string;
+        markPx: string;
+        prevDayPx: string;
+        deployer: string;
+        deployTime: string;
+    } | null>;
+    /**
+     * Get predicted funding rates across venues
+     */
+    getPredictedFundings(): Promise<Array<[
+        string,
+        Array<[string, {
+            fundingRate: string;
+            nextFundingTime: number;
+        }]>
+    ]>>;
+    /**
+     * Get L2 order book for an asset
+     * Returns best bid/ask and depth
+     */
+    getL2Book(coin: string): Promise<{
+        bids: Array<{
+            px: string;
+            sz: string;
+            n: number;
+        }>;
+        asks: Array<{
+            px: string;
+            sz: string;
+            n: number;
+        }>;
+        bestBid: number;
+        bestAsk: number;
+        midPrice: number;
+        spread: number;
+        spreadBps: number;
+    }>;
+    getAssetIndexAsync(coin: string): Promise<number>;
+    getAssetIndex(coin: string): number;
+    getSzDecimalsAsync(coin: string): Promise<number>;
+    getSzDecimals(coin: string): number;
+    /**
+     * Find HIP-3 assets matching a bare coin name (without dex prefix)
+     */
+    private findHip3Matches;
+    /**
+     * Get the dex name for a coin (null for main dex assets)
+     */
+    getCoinDex(coin: string): string | null;
+    /**
+     * Get the local (unprefixed) coin name for API calls that need it
+     * e.g., "xyz:CL" → "CL", "ETH" → "ETH"
+     */
+    getCoinLocalName(coin: string): string;
+    /**
+     * Check if a coin is a HIP-3 asset
+     */
+    isHip3(coin: string): boolean;
+    /**
+     * Invalidate cached metadata so next call fetches fresh data.
+     * Useful for long-running strategies that need updated funding rates.
+     */
+    invalidateMetaCache(): void;
+    /**
+     * Get all loaded asset names (main + HIP-3)
+     */
+    getAllAssetNames(): string[];
+    /**
+     * Get all HIP-3 asset names
+     */
+    getHip3AssetNames(): string[];
+    /**
+     * Get the account's abstraction mode.
+     * Returns: 'standard' | 'unified' | 'portfolio' | 'dexAbstraction'
+     * Unified accounts have a single USDC balance shared across all dexes.
+     * Standard accounts have separate balances per dex (need sendAsset transfers).
+     */
+    getAccountMode(user?: string): Promise<string>;
+    /** Whether the account uses unified balances (unified or portfolio margin) */
+    isUnifiedAccount(user?: string): Promise<boolean>;
+    /**
+     * Query the role of an address on HyperCore L1.
+     * Returns: "user" | "agent" | "vault" | "subAccount" | "missing"
+     * Useful for verifying API wallet (agent) registration.
+     */
+    getUserRole(address?: string): Promise<{
+        role: string;
+        data?: Record<string, string>;
+    }>;
+    /**
+     * Validate API wallet setup: check that the signing wallet is recognized
+     * as an "agent" on HyperCore and the account address exists.
+     * Logs warnings if misconfigured.
+     */
+    validateApiWalletSetup(): Promise<{
+        valid: boolean;
+        walletRole: string;
+        accountRole: string;
+    }>;
+    /**
+     * Check if an address has sub-accounts (is a master account)
+     * Sub-accounts cannot approve builder fees - only master accounts can
+     */
+    getSubAccounts(user?: string): Promise<Array<{
+        subAccountUser: string;
+        name: string;
+    }>>;
+    /**
+     * Check the maximum builder fee approved for a user/builder pair
+     * Returns the max fee rate as a string (e.g., "0.1%") or null if not approved
+     */
+    getMaxBuilderFee(user?: string, builder?: string): Promise<string | null>;
+    /**
+     * Approve a builder fee for the open-broker builder
+     * IMPORTANT: This must be signed by a MAIN wallet, not an API wallet or sub-account
+     *
+     * @param maxFeeRate - Max fee rate to approve (e.g., "0.01%" for 1 bps)
+     * @param builder - Builder address (defaults to open-broker builder)
+     */
+    approveBuilderFee(maxFeeRate?: string, builder?: string): Promise<{
+        status: 'ok' | 'err';
+        response?: unknown;
+    }>;
+    /**
+     * Get user funding ledger updates
+     * Returns array of funding payments received/paid per position
+     */
+    getUserFunding(user?: string, startTime?: number, endTime?: number): Promise<Array<{
+        time: number;
+        hash: string;
+        delta: {
+            type: 'funding';
+            coin: string;
+            usdc: string;
+            szi: string;
+            fundingRate: string;
+            nSamples: number | null;
+        };
+    }>>;
+    /**
+     * Get user trade fills
+     */
+    getUserFills(user?: string, aggregateByTime?: boolean): Promise<Array<{
+        coin: string;
+        px: string;
+        sz: string;
+        side: 'B' | 'A';
+        time: number;
+        startPosition: string;
+        dir: string;
+        closedPnl: string;
+        fee: string;
+        hash: string;
+        oid: number;
+        tid: number;
+        crossed: boolean;
+        feeToken: string;
+        twapId: number | null;
+        cloid: string | null;
+        builderFee: string | null;
+    }>>;
+    /**
+     * Get historical orders (all statuses)
+     */
+    getHistoricalOrders(user?: string): Promise<Array<{
+        order: {
+            coin: string;
+            side: string;
+            limitPx: string;
+            sz: string;
+            origSz: string;
+            oid: number;
+            timestamp: number;
+            orderType: string;
+            tif: string | null;
+            cloid: string | null;
+            triggerCondition: string;
+            triggerPx: string;
+            isTrigger: boolean;
+            isPositionTpsl: boolean;
+            reduceOnly: boolean;
+            children: unknown[];
+        };
+        status: string;
+        statusTimestamp: number;
+    }>>;
+    /**
+     * Get status of a specific order by OID or CLOID
+     */
+    getOrderStatus(oid: number | string, user?: string): Promise<{
+        status: string;
+        order?: {
+            order: {
+                coin: string;
+                side: string;
+                limitPx: string;
+                sz: string;
+                origSz: string;
+                oid: number;
+                timestamp: number;
+                orderType: string;
+                tif: string | null;
+                cloid: string | null;
+                triggerCondition: string;
+                triggerPx: string;
+                isTrigger: boolean;
+                isPositionTpsl: boolean;
+                reduceOnly: boolean;
+            };
+            status: string;
+            statusTimestamp: number;
+        };
+    }>;
+    /**
+     * Get user fee schedule and volume info
+     */
+    getUserFees(user?: string): Promise<{
+        dailyUserVlm: Array<{
+            date: string;
+            exchange: string;
+            userCross: string;
+            userAdd: string;
+        }>;
+        feeSchedule: Record<string, unknown>;
+        userCrossRate: string;
+        userAddRate: string;
+        userSpotCrossRate: string;
+        userSpotAddRate: string;
+        activeReferralDiscount: string;
+        trial: unknown;
+        feeTrialEscrow: string;
+        nextTrialAvailableTimestamp: unknown;
+        stakingLink: {
+            stakingUser: string;
+            status: string;
+        } | null;
+        activeStakingDiscount: {
+            basisPoints: number;
+            discountRate: string;
+        } | null;
+    }>;
+    /**
+     * Get OHLCV candle data for an asset
+     */
+    getCandleSnapshot(coin: string, interval: string, startTime: number, endTime?: number): Promise<Array<{
+        t: number;
+        T: number;
+        s: string;
+        i: string;
+        o: string;
+        c: string;
+        h: string;
+        l: string;
+        v: string;
+        n: number;
+    }>>;
+    /**
+     * Get historical funding rates for an asset
+     */
+    getFundingHistory(coin: string, startTime: number, endTime?: number): Promise<Array<{
+        coin: string;
+        fundingRate: string;
+        premium: string;
+        time: number;
+    }>>;
+    /**
+     * Get recent trades for an asset
+     */
+    getRecentTrades(coin: string): Promise<Array<{
+        coin: string;
+        side: 'B' | 'A';
+        px: string;
+        sz: string;
+        time: number;
+        hash: string;
+        tid: number;
+    }>>;
+    /**
+     * Get user API rate limit status
+     */
+    getUserRateLimit(user?: string): Promise<{
+        cumVlm: string;
+        nRequestsUsed: number;
+        nRequestsCap: number;
+        nRequestsSurplus: number;
+    }>;
+    getUserState(user?: string, dex?: string): Promise<ClearinghouseState>;
+    /**
+     * Get user state across all dexes (main + HIP-3).
+     * For unified accounts: equity comes from spotClearinghouseState (single USDC balance).
+     * For standard accounts: aggregates margin summaries from each dex.
+     */
+    getUserStateAll(user?: string): Promise<ClearinghouseState>;
+    getOpenOrders(user?: string): Promise<OpenOrder[]>;
+    /**
+     * HIP-3 perps: prepare for trading.
+     * 1. Set isolated margin mode (required for HIP-3)
+     * 2. For standard accounts only: transfer USDC from main perp to HIP-3 dex
+     *    (unified accounts share USDC across all dexes automatically)
+     */
+    private ensureHip3Ready;
+    order(coin: string, isBuy: boolean, size: number, price: number, orderType: {
+        limit: {
+            tif: 'Gtc' | 'Ioc' | 'Alo';
+        };
+    }, reduceOnly?: boolean, includeBuilder?: boolean, leverage?: number): Promise<OrderResponse>;
+    marketOrder(coin: string, isBuy: boolean, size: number, slippageBps?: number, leverage?: number): Promise<OrderResponse>;
+    limitOrder(coin: string, isBuy: boolean, size: number, price: number, tif?: 'Gtc' | 'Ioc' | 'Alo', reduceOnly?: boolean, leverage?: number): Promise<OrderResponse>;
+    /**
+     * Place a trigger order (stop loss or take profit)
+     * @param coin - Asset to trade
+     * @param isBuy - True for buy, false for sell
+     * @param size - Order size
+     * @param triggerPrice - Price at which the order triggers
+     * @param limitPrice - Limit price for the order (use triggerPrice for market-like execution)
+     * @param tpsl - 'tp' for take profit, 'sl' for stop loss
+     * @param reduceOnly - Whether order is reduce-only (should be true for TP/SL)
+     */
+    triggerOrder(coin: string, isBuy: boolean, size: number, triggerPrice: number, limitPrice: number, tpsl: 'tp' | 'sl', reduceOnly?: boolean, leverage?: number): Promise<OrderResponse>;
+    /**
+     * Place a stop loss order
+     */
+    stopLoss(coin: string, isBuy: boolean, size: number, triggerPrice: number, slippageBps?: number): Promise<OrderResponse>;
+    /**
+     * Place a take profit order
+     */
+    takeProfit(coin: string, isBuy: boolean, size: number, triggerPrice: number): Promise<OrderResponse>;
+    cancel(coin: string, oid: number): Promise<CancelResponse>;
+    cancelAll(coin?: string): Promise<CancelResponse[]>;
+    /**
+     * Place a spot order.
+     * Uses the same exchange.order() endpoint but with spot asset indices (10000 + spotIndex).
+     * Spot orders have no leverage, no reduce-only, and builder fee max is 1000 (vs 100 for perps).
+     *
+     * @param coin - Base token symbol (e.g. "PURR", "HYPE")
+     * @param isBuy - True to buy base token, false to sell
+     * @param size - Size in base token units
+     * @param price - Limit price in quote token (usually USDC)
+     * @param orderType - Order type with time-in-force
+     * @param includeBuilder - Whether to include builder fee (default: true)
+     */
+    spotOrder(coin: string, isBuy: boolean, size: number, price: number, orderType: {
+        limit: {
+            tif: 'Gtc' | 'Ioc' | 'Alo';
+        };
+    }, includeBuilder?: boolean): Promise<OrderResponse>;
+    /**
+     * Place a spot market order (IOC at slippage price).
+     * @param coin - Base token symbol (e.g. "PURR", "HYPE")
+     * @param isBuy - True to buy, false to sell
+     * @param size - Size in base token units
+     * @param slippageBps - Slippage tolerance in basis points (default: config value)
+     */
+    spotMarketOrder(coin: string, isBuy: boolean, size: number, slippageBps?: number): Promise<OrderResponse>;
+    /**
+     * Place a spot limit order.
+     * @param coin - Base token symbol (e.g. "PURR", "HYPE")
+     * @param isBuy - True to buy, false to sell
+     * @param size - Size in base token units
+     * @param price - Limit price in quote token (usually USDC)
+     * @param tif - Time-in-force (default: Gtc)
+     */
+    spotLimitOrder(coin: string, isBuy: boolean, size: number, price: number, tif?: 'Gtc' | 'Ioc' | 'Alo'): Promise<OrderResponse>;
+    /**
+     * Place a HIP-4 outcome order.
+     * Outcome assets are spot-like, but encoded as:
+     *   encoding = 10 * outcome + side
+     *   assetId = 100_000_000 + encoding
+     *   coin = #<encoding>
+     *
+     * Side 0 is usually YES and side 1 is usually NO, per outcomeMeta.sideSpecs.
+     */
+    outcomeOrder(outcomeRef: string | number, outcomeSide: string | number | undefined, isBuy: boolean, size: number, price: number, orderType: {
+        limit: {
+            tif: 'Gtc' | 'Ioc' | 'Alo';
+        };
+    }, includeBuilder?: boolean, szDecimalsOverride?: number): Promise<OrderResponse>;
+    outcomeMarketOrder(outcomeRef: string | number, outcomeSide: string | number | undefined, isBuy: boolean, size: number, slippageBps?: number, szDecimalsOverride?: number): Promise<OrderResponse>;
+    outcomeLimitOrder(outcomeRef: string | number, outcomeSide: string | number | undefined, isBuy: boolean, size: number, price: number, tif?: 'Gtc' | 'Ioc' | 'Alo', szDecimalsOverride?: number): Promise<OrderResponse>;
+    /**
+     * Cancel a spot order by coin and order ID.
+     */
+    spotCancel(coin: string, oid: number): Promise<CancelResponse>;
+    updateLeverage(coin: string, leverage: number, isCross?: boolean): Promise<unknown>;
+    /**
+     * Place a native Hyperliquid TWAP order.
+     * The exchange handles slicing and timing server-side.
+     * @param coin Asset symbol (e.g. "ETH")
+     * @param isBuy true for long, false for short
+     * @param size Total size in base currency
+     * @param durationMinutes Duration in minutes (5–1440)
+     * @param randomize Enable random order timing
+     * @param reduceOnly Reduce-only flag
+     * @param leverage Optional leverage to set before placing the TWAP
+     */
+    twapOrder(coin: string, isBuy: boolean, size: number, durationMinutes: number, randomize?: boolean, reduceOnly?: boolean, leverage?: number): Promise<{
+        status: "ok";
+        response: {
+            type: "twapOrder";
+            data: {
+                status: {
+                    running: {
+                        twapId: number;
+                    };
+                };
+            };
+        };
+    }>;
+    /**
+     * Cancel a running TWAP order.
+     * @param coin Asset symbol (e.g. "ETH")
+     * @param twapId The TWAP order ID to cancel
+     */
+    twapCancel(coin: string, twapId: number): Promise<{
+        status: "ok";
+        response: {
+            type: "twapCancel";
+            data: {
+                status: string;
+            };
+        };
+    }>;
+    /**
+     * Get TWAP order history for the current user.
+     */
+    twapHistory(): Promise<{
+        time: number;
+        state: {
+            coin: string;
+            executedNtl: string;
+            executedSz: string;
+            minutes: number;
+            randomize: boolean;
+            reduceOnly: boolean;
+            side: "B" | "A";
+            sz: string;
+            timestamp: number;
+            user: `0x${string}`;
+        };
+        status: {
+            status: "finished" | "activated" | "terminated";
+        } | {
+            status: "error";
+            description: string;
+        };
+        twapId?: number | undefined;
+    }[]>;
+}
+export declare function getClient(config?: OpenBrokerConfig): HyperliquidClient;
+export declare function resetClient(): void;
+//# sourceMappingURL=client.d.ts.map