openbroker 1.0.44 → 1.0.47

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.47] - 2026-03-09
+
+### Fixed
+- **HIP-3 Perp Trading**: All trading commands now work with HIP-3 assets using `dex:COIN` syntax (e.g., `--coin xyz:CL`)
+  - `getMetaAndAssetCtxs()` loads HIP-3 dex assets into asset/szDecimals maps (asset index = `10000 * dexIdx + assetIdx`)
+  - `getAllMids()` fetches and merges mid prices from all HIP-3 dexes
+  - `getCandleSnapshot()`, `getFundingHistory()`, `getRecentTrades()`, `getL2Book()` pass correct `dex` param for HIP-3 coins
+  - Market, limit, trigger, bracket, TWAP, scale, chase orders all work with HIP-3 assets
+- **HIP-3 Info Commands**: `candles`, `trades`, `funding-history` now return data for HIP-3 assets (previously returned null/empty)
+- **Better Error Messages**: When a bare coin name (e.g., `CL`) matches HIP-3 assets, the error now suggests the prefixed ticker (e.g., `xyz:CL`)
+
+### Added
+- **Funding Rate Scanner**: New `funding-scan` command for cross-dex funding rate scanning
+  - Scans all dexes (main + HIP-3) for high funding opportunities
+  - `--pairs` flag identifies opposing funding pairs for delta-neutral strategies
+  - `--watch --interval N` for periodic re-scanning
+  - `--json` output for piping to alerting systems
+  - `--main-only` / `--hip3-only` scope filters
+- **HIP-3 Funding Rates**: `funding` and `markets` commands now support `--include-hip3` flag
+- **HIP-3 Funding Arb**: `funding-arb` strategy now works with HIP-3 assets (monitoring loop correctly resolves HIP-3 funding data)
+- **Plugin**: New `ob_funding_scan` agent tool for cross-dex funding scanning with pairs support
+- **Plugin**: `ob_search` now searches HIP-3 perps in addition to main perps and spot
+- **Client**: Added `getCoinDex()`, `getCoinLocalName()`, `isHip3()`, `getAllAssetNames()`, `getHip3AssetNames()`, `invalidateMetaCache()` methods
+- **Client**: `getPerpDexs()` results are now cached to reduce redundant API calls
+
 ## [1.0.44] - 2026-02-25
 
 ### Added

package/README.md

@@ -31,10 +31,15 @@ openbroker setup                # One-command setup (wallet + config + builder a
 ```
 
 The setup command handles everything automatically:
-- Generates a new wallet or accepts your existing private key
+- Generates a fresh trading wallet (recommended for agents) or accepts your existing private key
 - Saves configuration to `~/.openbroker/.env` (permissions `0600`)
 - Approves the builder fee (required for trading)
 
+Setup offers three modes:
+1. **Generate fresh wallet** (recommended for agents) — cleanest option, no browser steps
+2. **Import existing key** — use a key you already have
+3. **Generate API wallet** — restricted wallet requiring browser approval from a master wallet
+
 ---
 
 ### Info Commands
@@ -636,16 +641,24 @@ export HYPERLIQUID_NETWORK=mainnet       # Optional: mainnet (default) or testne
 export HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets
 ```
 
-### API Wallet Setup
+### Fresh Wallet Setup (Recommended for Agents)
+
+The simplest setup for agents — generates a dedicated wallet, auto-approves the builder fee, and is ready to trade after funding:
+
+```bash
+openbroker setup    # Choose option 1, fund with USDC, start trading
+```
+
+### API Wallet Setup (Alternative)
 
-For automated trading, use an API wallet:
+For delegated trading without moving funds, use an API wallet:
 
 ```bash
 export HYPERLIQUID_PRIVATE_KEY="0x..."        # API wallet private key
 export HYPERLIQUID_ACCOUNT_ADDRESS="0x..."    # Main account address
 ```
 
-**Note:** Builder fee must be approved with the main wallet first. Sub-accounts cannot approve builder fees. After approval, you can switch to using the API wallet for trading.
+**Note:** API wallets require browser approval from the master wallet. The master wallet signs `ApproveAgent` and `ApproveBuilderFee` transactions via the approval URL provided during setup.
 
 ## Builder Fee
 

package/SKILL.md

@@ -4,8 +4,8 @@ description: Hyperliquid trading plugin with background position monitoring. Exe
 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.44", "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_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.47", "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_bracket ob_chase ob_watcher_status Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -40,16 +40,26 @@ openbroker approve-builder --check  # Check builder fee status (for troubleshoot
 ```
 
 The `setup` command offers three modes:
-1. **Import existing key** — use a private key you already have (master wallet)
-2. **Generate new wallet** — create a fresh master wallet
-3. **Generate API wallet** (recommended for agents) — creates a restricted wallet that can trade but cannot withdraw
+1. **Generate fresh wallet** (recommended for agents) — creates a dedicated trading wallet with builder fee auto-approved. No browser steps needed — just fund with USDC and start trading.
+2. **Import existing key** — use a private key you already have
+3. **Generate API wallet** — creates a restricted wallet that can trade but cannot withdraw. Requires browser approval from a master wallet.
 
 For options 1 and 2, setup saves config and approves the builder fee automatically.
 For option 3 (API wallet), see the API Wallet Setup section below.
 
-### API Wallet Setup (Recommended for Agents)
+### Fresh Wallet Setup (Recommended for Agents)
 
-API wallets can place trades on behalf of a master account but **cannot withdraw funds**. This is the safest option for automated agents.
+The simplest setup for agents. A fresh wallet is generated, the builder fee is auto-approved, and the agent is ready to trade immediately after funding.
+
+**Flow:**
+1. Run `openbroker setup` and choose option 1 ("Generate a fresh wallet")
+2. The CLI generates a wallet, saves the config, and approves the builder fee automatically
+3. Fund the wallet with USDC on Arbitrum, then deposit at https://app.hyperliquid.xyz/
+4. Start trading
+
+### API Wallet Setup (Alternative)
+
+API wallets can place trades on behalf of a master account but **cannot withdraw funds**. Use this if you prefer to keep funds in your existing wallet and only delegate trading access.
 
 **Flow:**
 1. Run `openbroker setup` and choose option 3 ("Generate API wallet")
@@ -160,8 +170,25 @@ openbroker trades --coin BTC --top 50     # Last 50 trades
 openbroker rate-limit                     # API usage and capacity
 ```
 
+### Funding Rate Scanner (Cross-Dex)
+```bash
+openbroker funding-scan                          # Scan all dexes, >25% threshold
+openbroker funding-scan --threshold 50 --pairs   # Show opposing funding pairs
+openbroker funding-scan --hip3-only --top 20     # HIP-3 only
+openbroker funding-scan --watch --interval 120   # Re-scan every 2 minutes
+```
+
 ## Trading Commands
 
+### HIP-3 Perp Trading
+All trading commands support HIP-3 assets using `dex:COIN` syntax:
+```bash
+openbroker buy --coin xyz:CL --size 1              # Buy crude oil on xyz dex
+openbroker sell --coin xyz:BRENTOIL --size 1        # Sell brent oil
+openbroker limit --coin xyz:GOLD --side buy --size 0.1 --price 2500
+openbroker funding-arb --coin xyz:CL --size 5000    # Funding arb on HIP-3
+```
+
 ### Market Orders (Quick)
 ```bash
 openbroker buy --coin ETH --size 0.1

package/bin/cli.ts

@@ -31,6 +31,7 @@ const commands: Record<string, { script: string; description: string }> = {
   'funding-history': { script: 'info/funding-history.ts', description: 'View historical funding rates' },
   'trades': { script: 'info/trades.ts', description: 'View recent trades for an asset' },
   'rate-limit': { script: 'info/rate-limit.ts', description: 'View API rate limit status' },
+  'funding-scan': { script: 'info/funding-scan.ts', description: 'Scan funding rates across all dexes' },
 
   // Operations
   'buy': { script: 'operations/market-order.ts', description: 'Market buy order' },
@@ -78,6 +79,7 @@ Info Commands:
   search               Search for assets across all providers
   spot                 View spot markets and balances
   rate-limit           View API rate limit status
+  funding-scan         Scan funding rates across all dexes (main + HIP-3)
 
 Trading Commands:
   buy                  Market buy order
@@ -148,7 +150,7 @@ function runScript(scriptPath: string, args: string[]) {
 function main() {
   const args = process.argv.slice(2);
 
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
     printHelp();
     process.exit(0);
   }

package/openclaw.plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.44",
+  "version": "1.0.47",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -38,6 +38,7 @@
     "scale": "tsx scripts/operations/scale.ts",
     "bracket": "tsx scripts/operations/bracket.ts",
     "chase": "tsx scripts/operations/chase.ts",
+    "funding-scan": "tsx scripts/info/funding-scan.ts",
     "funding-arb": "tsx scripts/strategies/funding-arb.ts",
     "grid": "tsx scripts/strategies/grid.ts",
     "dca": "tsx scripts/strategies/dca.ts",

package/scripts/core/client.ts

@@ -25,6 +25,12 @@ export class HyperliquidClient {
   private meta: MetaAndAssetCtxs | null = null;
   private assetMap: Map<string, number> = new Map();
   private szDecimalsMap: Map<string, number> = new Map();
+  /** Maps coin name → dex info for HIP-3 assets. Main dex assets have dexName=null */
+  private coinDexMap: Map<string, { dexName: string | null; dexIdx: number; localName: string }> = new Map();
+  /** Cache of perpDexs list */
+  private perpDexsCache: Array<{ name: string; fullName: string; deployer: string } | null> | null = null;
+  /** Whether HIP-3 assets have been loaded into maps */
+  private hip3Loaded: boolean = false;
   public verbose: boolean = false;
 
   constructor(config?: OpenBrokerConfig) {
@@ -106,18 +112,103 @@ export class HyperliquidClient {
       assetCtxs: response[1],
     };
 
-    // Build lookup maps
+    // Build lookup maps for main dex
     this.meta.meta.universe.forEach((asset, index) => {
       this.assetMap.set(asset.name, index);
       this.szDecimalsMap.set(asset.name, asset.szDecimals);
+      this.coinDexMap.set(asset.name, { dexName: null, dexIdx: 0, localName: asset.name });
     });
 
+    // Load HIP-3 dex assets (only once - maps persist across meta cache invalidation)
+    if (!this.hip3Loaded) {
+      await this.loadHip3Assets();
+      this.hip3Loaded = true;
+    }
+
     return this.meta;
   }
 
+  /**
+   * Load HIP-3 perp dex assets into the asset/szDecimals maps.
+   * Asset index formula: 10000 * dexIdx + assetIdx
+   * Coins are keyed as "dexName:COIN" (e.g., "xyz:CL")
+   */
+  private async loadHip3Assets(): Promise<void> {
+    try {
+      const dexs = await this.getPerpDexs();
+      const baseUrl = isMainnet()
+        ? 'https://api.hyperliquid.xyz'
+        : 'https://api.hyperliquid-testnet.xyz';
+
+      for (let dexIdx = 1; dexIdx < dexs.length; dexIdx++) {
+        const dex = dexs[dexIdx];
+        if (!dex) continue;
+
+        try {
+          const dexResponse = await fetch(baseUrl + '/info', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ type: 'metaAndAssetCtxs', dex: dex.name }),
+          });
+          const dexData = await dexResponse.json();
+
+          if (dexData && dexData[0]?.universe) {
+            const universe = dexData[0].universe as Array<{ name: string; szDecimals: number; maxLeverage: number; onlyIsolated?: boolean }>;
+            this.log(`Loading HIP-3 dex: ${dex.name} with ${universe.length} markets`);
+
+            universe.forEach((asset, assetIdx) => {
+              const prefixedName = `${dex.name}:${asset.name}`;
+              const globalIndex = 10000 * dexIdx + assetIdx;
+
+              this.assetMap.set(prefixedName, globalIndex);
+              this.szDecimalsMap.set(prefixedName, asset.szDecimals);
+              this.coinDexMap.set(prefixedName, { dexName: dex.name, dexIdx, localName: asset.name });
+            });
+          }
+        } catch (e) {
+          this.log(`Failed to load HIP-3 dex ${dex.name}:`, e);
+        }
+      }
+    } catch (e) {
+      this.log('Failed to load HIP-3 assets:', e);
+    }
+  }
+
   async getAllMids(): Promise<Record<string, string>> {
     this.log('Fetching allMids...');
-    const response = await this.info.allMids();
+    const response = await this.info.allMids() as Record<string, string>;
+
+    // Also fetch HIP-3 dex mids
+    try {
+      const dexs = await this.getPerpDexs();
+      const baseUrl = isMainnet()
+        ? 'https://api.hyperliquid.xyz'
+        : 'https://api.hyperliquid-testnet.xyz';
+
+      for (let i = 1; i < dexs.length; i++) {
+        const dex = dexs[i];
+        if (!dex) continue;
+
+        try {
+          const dexResponse = await fetch(baseUrl + '/info', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ type: 'allMids', dex: dex.name }),
+          });
+          const dexMids = await dexResponse.json() as Record<string, string>;
+
+          // Merge with prefixed keys
+          for (const [coin, mid] of Object.entries(dexMids)) {
+            response[`${dex.name}:${coin}`] = mid;
+          }
+        } catch (e) {
+          this.log(`Failed to fetch mids for HIP-3 dex ${dex.name}:`, e);
+        }
+      }
+    } catch (e) {
+      this.log('Failed to fetch HIP-3 mids:', e);
+    }
+
     return response;
   }
 
@@ -130,6 +221,8 @@ export class HyperliquidClient {
     fullName: string;
     deployer: string;
   } | null>> {
+    if (this.perpDexsCache) return this.perpDexsCache;
+
     this.log('Fetching perpDexs...');
     const baseUrl = isMainnet()
       ? 'https://api.hyperliquid.xyz'
@@ -142,6 +235,7 @@ export class HyperliquidClient {
     });
     const data = await response.json();
     this.log('perpDexs response:', JSON.stringify(data).slice(0, 500));
+    this.perpDexsCache = data;
     return data;
   }
 
@@ -412,7 +506,8 @@ export class HyperliquidClient {
     spreadBps: number;
   }> {
     this.log('Fetching l2Book for:', coin);
-    const response = await this.info.l2Book({ coin });
+    const localName = this.getCoinLocalName(coin);
+    const response = await this.info.l2Book({ coin: localName });
 
     const bids = response.levels[0] as Array<{ px: string; sz: string; n: number }>;
     const asks = response.levels[1] as Array<{ px: string; sz: string; n: number }>;
@@ -437,6 +532,15 @@ export class HyperliquidClient {
   getAssetIndex(coin: string): number {
     const index = this.assetMap.get(coin);
     if (index === undefined) {
+      // Check if bare name exists in HIP-3 dexes and suggest prefixed version
+      const hip3Matches = this.findHip3Matches(coin);
+      if (hip3Matches.length > 0) {
+        const suggestions = hip3Matches.map(m => `${m}`).join(', ');
+        throw new Error(
+          `Unknown asset: ${coin}. Did you mean one of these HIP-3 assets? ${suggestions}\n` +
+          `Use "openbroker search --query ${coin}" to find the full ticker.`
+        );
+      }
       throw new Error(`Unknown asset: ${coin}. Available: ${Array.from(this.assetMap.keys()).slice(0, 10).join(', ')}...`);
     }
     return index;
@@ -445,11 +549,78 @@ export class HyperliquidClient {
   getSzDecimals(coin: string): number {
     const decimals = this.szDecimalsMap.get(coin);
     if (decimals === undefined) {
+      const hip3Matches = this.findHip3Matches(coin);
+      if (hip3Matches.length > 0) {
+        throw new Error(
+          `Unknown asset: ${coin}. Did you mean: ${hip3Matches.join(', ')}?`
+        );
+      }
       throw new Error(`Unknown asset: ${coin}`);
     }
     return decimals;
   }
 
+  /**
+   * Find HIP-3 assets matching a bare coin name (without dex prefix)
+   */
+  private findHip3Matches(bareName: string): string[] {
+    const matches: string[] = [];
+    const upperName = bareName.toUpperCase();
+    for (const [key, info] of this.coinDexMap.entries()) {
+      if (info.dexName && info.localName.toUpperCase() === upperName) {
+        matches.push(key);
+      }
+    }
+    return matches;
+  }
+
+  /**
+   * Get the dex name for a coin (null for main dex assets)
+   */
+  getCoinDex(coin: string): string | null {
+    return this.coinDexMap.get(coin)?.dexName ?? null;
+  }
+
+  /**
+   * Get the local (unprefixed) coin name for API calls that need it
+   * e.g., "xyz:CL" → "CL", "ETH" → "ETH"
+   */
+  getCoinLocalName(coin: string): string {
+    return this.coinDexMap.get(coin)?.localName ?? coin;
+  }
+
+  /**
+   * Check if a coin is a HIP-3 asset
+   */
+  isHip3(coin: string): boolean {
+    return this.coinDexMap.get(coin)?.dexName != null;
+  }
+
+  /**
+   * Invalidate cached metadata so next call fetches fresh data.
+   * Useful for long-running strategies that need updated funding rates.
+   */
+  invalidateMetaCache(): void {
+    this.meta = null;
+    // Keep the asset/szDecimals/coinDex maps - they don't change
+  }
+
+  /**
+   * Get all loaded asset names (main + HIP-3)
+   */
+  getAllAssetNames(): string[] {
+    return Array.from(this.assetMap.keys());
+  }
+
+  /**
+   * Get all HIP-3 asset names
+   */
+  getHip3AssetNames(): string[] {
+    return Array.from(this.coinDexMap.entries())
+      .filter(([_, info]) => info.dexName !== null)
+      .map(([name]) => name);
+  }
+
   // ============ Account Info ============
 
   /**
@@ -783,8 +954,12 @@ export class HyperliquidClient {
       ? 'https://api.hyperliquid.xyz'
       : 'https://api.hyperliquid-testnet.xyz';
 
-    const req: Record<string, unknown> = { coin, interval, startTime };
+    const localName = this.getCoinLocalName(coin);
+    const dex = this.getCoinDex(coin);
+
+    const req: Record<string, unknown> = { coin: localName, interval, startTime };
     if (endTime !== undefined) req.endTime = endTime;
+    if (dex) req.dex = dex;
 
     const response = await fetch(baseUrl + '/info', {
       method: 'POST',
@@ -814,8 +989,12 @@ export class HyperliquidClient {
       ? 'https://api.hyperliquid.xyz'
       : 'https://api.hyperliquid-testnet.xyz';
 
-    const body: Record<string, unknown> = { type: 'fundingHistory', coin, startTime };
+    const localName = this.getCoinLocalName(coin);
+    const dex = this.getCoinDex(coin);
+
+    const body: Record<string, unknown> = { type: 'fundingHistory', coin: localName, startTime };
     if (endTime !== undefined) body.endTime = endTime;
+    if (dex) body.dex = dex;
 
     const response = await fetch(baseUrl + '/info', {
       method: 'POST',
@@ -844,10 +1023,16 @@ export class HyperliquidClient {
       ? 'https://api.hyperliquid.xyz'
       : 'https://api.hyperliquid-testnet.xyz';
 
+    const localName = this.getCoinLocalName(coin);
+    const dex = this.getCoinDex(coin);
+
+    const body: Record<string, unknown> = { type: 'recentTrades', coin: localName };
+    if (dex) body.dex = dex;
+
     const response = await fetch(baseUrl + '/info', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ type: 'recentTrades', coin }),
+      body: JSON.stringify(body),
     });
     const data = await response.json();
     this.log('recentTrades response length:', data?.length);

package/scripts/info/candles.ts

@@ -65,6 +65,9 @@ async function main() {
   console.log('='.repeat(40) + '\n');
 
   try {
+    // Load metadata (needed for HIP-3 coin resolution)
+    await client.getMetaAndAssetCtxs();
+
     const now = Date.now();
     const startTime = now - (bars * (INTERVAL_MS[interval] || 3_600_000));
     const candles = await client.getCandleSnapshot(coin.toUpperCase(), interval, startTime);

package/scripts/info/funding-history.ts

@@ -41,6 +41,9 @@ async function main() {
   console.log('='.repeat(40) + '\n');
 
   try {
+    // Load metadata (needed for HIP-3 coin resolution)
+    await client.getMetaAndAssetCtxs();
+
     const now = Date.now();
     const startTime = now - (hours * 3_600_000);
     const history = await client.getFundingHistory(coin.toUpperCase(), startTime);

package/scripts/info/funding-scan.ts

@@ -0,0 +1,212 @@
+#!/usr/bin/env npx tsx
+// Cross-dex funding rate scanner - scan all assets (main + HIP-3) for funding opportunities
+
+import { getClient } from '../core/client.js';
+import { formatUsd, formatPercent, annualizeFundingRate, parseArgs, sleep } from '../core/utils.js';
+
+function printUsage() {
+  console.log(`
+Usage: openbroker funding-scan [options]
+
+Scan funding rates across all dexes (main perps + HIP-3) and find opportunities.
+
+Options:
+  --threshold <n>   Min annualized funding rate % to show (default: 25)
+  --include-hip3    Include HIP-3 dex assets (default: true)
+  --main-only       Only scan main perps
+  --hip3-only       Only scan HIP-3 perps
+  --top <n>         Show top N results (default: 30)
+  --pairs           Show correlated pairs with opposing funding
+  --json            Output as JSON
+  --watch           Re-scan periodically
+  --interval <n>    Watch interval in seconds (default: 60)
+  --help, -h        Show this help
+
+Examples:
+  openbroker funding-scan
+  openbroker funding-scan --threshold 50 --pairs
+  openbroker funding-scan --hip3-only --top 20
+  openbroker funding-scan --watch --interval 120
+`);
+}
+
+interface FundingScanResult {
+  coin: string;
+  dex: string;
+  hourlyRate: number;
+  annualizedPct: number;
+  direction: 'longs pay' | 'shorts pay';
+  openInterest: number;
+  markPx: number;
+}
+
+async function scanFunding(client: ReturnType<typeof getClient>, options: {
+  threshold: number;
+  mainOnly: boolean;
+  hip3Only: boolean;
+  topN: number;
+}): Promise<FundingScanResult[]> {
+  const allPerps = await client.getAllPerpMetas();
+  const results: FundingScanResult[] = [];
+
+  for (const dexData of allPerps) {
+    const isMain = !dexData.dexName;
+    if (options.mainOnly && !isMain) continue;
+    if (options.hip3Only && isMain) continue;
+
+    for (let i = 0; i < dexData.meta.universe.length; i++) {
+      const asset = dexData.meta.universe[i];
+      const ctx = dexData.assetCtxs[i];
+      if (!ctx) continue;
+
+      const hourlyRate = parseFloat(ctx.funding);
+      const annualizedPct = annualizeFundingRate(hourlyRate) * 100;
+      const openInterest = parseFloat(ctx.openInterest);
+      const markPx = parseFloat(ctx.markPx);
+
+      if (Math.abs(annualizedPct) < options.threshold) continue;
+      if (openInterest < 100) continue;
+
+      const coin = dexData.dexName ? `${dexData.dexName}:${asset.name}` : asset.name;
+
+      results.push({
+        coin,
+        dex: dexData.dexName ?? 'main',
+        hourlyRate,
+        annualizedPct,
+        direction: hourlyRate > 0 ? 'longs pay' : 'shorts pay',
+        openInterest,
+        markPx,
+      });
+    }
+  }
+
+  // Sort by absolute annualized rate
+  results.sort((a, b) => Math.abs(b.annualizedPct) - Math.abs(a.annualizedPct));
+  return results.slice(0, options.topN);
+}
+
+function printResults(results: FundingScanResult[], showPairs: boolean) {
+  if (results.length === 0) {
+    console.log('No assets above threshold');
+    return;
+  }
+
+  // Table header
+  console.log(
+    'Coin'.padEnd(16) +
+    'Dex'.padEnd(8) +
+    'Annualized'.padEnd(14) +
+    'Direction'.padEnd(14) +
+    'OI'.padEnd(14) +
+    'Mark'
+  );
+  console.log('─'.repeat(75));
+
+  for (const r of results) {
+    const annStr = `${r.annualizedPct >= 0 ? '+' : ''}${r.annualizedPct.toFixed(1)}%`;
+    const oiStr = formatOI(r.openInterest);
+
+    console.log(
+      r.coin.padEnd(16) +
+      r.dex.padEnd(8) +
+      annStr.padStart(12).padEnd(14) +
+      r.direction.padEnd(14) +
+      oiStr.padStart(12).padEnd(14) +
+      formatUsd(r.markPx)
+    );
+  }
+
+  // Show opposing pairs
+  if (showPairs) {
+    console.log('\nOpposing Funding Pairs:');
+    console.log('─'.repeat(75));
+
+    const longs = results.filter(r => r.annualizedPct > 0); // longs pay shorts
+    const shorts = results.filter(r => r.annualizedPct < 0); // shorts pay longs
+
+    const pairs: Array<{ long: FundingScanResult; short: FundingScanResult; spread: number }> = [];
+
+    for (const l of longs) {
+      for (const s of shorts) {
+        // Only pair across different dexes or correlated assets
+        const spread = l.annualizedPct + Math.abs(s.annualizedPct);
+        if (spread > 20) {
+          pairs.push({ long: l, short: s, spread });
+        }
+      }
+    }
+
+    pairs.sort((a, b) => b.spread - a.spread);
+
+    for (const p of pairs.slice(0, 10)) {
+      console.log(
+        `  SHORT ${p.long.coin.padEnd(14)} (${p.long.annualizedPct.toFixed(1)}%) ` +
+        `+ LONG ${p.short.coin.padEnd(14)} (${p.short.annualizedPct.toFixed(1)}%) ` +
+        `= ${p.spread.toFixed(1)}% spread`
+      );
+    }
+
+    if (pairs.length === 0) {
+      console.log('  No strong opposing pairs found');
+    }
+  }
+}
+
+function formatOI(oi: number): string {
+  if (oi >= 1_000_000) return `$${(oi / 1_000_000).toFixed(2)}M`;
+  if (oi >= 1_000) return `$${(oi / 1_000).toFixed(1)}K`;
+  return `$${oi.toFixed(0)}`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help || args.h) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const threshold = args.threshold ? parseFloat(args.threshold as string) : 25;
+  const mainOnly = args['main-only'] as boolean ?? false;
+  const hip3Only = args['hip3-only'] as boolean ?? false;
+  const topN = parseInt(args.top as string) || 30;
+  const showPairs = args.pairs as boolean ?? false;
+  const outputJson = args.json as boolean ?? false;
+  const watch = args.watch as boolean ?? false;
+  const intervalSec = args.interval ? parseInt(args.interval as string) : 60;
+
+  const client = getClient();
+  if (args.verbose) client.verbose = true;
+
+  console.log('Open Broker - Funding Rate Scanner');
+  console.log('==================================\n');
+  console.log(`Threshold: ${threshold}% annualized | Scope: ${mainOnly ? 'main only' : hip3Only ? 'HIP-3 only' : 'all dexes'}\n`);
+
+  const options = { threshold, mainOnly, hip3Only, topN };
+
+  const runScan = async () => {
+    const results = await scanFunding(client, options);
+
+    if (outputJson) {
+      console.log(JSON.stringify(results, null, 2));
+    } else {
+      printResults(results, showPairs);
+    }
+
+    return results;
+  };
+
+  await runScan();
+
+  if (watch) {
+    console.log(`\nWatching every ${intervalSec}s... (Ctrl+C to stop)\n`);
+    while (true) {
+      await sleep(intervalSec * 1000);
+      console.log(`\n[${new Date().toLocaleTimeString()}] Rescanning...\n`);
+      await runScan();
+    }
+  }
+}
+
+main().catch(err => { console.error(err); process.exit(1); });

package/scripts/info/funding.ts

@@ -24,12 +24,14 @@ async function main() {
   console.log('===========================\n');
 
   const client = getClient();
+  const includeHip3 = args['include-hip3'] as boolean || args['hip3'] as boolean || (filterCoin?.includes(':') ?? false);
 
   try {
     const meta = await client.getMetaAndAssetCtxs();
 
     const fundingData: FundingDisplay[] = [];
 
+    // Main dex assets
     for (let i = 0; i < meta.meta.universe.length; i++) {
       const asset = meta.meta.universe[i];
       const ctx = meta.assetCtxs[i];
@@ -55,6 +57,39 @@ async function main() {
       });
     }
 
+    // Include HIP-3 dex assets
+    if (includeHip3 || showAll || (filterCoin && filterCoin.includes(':'))) {
+      const allPerps = await client.getAllPerpMetas();
+      for (const dexData of allPerps) {
+        if (!dexData.dexName) continue; // Skip main dex (already loaded)
+
+        for (let i = 0; i < dexData.meta.universe.length; i++) {
+          const asset = dexData.meta.universe[i];
+          const ctx = dexData.assetCtxs[i];
+          if (!ctx) continue;
+
+          const prefixedName = `${dexData.dexName}:${asset.name}`;
+          if (filterCoin && prefixedName !== filterCoin) continue;
+
+          const hourlyRate = parseFloat(ctx.funding);
+          const annualizedRate = annualizeFundingRate(hourlyRate);
+          const openInterest = parseFloat(ctx.openInterest);
+          const markPx = parseFloat(ctx.markPx);
+
+          if (!showAll && openInterest < 1000) continue;
+
+          fundingData.push({
+            coin: prefixedName,
+            hourlyRate,
+            annualizedRate,
+            premium: 0,
+            openInterest,
+            markPx,
+          });
+        }
+      }
+    }
+
     // Sort
     if (sortBy === 'hourly' || sortBy === 'annualized') {
       fundingData.sort((a, b) => Math.abs(b.annualizedRate) - Math.abs(a.annualizedRate));

package/scripts/info/markets.ts

@@ -26,6 +26,7 @@ async function main() {
   console.log('=====================\n');
 
   const client = getClient();
+  const includeHip3 = args['include-hip3'] as boolean || args['hip3'] as boolean || (filterCoin?.includes(':') ?? false);
 
   try {
     const meta = await client.getMetaAndAssetCtxs();
@@ -59,6 +60,42 @@ async function main() {
       });
     }
 
+    // Include HIP-3 markets
+    if (includeHip3 || (filterCoin && filterCoin.includes(':'))) {
+      const allPerps = await client.getAllPerpMetas();
+      for (const dexData of allPerps) {
+        if (!dexData.dexName) continue;
+
+        for (let i = 0; i < dexData.meta.universe.length; i++) {
+          const asset = dexData.meta.universe[i];
+          const ctx = dexData.assetCtxs[i];
+          if (!ctx) continue;
+
+          const prefixedName = `${dexData.dexName}:${asset.name}`;
+          if (filterCoin && prefixedName !== filterCoin) continue;
+
+          const markPx = parseFloat(ctx.markPx);
+          const oraclePx = parseFloat(ctx.oraclePx);
+          const prevDayPx = parseFloat(ctx.prevDayPx);
+          const volume24h = parseFloat(ctx.dayNtlVlm);
+          const openInterest = parseFloat(ctx.openInterest);
+          const change24h = prevDayPx > 0 ? (markPx - prevDayPx) / prevDayPx : 0;
+
+          markets.push({
+            coin: prefixedName,
+            markPx,
+            oraclePx,
+            prevDayPx,
+            change24h,
+            volume24h,
+            openInterest,
+            maxLeverage: asset.maxLeverage,
+            szDecimals: asset.szDecimals,
+          });
+        }
+      }
+    }
+
     // Sort
     if (sortBy === 'volume') {
       markets.sort((a, b) => b.volume24h - a.volume24h);

package/scripts/info/trades.ts

@@ -41,6 +41,9 @@ async function main() {
   console.log('='.repeat(40) + '\n');
 
   try {
+    // Load metadata (needed for HIP-3 coin resolution)
+    await client.getMetaAndAssetCtxs();
+
     let trades = await client.getRecentTrades(coin.toUpperCase());
 
     // Most recent first

package/scripts/plugin/tools.ts

@@ -228,6 +228,29 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           }
         }
 
+        // Search HIP-3 perps
+        if (!typeFilter || typeFilter === 'hip3' || typeFilter === 'perp') {
+          try {
+            const allPerps = await client.getAllPerpMetas();
+            for (const dexData of allPerps) {
+              if (!dexData.dexName) continue; // Skip main dex (already searched)
+              for (let i = 0; i < dexData.meta.universe.length; i++) {
+                const asset = dexData.meta.universe[i];
+                if (asset.name.toUpperCase().includes(query)) {
+                  results.push({
+                    coin: `${dexData.dexName}:${asset.name}`,
+                    type: 'hip3',
+                    dex: dexData.dexName,
+                    markPx: dexData.assetCtxs[i]?.markPx,
+                    dayVolume: dexData.assetCtxs[i]?.dayNtlVlm,
+                    maxLeverage: asset.maxLeverage,
+                  });
+                }
+              }
+            }
+          } catch { /* HIP-3 may not be available */ }
+        }
+
         // Search spot
         if (!typeFilter || typeFilter === 'spot') {
           try {
@@ -472,6 +495,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
           '1d': 86_400_000, '3d': 259_200_000, '1w': 604_800_000, '1M': 2_592_000_000,
         };
 
+        // Load metadata for HIP-3 coin resolution
+        await client.getMetaAndAssetCtxs();
         const now = Date.now();
         const startTime = now - (bars * (intervalMs[interval] || 3_600_000));
         const candles = await client.getCandleSnapshot(coin, interval, startTime);
@@ -512,6 +537,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const hours = (params.hours as number) || 24;
         const startTime = Date.now() - (hours * 3_600_000);
 
+        // Load metadata for HIP-3 coin resolution
+        await client.getMetaAndAssetCtxs();
         const history = await client.getFundingHistory(coin, startTime);
 
         const rates = history.map(e => parseFloat(e.fundingRate));
@@ -548,6 +575,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
         const client = getClient();
 
         const coin = (params.coin as string).toUpperCase();
+        // Load metadata for HIP-3 coin resolution
+        await client.getMetaAndAssetCtxs();
         let trades = await client.getRecentTrades(coin);
 
         trades.sort((a, b) => b.time - a.time);
@@ -600,6 +629,97 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
       },
     },
 
+    {
+      name: 'ob_funding_scan',
+      description: 'Scan funding rates across all dexes (main + HIP-3) for arbitrage opportunities',
+      parameters: {
+        type: 'object',
+        properties: {
+          threshold: { type: 'number', description: 'Min annualized funding rate % to show (default: 25)' },
+          mainOnly: { type: 'boolean', description: 'Only scan main perps' },
+          hip3Only: { type: 'boolean', description: 'Only scan HIP-3 perps' },
+          top: { type: 'number', description: 'Number of results (default: 30)' },
+          pairs: { type: 'boolean', description: 'Show opposing funding pairs' },
+        },
+      },
+      async execute(_id, params) {
+        const { getClient } = await import('../core/client.js');
+        const { annualizeFundingRate } = await import('../core/utils.js');
+        const client = getClient();
+
+        const threshold = (params.threshold as number) ?? 25;
+        const mainOnly = params.mainOnly as boolean ?? false;
+        const hip3Only = params.hip3Only as boolean ?? false;
+        const topN = (params.top as number) ?? 30;
+
+        const allPerps = await client.getAllPerpMetas();
+        const results: Array<Record<string, unknown>> = [];
+
+        for (const dexData of allPerps) {
+          const isMain = !dexData.dexName;
+          if (mainOnly && !isMain) continue;
+          if (hip3Only && isMain) continue;
+
+          for (let i = 0; i < dexData.meta.universe.length; i++) {
+            const asset = dexData.meta.universe[i];
+            const ctx = dexData.assetCtxs[i];
+            if (!ctx) continue;
+
+            const hourlyRate = parseFloat(ctx.funding);
+            const annualizedPct = annualizeFundingRate(hourlyRate) * 100;
+            const openInterest = parseFloat(ctx.openInterest);
+
+            if (Math.abs(annualizedPct) < threshold) continue;
+            if (openInterest < 100) continue;
+
+            results.push({
+              coin: dexData.dexName ? `${dexData.dexName}:${asset.name}` : asset.name,
+              dex: dexData.dexName ?? 'main',
+              annualizedPct: annualizedPct.toFixed(1),
+              direction: hourlyRate > 0 ? 'longs pay shorts' : 'shorts pay longs',
+              collectBy: hourlyRate > 0 ? 'SHORT' : 'LONG',
+              openInterest: ctx.openInterest,
+              markPx: ctx.markPx,
+            });
+          }
+        }
+
+        results.sort((a, b) => Math.abs(parseFloat(b.annualizedPct as string)) - Math.abs(parseFloat(a.annualizedPct as string)));
+
+        const output: Record<string, unknown> = {
+          threshold,
+          scope: mainOnly ? 'main' : hip3Only ? 'hip3' : 'all',
+          results: results.slice(0, topN),
+        };
+
+        // Find opposing pairs if requested
+        if (params.pairs) {
+          const longs = results.filter(r => parseFloat(r.annualizedPct as string) > 0);
+          const shorts = results.filter(r => parseFloat(r.annualizedPct as string) < 0);
+          const pairs: Array<Record<string, unknown>> = [];
+
+          for (const l of longs) {
+            for (const s of shorts) {
+              const spread = parseFloat(l.annualizedPct as string) + Math.abs(parseFloat(s.annualizedPct as string));
+              if (spread > 20) {
+                pairs.push({
+                  short: l.coin,
+                  shortFunding: l.annualizedPct,
+                  long: s.coin,
+                  longFunding: s.annualizedPct,
+                  spreadPct: spread.toFixed(1),
+                });
+              }
+            }
+          }
+          pairs.sort((a, b) => parseFloat(b.spreadPct as string) - parseFloat(a.spreadPct as string));
+          output.opposingPairs = pairs.slice(0, 10);
+        }
+
+        return json(output);
+      },
+    },
+
     // ── Trading Tools ───────────────────────────────────────────
 
     {

package/scripts/setup/onboard.ts

@@ -268,11 +268,13 @@ async function main(): Promise<OnboardResult> {
   console.log('Step 1/3: Wallet Setup');
   console.log('----------------------');
   console.log('How would you like to set up your wallet?\n');
-  console.log('  1) Import existing private key (master wallet)');
-  console.log('  2) Generate a new wallet (master wallet)');
-  console.log('  3) Generate API wallet (recommended for agents)');
-  console.log('     Safer: can trade but cannot withdraw funds.');
-  console.log('     Requires browser approval from your master wallet.\n');
+  console.log('  1) Generate a fresh wallet (recommended for agents)');
+  console.log('     Creates a dedicated trading wallet. Builder fee is auto-approved.');
+  console.log('     Just fund it with USDC and start trading — no browser steps needed.');
+  console.log('');
+  console.log('  2) Import existing private key');
+  console.log('  3) Generate API wallet (restricted, requires browser approval)');
+  console.log('     Can trade but cannot withdraw. Requires master wallet approval in browser.\n');
 
   let choice = '';
   while (choice !== '1' && choice !== '2' && choice !== '3') {
@@ -292,7 +294,7 @@ async function main(): Promise<OnboardResult> {
   // Options 1 & 2: Master wallet flow
   let privateKey: `0x${string}`;
 
-  if (choice === '1') {
+  if (choice === '2') {
     // User has existing key
     const rl2 = createReadline();
     console.log('\nEnter your private key (0x... format):\n');
@@ -313,7 +315,7 @@ async function main(): Promise<OnboardResult> {
 
     console.log('\n✅ Private key accepted');
   } else {
-    // Generate new wallet
+    // Generate new wallet (option 1)
     console.log('\nGenerating new wallet...');
     privateKey = generatePrivateKey();
     console.log('✅ New wallet created');
@@ -385,7 +387,7 @@ HYPERLIQUID_NETWORK=mainnet
   console.log(`Network: Hyperliquid (Mainnet)`);
   console.log(`Config:  ${CONFIG_PATH}`);
 
-  if (choice === '2') {
+  if (choice === '1' || choice === '2') {
     console.log('\n⚠️  IMPORTANT: Save your private key!');
     console.log('-----------------------------------');
     console.log(`Private Key: ${privateKey}`);

package/scripts/strategies/funding-arb.ts

@@ -95,11 +95,36 @@ async function main() {
   console.log('===============================\n');
 
   try {
-    // Initial funding check
+    // Initial funding check - loads main + HIP-3 assets
     await client.getMetaAndAssetCtxs();
-    const meta = await client.getMetaAndAssetCtxs();
-    const assetIndex = client.getAssetIndex(coin);
-    const assetCtx = meta.assetCtxs[assetIndex];
+
+    // For HIP-3 assets, we need to fetch funding from the dex-specific metadata
+    let hourlyFunding: number;
+    let openInterestVal: number;
+
+    if (client.isHip3(coin)) {
+      const allPerps = await client.getAllPerpMetas();
+      const dexName = client.getCoinDex(coin);
+      const localName = client.getCoinLocalName(coin);
+      const dexData = allPerps.find(d => d.dexName === dexName);
+      if (!dexData) {
+        console.error(`Error: No market data for HIP-3 dex ${dexName}`);
+        process.exit(1);
+      }
+      const assetIdx = dexData.meta.universe.findIndex(a => a.name === localName);
+      if (assetIdx === -1 || !dexData.assetCtxs[assetIdx]) {
+        console.error(`Error: No market data for ${coin}`);
+        process.exit(1);
+      }
+      hourlyFunding = parseFloat(dexData.assetCtxs[assetIdx].funding);
+      openInterestVal = parseFloat(dexData.assetCtxs[assetIdx].openInterest);
+    } else {
+      const meta = await client.getMetaAndAssetCtxs();
+      const assetIndex = client.getAssetIndex(coin);
+      const assetCtx = meta.assetCtxs[assetIndex];
+      hourlyFunding = parseFloat(assetCtx.funding);
+      openInterestVal = parseFloat(assetCtx.openInterest);
+    }
 
     const mids = await client.getAllMids();
     const midPrice = parseFloat(mids[coin]);
@@ -108,9 +133,7 @@ async function main() {
       process.exit(1);
     }
 
-    const hourlyFunding = parseFloat(assetCtx.funding);
     const annualizedFunding = annualizeFundingRate(hourlyFunding) * 100; // as percentage
-    const openInterest = parseFloat(assetCtx.openInterest);
     const positionSize = notionalSize / midPrice;
 
     console.log('Current Market State');
@@ -119,7 +142,7 @@ async function main() {
     console.log(`Mid Price:         ${formatUsd(midPrice)}`);
     console.log(`Hourly Funding:    ${(hourlyFunding * 100).toFixed(4)}%`);
     console.log(`Annualized:        ${annualizedFunding.toFixed(2)}%`);
-    console.log(`Open Interest:     ${formatUsd(openInterest)}`);
+    console.log(`Open Interest:     ${formatUsd(openInterestVal)}`);
     console.log(`\nStrategy Config`);
     console.log('---------------');
     console.log(`Target Notional:   ${formatUsd(notionalSize)}`);
@@ -218,9 +241,19 @@ async function main() {
         await sleep(checkInterval);
 
         // Get updated funding
-        const newMeta = await client.getMetaAndAssetCtxs();
-        const newAssetCtx = newMeta.assetCtxs[assetIndex];
-        const newHourlyFunding = parseFloat(newAssetCtx.funding);
+        let newHourlyFunding: number;
+        if (client.isHip3(coin)) {
+          const freshPerps = await client.getAllPerpMetas();
+          const dexName = client.getCoinDex(coin);
+          const localName = client.getCoinLocalName(coin);
+          const dexData = freshPerps.find(d => d.dexName === dexName);
+          const idx = dexData?.meta.universe.findIndex(a => a.name === localName) ?? -1;
+          newHourlyFunding = idx >= 0 && dexData?.assetCtxs[idx] ? parseFloat(dexData.assetCtxs[idx].funding) : 0;
+        } else {
+          const newMeta = await client.getMetaAndAssetCtxs();
+          const assetIndex = client.getAssetIndex(coin);
+          newHourlyFunding = parseFloat(newMeta.assetCtxs[assetIndex].funding);
+        }
         const newAnnualized = annualizeFundingRate(newHourlyFunding) * 100;
         const newMids = await client.getAllMids();
         const newPrice = parseFloat(newMids[coin]);