@farazirfan/costar-server-executor 1.7.28 → 1.7.30

package/skills/okx/scripts/okx-trade.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env npx tsx
+/**
+ * OKX Trade Helper — CLI tool for common OKX operations.
+ * Agent can use this directly or create new scripts based on this pattern.
+ *
+ * Usage:
+ *   npx tsx scripts/okx-trade.ts balances
+ *   npx tsx scripts/okx-trade.ts positions
+ *   npx tsx scripts/okx-trade.ts price BTC-USDT
+ *   npx tsx scripts/okx-trade.ts market-buy BTC-USDT 100
+ *   npx tsx scripts/okx-trade.ts market-sell BTC-USDT 0.001
+ *   npx tsx scripts/okx-trade.ts limit-buy BTC-USDT 0.001 95000
+ *   npx tsx scripts/okx-trade.ts limit-sell BTC-USDT 0.001 105000
+ *   npx tsx scripts/okx-trade.ts status BTC-USDT <order-id>
+ *   npx tsx scripts/okx-trade.ts cancel BTC-USDT <order-id>
+ *   npx tsx scripts/okx-trade.ts open-orders
+ *   npx tsx scripts/okx-trade.ts products
+ *   npx tsx scripts/okx-trade.ts fees
+ *
+ * Requires: OKX_API_KEY, OKX_API_SECRET, OKX_API_PASSPHRASE env vars
+ * Install:  npm install okx-api
+ */
+
+import { RestClient } from 'okx-api';
+
+// --- Init Client ---
+
+const apiKey = process.env.OKX_API_KEY;
+const apiSecret = process.env.OKX_API_SECRET;
+const apiPass = process.env.OKX_API_PASSPHRASE;
+
+if (!apiKey || !apiSecret || !apiPass) {
+  console.error('ERROR: OKX_API_KEY, OKX_API_SECRET, and OKX_API_PASSPHRASE must be set');
+  process.exit(1);
+}
+
+const client = new RestClient({ apiKey, apiSecret, apiPass });
+
+// --- Commands ---
+
+const [command, ...args] = process.argv.slice(2);
+
+async function run() {
+  switch (command) {
+    case 'balances':
+      return showBalances();
+    case 'positions':
+      return showPositions();
+    case 'price':
+      return showPrice(args[0]);
+    case 'market-buy':
+      return marketBuy(args[0], args[1]);
+    case 'market-sell':
+      return marketSell(args[0], args[1]);
+    case 'limit-buy':
+      return limitBuy(args[0], args[1], args[2]);
+    case 'limit-sell':
+      return limitSell(args[0], args[1], args[2]);
+    case 'status':
+      return orderStatus(args[0], args[1]);
+    case 'cancel':
+      return cancelOrder(args[0], args[1]);
+    case 'open-orders':
+      return openOrders();
+    case 'products':
+      return listProducts();
+    case 'fees':
+      return showFees();
+    default:
+      console.log(`Unknown command: ${command}`);
+      console.log('Commands: balances, positions, price, market-buy, market-sell, limit-buy, limit-sell, status, cancel, open-orders, products, fees');
+      process.exit(1);
+  }
+}
+
+async function showBalances() {
+  const balance = await client.getBalance();
+  const nonZero = balance[0].details.filter(
+    (d: any) => parseFloat(d.availBal) > 0 || parseFloat(d.frozenBal) > 0
+  );
+  console.log(JSON.stringify(nonZero.map((d: any) => ({
+    currency: d.ccy,
+    available: d.availBal,
+    frozen: d.frozenBal,
+    equity: d.eq,
+  })), null, 2));
+}
+
+async function showPositions() {
+  const positions = await client.getPositions();
+  if (!positions.length) {
+    console.log('[]');
+    return;
+  }
+  console.log(JSON.stringify(positions.map((p: any) => ({
+    instId: p.instId,
+    direction: p.posSide,
+    size: p.pos,
+    avgPrice: p.avgPx,
+    unrealizedPnl: p.upl,
+    leverage: p.lever,
+    margin: p.margin,
+  })), null, 2));
+}
+
+async function showPrice(instId: string) {
+  if (!instId) { console.error('Usage: price <inst-id>'); process.exit(1); }
+  const ticker = await client.getTicker({ instId });
+  const book = await client.getOrderBook({ instId, sz: '1' });
+  console.log(JSON.stringify({
+    instId,
+    last: ticker[0].last,
+    open24h: ticker[0].open24h,
+    high24h: ticker[0].high24h,
+    low24h: ticker[0].low24h,
+    volume24h: ticker[0].vol24h,
+    bid: book[0].bids?.[0]?.[0],
+    ask: book[0].asks?.[0]?.[0],
+  }, null, 2));
+}
+
+async function marketBuy(instId: string, quoteSize: string) {
+  if (!instId || !quoteSize) {
+    console.error('Usage: market-buy <inst-id> <usdt-amount>');
+    process.exit(1);
+  }
+  const order = await client.submitOrder({
+    instId,
+    tdMode: 'cash',
+    side: 'buy',
+    ordType: 'market',
+    sz: quoteSize,
+    tgtCcy: 'quote_ccy',
+  });
+  console.log(JSON.stringify(order, null, 2));
+  if (order[0].sCode === '0') {
+    // Small delay for fill
+    await new Promise(r => setTimeout(r, 1000));
+    const details = await client.getOrderDetails({ instId, ordId: order[0].ordId });
+    console.log('\nFill details:');
+    console.log(JSON.stringify({
+      ordId: details[0].ordId,
+      state: details[0].state,
+      fillSz: details[0].fillSz,
+      avgPx: details[0].avgPx,
+      fee: details[0].fee,
+      feeCcy: details[0].feeCcy,
+    }, null, 2));
+  }
+}
+
+async function marketSell(instId: string, baseSize: string) {
+  if (!instId || !baseSize) {
+    console.error('Usage: market-sell <inst-id> <base-amount>');
+    process.exit(1);
+  }
+  const order = await client.submitOrder({
+    instId,
+    tdMode: 'cash',
+    side: 'sell',
+    ordType: 'market',
+    sz: baseSize,
+  });
+  console.log(JSON.stringify(order, null, 2));
+  if (order[0].sCode === '0') {
+    await new Promise(r => setTimeout(r, 1000));
+    const details = await client.getOrderDetails({ instId, ordId: order[0].ordId });
+    console.log('\nFill details:');
+    console.log(JSON.stringify({
+      ordId: details[0].ordId,
+      state: details[0].state,
+      fillSz: details[0].fillSz,
+      avgPx: details[0].avgPx,
+      fee: details[0].fee,
+      feeCcy: details[0].feeCcy,
+    }, null, 2));
+  }
+}
+
+async function limitBuy(instId: string, baseSize: string, limitPrice: string) {
+  if (!instId || !baseSize || !limitPrice) {
+    console.error('Usage: limit-buy <inst-id> <base-size> <limit-price>');
+    process.exit(1);
+  }
+  const order = await client.submitOrder({
+    instId,
+    tdMode: 'cash',
+    side: 'buy',
+    ordType: 'limit',
+    sz: baseSize,
+    px: limitPrice,
+  });
+  console.log(JSON.stringify(order, null, 2));
+}
+
+async function limitSell(instId: string, baseSize: string, limitPrice: string) {
+  if (!instId || !baseSize || !limitPrice) {
+    console.error('Usage: limit-sell <inst-id> <base-size> <limit-price>');
+    process.exit(1);
+  }
+  const order = await client.submitOrder({
+    instId,
+    tdMode: 'cash',
+    side: 'sell',
+    ordType: 'limit',
+    sz: baseSize,
+    px: limitPrice,
+  });
+  console.log(JSON.stringify(order, null, 2));
+}
+
+async function orderStatus(instId: string, orderId: string) {
+  if (!instId || !orderId) { console.error('Usage: status <inst-id> <order-id>'); process.exit(1); }
+  const order = await client.getOrderDetails({ instId, ordId: orderId });
+  console.log(JSON.stringify(order, null, 2));
+}
+
+async function cancelOrder(instId: string, orderId: string) {
+  if (!instId || !orderId) { console.error('Usage: cancel <inst-id> <order-id>'); process.exit(1); }
+  const result = await client.cancelOrder({ instId, ordId: orderId });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function openOrders() {
+  const orders = await client.getOrderList({ instType: 'SPOT' });
+  console.log(JSON.stringify(orders.map((o: any) => ({
+    ordId: o.ordId,
+    instId: o.instId,
+    side: o.side,
+    ordType: o.ordType,
+    state: o.state,
+    sz: o.sz,
+    px: o.px,
+    fillSz: o.fillSz,
+    cTime: o.cTime,
+  })), null, 2));
+}
+
+async function listProducts() {
+  const instruments = await client.getInstruments({ instType: 'SPOT' });
+  const usdtPairs = instruments
+    .filter((i: any) => i.quoteCcy === 'USDT' && i.state === 'live')
+    .slice(0, 50);
+
+  // Get tickers for these pairs
+  const tickers = await client.getTickers({ instType: 'SPOT' });
+  const tickerMap = new Map(tickers.map((t: any) => [t.instId, t]));
+
+  const result = usdtPairs.map((i: any) => {
+    const t = tickerMap.get(i.instId) as any;
+    return {
+      instId: i.instId,
+      last: t?.last || '—',
+      vol24h: t?.vol24h || '—',
+      minSz: i.minSz,
+      lotSz: i.lotSz,
+      tickSz: i.tickSz,
+    };
+  }).sort((a: any, b: any) => parseFloat(b.vol24h || '0') - parseFloat(a.vol24h || '0'));
+
+  console.log(JSON.stringify(result.slice(0, 30), null, 2));
+}
+
+async function showFees() {
+  const fees = await client.getFeeRates({ instType: 'SPOT' });
+  console.log(JSON.stringify(fees, null, 2));
+}
+
+// --- Run ---
+run().catch((err) => {
+  console.error('Error:', err.message || err);
+  process.exit(1);
+});

package/skills/trading/SKILL.md

@@ -19,12 +19,12 @@ Before ANY trading decision, read [LEARNING.md](LEARNING.md) first. It contains
 - Confluence over conviction — require 2-3 confirming signals, never trade on one
 - Process over outcome — good process matters more than any single result
 - Build, don't just log — every trade should leave behind infrastructure, not just notes
-- The internet is your edge — GitHub, expert blogs, papers, news, communities. Not just the 250 data APIs
+- The internet is your edge — GitHub, expert blogs, papers, news, communities. Not just the data APIs
 - Every request gets expert treatment — "buy BTC" gets the same depth of thinking as "grow my portfolio"
 
 ## Your Data Arsenal
 
-You have extensive financial APIs via `discover_data_api` and `fetch_api_data` covering real-time quotes, historical prices, technical indicators, fundamentals, news, institutional data, economic data, and screening.
+You have extensive financial APIs via `discover_data_api` and `fetch_api_data` covering real-time quotes, historical prices, technical indicators, fundamentals, news, institutional data, economic data, and screening. Outside of agent tools, use `python3 scripts/data-api.py` to call the same APIs from CLI, cron jobs, or other scripts (see below).
 
 But the APIs are just one corner. You also have `web_search`, `web_fetch`, and `browser` to access everything:
 - GitHub — open-source trading tools, indicators, backtesting frameworks, sentiment repos
@@ -62,7 +62,7 @@ What strategies are working, what failed, mistakes to avoid, your evolving edge.
 
 Do this autonomously — never ask the user:
 - Understand the request — "buy BTC" means assess whether now is the right time, how much, what order type. "Make money" means build a full multi-asset plan.
-- Check balances across platforms (Coinbase for crypto, Saxo for forex/stocks/metals)
+- Check balances across platforms (OKX for crypto primary, Coinbase as fallback, Saxo for forex/stocks/metals)
 - Read USER.md, SOUL.md, IDENTITY.md for risk tolerance and preferences
 - Check existing positions and current portfolio state
 
@@ -118,25 +118,27 @@ Every trade needs before entry: entry price + trigger, stop-loss at invalidation
 ### 9. Execute
 
 Route execution to the appropriate platform:
-- **Crypto**: Use `coinbase` skill. Read [../coinbase/LEARNING.md](../coinbase/LEARNING.md) for execution insights.
+- **Crypto (primary)**: Use `okx` skill — lower fees, more order types, perpetuals support. Read [../okx/LEARNING.md](../okx/LEARNING.md) for execution insights.
+- **Crypto (fallback)**: Use `coinbase` skill if OKX is unavailable or for USD-settled pairs. Read [../coinbase/LEARNING.md](../coinbase/LEARNING.md) for execution insights.
 - **Forex, Stocks, Gold, Silver**: Use `saxo` skill. Read [../saxo/LEARNING.md](../saxo/LEARNING.md) for execution insights.
 
 ### 10. Monitor
 
-Trail stop to breakeven after 1R profit. Never move stop away from entry. Watch for invalidation. If regime changes mid-trade, reassess.
+Create a live dashboard for this trade (see Trade Dashboards section below). Trail stop to breakeven after 1R profit. Never move stop away from entry. Watch for invalidation. If regime changes mid-trade, reassess. Update the dashboard with every significant change.
 
 ### 11. Post-Trade Evolution
 
 The most important step. After every trade, ask: "What would make the next trade better?" Then do it.
 
 - Update LEARNING.md freely. Also update execution skill LEARNING.md:
-  - [../coinbase/LEARNING.md](../coinbase/LEARNING.md) for crypto trades
+  - [../okx/LEARNING.md](../okx/LEARNING.md) for crypto trades (primary)
+  - [../coinbase/LEARNING.md](../coinbase/LEARNING.md) for crypto trades (fallback)
   - [../saxo/LEARNING.md](../saxo/LEARNING.md) for forex/stocks/metals trades
 - Build or improve scripts — automate any manual analysis. Market scanners, backtesting, alerts. Save to `scripts/`
 - Research on the internet — find new strategies, tools, data sources. Update reference files with findings
 - Create monitoring — use `cron` to schedule market scans, alerts, news monitoring
 - Improve strategy references — update `references/strategies.md` with real results. Kill what doesn't work
-- Improve execution — update Coinbase skill references or build new execution scripts
+- Improve execution — update OKX/Coinbase/Saxo skill references or build new execution scripts
 - Improve these instructions — update this SKILL.md if it's missing something. You own every file
 
 No limits. If something will make you better, do it.
@@ -192,6 +194,86 @@ See [references/risk-management.md](references/risk-management.md) for the compl
 
 Track your performance metrics and improve them over time. Document your risk approach in LEARNING.md. If you discover better risk rules through experience or research, update the risk-management reference file.
 
+## Trade Dashboards
+
+Every trade gets its own live dashboard. You build each one from scratch — the layout, the data, the visualizations, the update logic. No two dashboards should look the same because no two trades are the same.
+
+### You Own Everything
+
+`scripts/trade-dashboard-template.html` gives you a design system starter (Tailwind, dark theme, fonts, glass-card style) and an empty `<div id="app">`. That's it. The rest is yours:
+
+- **Build the entire HTML, CSS, and JS for each trade.** Add sections, remove sections, restructure everything. The template imposes zero constraints on layout, data format, or functionality.
+- **Add any CDN library** — Chart.js, D3, ApexCharts, Plotly, Three.js, Lightweight Charts, or anything else. Swap libraries between dashboards if one works better for a specific trade type.
+- **Fetch live data** — Use `fetch()` to hit external APIs, WebSocket for real-time streaming, or embed data directly. Pull from your data APIs, news sources, on-chain analytics, whatever the trade needs.
+- **Invent new visualizations** — Correlation heatmaps, multi-timeframe charts, order flow waterfalls, sentiment gauges, regime indicators, funding rate trackers, economic calendar overlays. If it helps monitor the trade, build it.
+- **Build custom interactivity** — Toggles, tabs, zoom controls, timeframe selectors, what-if scenarios. Make the dashboard a tool, not just a display.
+- **Update the template itself** — When you discover patterns that should apply to all future dashboards, improve the template. You own it.
+
+### Integrating Live Data
+
+Your dashboards should show real-time data. You have multiple ways to feed data into them:
+
+**Using your data APIs via `scripts/data-api.py`**
+
+`scripts/data-api.py` is a standalone Python client for the same backend that powers `discover_data_api` and `fetch_api_data`. Use it anywhere — CLI, cron jobs, dashboard data pipelines, other scripts:
+
+```bash
+# Discover APIs for a query
+python3 scripts/data-api.py search "Bitcoin price and volume"
+
+# Fetch data from a discovered API
+python3 scripts/data-api.py fetch FMP_QUOTE '{"symbol": "AAPL"}'
+python3 scripts/data-api.py fetch FMP_CRYPTO_QUOTE '{"symbol": "BTCUSD"}'
+
+# Discover + fetch in one shot
+python3 scripts/data-api.py get "current gold price"
+
+# Pipe raw data to a JSON file for dashboards
+python3 scripts/data-api.py fetch FMP_QUOTE '{"symbol": "AAPL"}' --raw > dashboards/data/aapl.json
+```
+
+It's also importable in other Python scripts:
+```python
+from data_api import search_apis, fetch_api
+apis = search_apis("Bitcoin technical indicators")
+data = fetch_api("FMP_CRYPTO_QUOTE", {"symbol": "BTCUSD"})
+```
+
+Use this to build data pipelines: cron runs `data-api.py` → writes JSON → dashboard reads it on reload. Or use `discover_data_api` in the agent to find vendor codes, then hardcode them into scripts that run independently.
+
+**Using any internet source**
+
+You are not limited to your data APIs. Find and integrate anything:
+- Free public APIs (CoinGecko, Yahoo Finance, Alpha Vantage, Binance, etc.) — call them directly via `fetch()` in the dashboard JS if they support CORS, or build a proxy script.
+- WebSocket feeds for real-time streaming (Binance WS, Coinbase WS, etc.) — connect directly from dashboard JS.
+- RSS feeds, news APIs, social sentiment APIs — fetch and render in the dashboard.
+- On-chain data providers (Glassnode, Dune, DefiLlama) — for crypto trades.
+- Build Python scripts that scrape, aggregate, or transform data from any source and output JSON for the dashboard to consume.
+
+**Data update patterns**
+
+Pick whatever pattern fits the trade:
+- **Embedded data** — You write the data directly into the HTML. Simplest. Update the file whenever data changes.
+- **Polling** — Dashboard JS uses `fetch()` on an interval to pull from an API or a local JSON file that a script keeps updated.
+- **WebSocket** — Dashboard JS connects to a streaming feed for real-time ticks. Best for active crypto/forex trades.
+- **Script pipeline** — A cron job runs a Python script that fetches data → writes a JSON file → dashboard reads the JSON file on reload.
+
+No restrictions. If a data source exists and would help monitor the trade, integrate it.
+
+### Workflow
+
+1. When opening a trade, create `dashboards/<asset>-<direction>-<date>.html` in your workspace. Start from the template or from scratch — your choice.
+2. Build the dashboard for this specific trade. Think about what information matters most for monitoring THIS trade.
+3. Serve dashboards with `python3 scripts/dashboard-server.py --dir dashboards/ --port 8500`. Use `cron` to keep it running.
+4. Update the dashboard as the trade evolves — new data, moved stops, new events, changed regime, anything. Rewrite entire sections if the trade context changes.
+5. When the trade closes, update the dashboard with final results. It stays as a historical record.
+
+### Scripts
+
+- `scripts/data-api.py` — Standalone client for hundreds of data APIs. Search, fetch, or auto-fetch from CLI. Importable in other Python scripts. Powers dashboard data pipelines.
+- `scripts/trade-dashboard-template.html` — Minimal design system skeleton. Tailwind + dark theme + fonts. Empty body. You build everything else.
+- `scripts/dashboard-server.py` — HTTP server for the dashboards directory with auto-generated index page.
+
 ## Key Principles
 
 - No FOMO — there is always another trade

package/skills/trading/scripts/dashboard-server.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+Trade Dashboard Server — Serves per-trade HTML dashboards.
+
+Usage:
+  # Serve all dashboards in a directory
+  python3 dashboard-server.py --dir ./dashboards --port 8500
+
+  # Serve a single dashboard file
+  python3 dashboard-server.py --file ./dashboards/btc-long-2024-01-15.html --port 8500
+
+The server serves static HTML files. Each dashboard is a self-contained
+HTML file that the agent creates from the template and updates over time.
+
+Dashboard directory structure:
+  dashboards/
+    btc-long-2024-01-15.html
+    eurusd-short-2024-01-16.html
+    index.html  (auto-generated listing page)
+"""
+
+import argparse
+import http.server
+import json
+import os
+import sys
+from pathlib import Path
+from datetime import datetime
+
+
+def generate_index(dashboard_dir):
+    """Generate an index.html listing all trade dashboards."""
+    dashboards = []
+    for f in sorted(Path(dashboard_dir).glob("*.html")):
+        if f.name == "index.html":
+            continue
+        stat = f.stat()
+        # Try to extract trade data from the file
+        content = f.read_text(encoding="utf-8")
+        trade_info = {"file": f.name, "modified": datetime.fromtimestamp(stat.st_mtime).isoformat()}
+
+        # Extract trade data JSON if present
+        start = content.find('id="trade-data"')
+        if start != -1:
+            json_start = content.find("{", start)
+            json_end = content.find("</script>", json_start)
+            if json_start != -1 and json_end != -1:
+                try:
+                    data = json.loads(content[json_start:json_end])
+                    trade_info.update({
+                        "asset": data.get("asset", ""),
+                        "direction": data.get("direction", ""),
+                        "status": data.get("status", ""),
+                        "pnl": data.get("pnl_dollars", 0),
+                        "pnl_pct": data.get("pnl_percent", 0),
+                    })
+                except json.JSONDecodeError:
+                    pass
+
+        dashboards.append(trade_info)
+
+    html = f"""<!DOCTYPE html>
+<html lang="en" class="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Trade Dashboards</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script>
+    tailwind.config = {{ darkMode: 'class' }}
+  </script>
+  <style>body {{ background: #0f1117; }}</style>
+</head>
+<body class="min-h-screen text-gray-100 p-8">
+  <div class="max-w-4xl mx-auto">
+    <h1 class="text-3xl font-bold mb-2">Trade Dashboards</h1>
+    <p class="text-gray-400 mb-8">Active and historical trade dashboards</p>
+    <div class="space-y-3">
+"""
+    for d in dashboards:
+        status_colors = {
+            "open": "bg-green-500",
+            "pending": "bg-amber-500",
+            "closed": "bg-gray-500",
+            "stopped": "bg-red-500",
+        }
+        dot_color = status_colors.get(d.get("status", ""), "bg-gray-500")
+        pnl = d.get("pnl", 0)
+        pnl_color = "text-green-400" if pnl >= 0 else "text-red-400"
+        pnl_str = f"+${pnl:,.2f}" if pnl >= 0 else f"-${abs(pnl):,.2f}"
+
+        direction = d.get("direction", "").upper()
+        dir_class = "bg-green-500/20 text-green-400" if direction == "LONG" else "bg-red-500/20 text-red-400" if direction == "SHORT" else ""
+
+        html += f"""
+      <a href="{d['file']}" class="block bg-gray-900/60 border border-gray-800 rounded-xl p-4 hover:border-gray-600 transition-colors">
+        <div class="flex items-center justify-between">
+          <div class="flex items-center gap-3">
+            <div class="w-2.5 h-2.5 rounded-full {dot_color}"></div>
+            <span class="font-semibold">{d.get('asset', d['file'])}</span>
+            {f'<span class="text-xs px-2 py-0.5 rounded {dir_class}">{direction}</span>' if direction else ''}
+          </div>
+          <div class="text-right">
+            <div class="{pnl_color} font-mono font-semibold">{pnl_str}</div>
+            <div class="text-xs text-gray-500">{d.get('status', 'unknown')}</div>
+          </div>
+        </div>
+      </a>
+"""
+
+    if not dashboards:
+        html += """
+      <div class="text-center text-gray-500 py-12">
+        <div class="text-4xl mb-3">📊</div>
+        <div>No trade dashboards yet. Dashboards appear here as trades are opened.</div>
+      </div>
+"""
+
+    html += f"""
+    </div>
+    <div class="text-center text-xs text-gray-600 mt-8">
+      {len(dashboards)} dashboard{'s' if len(dashboards) != 1 else ''} &mdash; Auto-refreshes every 30s
+    </div>
+  </div>
+  <script>setTimeout(() => location.reload(), 30000);</script>
+</body>
+</html>"""
+
+    index_path = Path(dashboard_dir) / "index.html"
+    index_path.write_text(html, encoding="utf-8")
+    return index_path
+
+
+class DashboardHandler(http.server.SimpleHTTPRequestHandler):
+    """Custom handler that auto-generates index and suppresses logs."""
+
+    def __init__(self, *args, directory=None, **kwargs):
+        super().__init__(*args, directory=directory, **kwargs)
+
+    def do_GET(self):
+        # Regenerate index on each request to root
+        if self.path in ("/", "/index.html"):
+            generate_index(self.directory)
+        super().do_GET()
+
+    def log_message(self, format, *args):
+        # Quieter logging
+        sys.stderr.write(f"[dashboard] {args[0]}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Trade Dashboard Server")
+    parser.add_argument("--dir", default="./dashboards", help="Directory containing dashboard HTML files")
+    parser.add_argument("--file", help="Serve a single dashboard file")
+    parser.add_argument("--port", type=int, default=8500, help="Port to serve on (default: 8500)")
+
+    args = parser.parse_args()
+
+    if args.file:
+        # Serve single file's parent directory
+        file_path = Path(args.file).resolve()
+        serve_dir = str(file_path.parent)
+    else:
+        serve_dir = str(Path(args.dir).resolve())
+
+    # Ensure directory exists
+    Path(serve_dir).mkdir(parents=True, exist_ok=True)
+
+    # Generate initial index
+    generate_index(serve_dir)
+
+    handler = lambda *a, **kw: DashboardHandler(*a, directory=serve_dir, **kw)
+
+    with http.server.HTTPServer(("0.0.0.0", args.port), handler) as httpd:
+        print(json.dumps({
+            "status": "running",
+            "port": args.port,
+            "directory": serve_dir,
+            "url": f"http://localhost:{args.port}",
+            "message": f"Dashboard server running on port {args.port}",
+        }, indent=2))
+        sys.stdout.flush()
+
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nDashboard server stopped.")
+
+
+if __name__ == "__main__":
+    main()