Add Ticker24h support: hourly market snapshots with USD-normalized volume filtering

gateway/prompt/agent-research.md

@@ -66,6 +66,27 @@ Quick reference — approximate bars per resolution at various windows:
 
 **When to shorten the window**: only if 5 years at the chosen resolution would far exceed 200,000 bars (e.g., 5m over 5 years ≈ 525k → shorten to ~2 years). Otherwise always use the full 5 years.
 
+## Multi-Symbol Analysis
+
+When scanning many symbols, scale the per-symbol time window so total bars stay within the **2,000,000-bar script limit**. The API enforces this — exceeding it raises a `ValueError` with the limit number and suggestions.
+
+Budget rule: `bars_per_symbol ≈ 2,000,000 / num_symbols` (never exceed 200,000 per symbol)
+
+| Symbol count | Recommended period | Approx max window |
+|---|---|---|
+| ≤ 10 | any | 5 years |
+| 10–100 | 1h or coarser | scale to budget |
+| 100–500 | 1d (86400s) | ~1–2 years |
+| 500+ | 1d (86400s) | ≤ 1 year |
+
+**Strategy for large symbol lists**:
+1. **Filter first**: scan all symbols with a short window (90–180 days, daily bars) to rank/screen candidates
+2. **Zoom in**: fetch full history only for the top N (≤ 20) finalists
+3. **Never use intraday periods for > 50 symbols** in one script
+4. **Print progress** every 50 symbols so the output log shows the script is alive
+
+If you hit a `ValueError` about the bar budget, read the limit and suggestions in the error message, then adjust the period or window accordingly.
+
 ## Tool Behavior Notes
 
 - **`PythonWrite` / `PythonEdit` for research**: auto-executes the script and returns all output (stdout, stderr) and captured images. **Do not call `ExecuteResearch` afterward** — the script has already run.
@@ -89,6 +110,30 @@ The API provides two main components:
 
 See the knowledge base sections below for complete API documentation, examples, and the full pandas-ta indicator reference.
 
+### Scanner Pre-filtering with get_ticker_24h
+
+**Before fetching OHLC data for multiple symbols, always build a pre-filtered universe first.**
+
+Scanners must not blindly fetch OHLC for all symbols on an exchange — Binance has ~1800 symbols and the script budget is 2M bars total. Use `api.data.get_ticker_24h()` to get a ranked, filterable list of all symbols without consuming any OHLC budget:
+
+```python
+# Get top 50 most liquid Binance spot symbols by USD volume
+universe = asyncio.run(api.data.get_ticker_24h(
+    "BINANCE",
+    limit=50,
+    market_type="spot",
+    min_std_quote_volume=10_000_000  # $10M+ daily volume
+))
+tickers = universe["ticker"].tolist()
+print(f"Universe: {len(tickers)} symbols")
+
+# Now fetch OHLC only for these symbols
+for ticker in tickers:
+    df = asyncio.run(api.data.historical_ohlc(ticker, period_seconds=3600, ...))
+```
+
+`get_ticker_24h` returns a DataFrame sorted by `std_quote_volume` (USD-normalized) descending, with columns: `ticker`, `exchange_id`, `base_asset`, `quote_asset`, `last_price`, `price_change_pct`, `quote_volume_24h`, `std_quote_volume`, `bid_price`, `ask_price`, `open_24h`, `high_24h`, `low_24h`, `volume_24h`, `num_trades`, `timestamp_ms`. See the full docstring in the knowledge base `api-reference.md`.
+
 ## Technical Indicators — pandas-ta
 
 Use `import pandas_ta as ta` for all indicator calculations. Never write manual rolling/ewm implementations. The full indicator catalog, calling conventions, column naming patterns, and default parameters are in the pandas-ta-reference section of your knowledge base.