openbroker 1.0.75 → 1.0.79

package/SKILL.md

@@ -4,8 +4,8 @@ description: Hyperliquid trading plugin with background position monitoring and
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.75", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
-allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.79", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_spot_buy ob_spot_sell ob_twap ob_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI

package/bin/cli.ts

@@ -47,6 +47,9 @@ const commands: Record<string, { script: string; description: string }> = {
   'scale': { script: 'operations/scale.ts', description: 'Scale in/out orders' },
   'bracket': { script: 'operations/bracket.ts', description: 'Bracket order (entry + TP + SL)' },
   'chase': { script: 'operations/chase.ts', description: 'Chase order with ALO' },
+  'spot-buy': { script: 'operations/spot-order.ts', description: 'Spot buy order' },
+  'spot-sell': { script: 'operations/spot-order.ts', description: 'Spot sell order' },
+  'spot-order': { script: 'operations/spot-order.ts', description: 'Spot order (market or limit)' },
 
   // Automations
   'auto': { script: 'auto/cli.ts', description: 'Run/manage trading automations' },
@@ -88,6 +91,11 @@ Trading Commands:
   tpsl                 Set TP/SL on existing position
   cancel               Cancel orders
 
+Spot Trading:
+  spot-buy             Spot buy order
+  spot-sell            Spot sell order
+  spot-order           Spot order (market or limit, specify --side)
+
 Advanced Execution:
   twap                 Native TWAP order (exchange-managed)
   twap-cancel          Cancel a running TWAP order
@@ -167,6 +175,14 @@ function main() {
     runScript(commands['market'].script, ['--side', 'sell', ...commandArgs]);
     return;
   }
+  if (command === 'spot-buy') {
+    runScript(commands['spot-order'].script, ['--side', 'buy', ...commandArgs]);
+    return;
+  }
+  if (command === 'spot-sell') {
+    runScript(commands['spot-order'].script, ['--side', 'sell', ...commandArgs]);
+    return;
+  }
 
   // Handle version
   if (command === '--version' || command === '-v') {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openbroker",
   "name": "OpenBroker — Hyperliquid Trading",
-  "version": "1.0.75",
+  "version": "1.0.79",
   "description": "Trade on Hyperliquid DEX with background position monitoring",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.75",
+  "version": "1.0.79",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {

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

@@ -5,6 +5,7 @@ import { WebSocketTransport, SubscriptionClient } from '@nktkas/hyperliquid';
 import type { ISubscription } from '@nktkas/hyperliquid';
 import type {
   AllMidsWsEvent,
+  L2BookWsEvent,
   OrderUpdatesWsEvent,
   UserFillsWsEvent,
   UserEventsWsEvent,
@@ -14,6 +15,15 @@ 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.) */
@@ -174,6 +184,21 @@ export class WebSocketManager {
     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 ────────────────────────────────────────
 
   /**

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'),
           });

package/scripts/info/spot.ts

@@ -127,14 +127,29 @@ async function main() {
 
   const markets: SpotMarket[] = [];
 
-  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;
-
-    // Filter by coin if specified
-    if (args.coin && !pair.name.toUpperCase().includes(args.coin)) {
-      continue;
+  // Build ctx map by coin name — the contexts array is NOT aligned with universe by index.
+  // Each context has a 'coin' field matching pair.name.
+  const ctxMap = new Map<string, { markPx: string; prevDayPx: string; dayNtlVlm: string; midPx: string }>();
+  for (const ctx of spotData.assetCtxs as Array<{ coin?: string; markPx: string; prevDayPx: string; dayNtlVlm: string; midPx: string }>) {
+    if (ctx.coin) ctxMap.set(ctx.coin, ctx);
+  }
+
+  // Build token name map for filtering by base token name
+  const tokenNameMap = new Map<number, string>();
+  for (const token of spotData.meta.tokens) {
+    tokenNameMap.set(token.index, token.name);
+  }
+
+  for (const pair of spotData.meta.universe) {
+    if (!pair) continue;
+    const ctx = ctxMap.get(pair.name);
+    if (!ctx) continue;
+
+    // Filter by coin — match pair name or base token name
+    if (args.coin) {
+      const baseTokenName = tokenNameMap.get(pair.tokens[0]) ?? '';
+      const searchable = `${pair.name} ${baseTokenName}`.toUpperCase();
+      if (!searchable.includes(args.coin)) continue;
     }
 
     markets.push({

package/scripts/operations/spot-order.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env npx tsx
+// Execute a spot order on Hyperliquid
+
+import { getClient } from '../core/client.js';
+import { formatUsd, parseArgs, checkBuilderFeeApproval } from '../core/utils.js';
+
+function printUsage() {
+  console.log(`
+Open Broker - Spot Order
+========================
+
+Buy or sell spot tokens on Hyperliquid.
+
+Usage:
+  npx tsx scripts/operations/spot-order.ts --coin <COIN> --side <buy|sell> --size <SIZE>
+
+Options:
+  --coin      Base token to trade (e.g., PURR, HYPE)
+  --side      Order side: buy or sell
+  --size      Order size in base token units
+  --price     Limit price (omit for market order)
+  --tif       Time-in-force for limit orders: Gtc, Ioc, Alo (default: Gtc)
+  --slippage  Slippage tolerance in bps for market orders (default: from config, usually 50 = 0.5%)
+  --dry       Dry run - show order details without executing
+  --verbose   Show full API request/response for debugging
+
+Environment:
+  HYPERLIQUID_PRIVATE_KEY  Your wallet private key (0x...)
+  HYPERLIQUID_NETWORK      "mainnet" or "testnet" (default: mainnet)
+
+Examples:
+  npx tsx scripts/operations/spot-order.ts --coin PURR --side buy --size 1000
+  npx tsx scripts/operations/spot-order.ts --coin HYPE --side sell --size 50 --price 25.50
+  npx tsx scripts/operations/spot-order.ts --coin PURR --side buy --size 500 --dry
+`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  const coin = args.coin as string;
+  const side = args.side as string;
+  const size = parseFloat(args.size as string);
+  const price = args.price ? parseFloat(args.price as string) : undefined;
+  const tif = (args.tif as 'Gtc' | 'Ioc' | 'Alo') ?? 'Gtc';
+  const slippage = args.slippage ? parseInt(args.slippage as string) : undefined;
+  const dryRun = args.dry as boolean;
+
+  if (!coin || !side || isNaN(size)) {
+    printUsage();
+    process.exit(1);
+  }
+
+  if (side !== 'buy' && side !== 'sell') {
+    console.error('Error: --side must be "buy" or "sell"');
+    process.exit(1);
+  }
+
+  if (size <= 0) {
+    console.error('Error: --size must be positive');
+    process.exit(1);
+  }
+
+  const isBuy = side === 'buy';
+  const client = getClient();
+
+  if (args.verbose) {
+    client.verbose = true;
+  }
+
+  console.log('Open Broker - Spot Order');
+  console.log('========================\n');
+
+  await checkBuilderFeeApproval(client);
+
+  try {
+    // Load spot metadata to get the pair index, then use allMids for accurate price
+    const spotMeta = await client.getSpotMeta();
+    const tokenMap = new Map<number, string>();
+    for (const t of spotMeta.tokens) tokenMap.set(t.index, t.name);
+
+    // Find the USDC-quoted pair for this coin (prefer quote token 0 = USDC)
+    let pairName = '';
+    let spotCoinKey = '';
+    for (const pair of spotMeta.universe) {
+      const baseName = tokenMap.get(pair.tokens[0]) ?? '';
+      if (baseName.toUpperCase() !== coin.toUpperCase()) continue;
+      const quoteName = tokenMap.get(pair.tokens[1]) ?? 'USDC';
+      // Prefer USDC pair; if already found a USDC pair, skip non-USDC pairs
+      if (pairName && pair.tokens[1] !== 0) continue;
+      pairName = `${baseName}/${quoteName}`;
+      spotCoinKey = pair.name; // "@107" or "PURR/USDC"
+      if (pair.tokens[1] === 0) break; // USDC pair found, stop
+    }
+
+    if (!spotCoinKey) {
+      console.error(`Error: No spot market found for ${coin}`);
+      console.error('Use "openbroker spot" to see available spot markets.');
+      process.exit(1);
+    }
+
+    // Use allMids for live price (spotMetaAndAssetCtxs contexts can be misaligned)
+    const mids = await client.getAllMids();
+    const midPrice = parseFloat(mids[spotCoinKey] || '0');
+
+    if (!midPrice || midPrice === 0) {
+      console.error(`Error: No spot price for ${coin} (${spotCoinKey})`);
+      process.exit(1);
+    }
+
+    const isMarket = price === undefined;
+    const slippageBps = slippage ?? 50;
+    const displayPrice = isMarket
+      ? (isBuy ? midPrice * (1 + slippageBps / 10000) : midPrice * (1 - slippageBps / 10000))
+      : price;
+    const notional = midPrice * size;
+
+    console.log('Order Details');
+    console.log('-------------');
+    console.log(`Pair:         ${pairName}`);
+    console.log(`Side:         ${isBuy ? 'BUY' : 'SELL'}`);
+    console.log(`Size:         ${size} ${coin}`);
+    console.log(`Mid Price:    ${formatUsd(midPrice)}`);
+    if (isMarket) {
+      console.log(`Type:         Market (IOC)`);
+      console.log(`Limit Price:  ${formatUsd(displayPrice)} (${slippageBps} bps slippage)`);
+    } else {
+      console.log(`Type:         Limit (${tif})`);
+      console.log(`Limit Price:  ${formatUsd(price)}`);
+    }
+    console.log(`Notional:     ~${formatUsd(notional)}`);
+    console.log(`Builder Fee:  ${client.builderInfo.f / 10} bps`);
+
+    if (dryRun) {
+      console.log('\n🔍 Dry run - order not submitted');
+      return;
+    }
+
+    console.log('\nExecuting...');
+
+    const response = isMarket
+      ? await client.spotMarketOrder(coin, isBuy, size, slippage)
+      : await client.spotLimitOrder(coin, isBuy, size, price!, tif);
+
+    console.log('\nResult');
+    console.log('------');
+
+    if (args.verbose || process.env.VERBOSE) {
+      console.log('\nFull Response:');
+      console.log(JSON.stringify(response, null, 2));
+    }
+
+    if (response.status === 'ok' && response.response && typeof response.response === 'object') {
+      const statuses = response.response.data.statuses;
+      for (const status of statuses) {
+        if (status.filled) {
+          const fillSz = parseFloat(status.filled.totalSz);
+          const avgPx = parseFloat(status.filled.avgPx);
+          const fillNotional = fillSz * avgPx;
+
+          console.log(`✅ Filled`);
+          console.log(`   Order ID:  ${status.filled.oid}`);
+          console.log(`   Size:      ${fillSz} ${coin}`);
+          console.log(`   Avg Price: ${formatUsd(avgPx)}`);
+          console.log(`   Notional:  ${formatUsd(fillNotional)}`);
+        } else if (status.resting) {
+          console.log(`⏳ Resting`);
+          console.log(`   Order ID:  ${status.resting.oid}`);
+        } else if (status.error) {
+          console.log(`❌ Error: ${status.error}`);
+        } else {
+          console.log(`⚠️  Unknown status:`);
+          console.log(JSON.stringify(status, null, 2));
+        }
+      }
+    } else if (response.status === 'err') {
+      console.log(`❌ API Error: ${response.response || JSON.stringify(response)}`);
+    } else {
+      console.log(`❌ Unexpected response:`);
+      console.log(JSON.stringify(response, null, 2));
+    }
+
+  } catch (error) {
+    console.error('Error executing spot order:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/plugin/tools.ts

@@ -398,14 +398,27 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
         if (!typeFilter || typeFilter === 'spot') {
           try {
             const spotData = await client.getSpotMetaAndAssetCtxs();
-            for (let i = 0; i < spotData.meta.universe.length; i++) {
-              const pair = spotData.meta.universe[i];
-              if (pair.name.toUpperCase().includes(query)) {
+            // Build ctx map by coin name — contexts are NOT aligned with universe by index
+            const ctxMap = new Map<string, Record<string, string>>();
+            for (const ctx of spotData.assetCtxs as Array<Record<string, string>>) {
+              if (ctx.coin) ctxMap.set(ctx.coin, ctx);
+            }
+            // Build token name map
+            const tMap = new Map<number, string>();
+            for (const t of spotData.meta.tokens) tMap.set(t.index, t.name);
+
+            for (const pair of spotData.meta.universe) {
+              const baseName = tMap.get(pair.tokens[0]) ?? '';
+              const quoteName = tMap.get(pair.tokens[1]) ?? '';
+              const searchable = `${pair.name} ${baseName} ${quoteName}`.toUpperCase();
+              if (searchable.includes(query)) {
+                const ctx = ctxMap.get(pair.name);
+                const displayName = baseName && quoteName ? `${baseName}/${quoteName}` : pair.name;
                 results.push({
-                  coin: pair.name,
+                  coin: displayName,
                   type: 'spot',
-                  markPx: spotData.assetCtxs[i]?.markPx,
-                  dayVolume: spotData.assetCtxs[i]?.dayNtlVlm,
+                  markPx: ctx?.markPx,
+                  dayVolume: ctx?.dayNtlVlm,
                 });
               }
             }
@@ -1193,6 +1206,113 @@ export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext)
       },
     },
 
+    {
+      name: 'ob_spot_buy',
+      description: 'Buy spot tokens on Hyperliquid. Always use dry=true first to preview.',
+      parameters: {
+        type: 'object',
+        properties: {
+          coin: { type: 'string', description: 'Base token symbol (PURR, HYPE, etc.)' },
+          size: { type: 'number', description: 'Order size in base token units' },
+          price: { type: 'number', description: 'Limit price (omit for market order)' },
+          tif: { type: 'string', description: 'Time-in-force for limit: Gtc, Ioc, Alo (default: Gtc)' },
+          slippage: { type: 'number', description: 'Slippage tolerance in bps for market orders (default: 50)' },
+          dry: { type: 'boolean', description: 'Preview without executing' },
+        },
+        required: ['coin', 'size'],
+      },
+      async execute(_id, params) {
+        const { getClient } = await import('../core/client.js');
+        const { formatUsd } = await import('../core/utils.js');
+        const client = getClient();
+
+        if (client.isReadOnly) return error('Wallet not configured. Run "openbroker setup" first.');
+
+        const coin = (params.coin as string).toUpperCase();
+        const size = params.size as number;
+        const price = params.price as number | undefined;
+        const isMarket = price === undefined;
+
+        if (params.dry) {
+          // Use allMids for accurate spot price preview
+          await client.getMetaAndAssetCtxs(); // ensure spot meta loaded
+          const spotIdx = client.getSpotAssetIndex(coin);
+          const mids = await client.getAllMids();
+          const spotKey = spotIdx !== undefined ? (spotIdx === 10000 ? 'PURR/USDC' : `@${spotIdx - 10000}`) : '';
+          const midPrice = parseFloat(mids[spotKey] || '0');
+          return json({
+            dryRun: true,
+            action: 'spot_buy',
+            coin,
+            size,
+            type: isMarket ? 'market' : 'limit',
+            midPrice,
+            price: price ?? midPrice,
+            notional: formatUsd(midPrice * size),
+          });
+        }
+
+        const result = isMarket
+          ? await client.spotMarketOrder(coin, true, size, params.slippage as number | undefined)
+          : await client.spotLimitOrder(coin, true, size, price!, (params.tif as 'Gtc' | 'Ioc' | 'Alo') ?? 'Gtc');
+
+        return json({ action: 'spot_buy', coin, size, type: isMarket ? 'market' : 'limit', result });
+      },
+    },
+
+    {
+      name: 'ob_spot_sell',
+      description: 'Sell spot tokens on Hyperliquid. Always use dry=true first to preview.',
+      parameters: {
+        type: 'object',
+        properties: {
+          coin: { type: 'string', description: 'Base token symbol (PURR, HYPE, etc.)' },
+          size: { type: 'number', description: 'Order size in base token units' },
+          price: { type: 'number', description: 'Limit price (omit for market order)' },
+          tif: { type: 'string', description: 'Time-in-force for limit: Gtc, Ioc, Alo (default: Gtc)' },
+          slippage: { type: 'number', description: 'Slippage tolerance in bps for market orders (default: 50)' },
+          dry: { type: 'boolean', description: 'Preview without executing' },
+        },
+        required: ['coin', 'size'],
+      },
+      async execute(_id, params) {
+        const { getClient } = await import('../core/client.js');
+        const { formatUsd } = await import('../core/utils.js');
+        const client = getClient();
+
+        if (client.isReadOnly) return error('Wallet not configured. Run "openbroker setup" first.');
+
+        const coin = (params.coin as string).toUpperCase();
+        const size = params.size as number;
+        const price = params.price as number | undefined;
+        const isMarket = price === undefined;
+
+        if (params.dry) {
+          await client.getMetaAndAssetCtxs();
+          const spotIdx = client.getSpotAssetIndex(coin);
+          const mids = await client.getAllMids();
+          const spotKey = spotIdx !== undefined ? (spotIdx === 10000 ? 'PURR/USDC' : `@${spotIdx - 10000}`) : '';
+          const midPrice = parseFloat(mids[spotKey] || '0');
+          return json({
+            dryRun: true,
+            action: 'spot_sell',
+            coin,
+            size,
+            type: isMarket ? 'market' : 'limit',
+            midPrice,
+            price: price ?? midPrice,
+            notional: formatUsd(midPrice * size),
+          });
+        }
+
+        const result = isMarket
+          ? await client.spotMarketOrder(coin, false, size, params.slippage as number | undefined)
+          : await client.spotLimitOrder(coin, false, size, price!, (params.tif as 'Gtc' | 'Ioc' | 'Alo') ?? 'Gtc');
+
+        return json({ action: 'spot_sell', coin, size, type: isMarket ? 'market' : 'limit', result });
+      },
+    },
+
     {
       name: 'ob_cancel',
       description: 'Cancel open orders on Hyperliquid',