openbroker 1.0.82 → 1.0.85

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.82", "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.85", "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_spot_buy ob_spot_sell 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:*)
 ---
 
@@ -46,28 +46,52 @@ Or with the `ob_search` plugin tool: `{ "query": "gold" }` or `{ "query": "oil",
 
 **HIP-3 assets use `dex:COIN` format** — e.g., `xyz:CL` not just `CL`. If you get an error like "No market data found", search for the asset to find the correct prefixed ticker. Common HIP-3 dexes: `xyz`, `flx`, `km`, `hyna`, `vntl`, `cash`.
 
+### Asset IDs (disambiguation)
+
+Every info JSON output includes an `assetId` field — the canonical Hyperliquid asset index. Prefer it over the coin name when persisting references, because the same ticker can exist on multiple providers (e.g. `HYPE` perp, `hyna:HYPE` HIP-3, and `HYPE/USDC` spot all coexist).
+
+| Scope | Formula | Example |
+|-------|---------|---------|
+| Main perps | universe index | `HYPE` → `159` |
+| HIP-3 perps | `100000 + dexIdx * 10000 + assetIdx` | `hyna:HYPE` → `140002` |
+| Spot | `10000 + pair.index` | `HYPE/USDC` → `10107` |
+
+```bash
+openbroker search HYPE --json | jq '.[] | {coin, assetId, type, provider}'
+```
+
+Trading commands still take `--coin <name>` (including HIP-3 `dex:COIN`) — `assetId` is for queries, comparisons, and agent state, not order placement.
+
 ## Troubleshooting: CLI Fallback
 
 If an `ob_*` plugin tool returns unexpected errors, empty results, or crashes, **fall back to the equivalent CLI command** via Bash. The CLI and plugin tools share the same core code, but the CLI has more mature error handling and output.
 
+**Every info command supports `--json`** for structured output. The table below covers the commands with dedicated plugin tools; any other info command (e.g. `spot`, `trades`, `fees`, `order-status`, `rate-limit`, `funding-history`, `all-markets`) can be run as `openbroker <command> --json` for the same effect.
+
 | Plugin Tool | CLI Equivalent |
 |-------------|---------------|
 | `ob_account` | `openbroker account --json` |
 | `ob_positions` | `openbroker positions --json` |
 | `ob_funding` | `openbroker funding --json --include-hip3` |
 | `ob_markets` | `openbroker markets --json --include-hip3` |
-| `ob_search` | `openbroker search --query <QUERY>` |
+| `ob_search` | `openbroker search --query <QUERY> --json` |
+| `ob_spot` | `openbroker spot --json` (or `--balances --json`) |
+| `ob_fills` | `openbroker fills --json` |
+| `ob_orders` | `openbroker orders --json` |
+| `ob_order_status` | `openbroker order-status --oid <OID> --json` |
+| `ob_fees` | `openbroker fees --json` |
+| `ob_candles` | `openbroker candles --coin <COIN> --json` |
+| `ob_funding_history` | `openbroker funding-history --coin <COIN> --json` |
+| `ob_trades` | `openbroker trades --coin <COIN> --json` |
+| `ob_rate_limit` | `openbroker rate-limit --json` |
+| `ob_funding_scan` | `openbroker funding-scan --json` |
 | `ob_buy` | `openbroker buy --coin <COIN> --size <SIZE>` |
 | `ob_sell` | `openbroker sell --coin <COIN> --size <SIZE>` |
 | `ob_limit` | `openbroker limit --coin <COIN> --side <SIDE> --size <SIZE> --price <PRICE>` |
 | `ob_tpsl` | `openbroker tpsl --coin <COIN> --tp <PRICE> --sl <PRICE>` |
 | `ob_cancel` | `openbroker cancel --all` or `--coin <COIN>` |
-| `ob_fills` | `openbroker fills --json` |
-| `ob_orders` | `openbroker orders --json` |
-| `ob_funding_scan` | `openbroker funding-scan --json` |
-| `ob_candles` | `openbroker candles --coin <COIN> --json` |
 | `ob_auto_run` | `openbroker auto run <script> [--dry]` |
-| `ob_auto_stop` | (stop via SIGINT when using CLI) |
+| `ob_auto_stop` | `openbroker auto stop <id>` (or SIGINT if run in foreground) |
 | `ob_auto_list` | `openbroker auto list` |
 
 **When to use CLI fallback:**
@@ -137,12 +161,14 @@ openbroker positions --address 0xabc...  # Another account's positions
 ```bash
 openbroker funding --top 20   # Top 20 by funding rate
 openbroker funding --coin ETH # Specific coin
+openbroker funding --top 20 --json  # JSON (includes assetId)
 ```
 
 ### Markets
 ```bash
 openbroker markets --top 30   # Top 30 main perps
 openbroker markets --coin BTC # Specific coin
+openbroker markets --coin BTC --json  # JSON (includes assetId)
 ```
 
 ### All Markets (Perps + Spot + HIP-3)
@@ -152,6 +178,7 @@ openbroker all-markets --type perp     # Main perps only
 openbroker all-markets --type hip3     # HIP-3 perps only
 openbroker all-markets --type spot     # Spot markets only
 openbroker all-markets --top 20        # Top 20 by volume
+openbroker all-markets --json          # JSON (includes assetId)
 ```
 
 ### Search Markets (Find assets across providers)
@@ -159,6 +186,7 @@ openbroker all-markets --top 20        # Top 20 by volume
 openbroker search --query GOLD    # Find all GOLD markets
 openbroker search --query BTC     # Find BTC across all providers
 openbroker search --query ETH --type perp  # ETH perps only
+openbroker search HYPE --json     # JSON with assetId per result
 ```
 
 ### Spot Markets
@@ -168,6 +196,7 @@ 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
+openbroker spot --json            # JSON (includes assetId, base, quote)
 ```
 
 ### Trade Fills
@@ -193,12 +222,14 @@ openbroker orders --address 0xabc... --open  # Another account's open orders
 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
+openbroker order-status --oid 123456789 --json
 ```
 
 ### Fee Schedule
 ```bash
 openbroker fees                           # Fee tier, rates, and volume
 openbroker fees --address 0xabc...        # Another account's fees
+openbroker fees --json
 ```
 
 ### Candle Data (OHLCV)
@@ -206,23 +237,27 @@ openbroker fees --address 0xabc...        # Another account's fees
 openbroker candles --coin ETH                           # 24 hourly candles
 openbroker candles --coin BTC --interval 4h --bars 48   # 48 four-hour bars
 openbroker candles --coin SOL --interval 1d --bars 30   # 30 daily bars
+openbroker candles --coin ETH --json                    # JSON (coin, assetId, interval, candles)
 ```
 
 ### Funding History
 ```bash
 openbroker funding-history --coin ETH              # Last 24h
 openbroker funding-history --coin BTC --hours 168  # Last 7 days
+openbroker funding-history --coin ETH --json       # JSON (coin, assetId, history)
 ```
 
 ### Recent Trades (Tape)
 ```bash
 openbroker trades --coin ETH              # Last 30 trades
 openbroker trades --coin BTC --top 50     # Last 50 trades
+openbroker trades --coin ETH --json       # JSON (coin, assetId, trades)
 ```
 
 ### Rate Limit
 ```bash
 openbroker rate-limit                     # API usage and capacity
+openbroker rate-limit --json
 ```
 
 ### Funding Rate Scanner (Cross-Dex)
@@ -231,6 +266,7 @@ openbroker funding-scan                          # Scan all dexes, >25% threshol
 openbroker funding-scan --threshold 50 --pairs   # Show opposing funding pairs
 openbroker funding-scan --hip3-only --top 20     # HIP-3 only
 openbroker funding-scan --watch --interval 120   # Re-scan every 2 minutes
+openbroker funding-scan --json                   # JSON (includes assetId per result)
 ```
 
 ## Trading Commands
@@ -293,6 +329,27 @@ openbroker cancel --coin ETH      # Cancel ETH orders only
 openbroker cancel --oid 123456    # Cancel specific order
 ```
 
+### Spot Orders
+Spot trading uses a separate order path with its own asset indices (see Asset IDs section). Pass the base token symbol as `--coin` — quote is always USDC.
+
+```bash
+# Market orders (shortcuts)
+openbroker spot-buy --coin PURR --size 1000
+openbroker spot-sell --coin HYPE --size 5
+
+# Full form (specify --side)
+openbroker spot-order --coin PURR --side buy --size 1000
+
+# Limit orders (add --price)
+openbroker spot-order --coin HYPE --side sell --size 50 --price 25.50
+openbroker spot-order --coin PURR --side buy --size 500 --price 0.20 --tif Alo
+
+# Preview without executing
+openbroker spot-buy --coin PURR --size 500 --dry
+```
+
+**Spot flags:** `--coin`, `--side`, `--size`, `--price` (omit → market order), `--tif` (`Gtc`/`Ioc`/`Alo`, default `Gtc`), `--slippage` (bps, market orders only), `--dry`, `--verbose`.
+
 ## Advanced Execution
 
 ### TWAP (Native Exchange Order)
@@ -303,6 +360,9 @@ openbroker twap --coin ETH --side buy --size 1 --duration 30
 # Sell 0.5 BTC over 2 hours without randomized timing
 openbroker twap --coin BTC --side sell --size 0.5 --duration 120 --randomize false
 
+# Reduce-only (close position with TWAP). Note: TWAP uses `--reduce-only`, not `--reduce`
+openbroker twap --coin ETH --side sell --size 1 --duration 30 --reduce-only
+
 # Cancel a running TWAP
 openbroker twap-cancel --coin ETH --twap-id 77738308
 
@@ -407,6 +467,7 @@ 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 | Master account address (required for API wallets) |
+| `OB_DASHBOARD_URL` | No | Dashboard API URL for forwarding audit notes, metrics, and agent actions (e.g. `http://localhost:3001`) |
 
 The builder fee (1 bps / 0.01%) is hardcoded and not configurable.
 
@@ -591,6 +652,8 @@ export default function(api) {
 
 Automations now write a local audit trail automatically to `~/.openbroker/automation-audit.sqlite`. The runtime records run config, logs, state changes, write actions, order updates, fills, user events, and per-poll account snapshots so you can generate performance reports later.
 
+**Dashboard Forwarding:** When `OB_DASHBOARD_URL` is set (e.g. `http://localhost:3001`), audit notes, metrics, and trade actions are automatically forwarded to the OpenBroker Vaults dashboard API in real time. The vault address is read from `HYPERSTABLE_VAULT_ADDRESS` or `VAULT`. Forwarding is fire-and-forget — it never blocks the automation or causes errors if the dashboard is unreachable.
+
 ### Events
 
 | Event | Payload | When |
@@ -1053,10 +1116,14 @@ export default function(api) {
 openbroker auto run my-strategy --dry       # Test without trading
 openbroker auto run ./funding-scalp.ts      # Run from path
 openbroker auto run my-strategy --poll 5000 # Poll every 5s
+openbroker auto run my-strategy --no-ws     # Disable WebSocket, pure REST polling
 openbroker auto run --example dca --set coin=HYPE --set amount=50 --dry  # Run bundled example
 openbroker auto examples                    # List bundled examples with config
 openbroker auto list                        # Show available scripts
 openbroker auto status                      # Show running automations
+openbroker auto stop <id>                   # Unregister an automation (won't auto-restart)
+openbroker auto report <id>                 # Read the local audit report (logs, trades, metrics) for an automation
+openbroker auto clean                       # Remove stale entries from the registry
 ```
 
 **Plugin tools (for OpenClaw agents):**
@@ -1072,9 +1139,14 @@ openbroker auto status                      # Show running automations
 | `--verbose` | Show debug output | false |
 | `--id <name>` | Custom automation ID | filename |
 | `--poll <ms>` | Poll interval in milliseconds | 10000 |
+| `--no-ws` | Disable WebSocket; fall back to REST-only polling | WebSocket on |
 | `--example <name>` | Run a bundled example automation | - |
 | `--set key=value` | Set config values (repeatable) | - |
 
+**Inspecting automations after they run:**
+- `openbroker auto report <id>` — reads the local SQLite audit trail at `~/.openbroker/automation-audit.sqlite` and prints a summary of logs, write actions, fills, PnL, and custom metrics recorded via `api.audit.record()` / `api.audit.metric()`. Use this to review what a strategy actually did.
+- `openbroker auto clean` — prunes registry entries for automations that are no longer running or whose script file is gone. Safe to run anytime.
+
 **Guidelines for agents writing automations:**
 
 **Risk & Safety (mandatory):**

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/auto/cli.ts

@@ -32,6 +32,7 @@ Options (for run):
   --verbose          Show debug output
   --id <name>        Custom automation ID (default: filename)
   --poll <ms>        Poll interval in milliseconds (default: 10000)
+  --no-ws            Disable WebSocket; fall back to REST-only polling
 
 Scripts are loaded from:
   1. Absolute or relative path

package/scripts/auto/dashboard-forwarder.ts

@@ -0,0 +1,77 @@
+/**
+ * Dashboard audit forwarder.
+ *
+ * When OB_DASHBOARD_URL is set, wraps the AutomationAudit API to also POST
+ * audit notes, metrics, and agent action logs to the ob-app backend.
+ *
+ * Fires HTTP requests in the background — never blocks the automation loop.
+ */
+
+import type { AutomationAudit } from './types.js';
+
+const DASHBOARD_URL = process.env.OB_DASHBOARD_URL; // e.g. "http://localhost:3001"
+const DASHBOARD_API_KEY = process.env.OB_DASHBOARD_API_KEY || '';
+const VAULT_ADDRESS = process.env.HYPERSTABLE_VAULT_ADDRESS || process.env.VAULT || '';
+
+function postJSON(path: string, body: unknown): void {
+  if (!DASHBOARD_URL || !VAULT_ADDRESS) return;
+
+  const url = `${DASHBOARD_URL}/api/vaults/${VAULT_ADDRESS.toLowerCase()}${path}`;
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (DASHBOARD_API_KEY) {
+    headers['Authorization'] = `Bearer ${DASHBOARD_API_KEY}`;
+  }
+
+  fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(5_000),
+  }).catch(() => {
+    // Silently ignore — dashboard may be down, automation must not be affected.
+  });
+}
+
+/**
+ * Wrap an existing AutomationAudit to forward calls to the dashboard API.
+ * If OB_DASHBOARD_URL is not set, returns the original audit object unchanged.
+ */
+export function withDashboardForwarder(audit: AutomationAudit): AutomationAudit {
+  if (!DASHBOARD_URL || !VAULT_ADDRESS) return audit;
+
+  return {
+    record(kind: string, payload?: unknown): void {
+      audit.record(kind, payload);
+      postJSON('/audit/notes', {
+        category: kind,
+        label: typeof payload === 'object' && payload !== null && 'reason' in payload
+          ? String((payload as Record<string, unknown>).reason)
+          : kind,
+        data: payload ?? {},
+      });
+    },
+
+    metric(name: string, value: number, tags?: Record<string, unknown>): void {
+      audit.metric(name, value, tags);
+      postJSON('/audit/metrics', {
+        name,
+        value,
+        tags: tags ?? {},
+      });
+    },
+  };
+}
+
+/**
+ * Forward an agent action log to the dashboard.
+ * Call this from audited client wrappers or directly from automation code.
+ */
+export function forwardAgentAction(
+  action: string,
+  status: 'success' | 'error' | 'pending',
+  details: Record<string, unknown>,
+  txHash?: string,
+): void {
+  postJSON('/agent/logs', { action, status, details, txHash });
+}

package/scripts/auto/loader.ts

@@ -22,8 +22,10 @@ export function resolveScriptPath(nameOrPath: string): string {
     return nameOrPath;
   }
 
-  // Relative to cwd
-  const cwdPath = path.resolve(process.cwd(), nameOrPath);
+  // Relative to the user's original cwd (not the openbroker package root that
+  // `bin/openbroker.js` chdirs to before spawning tsx).
+  const userCwd = process.env.OPENBROKER_CWD || process.cwd();
+  const cwdPath = path.resolve(userCwd, nameOrPath);
   if (existsSync(cwdPath)) return cwdPath;
 
   // Relative to ~/.openbroker/automations/

package/scripts/auto/runtime.ts

@@ -15,6 +15,7 @@ import { AutomationEventBus } from './events.js';
 import { loadAutomation } from './loader.js';
 import { registerAutomation, unregisterAutomation, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
 import { createAutomationAudit, toSerializable, type AutomationAuditSink } from './audit.js';
+import { withDashboardForwarder, forwardAgentAction } from './dashboard-forwarder.js';
 import type {
   AutomationAPI,
   AutomationEventPayloads,
@@ -178,6 +179,11 @@ function createAuditedClient(
               result,
               dryRun,
             });
+            forwardAgentAction(
+              prop,
+              'success',
+              { args: toSerializable(args), result: toSerializable(result), dryRun },
+            );
             return result;
           } catch (error) {
             audit.recordAction({
@@ -187,6 +193,11 @@ function createAuditedClient(
               error,
               dryRun,
             });
+            forwardAgentAction(
+              prop,
+              'error',
+              { args: toSerializable(args), error: String(error), dryRun },
+            );
             throw error;
           }
         };
@@ -424,10 +435,10 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
 
   // Build the API object
   const publish = createAuditedPublish(createPublish(id, log, gatewayPort, hooksToken), audit);
-  const auditApi: AutomationAudit = {
+  const auditApi: AutomationAudit = withDashboardForwarder({
     record: (kind: string, payload?: unknown) => audit.recordNote(kind, payload),
     metric: (name: string, value: number, tags?: Record<string, unknown>) => audit.recordMetric(name, value, tags),
-  };
+  });
   const api: AutomationAPI = {
     client,
     utils: { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate },

package/scripts/core/config.ts

@@ -112,7 +112,7 @@ export function loadConfig(): OpenBrokerConfig {
     // Show warning once
     if (!readOnlyWarningShown) {
       readOnlyWarningShown = true;
-      console.log('\x1b[33m⚠️  Not configured for trading. Run "openbroker setup" to enable trades.\x1b[0m\n');
+      console.error('\x1b[33m⚠️  Not configured for trading. Run "openbroker setup" to enable trades.\x1b[0m\n');
     }
   }
 

package/scripts/info/all-markets.ts

@@ -7,6 +7,7 @@ interface Args {
   type?: 'perp' | 'spot' | 'hip3' | 'all';
   top?: number;
   verbose?: boolean;
+  json?: boolean;
 }
 
 function parseArgs(): Args {
@@ -23,6 +24,8 @@ function parseArgs(): Args {
       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') {
       console.log(`
 All Markets - View all available markets on Hyperliquid
@@ -32,6 +35,7 @@ Usage: npx tsx scripts/info/all-markets.ts [options]
 Options:
   --type <type>    Market type: perp, spot, hip3, or all (default: all)
   --top <n>        Show only top N markets by volume
+  --json           Output as JSON (machine-readable)
   --verbose        Show detailed output
   --help           Show this help
 
@@ -41,6 +45,7 @@ Examples:
   npx tsx scripts/info/all-markets.ts --type hip3    # Show only HIP-3 perps
   npx tsx scripts/info/all-markets.ts --type spot    # Show only spot markets
   npx tsx scripts/info/all-markets.ts --top 20       # Show top 20 by volume
+  npx tsx scripts/info/all-markets.ts --json         # JSON output
 `);
       process.exit(0);
     }
@@ -71,22 +76,27 @@ function formatFunding(rate: string): string {
   return `${sign}${annualized.toFixed(2)}%`;
 }
 
+interface MarketRow {
+  type: 'perp' | 'spot' | 'hip3';
+  provider: string;
+  coin: string;
+  assetId: number;
+  price: string;
+  volume24h: number;
+  funding?: string;
+  maxLeverage?: number;
+}
+
 async function main() {
   const args = parseArgs();
   const client = getClient();
   client.verbose = args.verbose ?? false;
 
-  console.log('Fetching market data...\n');
+  if (!args.json) {
+    console.log('Fetching market data...\n');
+  }
 
-  const allMarkets: Array<{
-    type: 'perp' | 'spot' | 'hip3';
-    provider: string;
-    coin: string;
-    price: string;
-    volume24h: number;
-    funding?: string;
-    maxLeverage?: number;
-  }> = [];
+  const allMarkets: MarketRow[] = [];
 
   // Fetch main perps
   if (args.type === 'all' || args.type === 'perp') {
@@ -98,6 +108,7 @@ async function main() {
         type: 'perp',
         provider: 'Hyperliquid',
         coin: asset.name,
+        assetId: i,
         price: ctx.markPx,
         volume24h: parseFloat(ctx.dayNtlVlm),
         funding: ctx.funding,
@@ -108,7 +119,7 @@ async function main() {
 
   // Fetch HIP-3 perps
   if (args.type === 'all' || args.type === 'hip3') {
-    if (client.isTestnet) {
+    if (client.isTestnet && !args.json) {
       console.log('Note: Testnet — HIP-3 dexes not auto-loaded. Use "dexName:COIN" syntax to load a specific dex.\n');
     }
     try {
@@ -123,10 +134,13 @@ async function main() {
           const ctx = dexData.assetCtxs[i];
           if (!asset || !ctx) continue;
 
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(asset.name); } catch { /* not registered */ }
           allMarkets.push({
             type: 'hip3',
             provider: dexData.dexName || `HIP-3 DEX ${dexIdx}`,
             coin: asset.name,
+            assetId,
             price: ctx.markPx,
             volume24h: parseFloat(ctx.dayNtlVlm || '0'),
             funding: ctx.funding,
@@ -143,15 +157,23 @@ async function main() {
   if (args.type === 'all' || args.type === 'spot') {
     try {
       const spotData = await client.getSpotMetaAndAssetCtxs();
-      for (let i = 0; i < spotData.meta.universe.length; i++) {
-        const pair = spotData.meta.universe[i];
-        const ctx = spotData.assetCtxs[i];
-        if (!pair || !ctx) continue;
+      // contexts carry coin field that matches pair.name; not necessarily aligned by index
+      const ctxMap = new Map<string, (typeof spotData.assetCtxs)[number]>();
+      for (const ctx of spotData.assetCtxs) {
+        if ((ctx as Record<string, unknown>).coin) {
+          ctxMap.set((ctx as Record<string, unknown>).coin as string, ctx);
+        }
+      }
+      for (const pair of spotData.meta.universe) {
+        if (!pair) continue;
+        const ctx = ctxMap.get(pair.name);
+        if (!ctx) continue;
 
         allMarkets.push({
           type: 'spot',
           provider: 'Spot',
           coin: pair.name,
+          assetId: 10000 + pair.index,
           price: ctx.markPx,
           volume24h: parseFloat(ctx.dayNtlVlm || '0'),
         });
@@ -167,6 +189,11 @@ async function main() {
   // Apply top filter
   const markets = args.top ? allMarkets.slice(0, args.top) : allMarkets;
 
+  if (args.json) {
+    console.log(JSON.stringify(markets, null, 2));
+    return;
+  }
+
   // Group by type for display
   const perps = markets.filter((m) => m.type === 'perp');
   const hip3 = markets.filter((m) => m.type === 'hip3');
@@ -183,11 +210,11 @@ async function main() {
   // Print perps
   if (perps.length > 0) {
     console.log('=== Main Perpetuals ===\n');
-    console.log('Coin           Price            24h Volume    Funding (Ann.)  Leverage');
-    console.log('-'.repeat(75));
+    console.log('Coin           AssetID    Price            24h Volume    Funding (Ann.)  Leverage');
+    console.log('-'.repeat(87));
     for (const m of perps) {
       console.log(
-        `${m.coin.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)} ${(m.maxLeverage ? `${m.maxLeverage}x` : '-').padStart(9)}`
+        `${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)} ${(m.maxLeverage ? `${m.maxLeverage}x` : '-').padStart(9)}`
       );
     }
     console.log();
@@ -196,11 +223,11 @@ async function main() {
   // Print HIP-3 markets
   if (hip3.length > 0) {
     console.log('=== HIP-3 Perpetuals ===\n');
-    console.log('Coin           Provider         Price            24h Volume    Funding (Ann.)');
-    console.log('-'.repeat(80));
+    console.log('Coin           Provider         AssetID    Price            24h Volume    Funding (Ann.)');
+    console.log('-'.repeat(92));
     for (const m of hip3) {
       console.log(
-        `${m.coin.padEnd(14)} ${m.provider.padEnd(16)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)}`
+        `${m.coin.padEnd(14)} ${m.provider.padEnd(16)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)}`
       );
     }
     console.log();
@@ -209,11 +236,11 @@ async function main() {
   // Print spot markets
   if (spots.length > 0) {
     console.log('=== Spot Markets ===\n');
-    console.log('Pair           Price            24h Volume');
-    console.log('-'.repeat(50));
+    console.log('Pair           AssetID    Price            24h Volume');
+    console.log('-'.repeat(62));
     for (const m of spots) {
       console.log(
-        `${m.coin.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)}`
+        `${m.coin.padEnd(14)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)}`
       );
     }
     console.log();

package/scripts/info/candles.ts

@@ -21,6 +21,7 @@ Options:
   --interval <interval> Candle interval (default: 1h)
                        Valid: ${VALID_INTERVALS.join(', ')}
   --bars <n>           Number of bars to fetch (default: 24)
+  --json               Output as JSON (machine-readable)
   --help, -h           Show this help
 
 Examples:
@@ -59,10 +60,13 @@ async function main() {
   }
 
   const bars = parseInt(args.bars as string) || 24;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log(`Open Broker - ${normalizeCoin(coin)} Candles (${interval})`);
-  console.log('='.repeat(40) + '\n');
+  if (!jsonOutput) {
+    console.log(`Open Broker - ${normalizeCoin(coin)} Candles (${interval})`);
+    console.log('='.repeat(40) + '\n');
+  }
 
   try {
     // Load metadata (needed for HIP-3 coin resolution)
@@ -75,6 +79,13 @@ async function main() {
     const startTime = now - (bars * (INTERVAL_MS[interval] || 3_600_000));
     const candles = await client.getCandleSnapshot(normalizeCoin(coin), interval, startTime);
 
+    if (jsonOutput) {
+      let assetId = -1;
+      try { assetId = client.getAssetIndex(normalizeCoin(coin)); } catch { /* noop */ }
+      console.log(JSON.stringify({ coin: normalizeCoin(coin), assetId, interval, candles }, null, 2));
+      return;
+    }
+
     if (candles.length === 0) {
       console.log('No candle data found');
       return;

package/scripts/info/fees.ts

@@ -9,10 +9,13 @@ function printUsage() {
 Usage: openbroker fees [options]
 
 Options:
-  --help, -h    Show this help
+  --address <0x...>  Look up another account's fees
+  --json             Output as JSON (machine-readable)
+  --help, -h         Show this help
 
 Examples:
   openbroker fees
+  openbroker fees --json
 `);
 }
 
@@ -25,19 +28,27 @@ async function main() {
   }
 
   const targetAddress = args.address as string | undefined;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
   const lookupAddress = targetAddress?.toLowerCase();
 
-  console.log('Open Broker - Fee Schedule');
-  console.log('=========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - Fee Schedule');
+    console.log('=========================\n');
 
-  if (targetAddress) {
-    console.log(`Lookup: ${lookupAddress}\n`);
+    if (targetAddress) {
+      console.log(`Lookup: ${lookupAddress}\n`);
+    }
   }
 
   try {
     const fees = await client.getUserFees(lookupAddress);
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(fees, null, 2));
+      return;
+    }
+
     // Fee rates
     console.log('Fee Rates');
     console.log('─'.repeat(40));

package/scripts/info/funding-history.ts

@@ -11,6 +11,7 @@ Usage: openbroker funding-history --coin <symbol> [options]
 Options:
   --coin <symbol>   Asset symbol (required, e.g. ETH, BTC)
   --hours <n>       Hours of history to fetch (default: 24)
+  --json            Output as JSON (machine-readable)
   --help, -h        Show this help
 
 Examples:
@@ -35,10 +36,13 @@ async function main() {
   }
 
   const hours = parseInt(args.hours as string) || 24;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log(`Open Broker - ${normalizeCoin(coin)} Funding History (${hours}h)`);
-  console.log('='.repeat(40) + '\n');
+  if (!jsonOutput) {
+    console.log(`Open Broker - ${normalizeCoin(coin)} Funding History (${hours}h)`);
+    console.log('='.repeat(40) + '\n');
+  }
 
   try {
     // Load metadata (needed for HIP-3 coin resolution)
@@ -51,6 +55,13 @@ async function main() {
     const startTime = now - (hours * 3_600_000);
     const history = await client.getFundingHistory(normalizeCoin(coin), startTime);
 
+    if (jsonOutput) {
+      let assetId = -1;
+      try { assetId = client.getAssetIndex(normalizeCoin(coin)); } catch { /* noop */ }
+      console.log(JSON.stringify({ coin: normalizeCoin(coin), assetId, history }, null, 2));
+      return;
+    }
+
     if (history.length === 0) {
       console.log('No funding history found');
       return;

package/scripts/info/funding-scan.ts

@@ -32,6 +32,7 @@ Examples:
 
 interface FundingScanResult {
   coin: string;
+  assetId: number;
   dex: string;
   hourlyRate: number;
   annualizedPct: number;
@@ -69,9 +70,14 @@ async function scanFunding(client: ReturnType<typeof getClient>, options: {
 
       // API returns HIP-3 names already prefixed (e.g., "xyz:CL")
       const coin = asset.name;
+      let assetId = isMain ? i : -1;
+      if (!isMain) {
+        try { assetId = client.getAssetIndex(coin); } catch { /* not registered */ }
+      }
 
       results.push({
         coin,
+        assetId,
         dex: dexData.dexName ?? 'main',
         hourlyRate,
         annualizedPct,

package/scripts/info/funding.ts

@@ -6,6 +6,7 @@ import { formatPercent, annualizeFundingRate, parseArgs } from '../core/utils.js
 
 interface FundingDisplay {
   coin: string;
+  assetId: number;
   hourlyRate: number;
   annualizedRate: number;
   premium: number;
@@ -47,6 +48,7 @@ async function main() {
 
       fundingData.push({
         coin: asset.name,
+        assetId: i,
         hourlyRate,
         annualizedRate,
         premium,
@@ -84,8 +86,12 @@ async function main() {
 
           if (!showAll && openInterest < 1000) continue;
 
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(coinName); } catch { /* not registered */ }
+
           fundingData.push({
             coin: coinName,
+            assetId,
             hourlyRate,
             annualizedRate,
             premium: 0,

package/scripts/info/markets.ts

@@ -6,6 +6,7 @@ import { formatUsd, parseArgs } from '../core/utils.js';
 
 interface MarketDisplay {
   coin: string;
+  assetId: number;
   markPx: number;
   oraclePx: number;
   prevDayPx: number;
@@ -47,6 +48,7 @@ async function main() {
 
       markets.push({
         coin: asset.name,
+        assetId: i,
         markPx,
         oraclePx,
         prevDayPx,
@@ -86,9 +88,12 @@ async function main() {
           const volume24h = parseFloat(ctx.dayNtlVlm);
           const openInterest = parseFloat(ctx.openInterest);
           const change24h = prevDayPx > 0 ? (markPx - prevDayPx) / prevDayPx : 0;
+          let assetId = -1;
+          try { assetId = client.getAssetIndex(coinName); } catch { /* not registered */ }
 
           markets.push({
             coin: coinName,
+            assetId,
             markPx,
             oraclePx,
             prevDayPx,

package/scripts/info/order-status.ts

@@ -11,6 +11,7 @@ Usage: openbroker order-status --oid <order-id>
 Options:
   --oid <id>          Order ID (number) or client order ID (hex string) — required
   --address <0x...>   Look up order on another account
+  --json              Output as JSON (machine-readable)
   --help, -h          Show this help
 
 Examples:
@@ -37,15 +38,23 @@ async function main() {
 
   const oid = oidArg.startsWith('0x') ? oidArg : parseInt(oidArg);
   const targetAddress = args.address as string | undefined;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
   const lookupAddress = targetAddress?.toLowerCase();
 
-  console.log('Open Broker - Order Status');
-  console.log('=========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - Order Status');
+    console.log('=========================\n');
+  }
 
   try {
     const result = await client.getOrderStatus(oid, lookupAddress);
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
     if (result.status === 'unknownOid') {
       console.log(`Order ${oidArg} not found`);
       return;

package/scripts/info/rate-limit.ts

@@ -9,6 +9,7 @@ function printUsage() {
 Usage: openbroker rate-limit [options]
 
 Options:
+  --json        Output as JSON (machine-readable)
   --help, -h    Show this help
 
 Examples:
@@ -24,14 +25,22 @@ async function main() {
     process.exit(0);
   }
 
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log('Open Broker - API Rate Limit');
-  console.log('===========================\n');
+  if (!jsonOutput) {
+    console.log('Open Broker - API Rate Limit');
+    console.log('===========================\n');
+  }
 
   try {
     const rl = await client.getUserRateLimit();
 
+    if (jsonOutput) {
+      console.log(JSON.stringify(rl, null, 2));
+      return;
+    }
+
     const used = rl.nRequestsUsed;
     const cap = rl.nRequestsCap;
     const surplus = rl.nRequestsSurplus;

package/scripts/info/search-markets.ts

@@ -7,6 +7,7 @@ interface Args {
   query: string;
   type?: 'perp' | 'spot' | 'hip3' | 'all';
   verbose?: boolean;
+  json?: boolean;
 }
 
 function parseArgs(): Args {
@@ -23,6 +24,8 @@ function parseArgs(): Args {
       }
     } else if (arg === '--verbose') {
       args.verbose = true;
+    } else if (arg === '--json') {
+      args.json = true;
     } else if (arg === '--help' || arg === '-h') {
       console.log(`
 Search Markets - Find assets across all Hyperliquid markets
@@ -32,6 +35,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)
+  --json            Output as JSON (machine-readable)
   --verbose         Show detailed output
   --help            Show this help
 
@@ -40,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 HYPE --json      # JSON output
 `);
       process.exit(0);
     } else if (!args.query && !arg.startsWith('-')) {
@@ -85,18 +90,23 @@ async function main() {
   client.verbose = args.verbose ?? false;
 
   const query = args.query.toUpperCase();
-  console.log(`Searching for "${query}" across all markets...\n`);
+  if (!args.json) {
+    console.log(`Searching for "${query}" across all markets...\n`);
+  }
 
-  const results: Array<{
+  interface Result {
     type: 'perp' | 'spot' | 'hip3';
     provider: string;
     coin: string;
+    assetId: number;
     price: string;
     volume24h: number;
     funding?: string;
     maxLeverage?: number;
     openInterest?: string;
-  }> = [];
+  }
+
+  const results: Result[] = [];
 
   // Search main perps
   if (args.type === 'all' || args.type === 'perp') {
@@ -110,6 +120,7 @@ async function main() {
           type: 'perp',
           provider: 'Hyperliquid',
           coin: asset.name,
+          assetId: i,
           price: ctx.markPx,
           volume24h: parseFloat(ctx.dayNtlVlm),
           funding: ctx.funding,
@@ -126,7 +137,7 @@ async function main() {
       // On testnet, load specific dex if query is "dex:COIN" format
       if (args.query.includes(':')) {
         await client.loadSingleHip3Dex(args.query.split(':')[0]);
-      } else {
+      } else if (!args.json) {
         console.log('  (Testnet: HIP-3 dexes not auto-loaded. Use "dexName:COIN" to search a specific dex.)\n');
       }
     }
@@ -143,10 +154,13 @@ async function main() {
           if (!asset || !ctx) continue;
 
           if (asset.name.toUpperCase().includes(query)) {
+            let assetId = -1;
+            try { assetId = client.getAssetIndex(asset.name); } catch { /* not registered */ }
             results.push({
               type: 'hip3',
               provider: dexData.dexName || `HIP-3 DEX ${dexIdx}`,
               coin: asset.name,
+              assetId,
               price: ctx.markPx,
               volume24h: parseFloat(ctx.dayNtlVlm || '0'),
               funding: ctx.funding,
@@ -199,6 +213,7 @@ async function main() {
             type: 'spot',
             provider: 'Spot',
             coin: displayName,
+            assetId: 10000 + pair.index,
             price: ctx.markPx,
             volume24h: parseFloat(ctx.dayNtlVlm || '0'),
           });
@@ -212,20 +227,25 @@ async function main() {
   // Sort by volume
   results.sort((a, b) => b.volume24h - a.volume24h);
 
+  if (args.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
   if (results.length === 0) {
     console.log(`No markets found matching "${query}"`);
     return;
   }
 
   console.log(`Found ${results.length} market(s) matching "${query}":\n`);
-  console.log('Type     Provider         Coin           Price            24h Volume    Funding (Ann.)  OI');
-  console.log('-'.repeat(100));
+  console.log('Type     Provider         Coin           AssetID    Price            24h Volume    Funding (Ann.)  OI');
+  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 oi = m.openInterest ? formatVolume(parseFloat(m.openInterest)) : '-';
     console.log(
-      `${typeStr.padEnd(8)} ${m.provider.padEnd(16)} ${m.coin.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${(m.funding ? formatFunding(m.funding) : '-').padStart(14)} ${oi.padStart(10)}`
+      `${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)}`
     );
   }
 
@@ -245,11 +265,11 @@ async function main() {
     const perpsWithFunding = markets.filter((m) => m.funding && m.type !== 'spot');
     if (perpsWithFunding.length > 1) {
       console.log(`\n=== ${coin} Funding Comparison ===\n`);
-      console.log('Provider         Coin           Funding (Ann.)    Price');
-      console.log('-'.repeat(65));
+      console.log('Provider         Coin           AssetID    Funding (Ann.)    Price');
+      console.log('-'.repeat(78));
       for (const m of perpsWithFunding.sort((a, b) => parseFloat(b.funding!) - parseFloat(a.funding!))) {
         console.log(
-          `${m.provider.padEnd(16)} ${m.coin.padEnd(14)} ${formatFunding(m.funding!).padStart(14)}    ${formatPrice(m.price)}`
+          `${m.provider.padEnd(16)} ${m.coin.padEnd(14)} ${String(m.assetId).padStart(7)}    ${formatFunding(m.funding!).padStart(14)}    ${formatPrice(m.price)}`
         );
       }
     }

package/scripts/info/spot.ts

@@ -9,6 +9,7 @@ interface Args {
   top?: number;
   verbose?: boolean;
   address?: string;
+  json?: boolean;
 }
 
 function parseArgs(): Args {
@@ -26,6 +27,8 @@ function parseArgs(): Args {
       args.address = process.argv[++i].toLowerCase();
     } else if (arg === '--verbose') {
       args.verbose = true;
+    } else if (arg === '--json') {
+      args.json = true;
     } else if (arg === '--help' || arg === '-h') {
       console.log(`
 Spot Markets - View Hyperliquid spot markets and balances
@@ -37,6 +40,7 @@ Options:
   --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
+  --json               Output as JSON (machine-readable)
   --verbose            Show detailed output
   --help               Show this help
 
@@ -85,10 +89,15 @@ async function main() {
   // Show balances
   if (args.balances) {
     const lookupAddress = args.address ?? client.address;
-    console.log(`Fetching spot balances for ${lookupAddress}...\n`);
+    if (!args.json) console.log(`Fetching spot balances for ${lookupAddress}...\n`);
 
     const balances = await client.getSpotBalances(args.address);
 
+    if (args.json) {
+      console.log(JSON.stringify(balances.balances ?? [], null, 2));
+      return;
+    }
+
     if (!balances.balances || balances.balances.length === 0) {
       console.log('No spot token balances found.');
       return;
@@ -112,17 +121,20 @@ async function main() {
   }
 
   // Show markets
-  console.log('Fetching spot market data...\n');
+  if (!args.json) console.log('Fetching spot market data...\n');
 
   const spotData = await client.getSpotMetaAndAssetCtxs();
 
   interface SpotMarket {
     name: string;
     index: number;
+    assetId: number;
     price: string;
     volume24h: number;
     change24h: string;
     tokens: [number, number];
+    base?: string;
+    quote?: string;
   }
 
   const markets: SpotMarket[] = [];
@@ -155,10 +167,13 @@ async function main() {
     markets.push({
       name: pair.name,
       index: pair.index,
+      assetId: 10000 + pair.index,
       price: ctx.markPx,
       volume24h: parseFloat(ctx.dayNtlVlm || '0'),
       change24h: formatChange(ctx.markPx, ctx.prevDayPx),
       tokens: pair.tokens,
+      base: tokenNameMap.get(pair.tokens[0]),
+      quote: tokenNameMap.get(pair.tokens[1]),
     });
   }
 
@@ -168,6 +183,11 @@ async function main() {
   // Apply top filter
   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(args.coin ? `No spot markets found for "${args.coin}"` : 'No spot markets found');
     return;
@@ -180,8 +200,8 @@ async function main() {
   }
 
   console.log(`=== Spot Markets (${displayMarkets.length} total) ===\n`);
-  console.log('Pair           Price            24h Volume    24h Change   Base/Quote');
-  console.log('-'.repeat(80));
+  console.log('Pair           AssetID    Price            24h Volume    24h Change   Base/Quote');
+  console.log('-'.repeat(92));
 
   for (const m of displayMarkets) {
     const baseToken = tokenMap.get(m.tokens[0]);
@@ -189,7 +209,7 @@ async function main() {
     const pairStr = `${baseToken?.name || '?'}/${quoteToken?.name || '?'}`;
 
     console.log(
-      `${m.name.padEnd(14)} ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${m.change24h.padStart(11)}   ${pairStr}`
+      `${m.name.padEnd(14)} ${String(m.assetId).padStart(7)}    ${formatPrice(m.price).padStart(16)} ${formatVolume(m.volume24h).padStart(13)} ${m.change24h.padStart(11)}   ${pairStr}`
     );
   }
 

package/scripts/info/trades.ts

@@ -11,6 +11,7 @@ Usage: openbroker trades --coin <symbol> [options]
 Options:
   --coin <symbol>   Asset symbol (required, e.g. ETH, BTC)
   --top <n>         Show last N trades (default: 30)
+  --json            Output as JSON (machine-readable)
   --help, -h        Show this help
 
 Examples:
@@ -35,10 +36,13 @@ async function main() {
   }
 
   const top = parseInt(args.top as string) || 30;
+  const jsonOutput = args.json as boolean;
   const client = getClient();
 
-  console.log(`Open Broker - ${normalizeCoin(coin)} Recent Trades`);
-  console.log('='.repeat(40) + '\n');
+  if (!jsonOutput) {
+    console.log(`Open Broker - ${normalizeCoin(coin)} Recent Trades`);
+    console.log('='.repeat(40) + '\n');
+  }
 
   try {
     // Load metadata (needed for HIP-3 coin resolution)
@@ -53,6 +57,13 @@ async function main() {
     trades.sort((a, b) => b.time - a.time);
     trades = trades.slice(0, top);
 
+    if (jsonOutput) {
+      let assetId = -1;
+      try { assetId = client.getAssetIndex(normalizeCoin(coin)); } catch { /* noop */ }
+      console.log(JSON.stringify({ coin: normalizeCoin(coin), assetId, trades }, null, 2));
+      return;
+    }
+
     if (trades.length === 0) {
       console.log('No recent trades found');
       return;