openbroker 1.0.33

package/scripts/core/config.ts

@@ -0,0 +1,92 @@
+// Configuration loader for Open Broker
+
+import { config as loadDotenv } from 'dotenv';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { OpenBrokerConfig } from './types.js';
+
+// Get project root relative to this file (scripts/core/config.ts -> project root)
+export const PROJECT_ROOT = resolve(import.meta.dirname, '../..');
+export const ENV_PATH = resolve(PROJECT_ROOT, '.env');
+
+// Load .env from project root (silently skip if doesn't exist)
+if (existsSync(ENV_PATH)) {
+  // Set DOTENV_CONFIG_QUIET to suppress dotenv's default logging
+  process.env.DOTENV_CONFIG_QUIET = 'true';
+  const result = loadDotenv({ path: ENV_PATH });
+
+  if (process.env.VERBOSE === '1' || process.env.VERBOSE === 'true') {
+    console.log(`[DEBUG] Loading .env from: ${ENV_PATH}`);
+    console.log(`[DEBUG] .env loaded: ${result.parsed ? 'yes' : 'no'}`);
+  }
+} else if (process.env.VERBOSE === '1' || process.env.VERBOSE === 'true') {
+  console.log(`[DEBUG] No .env file found at: ${ENV_PATH}`);
+  console.log(`[DEBUG] Run 'npx tsx scripts/setup/onboard.ts' to create one`);
+}
+
+const MAINNET_URL = 'https://api.hyperliquid.xyz';
+const TESTNET_URL = 'https://api.hyperliquid-testnet.xyz';
+
+// Open Broker builder address - receives builder fees on all trades
+// This funds continued development of the open-broker project
+export const OPEN_BROKER_BUILDER_ADDRESS = '0xbb67021fA3e62ab4DA985bb5a55c5c1884381068';
+
+export function loadConfig(): OpenBrokerConfig {
+  const privateKey = process.env.HYPERLIQUID_PRIVATE_KEY;
+  if (!privateKey) {
+    if (!existsSync(ENV_PATH)) {
+      throw new Error(
+        'No .env file found. Run onboarding first:\n\n' +
+        '  npx tsx scripts/setup/onboard.ts\n'
+      );
+    }
+    throw new Error(
+      'HYPERLIQUID_PRIVATE_KEY not found in .env file.\n' +
+      'Add it to your .env or run: npx tsx scripts/setup/onboard.ts'
+    );
+  }
+
+  if (!privateKey.startsWith('0x') || privateKey.length !== 66) {
+    throw new Error('HYPERLIQUID_PRIVATE_KEY must be a 64-character hex string with 0x prefix');
+  }
+
+  const network = process.env.HYPERLIQUID_NETWORK || 'mainnet';
+  const baseUrl = network === 'testnet' ? TESTNET_URL : MAINNET_URL;
+
+  // Use open-broker address by default, but allow override for custom builders
+  const builderAddress = (process.env.BUILDER_ADDRESS || OPEN_BROKER_BUILDER_ADDRESS).toLowerCase();
+  const builderFee = parseInt(process.env.BUILDER_FEE || '10', 10); // default 1 bps
+  const slippageBps = parseInt(process.env.SLIPPAGE_BPS || '50', 10); // default 0.5%
+
+  // Derive the wallet address from private key
+  const wallet = privateKeyToAccount(privateKey as `0x${string}`);
+  const walletAddress = wallet.address.toLowerCase();
+
+  // Account address can be different if using an API wallet
+  // If not specified, use the wallet address itself
+  const accountAddress = process.env.HYPERLIQUID_ACCOUNT_ADDRESS?.toLowerCase();
+
+  // Determine if this is an API wallet setup
+  const isApiWallet = accountAddress !== undefined && accountAddress !== walletAddress;
+
+  return {
+    baseUrl,
+    privateKey: privateKey as `0x${string}`,
+    walletAddress,
+    accountAddress: accountAddress || walletAddress,
+    isApiWallet,
+    builderAddress,
+    builderFee,
+    slippageBps,
+  };
+}
+
+export function getNetwork(): 'mainnet' | 'testnet' {
+  const network = process.env.HYPERLIQUID_NETWORK || 'mainnet';
+  return network === 'testnet' ? 'testnet' : 'mainnet';
+}
+
+export function isMainnet(): boolean {
+  return getNetwork() === 'mainnet';
+}

package/scripts/core/types.ts

@@ -0,0 +1,192 @@
+// Hyperliquid API Types for Open Broker
+
+// ============ Configuration ============
+
+export interface OpenBrokerConfig {
+  baseUrl: string;
+  privateKey: `0x${string}`;
+  walletAddress: string;      // Address derived from private key (the signer)
+  accountAddress: string;     // Address to trade on behalf of (may differ if using API wallet)
+  isApiWallet: boolean;       // True if walletAddress != accountAddress
+  builderAddress: string;
+  builderFee: number;         // tenths of bps (10 = 1 bps)
+  slippageBps: number;
+}
+
+// ============ Builder ============
+
+export interface BuilderInfo {
+  b: string; // builder address (lowercase)
+  f: number; // fee in tenths of bps
+}
+
+// ============ Order Types ============
+
+export type OrderType =
+  | { limit: { tif: 'Gtc' | 'Ioc' | 'Alo' } }
+  | { trigger: { triggerPx: string; isMarket: boolean; tpsl: 'tp' | 'sl' } };
+
+export interface OrderRequest {
+  coin: string;
+  is_buy: boolean;
+  sz: number;
+  limit_px: number;
+  order_type: OrderType;
+  reduce_only?: boolean;
+  cloid?: string;
+}
+
+export interface OrderWire {
+  a: number; // asset index
+  b: boolean; // is_buy
+  p: string; // price
+  s: string; // size
+  r: boolean; // reduce_only
+  t: OrderType;
+  c?: string; // cloid
+}
+
+export interface OrderResponse {
+  status: 'ok' | 'err';
+  response?: {
+    type: 'order';
+    data: {
+      statuses: Array<{
+        resting?: { oid: number };
+        filled?: { totalSz: string; avgPx: string; oid: number };
+        error?: string;
+        [key: string]: unknown; // Catch any other fields
+      }>;
+    };
+  } | string; // API can return string error message
+  error?: string;
+}
+
+// ============ Cancel Types ============
+
+export interface CancelRequest {
+  coin: string;
+  oid: number;
+}
+
+export interface CancelResponse {
+  status: 'ok' | 'err';
+  response?: {
+    type: 'cancel';
+    data: { statuses: string[] };
+  };
+}
+
+// ============ Market Data Types ============
+
+export interface AssetMeta {
+  name: string;
+  szDecimals: number;
+  maxLeverage: number;
+  onlyIsolated: boolean;
+}
+
+export interface AssetCtx {
+  funding: string;
+  openInterest: string;
+  prevDayPx: string;
+  dayNtlVlm: string;
+  premium: string;
+  oraclePx: string;
+  markPx: string;
+  midPx?: string;
+  impactPxs?: [string, string];
+}
+
+export interface Meta {
+  universe: AssetMeta[];
+}
+
+export interface MetaAndAssetCtxs {
+  meta: Meta;
+  assetCtxs: AssetCtx[];
+}
+
+// ============ Account Types ============
+
+export interface Position {
+  coin: string;
+  szi: string; // signed size (negative = short)
+  entryPx: string;
+  positionValue: string;
+  unrealizedPnl: string;
+  returnOnEquity: string;
+  liquidationPx: string | null;
+  leverage: {
+    type: 'cross' | 'isolated';
+    value: number;
+    rawUsd?: string;
+  };
+  marginUsed: string;
+  maxLeverage: number;
+}
+
+export interface AssetPosition {
+  position: Position;
+  type: 'oneWay';
+}
+
+export interface MarginSummary {
+  accountValue: string;
+  totalNtlPos: string;
+  totalRawUsd: string;
+  totalMarginUsed: string;
+  withdrawable: string;
+}
+
+export interface ClearinghouseState {
+  assetPositions: AssetPosition[];
+  crossMarginSummary: MarginSummary;
+  marginSummary: MarginSummary;
+  crossMaintenanceMarginUsed: string;
+}
+
+// ============ Funding Types ============
+
+export interface FundingInfo {
+  coin: string;
+  fundingRate: string; // hourly rate
+  annualizedRate: number; // calculated
+  premium: string;
+  openInterest: string;
+  markPx: string;
+  oraclePx: string;
+}
+
+// ============ Open Orders ============
+
+export interface OpenOrder {
+  coin: string;
+  oid: number;
+  cloid?: string;
+  side: 'B' | 'A'; // Bid or Ask
+  sz: string;
+  limitPx: string;
+  orderType: string;
+  origSz: string;
+  timestamp: number;
+}
+
+// ============ API Request/Response ============
+
+export interface InfoRequest {
+  type: string;
+  user?: string;
+  [key: string]: unknown;
+}
+
+export interface ExchangeRequest {
+  action: Record<string, unknown>;
+  nonce: number;
+  signature: {
+    r: string;
+    s: string;
+    v: number;
+  };
+  vaultAddress?: string | null;
+}

package/scripts/core/utils.ts

@@ -0,0 +1,156 @@
+// Utility functions for Open Broker
+
+import type { OrderType, OrderWire, OrderRequest } from './types.js';
+
+/**
+ * Round price to 5 significant figures and appropriate decimals
+ * Perps: max 6 decimals, Spot: max 8 decimals
+ */
+export function roundPrice(price: number, szDecimals: number, isSpot: boolean = false): string {
+  // Round to 5 significant figures first
+  const sigFigs = parseFloat(price.toPrecision(5));
+  // Then round to max decimals (6 for perps - szDecimals adjustment, 8 for spot)
+  const maxDecimals = isSpot ? 8 : Math.max(0, 6 - szDecimals);
+  return sigFigs.toFixed(maxDecimals);
+}
+
+/**
+ * Round size to asset's szDecimals
+ */
+export function roundSize(size: number, szDecimals: number): string {
+  return size.toFixed(szDecimals);
+}
+
+/**
+ * Calculate slippage-adjusted price for market orders
+ */
+export function getSlippagePrice(
+  midPrice: number,
+  isBuy: boolean,
+  slippageBps: number
+): number {
+  const slippageMultiplier = slippageBps / 10000;
+  return isBuy
+    ? midPrice * (1 + slippageMultiplier)
+    : midPrice * (1 - slippageMultiplier);
+}
+
+/**
+ * Convert order request to wire format
+ */
+export function orderToWire(
+  order: OrderRequest,
+  assetIndex: number,
+  szDecimals: number
+): OrderWire {
+  const wire: OrderWire = {
+    a: assetIndex,
+    b: order.is_buy,
+    p: roundPrice(order.limit_px, szDecimals),
+    s: roundSize(order.sz, szDecimals),
+    r: order.reduce_only ?? false,
+    t: order.order_type,
+  };
+
+  if (order.cloid) {
+    wire.c = order.cloid;
+  }
+
+  return wire;
+}
+
+/**
+ * Get current timestamp in milliseconds
+ */
+export function getTimestampMs(): number {
+  return Date.now();
+}
+
+/**
+ * Format USD amount for display
+ */
+export function formatUsd(amount: number | string): string {
+  const num = typeof amount === 'string' ? parseFloat(amount) : amount;
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(num);
+}
+
+/**
+ * Format percentage for display
+ */
+export function formatPercent(value: number | string, decimals: number = 2): string {
+  const num = typeof value === 'string' ? parseFloat(value) : value;
+  return `${(num * 100).toFixed(decimals)}%`;
+}
+
+/**
+ * Format funding rate (hourly to annualized)
+ */
+export function annualizeFundingRate(hourlyRate: number | string): number {
+  const rate = typeof hourlyRate === 'string' ? parseFloat(hourlyRate) : hourlyRate;
+  return rate * 8760; // 24 * 365 hours
+}
+
+/**
+ * Parse CLI arguments into key-value pairs
+ */
+export function parseArgs(args: string[]): Record<string, string | boolean> {
+  const result: Record<string, string | boolean> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+
+      if (nextArg && !nextArg.startsWith('--')) {
+        result[key] = nextArg;
+        i++;
+      } else {
+        result[key] = true;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Generate a random client order ID
+ */
+export function generateCloid(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < 16; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+
+/**
+ * Check if builder fee is approved and print warning if not
+ * Returns true if approved, false if not
+ */
+export async function checkBuilderFeeApproval(
+  client: { getMaxBuilderFee: () => Promise<string | null>; builderAddress: string }
+): Promise<boolean> {
+  const approval = await client.getMaxBuilderFee();
+  if (!approval) {
+    console.log('⚠️  Builder fee not approved!');
+    console.log(`   Run: npx tsx scripts/setup/approve-builder.ts`);
+    console.log(`   Builder: ${client.builderAddress}\n`);
+    return false;
+  }
+  return true;
+}

package/scripts/info/account.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env npx tsx
+// Get account info from Hyperliquid
+
+import { getClient } from '../core/client.js';
+import { formatUsd, formatPercent, parseArgs } from '../core/utils.js';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const client = getClient();
+
+  console.log('Open Broker - Account Info');
+  console.log('==========================\n');
+
+  console.log('Wallet Configuration');
+  console.log('--------------------');
+  console.log(`Trading Account:  ${client.address}`);
+  console.log(`Signing Wallet:   ${client.walletAddress}`);
+  console.log(`Wallet Type:      ${client.isApiWallet ? 'API Wallet' : 'Main Wallet'}`);
+
+  // 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})`);
+  } else {
+    console.log(`Builder Approved: ❌ No`);
+    console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
+  }
+  console.log('');
+
+  try {
+    const state = await client.getUserState();
+
+    const margin = state.crossMarginSummary;
+    const accountValue = parseFloat(margin.accountValue);
+    const totalMarginUsed = parseFloat(margin.totalMarginUsed);
+    const withdrawable = parseFloat(margin.withdrawable);
+    const totalNotional = parseFloat(margin.totalNtlPos);
+
+    console.log('Margin Summary');
+    console.log('--------------');
+    console.log(`Account Value:    ${formatUsd(accountValue)}`);
+    console.log(`Total Notional:   ${formatUsd(totalNotional)}`);
+    console.log(`Margin Used:      ${formatUsd(totalMarginUsed)}`);
+    console.log(`Withdrawable:     ${formatUsd(withdrawable)}`);
+
+    if (totalMarginUsed > 0) {
+      const marginRatio = totalMarginUsed / accountValue;
+      console.log(`Margin Ratio:     ${formatPercent(marginRatio)}`);
+    }
+
+    console.log('\nPositions Summary');
+    console.log('-----------------');
+
+    if (state.assetPositions.length === 0) {
+      console.log('No open positions');
+    } else {
+      let totalPnl = 0;
+      console.log('Coin     | Size       | Entry      | Mark       | PnL        | Leverage');
+      console.log('---------|------------|------------|------------|------------|----------');
+
+      for (const ap of state.assetPositions) {
+        const pos = ap.position;
+        const size = parseFloat(pos.szi);
+        if (Math.abs(size) < 0.0001) continue;
+
+        const entryPx = parseFloat(pos.entryPx);
+        const pnl = parseFloat(pos.unrealizedPnl);
+        totalPnl += pnl;
+
+        // Get mark price from leverage calculation
+        const notional = parseFloat(pos.positionValue);
+        const markPx = Math.abs(notional / size);
+
+        const side = size > 0 ? 'L' : 'S';
+        const leverageStr = `${pos.leverage.value}x ${pos.leverage.type}`;
+
+        console.log(
+          `${pos.coin.padEnd(8)} | ${side} ${Math.abs(size).toFixed(4).padStart(8)} | ` +
+          `${formatUsd(entryPx).padStart(10)} | ${formatUsd(markPx).padStart(10)} | ` +
+          `${formatUsd(pnl).padStart(10)} | ${leverageStr}`
+        );
+      }
+
+      console.log('---------|------------|------------|------------|------------|----------');
+      console.log(`Total Unrealized PnL: ${formatUsd(totalPnl)}`);
+    }
+
+    // Show open orders if requested
+    if (args.orders) {
+      console.log('\nOpen Orders');
+      console.log('-----------');
+
+      const orders = await client.getOpenOrders();
+      if (orders.length === 0) {
+        console.log('No open orders');
+      } else {
+        console.log('Coin     | Side | Size       | Price      | Type');
+        console.log('---------|------|------------|------------|------');
+        for (const order of orders) {
+          const side = order.side === 'B' ? 'BUY ' : 'SELL';
+          console.log(
+            `${order.coin.padEnd(8)} | ${side} | ${parseFloat(order.sz).toFixed(4).padStart(10)} | ` +
+            `${formatUsd(parseFloat(order.limitPx)).padStart(10)} | ${order.orderType}`
+          );
+        }
+      }
+    }
+
+  } catch (error) {
+    console.error('Error fetching account info:', error);
+    process.exit(1);
+  }
+}
+
+main();