openbroker 1.0.80 → 1.0.85

package/scripts/core/config.ts

@@ -42,6 +42,20 @@ function loadEnvFile(): string | null {
   const verbose = process.env.VERBOSE === '1' || process.env.VERBOSE === 'true';
   process.env.DOTENV_CONFIG_QUIET = 'true';
 
+  // Explicit config path via -c / --config (highest priority — overrides shell env vars)
+  const explicitPath = process.env.OPENBROKER_CONFIG;
+  if (explicitPath) {
+    if (existsSync(explicitPath)) {
+      loadDotenv({ path: explicitPath, override: true });
+      if (verbose) {
+        console.log(`[DEBUG] Loaded config from -c flag: ${explicitPath}`);
+      }
+      return explicitPath;
+    }
+    console.error(`Config file not found: ${explicitPath}`);
+    process.exit(1);
+  }
+
   // Check locations in order of priority
   const locations = [
     { path: LOCAL_ENV_PATH, name: 'local (.env)' },
@@ -98,7 +112,7 @@ export function loadConfig(): OpenBrokerConfig {
     // Show warning once
     if (!readOnlyWarningShown) {
       readOnlyWarningShown = true;
-      console.log('\x1b[33m⚠️  Not configured for trading. Run "openbroker setup" to enable trades.\x1b[0m\n');
+      console.error('\x1b[33m⚠️  Not configured for trading. Run "openbroker setup" to enable trades.\x1b[0m\n');
     }
   }
 
@@ -124,6 +138,10 @@ export function loadConfig(): OpenBrokerConfig {
   // Determine if this is an API wallet setup
   const isApiWallet = accountAddress !== undefined && accountAddress !== walletAddress;
 
+  // Vault address — only for vault trading (ERC4626 contracts / native vaults via CoreWriter).
+  // Standard API wallets (approved via approveAgent) do NOT need this.
+  const vaultAddress = process.env.HYPERLIQUID_VAULT_ADDRESS?.toLowerCase();
+
   return {
     baseUrl,
     privateKey: privateKey as `0x${string}`,
@@ -134,6 +152,7 @@ export function loadConfig(): OpenBrokerConfig {
     builderAddress,
     builderFee,
     slippageBps,
+    vaultAddress,
   };
 }
 

package/scripts/core/types.ts

@@ -12,6 +12,7 @@ export interface OpenBrokerConfig {
   builderAddress: string;
   builderFee: number;         // tenths of bps (10 = 1 bps)
   slippageBps: number;
+  vaultAddress?: string;      // Explicit vault address for vault trading (ERC4626 / native vaults via CoreWriter)
 }
 
 // ============ Builder ============

package/scripts/core/utils.ts

@@ -155,8 +155,11 @@ export function generateCloid(): string {
  * Returns true if approved, false if not
  */
 export async function checkBuilderFeeApproval(
-  client: { getMaxBuilderFee: () => Promise<string | null>; builderAddress: string }
+  client: { getMaxBuilderFee: () => Promise<string | null>; builderAddress: string; isTestnet: boolean }
 ): Promise<boolean> {
+  // Skip builder fee check on testnet — builder may not have balance
+  if (client.isTestnet) return true;
+
   const approval = await client.getMaxBuilderFee();
   if (!approval) {
     console.log('⚠️  Builder fee not approved!');

package/scripts/info/account.ts

@@ -123,15 +123,19 @@ async function main() {
     console.log(`Account Mode:     ${modeLabel[accountMode] ?? accountMode}`);
 
     if (!isOtherAccount) {
-      // Check builder fee approval
-      const builderApproval = await client.getMaxBuilderFee();
-      console.log(`Builder Address:  ${client.builderAddress}`);
-      console.log(`Builder Fee:      ${client.builderFeeBps} bps`);
-      if (builderApproval) {
-        console.log(`Builder Approved: ✅ Yes (max: ${builderApproval})`);
+      // Check builder fee approval (skip on testnet)
+      if (client.isTestnet) {
+        console.log(`Builder Fee:      skipped (testnet)`);
       } else {
-        console.log(`Builder Approved: ❌ No`);
-        console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
+        const builderApproval = await client.getMaxBuilderFee();
+        console.log(`Builder Address:  ${client.builderAddress}`);
+        console.log(`Builder Fee:      ${client.builderFeeBps} bps`);
+        if (builderApproval) {
+          console.log(`Builder Approved: ✅ Yes (max: ${builderApproval})`);
+        } else {
+          console.log(`Builder Approved: ❌ No`);
+          console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
+        }
       }
 
       // Warn if API wallet setup looks misconfigured

package/scripts/info/all-markets.ts

@@ -7,6 +7,7 @@ interface Args {
   type?: 'perp' | 'spot' | 'hip3' | 'all';
   top?: number;
   verbose?: boolean;
+  json?: boolean;
 }
 
 function parseArgs(): Args {
@@ -23,6 +24,8 @@ function parseArgs(): Args {
       args.top = parseInt(process.argv[++i], 10);
     } else if (arg === '--verbose') {
       args.verbose = true;
+    } else if (arg === '--json') {
+      args.json = true;
     } else if (arg === '--help' || arg === '-h') {
       console.log(`
 All Markets - View all available markets on Hyperliquid
@@ -32,6 +35,7 @@ Usage: npx tsx scripts/info/all-markets.ts [options]
 Options:
   --type <type>    Market type: perp, spot, hip3, or all (default: all)
   --top <n>        Show only top N markets by volume
+  --json           Output as JSON (machine-readable)
   --verbose        Show detailed output
   --help           Show this help
 
@@ -41,6 +45,7 @@ Examples:
   npx tsx scripts/info/all-markets.ts --type hip3    # Show only HIP-3 perps
   npx tsx scripts/info/all-markets.ts --type spot    # Show only spot markets
   npx tsx scripts/info/all-markets.ts --top 20       # Show top 20 by volume
+  npx tsx scripts/info/all-markets.ts --json         # JSON output
 `);
       process.exit(0);
     }
@@ -71,22 +76,27 @@ function formatFunding(rate: string): string {
   return `${sign}${annualized.toFixed(2)}%`;
 }
 
+interface MarketRow {
+  type: 'perp' | 'spot' | 'hip3';
+  provider: string;
+  coin: string;
+  assetId: number;
+  price: string;
+  volume24h: number;
+  funding?: string;
+  maxLeverage?: number;
+}
+
 async function main() {
   const args = parseArgs();
   const client = getClient();
   client.verbose = args.verbose ?? false;
 
-  console.log('Fetching market data...\n');
+  if (!args.json) {
+    console.log('Fetching market data...\n');
+  }
 
-  const allMarkets: Array<{
-    type: 'perp' | 'spot' | 'hip3';
-    provider: string;
-    coin: string;
-    price: string;
-    volume24h: number;
-    funding?: string;
-    maxLeverage?: number;
-  }> = [];
+  const allMarkets: MarketRow[] = [];
 
   // Fetch main perps
   if (args.type === 'all' || args.type === 'perp') {
@@ -98,6 +108,7 @@ async function main() {
         type: 'perp',
         provider: 'Hyperliquid',
         coin: asset.name,
+        assetId: i,
         price: ctx.markPx,
         volume24h: parseFloat(ctx.dayNtlVlm),
         funding: ctx.funding,
@@ -108,6 +119,9 @@ async function main() {
 
   // Fetch HIP-3 perps
   if (args.type === 'all' || args.type === 'hip3') {
+    if (client.isTestnet && !args.json) {
+      console.log('Note: Testnet — HIP-3 dexes not auto-loaded. Use "dexName:COIN" syntax to load a specific dex.\n');
+    }
     try {
       const allPerpMetas = await client.getAllPerpMetas();
       // Skip index 0 (main dex), process HIP-3 dexs
@@ -120,10 +134,13 @@ async function main() {
           const ctx = dexData.assetCtxs[i];
           if (!asset || !ctx) continue;
 
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(asset.name); } catch { /* not registered */ }
           allMarkets.push({
             type: 'hip3',
             provider: dexData.dexName || `HIP-3 DEX ${dexIdx}`,
             coin: asset.name,
+            assetId,
             price: ctx.markPx,
             volume24h: parseFloat(ctx.dayNtlVlm || '0'),
             funding: ctx.funding,
@@ -140,15 +157,23 @@ 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;
+      // contexts carry coin field that matches pair.name; not necessarily 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;
 
         allMarkets.push({
           type: 'spot',
           provider: 'Spot',
           coin: pair.name,
+          assetId: 10000 + pair.index,
           price: ctx.markPx,
           volume24h: parseFloat(ctx.dayNtlVlm || '0'),
         });
@@ -164,6 +189,11 @@ async function main() {
   // Apply top filter
   const markets = args.top ? allMarkets.slice(0, args.top) : allMarkets;
 
+  if (args.json) {
+    console.log(JSON.stringify(markets, null, 2));
+    return;
+  }
+
   // Group by type for display
   const perps = markets.filter((m) => m.type === 'perp');
   const hip3 = markets.filter((m) => m.type === 'hip3');
@@ -180,11 +210,11 @@ async function main() {
   // Print perps
   if (perps.length > 0) {
     console.log('=== Main Perpetuals ===\n');
-    console.log('Coin           Price            24h Volume    Funding (Ann.)  Leverage');
-    console.log('-'.repeat(75));
+    console.log('Coin           AssetID    Price            24h Volume    Funding (Ann.)  Leverage');
+    console.log('-'.repeat(87));
     for (const m of perps) {
       console.log(
-        `${m.coin.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)} ${(m.maxLeverage ? `${m.maxLeverage}x` : '-').padStart(9)}`
+        `${m.coin.padEnd(14)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)} ${(m.maxLeverage ? `${m.maxLeverage}x` : '-').padStart(9)}`
       );
     }
     console.log();
@@ -193,11 +223,11 @@ async function main() {
   // Print HIP-3 markets
   if (hip3.length > 0) {
     console.log('=== HIP-3 Perpetuals ===\n');
-    console.log('Coin           Provider         Price            24h Volume    Funding (Ann.)');
-    console.log('-'.repeat(80));
+    console.log('Coin           Provider         AssetID    Price            24h Volume    Funding (Ann.)');
+    console.log('-'.repeat(92));
     for (const m of hip3) {
       console.log(
-        `${m.coin.padEnd(14)} ${m.provider.padEnd(16)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)}`
+        `${m.coin.padEnd(14)} ${m.provider.padEnd(16)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)}`
       );
     }
     console.log();
@@ -206,11 +236,11 @@ async function main() {
   // Print spot markets
   if (spots.length > 0) {
     console.log('=== Spot Markets ===\n');
-    console.log('Pair           Price            24h Volume');
-    console.log('-'.repeat(50));
+    console.log('Pair           AssetID    Price            24h Volume');
+    console.log('-'.repeat(62));
     for (const m of spots) {
       console.log(
-        `${m.coin.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)}`
+        `${m.coin.padEnd(14)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)}`
       );
     }
     console.log();

package/scripts/info/candles.ts

@@ -21,6 +21,7 @@ Options:
   --interval <interval> Candle interval (default: 1h)
                        Valid: ${VALID_INTERVALS.join(', ')}
   --bars <n>           Number of bars to fetch (default: 24)
+  --json               Output as JSON (machine-readable)
   --help, -h           Show this help
 
 Examples:
@@ -59,19 +60,32 @@ async function main() {
   }
 
   const bars = parseInt(args.bars as string) || 24;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log(`Open Broker - ${normalizeCoin(coin)} Candles (${interval})`);
-  console.log('='.repeat(40) + '\n');
+  if (!jsonOutput) {
+    console.log(`Open Broker - ${normalizeCoin(coin)} Candles (${interval})`);
+    console.log('='.repeat(40) + '\n');
+  }
 
   try {
     // Load metadata (needed for HIP-3 coin resolution)
     await client.getMetaAndAssetCtxs();
+    if (client.isTestnet && coin.includes(':')) {
+      await client.loadSingleHip3Dex(coin.split(':')[0]);
+    }
 
     const now = Date.now();
     const startTime = now - (bars * (INTERVAL_MS[interval] || 3_600_000));
     const candles = await client.getCandleSnapshot(normalizeCoin(coin), interval, startTime);
 
+    if (jsonOutput) {
+      let assetId = -1;
+      try { assetId = client.getAssetIndex(normalizeCoin(coin)); } catch { /* noop */ }
+      console.log(JSON.stringify({ coin: normalizeCoin(coin), assetId, interval, candles }, null, 2));
+      return;
+    }
+
     if (candles.length === 0) {
       console.log('No candle data found');
       return;

package/scripts/info/fees.ts

@@ -9,10 +9,13 @@ function printUsage() {
 Usage: openbroker fees [options]
 
 Options:
-  --help, -h    Show this help
+  --address <0x...>  Look up another account's fees
+  --json             Output as JSON (machine-readable)
+  --help, -h         Show this help
 
 Examples:
   openbroker fees
+  openbroker fees --json
 `);
 }
 
@@ -25,19 +28,27 @@ async function main() {
   }
 
   const targetAddress = args.address as string | undefined;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
   const lookupAddress = targetAddress?.toLowerCase();
 
-  console.log('Open Broker - Fee Schedule');
-  console.log('=========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - Fee Schedule');
+    console.log('=========================\n');
 
-  if (targetAddress) {
-    console.log(`Lookup: ${lookupAddress}\n`);
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
   }
 
   try {
     const fees = await client.getUserFees(lookupAddress);
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(fees, null, 2));
+      return;
+    }
+
     // Fee rates
     console.log('Fee Rates');
     console.log('─'.repeat(40));

package/scripts/info/funding-history.ts

@@ -11,6 +11,7 @@ Usage: openbroker funding-history --coin <symbol> [options]
 Options:
   --coin <symbol>   Asset symbol (required, e.g. ETH, BTC)
   --hours <n>       Hours of history to fetch (default: 24)
+  --json            Output as JSON (machine-readable)
   --help, -h        Show this help
 
 Examples:
@@ -35,19 +36,32 @@ async function main() {
   }
 
   const hours = parseInt(args.hours as string) || 24;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log(`Open Broker - ${normalizeCoin(coin)} Funding History (${hours}h)`);
-  console.log('='.repeat(40) + '\n');
+  if (!jsonOutput) {
+    console.log(`Open Broker - ${normalizeCoin(coin)} Funding History (${hours}h)`);
+    console.log('='.repeat(40) + '\n');
+  }
 
   try {
     // Load metadata (needed for HIP-3 coin resolution)
     await client.getMetaAndAssetCtxs();
+    if (client.isTestnet && coin.includes(':')) {
+      await client.loadSingleHip3Dex(coin.split(':')[0]);
+    }
 
     const now = Date.now();
     const startTime = now - (hours * 3_600_000);
     const history = await client.getFundingHistory(normalizeCoin(coin), startTime);
 
+    if (jsonOutput) {
+      let assetId = -1;
+      try { assetId = client.getAssetIndex(normalizeCoin(coin)); } catch { /* noop */ }
+      console.log(JSON.stringify({ coin: normalizeCoin(coin), assetId, history }, null, 2));
+      return;
+    }
+
     if (history.length === 0) {
       console.log('No funding history found');
       return;

package/scripts/info/funding-scan.ts

@@ -32,6 +32,7 @@ Examples:
 
 interface FundingScanResult {
   coin: string;
+  assetId: number;
   dex: string;
   hourlyRate: number;
   annualizedPct: number;
@@ -69,9 +70,14 @@ async function scanFunding(client: ReturnType<typeof getClient>, options: {
 
       // API returns HIP-3 names already prefixed (e.g., "xyz:CL")
       const coin = asset.name;
+      let assetId = isMain ? i : -1;
+      if (!isMain) {
+        try { assetId = client.getAssetIndex(coin); } catch { /* not registered */ }
+      }
 
       results.push({
         coin,
+        assetId,
         dex: dexData.dexName ?? 'main',
         hourlyRate,
         annualizedPct,
@@ -184,6 +190,10 @@ async function main() {
   console.log('==================================\n');
   console.log(`Threshold: ${threshold}% annualized | Scope: ${mainOnly ? 'main only' : hip3Only ? 'HIP-3 only' : 'all dexes'}\n`);
 
+  if (client.isTestnet && !mainOnly) {
+    console.log('Note: Testnet — HIP-3 dexes not auto-loaded. Only main perps will be scanned.\n');
+  }
+
   const options = { threshold, mainOnly, hip3Only, topN };
 
   const runScan = async () => {

package/scripts/info/funding.ts

@@ -6,6 +6,7 @@ import { formatPercent, annualizeFundingRate, parseArgs } from '../core/utils.js
 
 interface FundingDisplay {
   coin: string;
+  assetId: number;
   hourlyRate: number;
   annualizedRate: number;
   premium: number;
@@ -47,6 +48,7 @@ async function main() {
 
       fundingData.push({
         coin: asset.name,
+        assetId: i,
         hourlyRate,
         annualizedRate,
         premium,
@@ -56,7 +58,14 @@ async function main() {
     }
 
     // Include HIP-3 dex assets
+    if (client.isTestnet && (includeHip3 || showAll) && !(filterCoin?.includes(':'))) {
+      console.log('Note: Testnet — HIP-3 dexes not auto-loaded. Use --coin dexName:COIN to view a specific HIP-3 asset.\n');
+    }
     if (includeHip3 || showAll || (filterCoin && filterCoin.includes(':'))) {
+      // On testnet, load the specific dex on demand if user specified dex:COIN
+      if (client.isTestnet && filterCoin?.includes(':')) {
+        await client.loadSingleHip3Dex(filterCoin.split(':')[0]);
+      }
       const allPerps = await client.getAllPerpMetas();
       for (const dexData of allPerps) {
         if (!dexData.dexName) continue; // Skip main dex (already loaded)
@@ -77,8 +86,12 @@ async function main() {
 
           if (!showAll && openInterest < 1000) continue;
 
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(coinName); } catch { /* not registered */ }
+
           fundingData.push({
             coin: coinName,
+            assetId,
             hourlyRate,
             annualizedRate,
             premium: 0,

package/scripts/info/markets.ts

@@ -6,6 +6,7 @@ import { formatUsd, parseArgs } from '../core/utils.js';
 
 interface MarketDisplay {
   coin: string;
+  assetId: number;
   markPx: number;
   oraclePx: number;
   prevDayPx: number;
@@ -47,6 +48,7 @@ async function main() {
 
       markets.push({
         coin: asset.name,
+        assetId: i,
         markPx,
         oraclePx,
         prevDayPx,
@@ -59,7 +61,14 @@ async function main() {
     }
 
     // Include HIP-3 markets
+    if (client.isTestnet && includeHip3 && !(filterCoin?.includes(':'))) {
+      console.log('Note: Testnet — HIP-3 dexes not auto-loaded. Use --coin dexName:COIN to view a specific HIP-3 asset.\n');
+    }
     if (includeHip3 || (filterCoin && filterCoin.includes(':'))) {
+      // On testnet, load the specific dex on demand if user specified dex:COIN
+      if (client.isTestnet && filterCoin?.includes(':')) {
+        await client.loadSingleHip3Dex(filterCoin.split(':')[0]);
+      }
       const allPerps = await client.getAllPerpMetas();
       for (const dexData of allPerps) {
         if (!dexData.dexName) continue;
@@ -79,9 +88,12 @@ async function main() {
           const volume24h = parseFloat(ctx.dayNtlVlm);
           const openInterest = parseFloat(ctx.openInterest);
           const change24h = prevDayPx > 0 ? (markPx - prevDayPx) / prevDayPx : 0;
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(coinName); } catch { /* not registered */ }
 
           markets.push({
             coin: coinName,
+            assetId,
             markPx,
             oraclePx,
             prevDayPx,

package/scripts/info/order-status.ts

@@ -11,6 +11,7 @@ Usage: openbroker order-status --oid <order-id>
 Options:
   --oid <id>          Order ID (number) or client order ID (hex string) — required
   --address <0x...>   Look up order on another account
+  --json              Output as JSON (machine-readable)
   --help, -h          Show this help
 
 Examples:
@@ -37,15 +38,23 @@ async function main() {
 
   const oid = oidArg.startsWith('0x') ? oidArg : parseInt(oidArg);
   const targetAddress = args.address as string | undefined;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
   const lookupAddress = targetAddress?.toLowerCase();
 
-  console.log('Open Broker - Order Status');
-  console.log('=========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - Order Status');
+    console.log('=========================\n');
+  }
 
   try {
     const result = await client.getOrderStatus(oid, lookupAddress);
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
     if (result.status === 'unknownOid') {
       console.log(`Order ${oidArg} not found`);
       return;

package/scripts/info/orders.ts

@@ -45,6 +45,11 @@ async function main() {
   const lookupAddress = targetAddress?.toLowerCase();
 
   try {
+    // On testnet, load specific HIP-3 dex on demand if filtering by dex:COIN
+    if (client.isTestnet && filterCoin?.includes(':')) {
+      await client.loadSingleHip3Dex(filterCoin.split(':')[0]);
+    }
+
     if (openOnly) {
       // Use the dedicated open orders endpoint
       let openOrders = await client.getOpenOrders(lookupAddress);

package/scripts/info/rate-limit.ts

@@ -9,6 +9,7 @@ function printUsage() {
 Usage: openbroker rate-limit [options]
 
 Options:
+  --json        Output as JSON (machine-readable)
   --help, -h    Show this help
 
 Examples:
@@ -24,14 +25,22 @@ async function main() {
     process.exit(0);
   }
 
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log('Open Broker - API Rate Limit');
-  console.log('===========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - API Rate Limit');
+    console.log('===========================\n');
+  }
 
   try {
     const rl = await client.getUserRateLimit();
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(rl, null, 2));
+      return;
+    }
+
     const used = rl.nRequestsUsed;
     const cap = rl.nRequestsCap;
     const surplus = rl.nRequestsSurplus;