openbroker 1.0.40 → 1.0.41

package/SKILL.md

@@ -39,10 +39,33 @@ openbroker setup              # One-command setup (wallet + config + builder app
 openbroker approve-builder --check  # Check builder fee status (for troubleshooting)
 ```
 
-The `setup` command handles everything:
-1. Generate new wallet or use existing private key
-2. Save config to `~/.openbroker/.env`
-3. Automatically approve builder fee (required for trading)
+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
+
+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)
+
+API wallets can place trades on behalf of a master account but **cannot withdraw funds**. This is the safest option for automated agents.
+
+**Flow:**
+1. Run `openbroker setup` and choose option 3 ("Generate API wallet")
+2. The CLI generates a keypair and prints an approval URL (e.g. `https://openbroker.dev/approve?agent=0xABC...`)
+3. The agent owner opens the URL in a browser and connects their master wallet (MetaMask etc.)
+4. The master wallet signs two transactions: `ApproveAgent` (authorizes the API wallet) and `ApproveBuilderFee` (approves the 1 bps fee)
+5. The CLI detects the approval automatically and saves the config
+
+**After setup, the config will contain:**
+```
+HYPERLIQUID_PRIVATE_KEY=0x...        # API wallet private key
+HYPERLIQUID_ACCOUNT_ADDRESS=0x...    # Master account address
+HYPERLIQUID_NETWORK=mainnet
+```
+
+**Important for agents:** When using an API wallet, pass the approval URL to the agent owner (the human who controls the master wallet). The owner must approve in a browser before the agent can trade. The CLI waits up to 10 minutes for the approval. If it times out, re-run `openbroker setup`.
 
 ### Account Info
 ```bash
@@ -294,7 +317,9 @@ Run `openbroker setup` to create the global config interactively.
 |----------|----------|-------------|
 | `HYPERLIQUID_PRIVATE_KEY` | Yes | Wallet private key (0x...) |
 | `HYPERLIQUID_NETWORK` | No | `mainnet` (default) or `testnet` |
-| `HYPERLIQUID_ACCOUNT_ADDRESS` | No | For API wallets |
+| `HYPERLIQUID_ACCOUNT_ADDRESS` | No | Master account address (required for API wallets) |
+
+The builder fee (1 bps / 0.01%) is hardcoded and not configurable.
 
 ## Risk Warning
 

package/package.json

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

package/scripts/core/config.ts

@@ -109,9 +109,9 @@ export function loadConfig(): OpenBrokerConfig {
   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
+  // Builder fee is hardcoded — set by OpenBroker, not configurable by users
+  const builderAddress = OPEN_BROKER_BUILDER_ADDRESS.toLowerCase();
+  const builderFee = 10; // 10 tenths-of-bps = 1 bps = 0.01%
   const slippageBps = parseInt(process.env.SLIPPAGE_BPS || '50', 10); // default 0.5%
 
   // Derive the wallet address from private key

package/scripts/setup/onboard.ts

@@ -116,11 +116,6 @@ HYPERLIQUID_ACCOUNT_ADDRESS=${masterAddress}
 
 # Network: mainnet or testnet
 HYPERLIQUID_NETWORK=mainnet
-
-# Builder fee (supports openbroker development)
-# Default: 1 bps (0.01%) on trades
-BUILDER_ADDRESS=${OPEN_BROKER_BUILDER_ADDRESS}
-BUILDER_FEE=10
 `;
 }
 
@@ -171,8 +166,6 @@ HYPERLIQUID_PRIVATE_KEY=${privateKey}
 # HYPERLIQUID_ACCOUNT_ADDRESS=0x...
 
 HYPERLIQUID_NETWORK=mainnet
-BUILDER_ADDRESS=${OPEN_BROKER_BUILDER_ADDRESS}
-BUILDER_FEE=10
 `;
     fs.writeFileSync(CONFIG_PATH, partialEnv, { mode: 0o600 });
     console.log(`   Partial config saved to: ${CONFIG_PATH}`);
@@ -343,11 +336,6 @@ HYPERLIQUID_PRIVATE_KEY=${privateKey}
 
 # Network: mainnet or testnet
 HYPERLIQUID_NETWORK=mainnet
-
-# Builder fee (supports openbroker development)
-# Default: 1 bps (0.01%) on trades
-BUILDER_ADDRESS=${OPEN_BROKER_BUILDER_ADDRESS}
-BUILDER_FEE=10
 `;
 
   fs.writeFileSync(CONFIG_PATH, envContent, { mode: 0o600 });