openbroker 1.0.71 → 1.0.73

package/SKILL.md

@@ -4,7 +4,7 @@ description: Hyperliquid trading plugin with background position monitoring and
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.71", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+metadata: {"author": "monemetrics", "version": "1.0.73", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
 allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_twap_cancel ob_twap_status ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
@@ -127,8 +127,10 @@ HYPERLIQUID_NETWORK=mainnet
 ```bash
 openbroker account            # Balance, equity, margin
 openbroker account --orders   # Include open orders
+openbroker account --address 0xabc...  # Look up another account
 openbroker positions          # Open positions with PnL
 openbroker positions --coin ETH  # Specific coin
+openbroker positions --address 0xabc...  # Another account's positions
 ```
 
 ### Funding Rates
@@ -164,6 +166,7 @@ openbroker search --query ETH --type perp  # ETH perps only
 openbroker spot                   # Show all spot markets
 openbroker spot --coin PURR       # Show PURR market info
 openbroker spot --balances        # Show your spot balances
+openbroker spot --balances --address 0xabc...  # Another account's spot balances
 openbroker spot --top 20          # Top 20 by volume
 ```
 
@@ -172,6 +175,7 @@ openbroker spot --top 20          # Top 20 by volume
 openbroker fills                          # Recent fills
 openbroker fills --coin ETH               # ETH fills only
 openbroker fills --coin BTC --side buy --top 50
+openbroker fills --address 0xabc...       # Another account's fills
 ```
 
 ### Order History
@@ -181,17 +185,20 @@ openbroker orders --open                  # Currently open orders only
 openbroker orders --open --coin ETH       # Open orders for a specific coin
 openbroker orders --coin ETH --status filled
 openbroker orders --top 50
+openbroker orders --address 0xabc... --open  # Another account's open orders
 ```
 
 ### Order Status
 ```bash
 openbroker order-status --oid 123456789   # Check specific order
 openbroker order-status --oid 0x1234...   # By client order ID
+openbroker order-status --oid 123456789 --address 0xabc...  # On another account
 ```
 
 ### Fee Schedule
 ```bash
 openbroker fees                           # Fee tier, rates, and volume
+openbroker fees --address 0xabc...        # Another account's fees
 ```
 
 ### Candle Data (OHLCV)
@@ -436,15 +443,66 @@ The plugin reads wallet credentials from `~/.openbroker/.env` (set up by `openbr
 
 ### Webhook setup for watcher alerts
 
-For position alerts to reach the agent, enable hooks in your gateway config:
+For the position watcher and automations to send alerts to the agent, you must enable webhooks in your OpenClaw gateway config and add a hook mapping. This is a manual configuration step — plugins cannot auto-configure gateway settings.
 
+**1. Generate a hook token** — any secure random string:
+```bash
+openssl rand -hex 32
+```
+
+**2. Enable hooks and add a mapping** in your `openclaw.json` (or `openclaw.yaml`) deployment config:
+```json
+"hooks": {
+  "enabled": true,
+  "path": "/hooks",
+  "token": "<your-generated-token>",
+  "allowedAgentIds": ["hooks", "main", "openbroker"],
+  "mappings": [
+    {
+      "id": "main",
+      "match": {
+        "path": "openbroker"
+      },
+      "action": "agent",
+      "wakeMode": "now",
+      "name": "Openbroker",
+      "agentId": "main",
+      "deliver": true,
+      "channel": "last",
+      "model": "anthropic/claude-sonnet-4-6"
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `token` | Shared secret — must match `hooksToken` in the plugin config |
+| `allowedAgentIds` | Agent IDs allowed to receive webhook requests |
+| `mappings[].match.path` | Matches the webhook path sent by the plugin (always `"openbroker"`) |
+| `mappings[].wakeMode` | `"now"` triggers an immediate agent turn. `"next-heartbeat"` queues for the next scheduled heartbeat |
+| `mappings[].deliver` | If `true`, the agent's response is delivered to the user via the configured channel |
+| `mappings[].channel` | Delivery channel: `"last"` (most recent), `"slack"`, `"telegram"`, `"discord"`, `"whatsapp"`, etc. |
+| `mappings[].model` | Model override for webhook-triggered turns. Optional — uses deployment default if omitted |
+
+**3. Set the same token in your plugin config:**
 ```yaml
-hooks:
-  enabled: true
-  token: "your-hooks-secret"   # Must match hooksToken above
+plugins:
+  entries:
+    openbroker:
+      enabled: true
+      config:
+        hooksToken: "<your-generated-token>"   # Same token as hooks.token
+        watcher:
+          enabled: true
+```
+
+**4. Restart the gateway** and verify:
+```bash
+openclaw ob status
 ```
 
-Without hooks, the watcher still runs and tracks state (accessible via `ob_watcher_status`), but it can't wake the agent.
+The watcher sends alerts to `POST /hooks/agent` with `Authorization: Bearer <token>`. The gateway matches the request against the mapping and triggers an agent turn. Without hooks enabled, the watcher still tracks state (accessible via `ob_watcher_status`), but it can't wake the agent.
 
 ### Using with or without the plugin
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openbroker",
   "name": "OpenBroker — Hyperliquid Trading",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "description": "Trade on Hyperliquid DEX with background position monitoring",
   "configSchema": {
     "type": "object",

package/package.json

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

package/scripts/info/account.ts

@@ -7,16 +7,20 @@ import { formatUsd, formatPercent, parseArgs } from '../core/utils.js';
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
   if (args.verbose) {
     client.verbose = true;
   }
 
-  const accountMode = await client.getAccountMode();
+  const lookupAddress = targetAddress?.toLowerCase() ?? client.address;
+  const isOtherAccount = !!targetAddress;
+
+  const accountMode = await client.getAccountMode(isOtherAccount ? lookupAddress : undefined);
 
   try {
-    const state = await client.getUserStateAll();
+    const state = await client.getUserStateAll(isOtherAccount ? lookupAddress : undefined);
 
     const margin = state.crossMarginSummary;
     const accountValue = parseFloat(margin.accountValue);
@@ -51,9 +55,11 @@ async function main() {
     // JSON output
     if (jsonOutput) {
       const result: Record<string, unknown> = {
-        address: client.address,
-        signingWallet: client.walletAddress,
-        walletType: client.isApiWallet ? 'api' : 'main',
+        address: lookupAddress,
+        ...(isOtherAccount ? {} : {
+          signingWallet: client.walletAddress,
+          walletType: client.isApiWallet ? 'api' : 'main',
+        }),
         accountMode,
         equity: accountValue,
         totalNotional,
@@ -65,7 +71,7 @@ async function main() {
       };
 
       if (args.orders) {
-        const orders = await client.getOpenOrders();
+        const orders = await client.getOpenOrders(isOtherAccount ? lookupAddress : undefined);
         result.openOrders = orders.map(o => ({
           coin: o.coin,
           oid: o.oid,
@@ -85,11 +91,17 @@ async function main() {
     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'}`);
+    if (isOtherAccount) {
+      console.log('Lookup Address');
+      console.log('--------------------');
+      console.log(`Address:          ${lookupAddress}`);
+    } else {
+      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'}`);
+    }
 
     const modeLabel: Record<string, string> = {
       standard: 'Standard (separate balances per dex)',
@@ -99,22 +111,24 @@ async function main() {
     };
     console.log(`Account Mode:     ${modeLabel[accountMode] ?? accountMode}`);
 
-    // 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`);
-    }
+    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})`);
+      } else {
+        console.log(`Builder Approved: ❌ No`);
+        console.log(`\n⚠️  Run: npx tsx scripts/setup/approve-builder.ts`);
+      }
 
-    // Warn if API wallet setup looks misconfigured
-    if (!client.isApiWallet && accountValue === 0 && positions.length === 0) {
-      console.log('\n⚠️  No positions and $0 equity.');
-      console.log('   If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
-      console.log('   in ~/.openbroker/.env to the master account address (the wallet that holds funds).');
+      // Warn if API wallet setup looks misconfigured
+      if (!client.isApiWallet && accountValue === 0 && positions.length === 0) {
+        console.log('\n⚠️  No positions and $0 equity.');
+        console.log('   If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
+        console.log('   in ~/.openbroker/.env to the master account address (the wallet that holds funds).');
+      }
     }
     console.log('');
 
@@ -157,7 +171,7 @@ async function main() {
       console.log('\nOpen Orders');
       console.log('-----------');
 
-      const orders = await client.getOpenOrders();
+      const orders = await client.getOpenOrders(isOtherAccount ? lookupAddress : undefined);
       if (orders.length === 0) {
         console.log('No open orders');
       } else {

package/scripts/info/fees.ts

@@ -24,13 +24,19 @@ async function main() {
     process.exit(0);
   }
 
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
+  const lookupAddress = targetAddress?.toLowerCase();
 
   console.log('Open Broker - Fee Schedule');
   console.log('=========================\n');
 
+  if (targetAddress) {
+    console.log(`Lookup: ${lookupAddress}\n`);
+  }
+
   try {
-    const fees = await client.getUserFees();
+    const fees = await client.getUserFees(lookupAddress);
 
     // Fee rates
     console.log('Fee Rates');

package/scripts/info/fills.ts

@@ -9,15 +9,17 @@ function printUsage() {
 Usage: openbroker fills [options]
 
 Options:
-  --coin <symbol>   Filter by coin (e.g. ETH, BTC)
-  --side <buy|sell>  Filter by side
-  --top <n>         Show last N fills (default: 20)
-  --help, -h        Show this help
+  --coin <symbol>      Filter by coin (e.g. ETH, BTC)
+  --side <buy|sell>    Filter by side
+  --top <n>            Show last N fills (default: 20)
+  --address <0x...>    Look up another account's fills
+  --help, -h           Show this help
 
 Examples:
   openbroker fills
   openbroker fills --coin ETH
   openbroker fills --coin BTC --side buy --top 50
+  openbroker fills --address 0xabc... --coin ETH
 `);
 }
 
@@ -33,10 +35,13 @@ async function main() {
   const filterSide = args.side as string | undefined;
   const top = parseInt(args.top as string) || 20;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
+  const lookupAddress = targetAddress?.toLowerCase();
+
   try {
-    let fills = await client.getUserFills();
+    let fills = await client.getUserFills(lookupAddress);
 
     if (filterCoin) {
       fills = fills.filter(f => f.coin === normalizeCoin(filterCoin));
@@ -66,6 +71,10 @@ async function main() {
     console.log('Open Broker - Trade Fills');
     console.log('========================\n');
 
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (fills.length === 0) {
       console.log('No fills found');
       return;

package/scripts/info/order-status.ts

@@ -9,12 +9,14 @@ function printUsage() {
 Usage: openbroker order-status --oid <order-id>
 
 Options:
-  --oid <id>    Order ID (number) or client order ID (hex string) — required
-  --help, -h    Show this help
+  --oid <id>          Order ID (number) or client order ID (hex string) — required
+  --address <0x...>   Look up order on another account
+  --help, -h          Show this help
 
 Examples:
   openbroker order-status --oid 123456789
   openbroker order-status --oid 0x1234abcd...
+  openbroker order-status --oid 123456789 --address 0xabc...
 `);
 }
 
@@ -34,13 +36,15 @@ async function main() {
   }
 
   const oid = oidArg.startsWith('0x') ? oidArg : parseInt(oidArg);
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
+  const lookupAddress = targetAddress?.toLowerCase();
 
   console.log('Open Broker - Order Status');
   console.log('=========================\n');
 
   try {
-    const result = await client.getOrderStatus(oid);
+    const result = await client.getOrderStatus(oid, lookupAddress);
 
     if (result.status === 'unknownOid') {
       console.log(`Order ${oidArg} not found`);

package/scripts/info/orders.ts

@@ -13,6 +13,7 @@ Options:
   --status <status>   Filter by status (filled, canceled, open, triggered, rejected, etc.)
   --open              Show only currently open orders
   --top <n>           Show last N orders (default: 20)
+  --address <0x...>   Look up another account's orders
   --help, -h          Show this help
 
 Examples:
@@ -21,6 +22,7 @@ Examples:
   openbroker orders --open --coin ETH
   openbroker orders --coin ETH --status filled
   openbroker orders --top 50
+  openbroker orders --address 0xabc... --open
 `);
 }
 
@@ -37,12 +39,15 @@ async function main() {
   const openOnly = args.open as boolean;
   const top = parseInt(args.top as string) || 20;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
+  const lookupAddress = targetAddress?.toLowerCase();
+
   try {
     if (openOnly) {
       // Use the dedicated open orders endpoint
-      let openOrders = await client.getOpenOrders();
+      let openOrders = await client.getOpenOrders(lookupAddress);
 
       if (filterCoin) {
         openOrders = openOrders.filter(o => o.coin === normalizeCoin(filterCoin));
@@ -69,6 +74,10 @@ async function main() {
       console.log('Open Broker - Open Orders');
       console.log('=========================\n');
 
+      if (targetAddress) {
+        console.log(`Lookup: ${lookupAddress}\n`);
+      }
+
       if (openOrders.length === 0) {
         console.log('No open orders found');
         return;
@@ -106,7 +115,7 @@ async function main() {
       return;
     }
 
-    let orders = await client.getHistoricalOrders();
+    let orders = await client.getHistoricalOrders(lookupAddress);
 
     if (filterCoin) {
       orders = orders.filter(o => o.order.coin === normalizeCoin(filterCoin));
@@ -137,6 +146,10 @@ async function main() {
     console.log('Open Broker - Order History');
     console.log('==========================\n');
 
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (orders.length === 0) {
       console.log('No orders found');
       return;

package/scripts/info/positions.ts

@@ -8,17 +8,21 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   const filterCoin = args.coin as string | undefined;
   const jsonOutput = args.json as boolean;
+  const targetAddress = args.address as string | undefined;
   const client = getClient();
 
   if (args.verbose) {
     client.verbose = true;
   }
 
+  const lookupAddress = targetAddress?.toLowerCase();
+  const isOtherAccount = !!targetAddress;
+
   try {
     const [state, mids, fundingHistory] = await Promise.all([
-      client.getUserStateAll(),
+      client.getUserStateAll(lookupAddress),
       client.getAllMids(),
-      client.getUserFunding(),
+      client.getUserFunding(lookupAddress),
     ]);
 
     const positions = state.assetPositions.filter(ap => {
@@ -69,9 +73,13 @@ async function main() {
     console.log('Open Broker - Positions');
     console.log('=======================\n');
 
+    if (isOtherAccount) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
+
     if (positions.length === 0) {
       console.log(filterCoin ? `No position in ${filterCoin}` : 'No open positions');
-      if (!filterCoin && !client.isApiWallet) {
+      if (!filterCoin && !isOtherAccount && !client.isApiWallet) {
         console.log('\n⚠️  If this account is traded via an API wallet, set HYPERLIQUID_ACCOUNT_ADDRESS');
         console.log('   in ~/.openbroker/.env to the master account address.');
       }

package/scripts/info/spot.ts

@@ -8,6 +8,7 @@ interface Args {
   balances?: boolean;
   top?: number;
   verbose?: boolean;
+  address?: string;
 }
 
 function parseArgs(): Args {
@@ -21,6 +22,8 @@ function parseArgs(): Args {
       args.balances = true;
     } else if (arg === '--top' && process.argv[i + 1]) {
       args.top = parseInt(process.argv[++i], 10);
+    } else if (arg === '--address' && process.argv[i + 1]) {
+      args.address = process.argv[++i].toLowerCase();
     } else if (arg === '--verbose') {
       args.verbose = true;
     } else if (arg === '--help' || arg === '-h') {
@@ -30,11 +33,12 @@ Spot Markets - View Hyperliquid spot markets and balances
 Usage: npx tsx scripts/info/spot.ts [options]
 
 Options:
-  --coin <symbol>  Filter by coin symbol
-  --balances       Show your spot token balances
-  --top <n>        Show only top N markets by volume
-  --verbose        Show detailed output
-  --help           Show this help
+  --coin <symbol>      Filter by coin symbol
+  --balances           Show your spot token balances
+  --address <0x...>    Look up another account's spot balances (with --balances)
+  --top <n>            Show only top N markets by volume
+  --verbose            Show detailed output
+  --help               Show this help
 
 Examples:
   npx tsx scripts/info/spot.ts                  # Show all spot markets
@@ -80,9 +84,10 @@ async function main() {
 
   // Show balances
   if (args.balances) {
-    console.log(`Fetching spot balances for ${client.address}...\n`);
+    const lookupAddress = args.address ?? client.address;
+    console.log(`Fetching spot balances for ${lookupAddress}...\n`);
 
-    const balances = await client.getSpotBalances();
+    const balances = await client.getSpotBalances(args.address);
 
     if (!balances.balances || balances.balances.length === 0) {
       console.log('No spot token balances found.');