openbroker 1.1.2 → 1.3.0

package/scripts/info/outcomes.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env tsx
+// HIP-4 Outcomes - search and inspect prediction markets
+
+import { getClient } from '../core/client.js';
+
+interface Args {
+  query?: string;
+  outcome?: string;
+  side?: string;
+  balances?: boolean;
+  top?: number;
+  verbose?: boolean;
+  json?: boolean;
+}
+
+function parseArgs(): Args {
+  const args: Args = {};
+
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+    if ((arg === '--query' || arg === '-q') && process.argv[i + 1]) {
+      args.query = process.argv[++i];
+    } else if ((arg === '--outcome' || arg === '--id') && process.argv[i + 1]) {
+      args.outcome = process.argv[++i];
+    } else if (arg === '--side' && process.argv[i + 1]) {
+      args.side = process.argv[++i];
+    } else if (arg === '--balances') {
+      args.balances = true;
+    } else if (arg === '--top' && process.argv[i + 1]) {
+      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') {
+      printUsage();
+      process.exit(0);
+    } else if (!args.query && !arg.startsWith('-')) {
+      args.query = arg;
+    }
+  }
+
+  return args;
+}
+
+function printUsage() {
+  console.log(`
+Open Broker - HIP-4 Outcomes
+============================
+
+Search and inspect Hyperliquid outcome markets.
+
+Usage:
+  openbroker outcomes [--query <text>] [--outcome <id|#encoding|+encoding>] [options]
+
+Options:
+  --query, -q <text>       Search market name, description, underlying, expiry, target
+  --outcome, --id <ref>    Show one outcome by id or encoded coin (#1230 / +1230)
+  --side <yes|no|0|1>      Select a side when using a plain outcome id
+  --balances               Show outcome token balances for the configured account
+  --top <n>                Show only top N matches
+  --json                   Output as JSON
+  --verbose                Include raw descriptions and question metadata
+
+Examples:
+  openbroker outcomes --query BTC
+  openbroker outcomes --outcome 123
+  openbroker outcomes --outcome 123 --side yes --json
+  openbroker outcomes --balances
+`);
+}
+
+function formatPrice(value?: string): string {
+  if (!value) return '-';
+  const n = parseFloat(value);
+  if (!Number.isFinite(n)) return value;
+  return n.toFixed(4);
+}
+
+function formatVolume(value?: string): string {
+  if (!value) return '-';
+  const n = parseFloat(value);
+  if (!Number.isFinite(n)) return value;
+  if (n >= 1_000_000) return `$${(n / 1_000_000).toFixed(2)}M`;
+  if (n >= 1_000) return `$${(n / 1_000).toFixed(2)}K`;
+  return `$${n.toFixed(2)}`;
+}
+
+async function main() {
+  const args = parseArgs();
+  const client = getClient();
+  client.verbose = args.verbose ?? false;
+
+  if (!args.json) {
+    console.log('Open Broker - HIP-4 Outcomes');
+    console.log('============================\n');
+  }
+
+  try {
+    if (args.balances) {
+      const balances = await client.getSpotBalances();
+      const outcomeBalances = (balances.balances ?? []).filter((b) =>
+        b.coin.startsWith('+') || b.coin.startsWith('#')
+      );
+
+      if (args.json) {
+        console.log(JSON.stringify(outcomeBalances, null, 2));
+        return;
+      }
+
+      if (outcomeBalances.length === 0) {
+        console.log('No outcome token balances found.');
+        return;
+      }
+
+      console.log('Outcome Balances');
+      console.log('----------------');
+      console.log('Token        Total              Hold               Entry Value');
+      console.log('-'.repeat(70));
+      for (const b of outcomeBalances) {
+        console.log(
+          `${b.coin.padEnd(12)} ${parseFloat(b.total).toFixed(6).padStart(18)} ` +
+          `${parseFloat(b.hold).toFixed(6).padStart(18)} ${formatVolume(b.entryNtl).padStart(15)}`
+        );
+      }
+      return;
+    }
+
+    let markets = await client.getOutcomeMarkets();
+
+    if (args.outcome) {
+      const resolved = client.resolveOutcomeRef(args.outcome, args.side);
+      markets = markets.filter((market) => market.outcome === resolved.outcome);
+      for (const market of markets) {
+        market.sides = market.sides.filter((side) => side.side === resolved.side);
+      }
+    }
+
+    if (args.query) {
+      const query = args.query.toUpperCase();
+      markets = markets.filter((market) => {
+        const parsed = Object.values(market.parsedDescription).join(' ');
+        const searchable = `${market.name} ${market.description} ${parsed}`.toUpperCase();
+        return searchable.includes(query);
+      });
+    }
+
+    markets.sort((a, b) => {
+      const aVol = Math.max(...a.sides.map((s) => parseFloat(s.dayNtlVlm ?? '0')));
+      const bVol = Math.max(...b.sides.map((s) => parseFloat(s.dayNtlVlm ?? '0')));
+      return bVol - aVol;
+    });
+
+    const displayMarkets = args.top ? markets.slice(0, args.top) : markets;
+
+    if (args.json) {
+      console.log(JSON.stringify(displayMarkets, null, 2));
+      return;
+    }
+
+    if (displayMarkets.length === 0) {
+      console.log('No outcome markets found.');
+      return;
+    }
+
+    console.log(`Found ${displayMarkets.length} outcome market(s)\n`);
+    console.log('Outcome   Side  Coin       AssetID      Price    24h Volume   Market');
+    console.log('-'.repeat(98));
+
+    for (const market of displayMarkets) {
+      const spec = market.parsedDescription;
+      const labelParts = [
+        spec.underlying,
+        spec.expiry ? `exp ${spec.expiry}` : undefined,
+        spec.targetPrice ? `target ${spec.targetPrice}` : undefined,
+      ].filter(Boolean);
+      const label = labelParts.length > 0 ? labelParts.join(' | ') : market.description;
+
+      for (const side of market.sides) {
+        console.log(
+          `${String(market.outcome).padStart(7)}   ${side.name.padEnd(4)}  ${side.coin.padEnd(9)} ` +
+          `${String(side.assetId).padStart(10)}   ${formatPrice(side.midPx ?? side.markPx).padStart(7)} ` +
+          `${formatVolume(side.dayNtlVlm).padStart(13)}   ${label}`
+        );
+      }
+
+      if (args.verbose) {
+        console.log(`          Description: ${market.description}`);
+        if (market.question) console.log(`          Question: ${market.question.name}`);
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    console.error('Note: Hyperliquid currently documents outcomeMeta as testnet-only.');
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/info/search-markets.ts

@@ -5,7 +5,7 @@ import { getClient } from '../core/client.js';
 
 interface Args {
   query: string;
-  type?: 'perp' | 'spot' | 'hip3' | 'all';
+  type?: 'perp' | 'spot' | 'hip3' | 'outcome' | 'all';
   verbose?: boolean;
   json?: boolean;
 }
@@ -19,7 +19,7 @@ function parseArgs(): Args {
       args.query = process.argv[++i];
     } else if (arg === '--type' && process.argv[i + 1]) {
       const val = process.argv[++i].toLowerCase();
-      if (['perp', 'spot', 'hip3', 'all'].includes(val)) {
+      if (['perp', 'spot', 'hip3', 'outcome', 'all'].includes(val)) {
         args.type = val as Args['type'];
       }
     } else if (arg === '--verbose') {
@@ -34,7 +34,7 @@ Usage: npx tsx scripts/info/search-markets.ts --query <search> [options]
 
 Options:
   --query <search>  Search term (required) - matches coin name
-  --type <type>     Filter by market type: perp, spot, hip3, or all (default: all)
+  --type <type>     Filter by market type: perp, spot, hip3, outcome, or all (default: all)
   --json            Output as JSON (machine-readable)
   --verbose         Show detailed output
   --help            Show this help
@@ -44,6 +44,7 @@ Examples:
   npx tsx scripts/info/search-markets.ts --query BTC        # Find all BTC markets
   npx tsx scripts/info/search-markets.ts --query ETH --type perp  # ETH perps only
   npx tsx scripts/info/search-markets.ts --query PURR --type spot # PURR spot only
+  npx tsx scripts/info/search-markets.ts --query BTC --type outcome # HIP-4 outcomes only
   npx tsx scripts/info/search-markets.ts --query HYPE --json      # JSON output
 `);
       process.exit(0);
@@ -95,7 +96,7 @@ async function main() {
   }
 
   interface Result {
-    type: 'perp' | 'spot' | 'hip3';
+    type: 'perp' | 'spot' | 'hip3' | 'outcome';
     provider: string;
     coin: string;
     assetId: number;
@@ -104,6 +105,9 @@ async function main() {
     funding?: string;
     maxLeverage?: number;
     openInterest?: string;
+    outcome?: number;
+    outcomeSide?: string;
+    description?: string;
   }
 
   const results: Result[] = [];
@@ -224,6 +228,34 @@ async function main() {
     }
   }
 
+  // Search HIP-4 outcome markets
+  if (args.type === 'all' || args.type === 'outcome') {
+    try {
+      const outcomes = await client.getOutcomeMarkets();
+      for (const market of outcomes) {
+        const parsed = Object.values(market.parsedDescription).join(' ');
+        const searchable = `${market.name} ${market.description} ${parsed}`.toUpperCase();
+        if (!searchable.includes(query)) continue;
+
+        for (const side of market.sides) {
+          results.push({
+            type: 'outcome',
+            provider: 'HIP-4',
+            coin: side.coin,
+            assetId: side.assetId,
+            price: side.midPx ?? side.markPx ?? '0',
+            volume24h: parseFloat(side.dayNtlVlm || '0'),
+            outcome: market.outcome,
+            outcomeSide: side.name,
+            description: market.description,
+          });
+        }
+      }
+    } catch (e) {
+      if (args.verbose) console.error('Failed to fetch HIP-4 outcomes:', e);
+    }
+  }
+
   // Sort by volume
   results.sort((a, b) => b.volume24h - a.volume24h);
 
@@ -242,11 +274,14 @@ async function main() {
   console.log('-'.repeat(112));
 
   for (const m of results) {
-    const typeStr = m.type === 'hip3' ? 'HIP-3' : m.type.charAt(0).toUpperCase() + m.type.slice(1);
+    const typeStr = m.type === 'hip3' ? 'HIP-3' : m.type === 'outcome' ? 'HIP-4' : m.type.charAt(0).toUpperCase() + m.type.slice(1);
     const oi = m.openInterest ? formatVolume(parseFloat(m.openInterest)) : '-';
     console.log(
       `${typeStr.padEnd(8)} ${m.provider.padEnd(16)} ${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)} ${oi.padStart(10)}`
     );
+    if (m.type === 'outcome' && args.verbose) {
+      console.log(`         Outcome ${m.outcome} ${m.outcomeSide}: ${m.description}`);
+    }
   }
 
   // Show comparison if same asset on multiple providers

package/scripts/operations/outcome-order.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env npx tsx
+// Execute a HIP-4 outcome order on Hyperliquid
+
+import { getClient } from '../core/client.js';
+import { checkBuilderFeeApproval, formatUsd, parseArgs } from '../core/utils.js';
+
+function printUsage() {
+  console.log(`
+Open Broker - HIP-4 Outcome Order
+=================================
+
+Buy or sell a YES/NO outcome token.
+
+Usage:
+  openbroker outcome-order --outcome <id|#encoding|+encoding> --outcome-side <yes|no> --side <buy|sell> --size <SIZE>
+
+Options:
+  --outcome        Outcome id, outcome spot coin (#1230), or token name (+1230)
+  --outcome-side   Outcome side when --outcome is a plain id: yes/no or 0/1 (default: yes)
+  --side           Trade side: buy or sell
+  --size           Order size in outcome token units
+  --price          Limit price between 0.001 and 0.999 (omit for market IOC)
+  --tif            Time-in-force for limit orders: Gtc, Ioc, Alo (default: Gtc)
+  --slippage       Slippage tolerance in bps for market orders (default: config, usually 50)
+  --sz-decimals    Override size decimals if outcome metadata omits token decimals
+  --dry            Dry run - show order details without executing
+  --verbose        Show full API request/response for debugging
+
+Examples:
+  openbroker outcomes --query BTC
+  openbroker outcome-order --outcome 123 --outcome-side yes --side buy --size 10 --dry
+  openbroker outcome-buy --outcome 123 --outcome-side no --size 5 --price 0.42
+  openbroker outcome-sell --outcome #1230 --size 10
+`);
+}
+
+function formatOutcomePrice(price: number): string {
+  return price.toFixed(4);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help || args.h) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const outcomeRef = args.outcome as string;
+  const outcomeSide = args['outcome-side'] as string | undefined;
+  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 szDecimals = args['sz-decimals'] ? parseInt(args['sz-decimals'] as string, 10) : undefined;
+  const dryRun = args.dry as boolean;
+
+  if (!outcomeRef || !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);
+  }
+
+  if (price !== undefined && (price <= 0 || price >= 1)) {
+    console.error('Error: --price must be between 0 and 1 for outcome tokens');
+    process.exit(1);
+  }
+
+  if (szDecimals !== undefined && (szDecimals < 0 || szDecimals > 8)) {
+    console.error('Error: --sz-decimals must be between 0 and 8');
+    process.exit(1);
+  }
+
+  const client = getClient();
+  if (args.verbose) client.verbose = true;
+
+  const isBuy = side === 'buy';
+  const isMarket = price === undefined;
+
+  console.log('Open Broker - HIP-4 Outcome Order');
+  console.log('=================================\n');
+
+  await checkBuilderFeeApproval(client);
+
+  try {
+    const resolved = client.resolveOutcomeRef(outcomeRef, outcomeSide);
+    const market = await client.getOutcomeMarket(resolved.outcome);
+    const marketSide = market?.sides.find((s) => s.side === resolved.side);
+    const sideName = marketSide?.name ?? (resolved.side === 0 ? 'Yes' : 'No');
+    const midPrice = await client.getOutcomeMidPrice(resolved.outcome, resolved.side);
+    const slippageBps = slippage ?? 50;
+    const limitPrice = isMarket
+      ? (isBuy ? midPrice * (1 + slippageBps / 10000) : midPrice * (1 - slippageBps / 10000))
+      : price;
+    const notional = midPrice * size;
+
+    console.log('Order Details');
+    console.log('-------------');
+    console.log(`Outcome:      ${resolved.outcome}`);
+    console.log(`Market:       ${market?.name ?? 'Unknown'}${market?.parsedDescription.underlying ? ` (${market.parsedDescription.underlying})` : ''}`);
+    if (market?.parsedDescription.expiry) console.log(`Expiry:       ${market.parsedDescription.expiry}`);
+    if (market?.parsedDescription.targetPrice) console.log(`Target:       ${market.parsedDescription.targetPrice}`);
+    console.log(`Outcome Side: ${sideName.toUpperCase()} (${resolved.side})`);
+    console.log(`Coin:         ${resolved.coin}`);
+    console.log(`Asset ID:     ${resolved.assetId}`);
+    console.log(`Trade Side:   ${isBuy ? 'BUY' : 'SELL'}`);
+    console.log(`Size:         ${size}`);
+    console.log(`Mid Price:    ${formatOutcomePrice(midPrice)}`);
+    if (isMarket) {
+      console.log(`Type:         Market (IOC)`);
+      console.log(`Limit Price:  ${formatOutcomePrice(limitPrice)} (${slippageBps} bps slippage)`);
+    } else {
+      console.log(`Type:         Limit (${tif})`);
+      console.log(`Limit Price:  ${formatOutcomePrice(price)}`);
+    }
+    console.log(`Notional:     ~${formatUsd(notional)}`);
+    if (marketSide?.szDecimals !== undefined || szDecimals !== undefined) {
+      console.log(`Sz Decimals:  ${szDecimals ?? marketSide?.szDecimals}`);
+    }
+    console.log(`Builder Fee:  ${client.builderInfo.f / 10} bps`);
+
+    if (dryRun) {
+      console.log('\nDry run - order not submitted');
+      return;
+    }
+
+    console.log('\nExecuting...');
+
+    const response = isMarket
+      ? await client.outcomeMarketOrder(outcomeRef, outcomeSide, isBuy, size, slippage, szDecimals)
+      : await client.outcomeLimitOrder(outcomeRef, outcomeSide, isBuy, size, price!, tif, szDecimals);
+
+    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);
+          console.log('Filled');
+          console.log(`   Order ID:  ${status.filled.oid}`);
+          console.log(`   Size:      ${fillSz}`);
+          console.log(`   Avg Price: ${formatOutcomePrice(avgPx)}`);
+          console.log(`   Notional:  ${formatUsd(fillSz * avgPx)}`);
+        } 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 outcome order:', error);
+    console.error('Note: Hyperliquid currently documents outcomeMeta as testnet-only.');
+    process.exit(1);
+  }
+}
+
+main();