openbroker 1.0.73 → 1.0.79

package/scripts/core/client.ts

@@ -37,6 +37,12 @@ export class HyperliquidClient {
   private hip3MaxLeverageMap: Map<string, number> = new Map();
   /** Cached account abstraction mode: 'standard' | 'unified' | 'portfolio' | 'dexAbstraction' */
   private accountMode: string | null = null;
+  /** Spot asset index map: coin name → 10000 + spotMeta.universe[i].index */
+  private spotAssetMap: Map<string, number> = new Map();
+  /** Spot szDecimals map: coin name → base token szDecimals */
+  private spotSzDecimalsMap: Map<string, number> = new Map();
+  /** Whether spot metadata has been loaded */
+  private spotMetaLoaded: boolean = false;
   public verbose: boolean = false;
 
   constructor(config?: OpenBrokerConfig) {
@@ -412,6 +418,68 @@ export class HyperliquidClient {
     };
   }
 
+  /**
+   * 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 async loadSpotMeta(): Promise<void> {
+    if (this.spotMetaLoaded) return;
+
+    try {
+      const spotData = await this.getSpotMeta();
+      // Build token lookup for szDecimals
+      const tokenMap = new Map<number, { name: string; szDecimals: number }>();
+      for (const token of spotData.tokens) {
+        tokenMap.set(token.index, { name: token.name, szDecimals: token.szDecimals });
+      }
+
+      for (const pair of spotData.universe) {
+        // pair.name is the market name (e.g., "PURR/USDC", "@107")
+        // pair.tokens = [baseTokenIndex, quoteTokenIndex]
+        // pair.index is the spot universe index
+        const baseToken = tokenMap.get(pair.tokens[0]);
+        if (!baseToken) continue;
+
+        const spotAssetIndex = 10000 + pair.index;
+        const quoteTokenIdx = pair.tokens[1];
+
+        // A token can appear in multiple pairs (e.g., HYPE/USDC, HYPE/USDE, HYPE/USDH).
+        // Prefer the USDC pair (quote token index 0) for the primary mapping.
+        const existing = this.spotAssetMap.get(baseToken.name);
+        if (existing !== undefined && quoteTokenIdx !== 0) {
+          // Already have a mapping — skip non-USDC pairs
+          continue;
+        }
+
+        this.spotAssetMap.set(baseToken.name, spotAssetIndex);
+        this.spotSzDecimalsMap.set(baseToken.name, baseToken.szDecimals);
+
+        this.log(`Spot: ${baseToken.name} → asset ${spotAssetIndex} (szDecimals: ${baseToken.szDecimals})`);
+      }
+
+      this.spotMetaLoaded = true;
+      this.log(`Loaded ${this.spotAssetMap.size} spot markets`);
+    } catch (e) {
+      this.log('Failed to load spot metadata:', e);
+    }
+  }
+
+  /** Get the spot asset index for a coin, or undefined if not a spot asset */
+  getSpotAssetIndex(coin: string): number | undefined {
+    return this.spotAssetMap.get(coin);
+  }
+
+  /** Get spot szDecimals for a coin */
+  getSpotSzDecimals(coin: string): number | undefined {
+    return this.spotSzDecimalsMap.get(coin);
+  }
+
+  /** Get all loaded spot asset names */
+  getSpotAssetNames(): string[] {
+    return Array.from(this.spotAssetMap.keys());
+  }
+
   /**
    * Get user's spot token balances
    */
@@ -1598,6 +1666,183 @@ export class HyperliquidClient {
     return results;
   }
 
+  // ============ Spot Trading ============
+
+  /**
+   * 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)
+   */
+  async spotOrder(
+    coin: string,
+    isBuy: boolean,
+    size: number,
+    price: number,
+    orderType: { limit: { tif: 'Gtc' | 'Ioc' | 'Alo' } },
+    includeBuilder: boolean = true,
+  ): Promise<OrderResponse> {
+    this.requireTrading();
+    await this.loadSpotMeta();
+
+    const assetIndex = this.spotAssetMap.get(coin);
+    if (assetIndex === undefined) {
+      throw new Error(
+        `Unknown spot asset: ${coin}. Available: ${Array.from(this.spotAssetMap.keys()).slice(0, 15).join(', ')}...\n` +
+        `Use "openbroker spot" to see all spot markets.`
+      );
+    }
+
+    const szDecimals = this.spotSzDecimalsMap.get(coin)!;
+
+    const orderWire = {
+      a: assetIndex,
+      b: isBuy,
+      p: roundPrice(price, szDecimals, true),
+      s: roundSize(size, szDecimals),
+      r: false, // reduce-only not applicable for spot
+      t: orderType,
+    };
+
+    this.log('Placing spot order:', JSON.stringify(orderWire, null, 2));
+
+    const orderRequest: {
+      orders: typeof orderWire[];
+      grouping: 'na';
+      builder?: BuilderInfo;
+    } = {
+      orders: [orderWire],
+      grouping: 'na',
+    };
+
+    // Add builder fee if configured (spot max is 1000 vs 100 for perps)
+    if (includeBuilder && this.config.builderAddress !== '0x0000000000000000000000000000000000000000') {
+      orderRequest.builder = this.builderInfo;
+      this.log('Including builder fee:', this.builderInfo);
+    }
+
+    try {
+      const response = await this.exchange.order(orderRequest);
+      this.log('Spot order response:', JSON.stringify(response, null, 2));
+      return response as unknown as OrderResponse;
+    } catch (error) {
+      this.log('Spot order error:', error);
+      return {
+        status: 'err',
+        response: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * 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)
+   */
+  async spotMarketOrder(
+    coin: string,
+    isBuy: boolean,
+    size: number,
+    slippageBps?: number,
+  ): Promise<OrderResponse> {
+    await this.loadSpotMeta();
+
+    // Get the spot pair name (@index or PURR/USDC) for allMids lookup
+    const assetIndex = this.spotAssetMap.get(coin);
+    if (assetIndex === undefined) {
+      throw new Error(`Unknown spot asset: ${coin}. Use "openbroker spot" to see available markets.`);
+    }
+    const spotPairIndex = assetIndex - 10000;
+    // Canonical PURR/USDC is index 0, everything else uses @index
+    const spotCoinKey = spotPairIndex === 0 ? 'PURR/USDC' : `@${spotPairIndex}`;
+
+    // Use allMids for accurate live prices (spotMetaAndAssetCtxs contexts can be misaligned)
+    const mids = await this.getAllMids();
+    const midStr = mids[spotCoinKey];
+    const midPrice = midStr ? parseFloat(midStr) : 0;
+
+    if (!midPrice || midPrice === 0) {
+      throw new Error(`No spot price for ${coin} (${spotCoinKey}). Check if the spot market exists with "openbroker spot --coin ${coin}".`);
+    }
+
+    // Calculate slippage price
+    const slippage = (slippageBps ?? this.config.slippageBps) / 10000;
+    const limitPrice = isBuy
+      ? midPrice * (1 + slippage)
+      : midPrice * (1 - slippage);
+
+    this.log(`Spot market order: ${coin} ${isBuy ? 'BUY' : 'SELL'} ${size} @ ${limitPrice} (mid: ${midPrice}, slippage: ${slippage * 100}%)`);
+
+    return this.spotOrder(
+      coin,
+      isBuy,
+      size,
+      limitPrice,
+      { limit: { tif: 'Ioc' } },
+    );
+  }
+
+  /**
+   * 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)
+   */
+  async spotLimitOrder(
+    coin: string,
+    isBuy: boolean,
+    size: number,
+    price: number,
+    tif: 'Gtc' | 'Ioc' | 'Alo' = 'Gtc',
+  ): Promise<OrderResponse> {
+    return this.spotOrder(
+      coin,
+      isBuy,
+      size,
+      price,
+      { limit: { tif } },
+    );
+  }
+
+  /**
+   * Cancel a spot order by coin and order ID.
+   */
+  async spotCancel(coin: string, oid: number): Promise<CancelResponse> {
+    this.requireTrading();
+    await this.loadSpotMeta();
+
+    const assetIndex = this.spotAssetMap.get(coin);
+    if (assetIndex === undefined) {
+      throw new Error(`Unknown spot asset: ${coin}`);
+    }
+
+    this.log(`Cancelling spot order: ${coin} (asset ${assetIndex}) oid ${oid}`);
+
+    try {
+      const response = await this.exchange.cancel({
+        cancels: [{ a: assetIndex, o: oid }],
+      });
+      this.log('Spot cancel response:', JSON.stringify(response, null, 2));
+      return response as unknown as CancelResponse;
+    } catch (error) {
+      this.log('Spot cancel error:', error);
+      return {
+        status: 'err',
+        response: { type: 'cancel', data: { statuses: [error instanceof Error ? error.message : String(error)] } },
+      };
+    }
+  }
+
   // ============ Leverage ============
 
   async updateLeverage(

package/scripts/core/ws.ts

@@ -0,0 +1,308 @@
+// WebSocket Manager for Hyperliquid real-time data
+// Wraps @nktkas/hyperliquid SubscriptionClient with event-driven API
+
+import { WebSocketTransport, SubscriptionClient } from '@nktkas/hyperliquid';
+import type { ISubscription } from '@nktkas/hyperliquid';
+import type {
+  AllMidsWsEvent,
+  L2BookWsEvent,
+  OrderUpdatesWsEvent,
+  UserFillsWsEvent,
+  UserEventsWsEvent,
+} from '@nktkas/hyperliquid';
+import { isMainnet } from './config.js';
+
+// ── Event types ────────────────────────────────────────────────────
+
+export interface WsEventMap {
+  /** L2 order book snapshot for a specific coin */
+  l2Book: {
+    coin: string;
+    time: number;
+    levels: [
+      Array<{ px: string; sz: string; n: number }>,
+      Array<{ px: string; sz: string; n: number }>,
+    ];
+  };
+  /** Mid prices for all assets updated */
+  allMids: { mids: Record<string, string> };
+  /** Order status changed (filled, canceled, rejected, etc.) */
+  orderUpdate: {
+    order: {
+      coin: string;
+      side: 'B' | 'A';
+      limitPx: string;
+      sz: string;
+      oid: number;
+      timestamp: number;
+      origSz: string;
+      cloid?: string;
+      reduceOnly?: boolean;
+    };
+    status: string;
+    statusTimestamp: number;
+  };
+  /** Trade fill received */
+  userFill: {
+    coin: string;
+    px: string;
+    sz: string;
+    side: 'B' | 'A';
+    time: number;
+    closedPnl: string;
+    fee: string;
+    oid: number;
+    crossed: boolean;
+  };
+  /** User event (fills, funding, liquidation, non-user cancels) */
+  userEvent: UserEventsWsEvent;
+  /** WebSocket connected */
+  connected: undefined;
+  /** WebSocket disconnected */
+  disconnected: { reason?: string };
+  /** WebSocket error */
+  error: { error: Error };
+}
+
+export type WsEventType = keyof WsEventMap;
+export type WsEventHandler<E extends WsEventType> = (data: WsEventMap[E]) => void;
+
+// ── Manager ────────────────────────────────────────────────────────
+
+export class WebSocketManager {
+  private transport: WebSocketTransport | null = null;
+  private client: SubscriptionClient | null = null;
+  private subscriptions: ISubscription[] = [];
+  private handlers = new Map<WsEventType, Set<Function>>();
+  private _connected = false;
+  private verbose: boolean;
+
+  constructor(verbose = false) {
+    this.verbose = verbose;
+  }
+
+  private log(...args: unknown[]) {
+    if (this.verbose) console.log('[WS]', ...args);
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  // ── Connection management ──────────────────────────────────────
+
+  async connect(): Promise<void> {
+    if (this.transport) return; // already connected
+
+    this.transport = new WebSocketTransport({
+      isTestnet: !isMainnet(),
+      resubscribe: true, // auto-resubscribe on reconnect
+    });
+
+    this.client = new SubscriptionClient({ transport: this.transport });
+
+    await this.transport.ready();
+    this._connected = true;
+    this.emit('connected', undefined);
+    this.log('Connected to', isMainnet() ? 'mainnet' : 'testnet');
+  }
+
+  async close(): Promise<void> {
+    for (const sub of this.subscriptions) {
+      try { await sub.unsubscribe(); } catch { /* ignore */ }
+    }
+    this.subscriptions = [];
+
+    if (this.transport) {
+      try { await this.transport.close(); } catch { /* ignore */ }
+      this.transport = null;
+      this.client = null;
+    }
+
+    this._connected = false;
+    this.emit('disconnected', { reason: 'manual close' });
+    this.log('Closed');
+  }
+
+  // ── Event system ───────────────────────────────────────────────
+
+  on<E extends WsEventType>(event: E, handler: WsEventHandler<E>): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+  }
+
+  off<E extends WsEventType>(event: E, handler: WsEventHandler<E>): void {
+    this.handlers.get(event)?.delete(handler);
+  }
+
+  private emit<E extends WsEventType>(event: E, data: WsEventMap[E]): void {
+    const set = this.handlers.get(event);
+    if (!set) return;
+    for (const handler of set) {
+      try {
+        handler(data);
+      } catch (err) {
+        this.log('Handler error:', err instanceof Error ? err.message : String(err));
+        this.emit('error' as E, { error: err instanceof Error ? err : new Error(String(err)) } as WsEventMap[E]);
+      }
+    }
+  }
+
+  removeAllListeners(): void {
+    this.handlers.clear();
+  }
+
+  // ── Subscription helpers ───────────────────────────────────────
+
+  private ensureClient(): SubscriptionClient {
+    if (!this.client) throw new Error('WebSocket not connected. Call connect() first.');
+    return this.client;
+  }
+
+  private trackSub(sub: ISubscription): ISubscription {
+    this.subscriptions.push(sub);
+    sub.failureSignal.addEventListener('abort', () => {
+      this.log('Subscription failed, removing from tracked list');
+      const idx = this.subscriptions.indexOf(sub);
+      if (idx >= 0) this.subscriptions.splice(idx, 1);
+    });
+    return sub;
+  }
+
+  // ── Market data subscriptions ──────────────────────────────────
+
+  /**
+   * Subscribe to mid prices for all assets. Fires on every price update.
+   */
+  async subscribeAllMids(): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.allMids((data: AllMidsWsEvent) => {
+      this.emit('allMids', { mids: data.mids });
+    });
+    return this.trackSub(sub);
+  }
+
+  /**
+   * Subscribe to L2 order book snapshots for a specific coin.
+   */
+  async subscribeL2Book(coin: string): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.l2Book({ coin }, (data: L2BookWsEvent) => {
+      this.emit('l2Book', {
+        coin: data.coin,
+        time: data.time,
+        levels: data.levels,
+      });
+    });
+    return this.trackSub(sub);
+  }
+
+  // ── User subscriptions ────────────────────────────────────────
+
+  /**
+   * Subscribe to order lifecycle events (fill, cancel, reject, etc.).
+   * This is the most important subscription for trading automations.
+   */
+  async subscribeOrderUpdates(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.orderUpdates({ user }, (data: OrderUpdatesWsEvent) => {
+      for (const update of data) {
+        this.emit('orderUpdate', {
+          order: {
+            coin: update.order.coin,
+            side: update.order.side,
+            limitPx: update.order.limitPx,
+            sz: update.order.sz,
+            oid: update.order.oid,
+            timestamp: update.order.timestamp,
+            origSz: update.order.origSz,
+            cloid: update.order.cloid,
+            reduceOnly: update.order.reduceOnly,
+          },
+          status: update.status,
+          statusTimestamp: update.statusTimestamp,
+        });
+      }
+    });
+    return this.trackSub(sub);
+  }
+
+  /**
+   * Subscribe to trade fills for a user.
+   */
+  async subscribeUserFills(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.userFills({ user }, (data: UserFillsWsEvent) => {
+      if (data.isSnapshot) return; // skip initial snapshot
+      for (const fill of data.fills) {
+        this.emit('userFill', {
+          coin: fill.coin,
+          px: fill.px,
+          sz: fill.sz,
+          side: fill.side,
+          time: fill.time,
+          closedPnl: fill.closedPnl,
+          fee: fill.fee,
+          oid: fill.oid,
+          crossed: fill.crossed,
+        });
+      }
+    });
+    return this.trackSub(sub);
+  }
+
+  /**
+   * Subscribe to all user events (fills, funding, liquidations, non-user cancels).
+   * This is the only way to get liquidation alerts.
+   */
+  async subscribeUserEvents(user: `0x${string}`): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.userEvents({ user }, (data: UserEventsWsEvent) => {
+      this.emit('userEvent', data);
+    });
+    return this.trackSub(sub);
+  }
+
+  // ── Convenience: subscribe to all relevant feeds for an automation ──
+
+  /**
+   * Start all subscriptions needed for the automation runtime:
+   * - allMids (price feed)
+   * - orderUpdates (order lifecycle)
+   * - userFills (trade fills)
+   * - userEvents (liquidations, funding payments, system cancels)
+   */
+  async subscribeAll(user: `0x${string}`): Promise<void> {
+    await this.connect();
+    this.log('Subscribing to all feeds for', user);
+
+    await Promise.all([
+      this.subscribeAllMids(),
+      this.subscribeOrderUpdates(user),
+      this.subscribeUserFills(user),
+      this.subscribeUserEvents(user),
+    ]);
+
+    this.log('All subscriptions active');
+  }
+}
+
+// ── Singleton ──────────────────────────────────────────────────────
+
+let wsInstance: WebSocketManager | null = null;
+
+export function getWebSocket(verbose = false): WebSocketManager {
+  if (!wsInstance) {
+    wsInstance = new WebSocketManager(verbose);
+  }
+  return wsInstance;
+}
+
+export function resetWebSocket(): void {
+  if (wsInstance) {
+    wsInstance.close().catch(() => {});
+    wsInstance = null;
+  }
+}

package/scripts/info/account.ts

@@ -52,6 +52,11 @@ async function main() {
 
     const totalPnl = positions.reduce((sum, p) => sum + p.unrealizedPnl, 0);
 
+    // Fetch spot balances
+    const userParam = isOtherAccount ? lookupAddress : undefined;
+    const spotState = await client.getSpotBalances(userParam);
+    const spotBalances = (spotState?.balances ?? []).filter(b => parseFloat(b.total) > 0);
+
     // JSON output
     if (jsonOutput) {
       const result: Record<string, unknown> = {
@@ -68,6 +73,12 @@ async function main() {
         marginRatio: totalMarginUsed > 0 && accountValue > 0 ? totalMarginUsed / accountValue : 0,
         totalUnrealizedPnl: totalPnl,
         positions,
+        spotBalances: spotBalances.map(b => ({
+          coin: b.coin,
+          total: b.total,
+          hold: b.hold,
+          entryNtl: b.entryNtl,
+        })),
       };
 
       if (args.orders) {
@@ -166,6 +177,23 @@ async function main() {
       console.log(`Total Unrealized PnL: ${formatUsd(totalPnl)}`);
     }
 
+    // Show spot balances
+    if (spotBalances.length > 0) {
+      console.log('\nSpot Balances');
+      console.log('-------------');
+      console.log('Token        | Total              | Hold               | Entry Value');
+      console.log('-------------|--------------------|--------------------|------------');
+
+      for (const b of spotBalances) {
+        const total = parseFloat(b.total);
+        const hold = parseFloat(b.hold);
+        const entry = parseFloat(b.entryNtl);
+        console.log(
+          `${b.coin.padEnd(12)} | ${total.toFixed(6).padStart(18)} | ${hold.toFixed(6).padStart(18)} | ${formatUsd(entry)}`
+        );
+      }
+    }
+
     // Show open orders if requested
     if (args.orders) {
       console.log('\nOpen Orders');

package/scripts/info/funding-history.ts

@@ -73,9 +73,9 @@ async function main() {
 
       console.log(
         time.padEnd(20) +
-        formatPercent(rate * 100, 6).padEnd(16) +
-        formatPercent(annualized * 100).padEnd(14) +
-        formatPercent(premium * 100, 4)
+        formatPercent(rate, 6).padEnd(16) +
+        formatPercent(annualized).padEnd(14) +
+        formatPercent(premium, 4)
       );
     }
 
@@ -85,8 +85,8 @@ async function main() {
 
     console.log('─'.repeat(60));
     console.log(`Samples: ${history.length}`);
-    console.log(`Avg Hourly Rate:  ${formatPercent(avgRate * 100, 6)}`);
-    console.log(`Avg Annualized:   ${formatPercent(avgAnnualized * 100)}`);
+    console.log(`Avg Hourly Rate:  ${formatPercent(avgRate, 6)}`);
+    console.log(`Avg Annualized:   ${formatPercent(avgAnnualized)}`);
 
     if (avgRate > 0) {
       console.log('Longs pay shorts');

package/scripts/info/search-markets.ts

@@ -157,16 +157,40 @@ async function main() {
   if (args.type === 'all' || args.type === 'spot') {
     try {
       const spotData = await client.getSpotMetaAndAssetCtxs();
-      for (let i = 0; i < spotData.meta.universe.length; i++) {
-        const pair = spotData.meta.universe[i];
-        const ctx = spotData.assetCtxs[i];
-        if (!pair || !ctx) continue;
 
-        if (pair.name.toUpperCase().includes(query)) {
+      // Build token index → name lookup for matching by base token name
+      const tokenNameMap = new Map<number, string>();
+      for (const token of spotData.meta.tokens) {
+        tokenNameMap.set(token.index, token.name);
+      }
+
+      // Build ctx map by coin name (contexts have a 'coin' field that matches pair.name).
+      // The contexts array can be longer than universe and is NOT aligned by index.
+      const ctxMap = new Map<string, (typeof spotData.assetCtxs)[number]>();
+      for (const ctx of spotData.assetCtxs) {
+        if ((ctx as Record<string, unknown>).coin) {
+          ctxMap.set((ctx as Record<string, unknown>).coin as string, ctx);
+        }
+      }
+
+      for (const pair of spotData.meta.universe) {
+        if (!pair) continue;
+        const ctx = ctxMap.get(pair.name);
+        if (!ctx) continue;
+
+        // Match against pair name, base token name, and quote token name
+        const baseTokenName = tokenNameMap.get(pair.tokens[0]) ?? '';
+        const quoteTokenName = tokenNameMap.get(pair.tokens[1]) ?? '';
+        const searchable = `${pair.name} ${baseTokenName} ${quoteTokenName}`.toUpperCase();
+
+        if (searchable.includes(query)) {
+          const displayName = baseTokenName && quoteTokenName
+            ? `${baseTokenName}/${quoteTokenName}`
+            : pair.name;
           results.push({
             type: 'spot',
             provider: 'Spot',
-            coin: pair.name,
+            coin: displayName,
             price: ctx.markPx,
             volume24h: parseFloat(ctx.dayNtlVlm || '0'),
           });