@exagent/agent 0.1.18 → 0.1.19

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Address, Hash } from 'viem';
+import { Address, Hash, WalletClient } from 'viem';
 import { ExagentClient } from '@exagent/sdk';
 
 declare const LLMProviderSchema: z.ZodEnum<["openai", "anthropic", "google", "deepseek", "mistral", "groq", "together", "ollama", "custom"]>;
@@ -91,6 +91,47 @@ declare const RelayConfigSchema: z.ZodOptional<z.ZodObject<{
     heartbeatIntervalMs?: number | undefined;
 }>>;
 type RelayConfig$1 = z.infer<typeof RelayConfigSchema>;
+declare const PerpConfigSchema: z.ZodOptional<z.ZodObject<{
+    /** Enable perp trading */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Hyperliquid REST API URL */
+    apiUrl: z.ZodDefault<z.ZodString>;
+    /** Hyperliquid WebSocket URL */
+    wsUrl: z.ZodDefault<z.ZodString>;
+    /** Builder address for fee collection (must have >= 100 USDC on HL) */
+    builderAddress: z.ZodString;
+    /** Builder fee in tenths of basis points (100 = 10 bps = 0.10%) */
+    builderFeeTenthsBps: z.ZodDefault<z.ZodNumber>;
+    /** Private key for the perp relayer (calls recordPerpTrade on Base). Falls back to agent wallet. */
+    perpRelayerKey: z.ZodOptional<z.ZodString>;
+    /** Maximum leverage per position (default: 10) */
+    maxLeverage: z.ZodDefault<z.ZodNumber>;
+    /** Maximum notional position size in USD (default: 50000) */
+    maxNotionalUSD: z.ZodDefault<z.ZodNumber>;
+    /** Allowed perp instruments (e.g. ["ETH", "BTC", "SOL"]). If empty, all instruments allowed. */
+    allowedInstruments: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    apiUrl: string;
+    wsUrl: string;
+    builderAddress: string;
+    builderFeeTenthsBps: number;
+    maxLeverage: number;
+    maxNotionalUSD: number;
+    perpRelayerKey?: string | undefined;
+    allowedInstruments?: string[] | undefined;
+}, {
+    builderAddress: string;
+    enabled?: boolean | undefined;
+    apiUrl?: string | undefined;
+    wsUrl?: string | undefined;
+    builderFeeTenthsBps?: number | undefined;
+    perpRelayerKey?: string | undefined;
+    maxLeverage?: number | undefined;
+    maxNotionalUSD?: number | undefined;
+    allowedInstruments?: string[] | undefined;
+}>>;
+type PerpConfig$1 = z.infer<typeof PerpConfigSchema>;
 declare const AgentConfigSchema: z.ZodObject<{
     agentId: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
     name: z.ZodString;
@@ -182,6 +223,46 @@ declare const AgentConfigSchema: z.ZodObject<{
         enabled?: boolean | undefined;
         heartbeatIntervalMs?: number | undefined;
     }>>;
+    perp: z.ZodOptional<z.ZodObject<{
+        /** Enable perp trading */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Hyperliquid REST API URL */
+        apiUrl: z.ZodDefault<z.ZodString>;
+        /** Hyperliquid WebSocket URL */
+        wsUrl: z.ZodDefault<z.ZodString>;
+        /** Builder address for fee collection (must have >= 100 USDC on HL) */
+        builderAddress: z.ZodString;
+        /** Builder fee in tenths of basis points (100 = 10 bps = 0.10%) */
+        builderFeeTenthsBps: z.ZodDefault<z.ZodNumber>;
+        /** Private key for the perp relayer (calls recordPerpTrade on Base). Falls back to agent wallet. */
+        perpRelayerKey: z.ZodOptional<z.ZodString>;
+        /** Maximum leverage per position (default: 10) */
+        maxLeverage: z.ZodDefault<z.ZodNumber>;
+        /** Maximum notional position size in USD (default: 50000) */
+        maxNotionalUSD: z.ZodDefault<z.ZodNumber>;
+        /** Allowed perp instruments (e.g. ["ETH", "BTC", "SOL"]). If empty, all instruments allowed. */
+        allowedInstruments: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        apiUrl: string;
+        wsUrl: string;
+        builderAddress: string;
+        builderFeeTenthsBps: number;
+        maxLeverage: number;
+        maxNotionalUSD: number;
+        perpRelayerKey?: string | undefined;
+        allowedInstruments?: string[] | undefined;
+    }, {
+        builderAddress: string;
+        enabled?: boolean | undefined;
+        apiUrl?: string | undefined;
+        wsUrl?: string | undefined;
+        builderFeeTenthsBps?: number | undefined;
+        perpRelayerKey?: string | undefined;
+        maxLeverage?: number | undefined;
+        maxNotionalUSD?: number | undefined;
+        allowedInstruments?: string[] | undefined;
+    }>>;
     allowedTokens: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     agentId: string | number;
@@ -220,6 +301,17 @@ declare const AgentConfigSchema: z.ZodObject<{
         apiUrl: string;
         heartbeatIntervalMs: number;
     } | undefined;
+    perp?: {
+        enabled: boolean;
+        apiUrl: string;
+        wsUrl: string;
+        builderAddress: string;
+        builderFeeTenthsBps: number;
+        maxLeverage: number;
+        maxNotionalUSD: number;
+        perpRelayerKey?: string | undefined;
+        allowedInstruments?: string[] | undefined;
+    } | undefined;
     allowedTokens?: string[] | undefined;
 }, {
     agentId: string | number;
@@ -258,6 +350,17 @@ declare const AgentConfigSchema: z.ZodObject<{
         enabled?: boolean | undefined;
         heartbeatIntervalMs?: number | undefined;
     } | undefined;
+    perp?: {
+        builderAddress: string;
+        enabled?: boolean | undefined;
+        apiUrl?: string | undefined;
+        wsUrl?: string | undefined;
+        builderFeeTenthsBps?: number | undefined;
+        perpRelayerKey?: string | undefined;
+        maxLeverage?: number | undefined;
+        maxNotionalUSD?: number | undefined;
+        allowedInstruments?: string[] | undefined;
+    } | undefined;
     allowedTokens?: string[] | undefined;
 }>;
 type AgentConfig = z.infer<typeof AgentConfigSchema>;
@@ -414,13 +517,13 @@ declare class VaultManager {
  * Used by both the SDK relay client and the API relay service.
  */
 type AgentMode = 'idle' | 'trading';
-type CommandType = 'start_trading' | 'stop_trading' | 'update_risk_params' | 'update_trading_interval' | 'create_vault' | 'refresh_status' | 'shutdown';
+type CommandType = 'start_trading' | 'stop_trading' | 'enable_hyperliquid' | 'disable_hyperliquid' | 'start_perp_trading' | 'stop_perp_trading' | 'update_risk_params' | 'update_perp_params' | 'update_trading_interval' | 'create_vault' | 'refresh_status' | 'shutdown';
 interface RelayCommand {
     id: string;
     type: CommandType;
     params?: Record<string, unknown>;
 }
-type MessageType = 'trade_executed' | 'trade_failed' | 'funds_low' | 'risk_limit_hit' | 'vault_created' | 'config_updated' | 'llm_error' | 'command_result' | 'system';
+type MessageType = 'trade_executed' | 'trade_failed' | 'perp_fill' | 'perp_liquidation_warning' | 'perp_funding' | 'funds_low' | 'risk_limit_hit' | 'vault_created' | 'config_updated' | 'llm_error' | 'command_result' | 'system';
 type MessageLevel = 'info' | 'warning' | 'error' | 'success';
 interface AgentStatusPayload {
     mode: AgentMode;
@@ -445,6 +548,16 @@ interface AgentStatusPayload {
         hasVault: boolean;
         vaultAddress: string | null;
     };
+    perp?: {
+        enabled: boolean;
+        trading: boolean;
+        equity: number;
+        unrealizedPnl: number;
+        marginUsed: number;
+        openPositions: number;
+        effectiveLeverage: number;
+        pendingRecords: number;
+    };
 }
 interface RelayConfig {
     enabled: boolean;
@@ -483,6 +596,16 @@ declare class AgentRuntime {
     private processAlive;
     private riskUniverse;
     private allowedTokens;
+    private perpClient;
+    private perpSigner;
+    private perpOrders;
+    private perpPositions;
+    private perpWebSocket;
+    private perpRecorder;
+    private perpOnboarding;
+    private perpStrategy;
+    private perpConnected;
+    private perpTradingActive;
     constructor(config: RuntimeConfig);
     /**
      * Initialize the agent runtime
@@ -496,6 +619,11 @@ declare class AgentRuntime {
      * Initialize the vault manager based on config
      */
     private initializeVaultManager;
+    /**
+     * Initialize Hyperliquid perp trading components.
+     * Only initializes if perp is enabled in config AND risk universe >= 2.
+     */
+    private initializePerp;
     /**
      * Ensure the current wallet is linked to the agent.
      * If the trading wallet differs from the owner, enters a recovery loop
@@ -537,6 +665,12 @@ declare class AgentRuntime {
      * Run a single trading cycle
      */
     private runCycle;
+    /**
+     * Run a single perp trading cycle.
+     * Fetches market data, positions, calls perp strategy, applies risk filters, executes.
+     * Fills arrive async via WebSocket and are auto-recorded on Base.
+     */
+    private runPerpCycle;
     /**
      * Check if ETH balance is below threshold and notify.
      * Returns true if trading should continue, false if ETH is critically low.
@@ -796,6 +930,174 @@ declare class TradeExecutor {
     private delay;
 }
 
+/**
+ * Hyperliquid Perp Trading Types
+ *
+ * Core type definitions for perp trading via Hyperliquid L1.
+ * Agents record fills on-chain via Router.recordPerpTrade() for leaderboard attribution.
+ */
+
+interface PerpConfig {
+    /** Enable perp trading */
+    enabled: boolean;
+    /** Hyperliquid REST API URL */
+    apiUrl: string;
+    /** Hyperliquid WebSocket URL */
+    wsUrl: string;
+    /** Builder address for fee collection (must have >= 100 USDC on HL) */
+    builderAddress: string;
+    /** Builder fee in tenths of basis points (100 = 10 bps = 0.10%) */
+    builderFeeTenthsBps: number;
+    /** Private key for the perp relayer (calls recordPerpTrade on Base). Falls back to agent wallet. */
+    perpRelayerKey?: string;
+    /** Maximum leverage per position (default: 10) */
+    maxLeverage: number;
+    /** Maximum notional position size in USD (default: 50000) */
+    maxNotionalUSD: number;
+    /** Allowed instruments (e.g. ["ETH", "BTC", "SOL"]). If empty, all instruments allowed. */
+    allowedInstruments?: string[];
+}
+type PerpAction = 'open_long' | 'open_short' | 'close_long' | 'close_short' | 'hold';
+interface PerpTradeSignal {
+    /** Trading action */
+    action: PerpAction;
+    /** Instrument symbol (e.g. "ETH", "BTC", "SOL") */
+    instrument: string;
+    /** Position size in base units (e.g. 1.5 ETH) */
+    size: number;
+    /** Limit price (0 = market order) */
+    price: number;
+    /** Leverage multiplier (1-50) */
+    leverage: number;
+    /** Order type */
+    orderType: 'limit' | 'market';
+    /** Only reduce existing position (close/partial close) */
+    reduceOnly: boolean;
+    /** Signal confidence (0.0 - 1.0) */
+    confidence: number;
+    /** LLM reasoning for this signal */
+    reasoning?: string;
+}
+interface PerpPosition {
+    /** Instrument symbol */
+    instrument: string;
+    /** Hyperliquid asset index */
+    assetIndex: number;
+    /** Position size (positive = long, negative = short) */
+    size: number;
+    /** Average entry price */
+    entryPrice: number;
+    /** Current mark price */
+    markPrice: number;
+    /** Unrealized PnL in USD */
+    unrealizedPnl: number;
+    /** Current leverage */
+    leverage: number;
+    /** Margin type */
+    marginType: 'cross' | 'isolated';
+    /** Estimated liquidation price */
+    liquidationPrice: number;
+    /** Notional value in USD (|size| * markPrice) */
+    notionalUSD: number;
+    /** Margin used for this position */
+    marginUsed: number;
+}
+interface AccountSummary {
+    /** Total account equity (cash + unrealized PnL) */
+    totalEquity: number;
+    /** Available margin for new positions */
+    availableMargin: number;
+    /** Total margin used across all positions */
+    totalMarginUsed: number;
+    /** Total unrealized PnL across all positions */
+    totalUnrealizedPnl: number;
+    /** Total notional exposure */
+    totalNotional: number;
+    /** Maintenance margin requirement */
+    maintenanceMargin: number;
+    /** Effective aggregate leverage (totalNotional / totalEquity) */
+    effectiveLeverage: number;
+    /** Cash balance (USDC) */
+    cashBalance: number;
+}
+interface PerpFill {
+    /** Order ID on Hyperliquid */
+    oid: number;
+    /** Instrument symbol */
+    coin: string;
+    /** Direction */
+    side: 'B' | 'A';
+    /** Fill price */
+    px: string;
+    /** Fill size */
+    sz: string;
+    /** Fee paid */
+    fee: string;
+    /** Fill timestamp (ms) */
+    time: number;
+    /** Fill hash from Hyperliquid */
+    hash: string;
+    /** Whether this was a maker fill */
+    isMaker: boolean;
+    /** Builder fee paid (if any) */
+    builderFee?: string;
+    /** Whether this was a liquidation */
+    liquidation?: boolean;
+}
+interface PerpMarketData {
+    /** Instrument symbol */
+    instrument: string;
+    /** Mid-market price */
+    midPrice: number;
+    /** Best bid */
+    bestBid: number;
+    /** Best ask */
+    bestAsk: number;
+    /** 8-hour funding rate */
+    funding8h: number;
+    /** Open interest in USD */
+    openInterest: number;
+    /** 24h volume in USD */
+    volume24h: number;
+    /** 24h price change (percentage) */
+    priceChange24h: number;
+}
+/**
+ * Perp strategy function signature.
+ * Called once per perp trading cycle.
+ *
+ * @param marketData - Current market data for allowed instruments
+ * @param positions - Current open positions
+ * @param account - Account equity and margin state
+ * @param llm - LLM adapter for reasoning
+ * @param config - Agent configuration
+ * @returns Array of perp trade signals
+ */
+type PerpStrategyFunction = (marketData: PerpMarketData[], positions: PerpPosition[], account: AccountSummary, llm: LLMAdapter, config: Record<string, unknown>) => Promise<PerpTradeSignal[]>;
+interface OrderResult {
+    /** Whether the order was accepted */
+    success: boolean;
+    /** Hyperliquid order ID */
+    orderId?: number;
+    /** Fill status */
+    status: 'filled' | 'resting' | 'error';
+    /** Average fill price (if filled) */
+    avgPrice?: string;
+    /** Total filled size (if filled) */
+    filledSize?: string;
+    /** Error message (if error) */
+    error?: string;
+}
+interface RecordPerpTradeParams {
+    agentId: bigint;
+    configHash: `0x${string}`;
+    instrument: string;
+    isLong: boolean;
+    notionalUSD: bigint;
+    feeUSD: bigint;
+    fillId: `0x${string}`;
+}
+
 /**
  * Risk Manager
  * Applies guardrails to trade signals before execution
@@ -850,6 +1152,26 @@ declare class RiskManager {
         dailyLossLimit: number;
         isLimitHit: boolean;
     };
+    /**
+     * Filter perp trade signals through risk checks.
+     * Reduce-only signals (closes) always pass.
+     *
+     * @param signals - Raw perp signals from strategy
+     * @param positions - Current open positions on Hyperliquid
+     * @param account - Current account equity and margin
+     * @param maxLeverage - Maximum allowed leverage
+     * @param maxNotionalUSD - Maximum notional per position
+     * @returns Signals that pass risk checks
+     */
+    filterPerpSignals(signals: PerpTradeSignal[], positions: PerpPosition[], account: AccountSummary, maxLeverage: number, maxNotionalUSD: number): PerpTradeSignal[];
+    /**
+     * Validate an individual perp signal.
+     */
+    private validatePerpSignal;
+    /**
+     * Calculate liquidation proximity for a position (0.0 = safe, 1.0 = liquidated).
+     */
+    private calculateLiquidationProximity;
 }
 
 /**
@@ -983,6 +1305,520 @@ declare class RelayClient {
     disconnect(): void;
 }
 
+/**
+ * Hyperliquid REST Client
+ *
+ * Wraps @nktkas/hyperliquid for Info + Exchange API access.
+ * Handles meta caching, asset index lookups, and typed responses.
+ */
+
+declare class HyperliquidClient {
+    private readonly apiUrl;
+    private meta;
+    private assetIndexCache;
+    constructor(config: PerpConfig);
+    /** Fetch perpetuals metadata (asset specs, names, indices) */
+    getMeta(): Promise<AssetMeta[]>;
+    /** Get asset index from symbol (e.g. "ETH" -> 1). Caches after first getMeta() call. */
+    getAssetIndex(coin: string): Promise<number>;
+    /** Get mid-market prices for all perpetuals */
+    getAllMids(): Promise<Record<string, string>>;
+    /** Get clearinghouse state (positions, margin, equity) for a user */
+    getClearinghouseState(user: string): Promise<ClearinghouseState>;
+    /** Get user's recent fills */
+    getUserFills(user: string, startTime?: number): Promise<HyperliquidFill[]>;
+    /** Get user's fills in a time range */
+    getUserFillsByTime(user: string, startTime: number, endTime?: number): Promise<HyperliquidFill[]>;
+    /** Get user's open orders */
+    getOpenOrders(user: string): Promise<HyperliquidOrder[]>;
+    /** Get user's funding history */
+    getUserFunding(user: string, startTime: number): Promise<HyperliquidFunding[]>;
+    /** Check max approved builder fee for a user */
+    getMaxBuilderFee(user: string, builder: string): Promise<number>;
+    /** Get L2 order book for a coin */
+    getL2Book(coin: string, depth?: number): Promise<L2Book>;
+    /** Get parsed positions for a user address */
+    getPositions(user: string): Promise<PerpPosition[]>;
+    /** Get account summary (equity, margin, leverage) */
+    getAccountSummary(user: string): Promise<AccountSummary>;
+    /** Get market data for a list of instruments */
+    getMarketData(instruments: string[]): Promise<PerpMarketData[]>;
+    /** Convert fills to our PerpFill type */
+    parseFill(fill: HyperliquidFill): PerpFill;
+    private parsePosition;
+    private infoRequest;
+}
+interface AssetMeta {
+    name: string;
+    szDecimals: number;
+    maxLeverage: number;
+    onlyIsolated: boolean;
+}
+interface ClearinghouseState {
+    assetPositions: AssetPosition[];
+    crossMarginSummary: {
+        accountValue: string;
+        totalNtlPos: string;
+        totalRawUsd: string;
+        totalMarginUsed: string;
+    };
+}
+interface AssetPosition {
+    position: {
+        coin: string;
+        szi: string;
+        entryPx: string;
+        positionValue: string;
+        unrealizedPnl: string;
+        liquidationPx: string | null;
+        marginUsed: string;
+        leverage: {
+            type: string;
+            value: string;
+        } | null;
+    };
+}
+interface HyperliquidFill {
+    coin: string;
+    px: string;
+    sz: string;
+    side: 'B' | 'A';
+    time: number;
+    startPosition: string;
+    dir: string;
+    closedPnl: string;
+    hash: string;
+    oid: number;
+    crossed: boolean;
+    fee: string;
+    tid: number;
+    builderFee?: string;
+    liquidation?: boolean;
+}
+interface HyperliquidOrder {
+    coin: string;
+    side: 'B' | 'A';
+    limitPx: string;
+    sz: string;
+    oid: number;
+    timestamp: number;
+    origSz: string;
+    cloid: string | null;
+}
+interface HyperliquidFunding {
+    time: number;
+    coin: string;
+    usdc: string;
+    szi: string;
+    fundingRate: string;
+}
+interface L2Book {
+    coin: string;
+    levels: Array<Array<{
+        px: string;
+        sz: string;
+        n: number;
+    }>>;
+    time: number;
+}
+
+/**
+ * Hyperliquid EIP-712 Signer
+ *
+ * Handles EIP-712 signing for Hyperliquid L1 actions (orders, cancels, transfers).
+ * Uses viem's signTypedData for compatibility with our existing wallet infrastructure.
+ *
+ * Key details:
+ * - Domain chainId is ALWAYS 42161 (Arbitrum), regardless of user's actual chain
+ * - Nonces are timestamp-based (milliseconds), NOT sequential
+ * - Hyperliquid stores the 100 highest nonces per address
+ */
+
+/** Hyperliquid's fixed EIP-712 domain (never changes) */
+declare const HYPERLIQUID_DOMAIN: {
+    readonly name: "HyperliquidSignTransaction";
+    readonly version: "1";
+    readonly chainId: 42161n;
+    readonly verifyingContract: `0x${string}`;
+};
+/**
+ * Generate a timestamp-based nonce.
+ * Ensures strictly increasing nonces even when called in rapid succession.
+ */
+declare function getNextNonce(): bigint;
+declare class HyperliquidSigner {
+    private readonly walletClient;
+    constructor(walletClient: WalletClient);
+    /**
+     * Sign an exchange action (order, cancel, etc.)
+     *
+     * @param action - The action object (will be JSON-serialized)
+     * @param nonce - Nonce (defaults to current timestamp)
+     * @returns Signature hex string
+     */
+    signAction(action: Record<string, unknown>, nonce?: bigint): Promise<{
+        signature: `0x${string}`;
+        nonce: bigint;
+    }>;
+    /**
+     * Sign a user-level approval action (approve builder fee, approve agent).
+     * These use the same EIP-712 structure but with different action payloads.
+     */
+    signApproval(action: Record<string, unknown>, nonce?: bigint): Promise<{
+        signature: `0x${string}`;
+        nonce: bigint;
+    }>;
+    /**
+     * Get the signer's address
+     */
+    getAddress(): `0x${string}`;
+}
+/**
+ * Convert a Hyperliquid fill hash to a bytes32 fill ID for on-chain recording.
+ * Uses keccak256 to ensure consistent 32-byte output.
+ */
+declare function fillHashToBytes32(fillHash: string): `0x${string}`;
+/**
+ * Convert a fill OID to a bytes32 fill ID (fallback if no hash available).
+ */
+declare function fillOidToBytes32(oid: number): `0x${string}`;
+
+/**
+ * Hyperliquid Order Management
+ *
+ * Handles order placement, cancellation, and leverage updates on Hyperliquid L1.
+ * All orders include builder fee for monetization.
+ * Fills are recorded on Base via the recorder module.
+ */
+
+declare class OrderManager {
+    private readonly client;
+    private readonly signer;
+    private readonly config;
+    constructor(client: HyperliquidClient, signer: HyperliquidSigner, config: PerpConfig);
+    /**
+     * Place an order on Hyperliquid from a trade signal.
+     * Attaches builder fee for revenue collection.
+     */
+    placeOrder(signal: PerpTradeSignal): Promise<OrderResult>;
+    /**
+     * Cancel an open order by ID.
+     */
+    cancelOrder(instrument: string, orderId: number): Promise<boolean>;
+    /**
+     * Close an entire position for an instrument.
+     * Uses a market order with reduceOnly flag.
+     */
+    closePosition(instrument: string, positionSize: number): Promise<OrderResult>;
+    /**
+     * Update leverage for an instrument.
+     */
+    updateLeverage(instrument: string, leverage: number, isCross?: boolean): Promise<boolean>;
+    /**
+     * Get a market price string for IOC orders.
+     * Uses a generous slippage buffer to ensure fills.
+     */
+    private getMarketPrice;
+    /**
+     * Parse Hyperliquid exchange response into OrderResult.
+     */
+    private parseOrderResponse;
+    /**
+     * Send a signed request to the Hyperliquid Exchange API.
+     */
+    private exchangeRequest;
+}
+
+/**
+ * Hyperliquid Position Tracking
+ *
+ * Provides high-level position management, account summary,
+ * and liquidation proximity monitoring.
+ */
+
+declare class PositionManager {
+    private readonly client;
+    private readonly userAddress;
+    /** Cached positions (updated each cycle) */
+    private cachedPositions;
+    private cachedAccount;
+    private lastRefreshAt;
+    /** Cache TTL in ms (5 seconds — positions refresh each cycle anyway) */
+    private readonly cacheTtlMs;
+    constructor(client: HyperliquidClient, userAddress: string);
+    /**
+     * Get all open positions. Uses cache if fresh.
+     */
+    getPositions(forceRefresh?: boolean): Promise<PerpPosition[]>;
+    /**
+     * Get a specific position by instrument.
+     * Returns null if no position is open.
+     */
+    getPosition(instrument: string): Promise<PerpPosition | null>;
+    /**
+     * Get account summary (equity, margin, leverage).
+     */
+    getAccountSummary(forceRefresh?: boolean): Promise<AccountSummary>;
+    /**
+     * Get liquidation proximity for all positions.
+     * Returns a value between 0.0 (safe) and 1.0 (at liquidation price).
+     * Values above 0.7 should trigger risk warnings.
+     */
+    getLiquidationProximity(): Promise<Map<string, number>>;
+    /**
+     * Check if any position is dangerously close to liquidation.
+     * Returns instruments with proximity > threshold.
+     */
+    getDangerousPositions(threshold?: number): Promise<PerpPosition[]>;
+    /**
+     * Get total unrealized PnL across all positions.
+     */
+    getTotalUnrealizedPnl(): Promise<number>;
+    /**
+     * Get total notional exposure.
+     */
+    getTotalNotional(): Promise<number>;
+    /**
+     * Get position count.
+     */
+    getPositionCount(): Promise<number>;
+    /**
+     * Force refresh positions and account from Hyperliquid.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Check if cache is still fresh.
+     */
+    private isCacheFresh;
+}
+
+/**
+ * Hyperliquid WebSocket Client
+ *
+ * Subscribes to real-time fill and funding events.
+ * Auto-reconnects with exponential backoff.
+ * Checkpoints last processed fill time for REST backfill on reconnect.
+ */
+
+type FillCallback = (fill: PerpFill) => void;
+type FundingCallback = (funding: FundingPayment) => void;
+type LiquidationCallback = (instrument: string, size: number) => void;
+interface FundingPayment {
+    time: number;
+    coin: string;
+    usdc: string;
+    szi: string;
+    fundingRate: string;
+}
+declare class HyperliquidWebSocket {
+    private readonly wsUrl;
+    private readonly userAddress;
+    private readonly client;
+    private ws;
+    private reconnectAttempts;
+    private readonly maxReconnectAttempts;
+    private readonly baseReconnectMs;
+    private readonly maxReconnectMs;
+    private reconnectTimer;
+    private pingTimer;
+    private isConnecting;
+    private shouldReconnect;
+    /** Last processed fill time (ms) — used for REST backfill on reconnect */
+    private lastProcessedFillTime;
+    /** Callbacks */
+    private onFill;
+    private onFunding;
+    private onLiquidation;
+    constructor(config: PerpConfig, userAddress: string, client: HyperliquidClient);
+    /**
+     * Connect to Hyperliquid WebSocket and subscribe to user events.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect and stop reconnecting.
+     */
+    disconnect(): void;
+    /**
+     * Check if WebSocket is connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Register callback for fill events.
+     */
+    onFillReceived(callback: FillCallback): void;
+    /**
+     * Register callback for funding payment events.
+     */
+    onFundingReceived(callback: FundingCallback): void;
+    /**
+     * Register callback for liquidation events.
+     */
+    onLiquidationDetected(callback: LiquidationCallback): void;
+    /**
+     * Get the last processed fill time (for external checkpoint management).
+     */
+    getLastProcessedFillTime(): number;
+    private handleMessage;
+    private handleFillMessage;
+    private handleFundingMessage;
+    /**
+     * Backfill fills that may have been missed during WebSocket downtime.
+     * Uses the last processed fill time as the starting point.
+     */
+    private backfillMissedFills;
+    private scheduleReconnect;
+    private startPing;
+    private stopPing;
+    private subscribe;
+}
+
+/**
+ * Perp Trade Recorder
+ *
+ * Records Hyperliquid perp fills on Base via Router.recordPerpTrade().
+ * This is what makes perp trades visible on the leaderboard and indexer.
+ *
+ * Key details:
+ * - Each fill is individually recorded on-chain
+ * - Fill ID deduplication prevents double-recording (contract enforces)
+ * - Retry queue handles transient failures
+ * - notionalUSD = px * sz * 1e6 (6-decimal)
+ * - feeUSD = fee * 1e6 (6-decimal)
+ */
+
+declare class PerpTradeRecorder {
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly account;
+    private readonly agentId;
+    private configHash;
+    /** Retry queue for failed recordings */
+    private retryQueue;
+    /** Set of fill IDs already recorded (or in-progress) to prevent local dups */
+    private recordedFills;
+    /** Timer for processing retry queue */
+    private retryTimer;
+    constructor(opts: {
+        privateKey: `0x${string}`;
+        rpcUrl?: string;
+        agentId: bigint;
+        configHash: `0x${string}`;
+    });
+    /**
+     * Record a fill on-chain.
+     * Converts the Hyperliquid fill into recordPerpTrade params and submits.
+     */
+    recordFill(fill: PerpFill): Promise<{
+        success: boolean;
+        txHash?: string;
+        error?: string;
+    }>;
+    /**
+     * Update the config hash (when epoch changes).
+     */
+    updateConfigHash(configHash: `0x${string}`): void;
+    /**
+     * Get the number of fills pending retry.
+     */
+    get pendingRetries(): number;
+    /**
+     * Get the number of fills recorded (local dedup set size).
+     */
+    get recordedCount(): number;
+    /**
+     * Stop the recorder (clear retry timer).
+     */
+    stop(): void;
+    /**
+     * Submit a recordPerpTrade transaction on Base.
+     */
+    private submitRecord;
+    /**
+     * Process the retry queue — attempt to re-submit failed recordings.
+     */
+    private processRetryQueue;
+    /**
+     * Calculate notional USD from a fill (6-decimal).
+     * notionalUSD = px * sz * 1e6
+     */
+    private calculateNotionalUSD;
+    /**
+     * Calculate fee USD from a fill (6-decimal).
+     * feeUSD = fee * 1e6 (fee is already in USD on Hyperliquid)
+     */
+    private calculateFeeUSD;
+}
+
+/**
+ * Hyperliquid Onboarding
+ *
+ * Handles one-time setup tasks for perp trading:
+ * - Builder fee approval (required before orders with builder fee)
+ * - Balance verification
+ * - Risk universe check (perps require universe >= 2)
+ */
+
+declare class PerpOnboarding {
+    private readonly client;
+    private readonly signer;
+    private readonly config;
+    constructor(client: HyperliquidClient, signer: HyperliquidSigner, config: PerpConfig);
+    /**
+     * Check if the user has approved the builder fee.
+     * Builder fee must be approved before orders can include builder fees.
+     */
+    isBuilderFeeApproved(): Promise<boolean>;
+    /**
+     * Approve the builder fee on Hyperliquid.
+     * This is a one-time approval per builder address.
+     */
+    approveBuilderFee(): Promise<boolean>;
+    /**
+     * Check if the user has sufficient USDC balance on Hyperliquid.
+     * Returns the account equity in USD.
+     */
+    checkBalance(): Promise<{
+        hasBalance: boolean;
+        equity: number;
+    }>;
+    /**
+     * Verify that the agent's risk universe allows perp trading.
+     * Perps require risk universe >= 2 (Derivatives or higher).
+     */
+    verifyRiskUniverse(riskUniverse: number): {
+        allowed: boolean;
+        message: string;
+    };
+    /**
+     * Run all onboarding checks and return status.
+     * Does NOT auto-approve — caller must explicitly approve after review.
+     */
+    checkOnboardingStatus(riskUniverse: number): Promise<OnboardingStatus>;
+    /**
+     * Run full onboarding: check status and auto-approve builder fee if needed.
+     * Returns the final status after all actions.
+     */
+    onboard(riskUniverse: number): Promise<OnboardingStatus>;
+}
+interface OnboardingStatus {
+    /** Whether the agent is fully ready for perp trading */
+    ready: boolean;
+    /** Whether risk universe allows perps */
+    riskUniverseOk: boolean;
+    /** Risk universe message */
+    riskUniverseMessage: string;
+    /** Whether user has USDC balance on Hyperliquid */
+    hasBalance: boolean;
+    /** Account equity in USD */
+    equity: number;
+    /** Whether builder fee is approved */
+    builderFeeApproved: boolean;
+    /** Builder address */
+    builderAddress: string;
+    /** Builder fee in bps */
+    builderFeeBps: number;
+}
+
 /**
  * Secure Environment Storage
  *
@@ -1025,4 +1861,4 @@ declare function decryptEnvFile(encPath: string, passphrase: string): Record<str
  */
 declare function loadSecureEnv(basePath: string, passphrase?: string): boolean;
 
-export { type AgentConfig, AgentConfigSchema, type AgentMode, AgentRuntime, type AgentStatusPayload, AnthropicAdapter, BaseLLMAdapter, type CommandType, DeepSeekAdapter, GoogleAdapter, GroqAdapter, type LLMAdapter, type LLMConfig, LLMConfigSchema, type LLMMessage, type LLMMetadata, type LLMProvider, LLMProviderSchema, type LLMResponse, type MarketData, MarketDataService, type MessageLevel, type MessageType, MistralAdapter, OllamaAdapter, OpenAIAdapter, RelayClient, type RelayCommand, type RelayConfig$1 as RelayConfig, RelayConfigSchema, RiskManager, type RiskUniverse, RiskUniverseSchema, type RuntimeConfig, STRATEGY_TEMPLATES, type StrategyFunction, type StrategyTemplate, TogetherAdapter, TradeExecutor, type TradeSignal, type TradingConfig, TradingConfigSchema, type VaultConfig, VaultConfigSchema, VaultManager, type VaultManagerConfig, type VaultPolicy, VaultPolicySchema, type VaultStatus, createLLMAdapter, createSampleConfig, decryptEnvFile, encryptEnvFile, getAllStrategyTemplates, getStrategyTemplate, loadConfig, loadSecureEnv, loadStrategy, validateConfig, validateStrategy };
+export { type AccountSummary, type AgentConfig, AgentConfigSchema, type AgentMode, AgentRuntime, type AgentStatusPayload, AnthropicAdapter, BaseLLMAdapter, type CommandType, DeepSeekAdapter, type FillCallback, type FundingCallback, type FundingPayment, GoogleAdapter, GroqAdapter, HYPERLIQUID_DOMAIN, HyperliquidClient, HyperliquidSigner, HyperliquidWebSocket, type LLMAdapter, type LLMConfig, LLMConfigSchema, type LLMMessage, type LLMMetadata, type LLMProvider, LLMProviderSchema, type LLMResponse, type LiquidationCallback, type MarketData, MarketDataService, type MessageLevel, type MessageType, MistralAdapter, OllamaAdapter, type OnboardingStatus, OpenAIAdapter, OrderManager, type OrderResult, type PerpAction, type PerpConfig$1 as PerpConfig, PerpConfigSchema, type PerpFill, type PerpMarketData, PerpOnboarding, type PerpPosition, type PerpStrategyFunction, PerpTradeRecorder, type PerpTradeSignal, type PerpConfig as PerpTradingConfig, PositionManager, type RecordPerpTradeParams, RelayClient, type RelayCommand, type RelayConfig$1 as RelayConfig, RelayConfigSchema, RiskManager, type RiskUniverse, RiskUniverseSchema, type RuntimeConfig, STRATEGY_TEMPLATES, type StrategyFunction, type StrategyTemplate, TogetherAdapter, TradeExecutor, type TradeSignal, type TradingConfig, TradingConfigSchema, type VaultConfig, VaultConfigSchema, VaultManager, type VaultManagerConfig, type VaultPolicy, VaultPolicySchema, type VaultStatus, createLLMAdapter, createSampleConfig, decryptEnvFile, encryptEnvFile, fillHashToBytes32, fillOidToBytes32, getAllStrategyTemplates, getNextNonce, getStrategyTemplate, loadConfig, loadSecureEnv, loadStrategy, validateConfig, validateStrategy };