openbroker 1.0.33 → 1.0.35

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.0.34] - 2025-02-05
+
+### Changed
+- **Global Config**: Config now stored in `~/.openbroker/.env` for global CLI usage
+  - Config loaded from: env vars > local `.env` > `~/.openbroker/.env`
+  - `openbroker setup` creates config in home directory
+  - Works from any directory without local `.env` file
+- **Read-Only Mode**: Info commands work without configuration
+  - Market data, funding rates, search all work immediately
+  - Shows warning: "Not configured for trading. Run openbroker setup to enable trades."
+  - Trading commands fail with clear error until configured
+- **Better Error Messages**: Clear instructions when config missing
+
 ## [1.0.3] - 2025-02-05
 
 ### Added

package/README.md

@@ -116,12 +116,17 @@ export HYPERLIQUID_NETWORK="testnet"
 
 ## Configuration
 
-Create a `.env` file (or run `openbroker setup`):
+Config is loaded from these locations (in order of priority):
+1. Environment variables
+2. `.env` file in current directory
+3. `~/.openbroker/.env` (global config)
+
+Run `openbroker setup` to create the global config, or set environment variables:
 
 ```bash
-HYPERLIQUID_PRIVATE_KEY=0x...     # Required: wallet private key
-HYPERLIQUID_NETWORK=mainnet       # Optional: mainnet (default) or testnet
-HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets
+export HYPERLIQUID_PRIVATE_KEY=0x...     # Required: wallet private key
+export HYPERLIQUID_NETWORK=mainnet       # Optional: mainnet (default) or testnet
+export HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets
 ```
 
 ### API Wallet Setup
@@ -129,8 +134,8 @@ HYPERLIQUID_ACCOUNT_ADDRESS=0x... # Optional: for API wallets
 For automated trading, use an API wallet:
 
 ```bash
-HYPERLIQUID_PRIVATE_KEY="0x..."        # API wallet private key
-HYPERLIQUID_ACCOUNT_ADDRESS="0x..."    # Main account address
+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.

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 metadata:
   author: monemetrics
-  version: "1.0.3"
+  version: "1.0.34"
 allowed-tools: Bash(openbroker:*) Bash(npm:*) Read
 ---
 
@@ -278,9 +278,14 @@ All commands support `--dry` for dry run (preview without executing).
 | Percentage down | `--sl -5%` | 5% below entry |
 | Entry price | `--sl entry` | Breakeven stop |
 
-## Environment Variables
+## Configuration
 
-Create a `.env` file or set these environment variables:
+Config is loaded from (in priority order):
+1. Environment variables
+2. `.env` in current directory
+3. `~/.openbroker/.env` (global config)
+
+Run `openbroker setup` to create the global config interactively.
 
 | Variable | Required | Description |
 |----------|----------|-------------|

package/bin/openbroker.js

@@ -1,24 +1,58 @@
 #!/usr/bin/env node
 
-// This wrapper uses tsx to run the TypeScript CLI
+// This wrapper runs the TypeScript CLI using tsx
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import path from 'path';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const packageRoot = path.dirname(__dirname);
 const cliPath = path.join(__dirname, 'cli.ts');
 
-// Run the TypeScript CLI with tsx
+// Run the TypeScript CLI with tsx from package's node_modules
+const tsxBin = path.join(packageRoot, 'node_modules', '.bin', 'tsx');
+
 const child = spawn(
-  process.execPath,
-  ['--import', 'tsx', cliPath, ...process.argv.slice(2)],
+  tsxBin,
+  [cliPath, ...process.argv.slice(2)],
   {
     stdio: 'inherit',
-    cwd: process.cwd(),
+    cwd: packageRoot,
+    env: {
+      ...process.env,
+      // Preserve the original working directory for local .env lookup
+      OPENBROKER_CWD: process.cwd(),
+    },
   }
 );
 
+child.on('error', (err) => {
+  // If tsx binary not found, try npx tsx as fallback
+  if (err.code === 'ENOENT') {
+    const fallback = spawn(
+      'npx',
+      ['tsx', cliPath, ...process.argv.slice(2)],
+      {
+        stdio: 'inherit',
+        cwd: packageRoot,
+        env: {
+          ...process.env,
+          OPENBROKER_CWD: process.cwd(),
+        },
+      }
+    );
+    fallback.on('exit', (code) => process.exit(code ?? 0));
+    fallback.on('error', () => {
+      console.error('Error: tsx not found. Try reinstalling openbroker.');
+      process.exit(1);
+    });
+  } else {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+});
+
 child.on('exit', (code) => {
   process.exit(code ?? 0);
 });

package/package.json

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

package/scripts/core/client.ts

@@ -78,6 +78,20 @@ export class HyperliquidClient {
     return this.config.builderFee / 10; // Convert from tenths of bps to bps
   }
 
+  /** Whether client is in read-only mode (no trading capability) */
+  get isReadOnly(): boolean {
+    return this.config.isReadOnly;
+  }
+
+  /** Throw error if trying to trade in read-only mode */
+  private requireTrading(): void {
+    if (this.config.isReadOnly) {
+      throw new Error(
+        'Trading not available. Run "openbroker setup" to configure your wallet.'
+      );
+    }
+  }
+
   // ============ Market Data ============
 
   async getMetaAndAssetCtxs(): Promise<MetaAndAssetCtxs> {
@@ -562,6 +576,7 @@ export class HyperliquidClient {
     reduceOnly: boolean = false,
     includeBuilder: boolean = true
   ): Promise<OrderResponse> {
+    this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
     const assetIndex = this.getAssetIndex(coin);
@@ -679,6 +694,7 @@ export class HyperliquidClient {
     tpsl: 'tp' | 'sl',
     reduceOnly: boolean = true
   ): Promise<OrderResponse> {
+    this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
     const assetIndex = this.getAssetIndex(coin);
@@ -766,6 +782,7 @@ export class HyperliquidClient {
   }
 
   async cancel(coin: string, oid: number): Promise<CancelResponse> {
+    this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
     const assetIndex = this.getAssetIndex(coin);
@@ -807,6 +824,7 @@ export class HyperliquidClient {
     leverage: number,
     isCross: boolean = true
   ): Promise<unknown> {
+    this.requireTrading();
     await this.getMetaAndAssetCtxs();
 
     const assetIndex = this.getAssetIndex(coin);

package/scripts/core/config.ts

@@ -1,50 +1,105 @@
 // Configuration loader for Open Broker
 
 import { config as loadDotenv } from 'dotenv';
-import { resolve } from 'path';
-import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
 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');
+// Config locations (in order of priority)
+// 1. Environment variables (always checked first by process.env)
+// 2. Local .env in current working directory
+// 3. Global config at ~/.openbroker/.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 });
+export const GLOBAL_CONFIG_DIR = join(homedir(), '.openbroker');
+export const GLOBAL_ENV_PATH = join(GLOBAL_CONFIG_DIR, '.env');
+// Use OPENBROKER_CWD if set (from CLI wrapper), otherwise use process.cwd()
+const userCwd = process.env.OPENBROKER_CWD || process.cwd();
+export const LOCAL_ENV_PATH = resolve(userCwd, '.env');
 
-  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`);
-}
+// Package root (for reference, not config loading)
+export const PROJECT_ROOT = resolve(import.meta.dirname, '../..');
 
 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';
 
+// Default read-only key (for info commands that don't need authentication)
+// This is a valid but essentially useless private key
+const DEFAULT_READ_ONLY_KEY = '0x0000000000000000000000000000000000000000000000000000000000000001' as const;
+
+// Track if we've shown the read-only warning
+let readOnlyWarningShown = false;
+
+/**
+ * Find and load the config file from multiple locations
+ * Priority: env vars > local .env > global ~/.openbroker/.env > project .env
+ */
+function loadEnvFile(): string | null {
+  const verbose = process.env.VERBOSE === '1' || process.env.VERBOSE === 'true';
+  process.env.DOTENV_CONFIG_QUIET = 'true';
+
+  // Check locations in order of priority
+  const locations = [
+    { path: LOCAL_ENV_PATH, name: 'local (.env)' },
+    { path: GLOBAL_ENV_PATH, name: 'global (~/.openbroker/.env)' },
+  ];
+
+  for (const { path, name } of locations) {
+    if (existsSync(path)) {
+      const result = loadDotenv({ path });
+      if (verbose) {
+        console.log(`[DEBUG] Loaded config from ${name}: ${path}`);
+      }
+      return path;
+    }
+  }
+
+  if (verbose) {
+    console.log('[DEBUG] No config file found in any location');
+    console.log('[DEBUG] Run "openbroker setup" to configure');
+  }
+
+  return null;
+}
+
+// Load config on module import
+const loadedConfigPath = loadEnvFile();
+
+/**
+ * Ensure the global config directory exists
+ */
+export function ensureConfigDir(): string {
+  if (!existsSync(GLOBAL_CONFIG_DIR)) {
+    mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  return GLOBAL_CONFIG_DIR;
+}
+
+/**
+ * Get the path where config was loaded from, or where it should be saved
+ */
+export function getConfigPath(): string {
+  return loadedConfigPath || GLOBAL_ENV_PATH;
+}
+
 export function loadConfig(): OpenBrokerConfig {
-  const privateKey = process.env.HYPERLIQUID_PRIVATE_KEY;
+  let privateKey = process.env.HYPERLIQUID_PRIVATE_KEY;
+  let isReadOnly = false;
+
   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'
-      );
+    // Use default read-only key for info commands
+    privateKey = DEFAULT_READ_ONLY_KEY;
+    isReadOnly = true;
+
+    // Show warning once
+    if (!readOnlyWarningShown) {
+      readOnlyWarningShown = true;
+      console.log('\x1b[33m⚠️  Not configured for trading. Run "openbroker setup" to enable trades.\x1b[0m\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) {
@@ -64,7 +119,6 @@ export function loadConfig(): OpenBrokerConfig {
   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
@@ -76,12 +130,20 @@ export function loadConfig(): OpenBrokerConfig {
     walletAddress,
     accountAddress: accountAddress || walletAddress,
     isApiWallet,
+    isReadOnly,
     builderAddress,
     builderFee,
     slippageBps,
   };
 }
 
+/**
+ * Check if the current config is read-only (no trading capability)
+ */
+export function isConfigured(): boolean {
+  return !!process.env.HYPERLIQUID_PRIVATE_KEY;
+}
+
 export function getNetwork(): 'mainnet' | 'testnet' {
   const network = process.env.HYPERLIQUID_NETWORK || 'mainnet';
   return network === 'testnet' ? 'testnet' : 'mainnet';

package/scripts/core/types.ts

@@ -8,6 +8,7 @@ export interface OpenBrokerConfig {
   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
+  isReadOnly: boolean;        // True if using default key (no trading capability)
   builderAddress: string;
   builderFee: number;         // tenths of bps (10 = 1 bps)
   slippageBps: number;

package/scripts/setup/onboard.ts

@@ -1,15 +1,19 @@
 #!/usr/bin/env npx tsx
-// Open Broker - Automated Onboarding for AI Agents
+// Open Broker - Automated Onboarding
 // Creates wallet, configures environment, and approves builder fee
 
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
-import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 
 const OPEN_BROKER_BUILDER_ADDRESS = '0xbb67021fA3e62ab4DA985bb5a55c5c1884381068';
 
+// Global config directory: ~/.openbroker/
+const CONFIG_DIR = path.join(homedir(), '.openbroker');
+const CONFIG_PATH = path.join(CONFIG_DIR, '.env');
+
 interface OnboardResult {
   success: boolean;
   walletAddress?: string;
@@ -33,41 +37,39 @@ function prompt(rl: readline.Interface, question: string): Promise<string> {
 }
 
 function isValidPrivateKey(key: string): boolean {
-  // Check if it's a valid 64-char hex string with 0x prefix
   return /^0x[a-fA-F0-9]{64}$/.test(key);
 }
 
-// Get project root relative to this script (scripts/setup/onboard.ts -> project root)
-function getProjectRoot(): string {
-  const __filename = fileURLToPath(import.meta.url);
-  const __dirname = path.dirname(__filename);
-  return path.resolve(__dirname, '../..');
+function ensureConfigDir(): void {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
 }
 
 async function main(): Promise<OnboardResult> {
-  console.log('Open Broker - Automated Onboarding');
-  console.log('===================================\n');
-
-  const projectRoot = getProjectRoot();
-  const envPath = path.join(projectRoot, '.env');
+  console.log('OpenBroker - Setup');
+  console.log('==================\n');
 
-  // Check if .env already exists
-  if (fs.existsSync(envPath)) {
-    console.log('⚠️  .env file already exists!');
-    console.log('   To re-onboard, delete .env first or edit manually.\n');
+  // Check if config already exists
+  if (fs.existsSync(CONFIG_PATH)) {
+    console.log('⚠️  Config already exists!');
+    console.log(`   Location: ${CONFIG_PATH}\n`);
 
     // Read existing config and show wallet address
-    const envContent = fs.readFileSync(envPath, 'utf-8');
+    const envContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
     const keyMatch = envContent.match(/HYPERLIQUID_PRIVATE_KEY=0x([a-fA-F0-9]{64})/);
 
     if (keyMatch) {
       const existingKey = `0x${keyMatch[1]}` as `0x${string}`;
       const account = privateKeyToAccount(existingKey);
-      console.log('Existing Configuration');
-      console.log('----------------------');
+      console.log('Current Configuration');
+      console.log('---------------------');
       console.log(`Wallet Address: ${account.address}`);
-      console.log(`\nTo fund this wallet, send USDC to the address above on Arbitrum.`);
-      console.log(`Then deposit to Hyperliquid at: https://app.hyperliquid.xyz/`);
+      console.log(`Config File:    ${CONFIG_PATH}`);
+      console.log(`\nTo reconfigure, delete the config file first:`);
+      console.log(`  rm ${CONFIG_PATH}`);
+      console.log(`\nTo fund this wallet, send USDC on Arbitrum, then deposit at:`);
+      console.log(`  https://app.hyperliquid.xyz/`);
 
       return {
         success: true,
@@ -77,7 +79,7 @@ async function main(): Promise<OnboardResult> {
 
     return {
       success: false,
-      error: 'Invalid .env file - missing or malformed private key',
+      error: 'Invalid config file - missing or malformed private key',
     };
   }
 
@@ -100,8 +102,7 @@ async function main(): Promise<OnboardResult> {
 
   if (choice === '1') {
     // User has existing key
-    console.log('\nEnter your private key (0x... format):');
-    console.log('(Input is hidden for security)\n');
+    console.log('\nEnter your private key (0x... format):\n');
 
     let validKey = false;
     while (!validKey) {
@@ -130,12 +131,13 @@ async function main(): Promise<OnboardResult> {
   const account = privateKeyToAccount(privateKey);
   console.log(`\nWallet Address: ${account.address}\n`);
 
-  // Create .env file
-  console.log('Creating .env file...');
+  // Create config directory and file
+  console.log('Creating config...');
+  ensureConfigDir();
 
-  const envContent = `# Open Broker - Environment Variables
-# Generated automatically during onboarding
-# WARNING: Keep this file secret! Never commit to git!
+  const envContent = `# OpenBroker Configuration
+# Location: ~/.openbroker/.env
+# WARNING: Keep this file secret! Never share it!
 
 # Your wallet private key
 HYPERLIQUID_PRIVATE_KEY=${privateKey}
@@ -143,14 +145,14 @@ HYPERLIQUID_PRIVATE_KEY=${privateKey}
 # Network: mainnet or testnet
 HYPERLIQUID_NETWORK=mainnet
 
-# Builder fee configuration (supports open-broker development)
+# Builder fee (supports openbroker development)
 # Default: 1 bps (0.01%) on trades
 BUILDER_ADDRESS=${OPEN_BROKER_BUILDER_ADDRESS}
 BUILDER_FEE=10
 `;
 
-  fs.writeFileSync(envPath, envContent, { mode: 0o600 }); // Restricted permissions
-  console.log(`✅ .env created at: ${envPath}\n`);
+  fs.writeFileSync(CONFIG_PATH, envContent, { mode: 0o600 });
+  console.log(`✅ Config saved to: ${CONFIG_PATH}\n`);
 
   // Approve builder fee
   console.log('Approving builder fee...');
@@ -177,48 +179,49 @@ BUILDER_FEE=10
         console.log('✅ Builder fee approved successfully!');
       } else {
         console.log(`⚠️  Approval may have failed: ${result.response}`);
-        console.log('   You can retry later: npx tsx scripts/setup/approve-builder.ts');
+        console.log('   You can retry later: openbroker approve-builder');
       }
     }
   } catch (error) {
     console.log(`⚠️  Could not approve builder fee: ${error}`);
-    console.log('   You can retry later: npx tsx scripts/setup/approve-builder.ts');
+    console.log('   You can retry later: openbroker approve-builder');
   }
 
   // Final summary
   console.log('\n========================================');
-  console.log('         ONBOARDING COMPLETE!          ');
+  console.log('           SETUP COMPLETE!             ');
   console.log('========================================\n');
 
   console.log('Your Trading Wallet');
   console.log('-------------------');
   console.log(`Address: ${account.address}`);
   console.log(`Network: Hyperliquid (Mainnet)`);
+  console.log(`Config:  ${CONFIG_PATH}`);
 
   if (choice === '2') {
     console.log('\n⚠️  IMPORTANT: Save your private key!');
     console.log('-----------------------------------');
     console.log(`Private Key: ${privateKey}`);
-    console.log('\nThis key is stored in .env but you should back it up securely.');
+    console.log('\nThis key is stored in ~/.openbroker/.env');
+    console.log('Back it up securely - if lost, funds cannot be recovered!');
   }
 
-  console.log('\n📋 Next Step: Fund Your Wallet');
-  console.log('-------------------------------');
-  console.log('1. Send USDC to your wallet on Arbitrum:');
+  console.log('\n📋 Next Steps');
+  console.log('--------------');
+  console.log('1. Fund your wallet with USDC on Arbitrum:');
   console.log(`   ${account.address}`);
   console.log('');
   console.log('2. Deposit USDC to Hyperliquid:');
   console.log('   https://app.hyperliquid.xyz/');
-  console.log('   (Connect wallet → Deposit → Select amount)');
   console.log('');
   console.log('3. Start trading!');
-  console.log('   npx tsx scripts/info/account.ts');
-  console.log('   npx tsx scripts/operations/market-order.ts --coin ETH --side buy --size 0.01 --dry');
+  console.log('   openbroker account');
+  console.log('   openbroker buy --coin ETH --size 0.01 --dry');
 
-  console.log('\n⚠️  SECURITY REMINDER');
-  console.log('---------------------');
-  console.log('Your private key is stored in .env');
-  console.log('NEVER share this file or commit it to git!');
+  console.log('\n⚠️  Security');
+  console.log('------------');
+  console.log(`Config stored at: ${CONFIG_PATH}`);
+  console.log('Never share this file or your private key!');
 
   return {
     success: true,
@@ -233,10 +236,10 @@ export { main as onboard };
 // Run if executed directly
 main().then(result => {
   if (!result.success) {
-    console.error(`\nOnboarding failed: ${result.error}`);
+    console.error(`\nSetup failed: ${result.error}`);
     process.exit(1);
   }
 }).catch(error => {
-  console.error('Onboarding error:', error);
+  console.error('Setup error:', error);
   process.exit(1);
 });