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

gateway/knowledge/api-reference.md

@@ -247,6 +247,63 @@ class DataAPI(ABC):
         """
         pass
 
+    @abstractmethod
+    async def get_ticker_24h(
+        self,
+        exchange: str,
+        limit: Optional[int] = None,
+        min_std_quote_volume: Optional[float] = None,
+        market_type: Optional[str] = None,
+        base_asset_contains: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Retrieve 24h rolling market stats for all symbols on an exchange.
+
+        Data is refreshed hourly by the ingestor pipeline. Use this to build a
+        pre-filtered symbol universe before running a scanner — it avoids requesting
+        per-symbol OHLC data for thousands of symbols.
+
+        Args:
+            exchange: Exchange name (e.g., "BINANCE", "COINBASE", "KRAKEN")
+            limit: If set, return only the Top N symbols By Volume. None = return all.
+            min_std_quote_volume: Exclude symbols with USD volume below this threshold.
+            market_type: Filter by market type: "spot" or "perp". None = return all.
+            base_asset_contains: Filter to symbols whose base asset contains this string
+                                  (case-insensitive). E.g., "BTC" matches "BTC/USDT".
+
+        Returns:
+            DataFrame sorted by std_quote_volume descending (NULLs last). Columns:
+            - ticker: Full ticker (e.g., "BTC/USDT.BINANCE")
+            - exchange_id: Exchange name
+            - base_asset: Base currency (e.g., "BTC")
+            - quote_asset: Quote currency (e.g., "USDT")
+            - last_price: Last traded price in quote currency
+            - price_change_pct: 24h price change as percentage (e.g. 2.5 = +2.5%)
+            - quote_volume_24h: Raw 24h volume in quote asset
+            - std_quote_volume: quote_volume_24h normalized to USD (NaN if conversion unknown)
+            - bid_price, ask_price: Current best bid/ask (NaN if not provided by exchange)
+            - open_24h, high_24h, low_24h: 24h OHLC prices (NaN if not provided)
+            - volume_24h: Base-asset volume (NaN if not provided)
+            - num_trades: 24h trade count (NaN if not provided)
+            - timestamp_ms: Snapshot timestamp in milliseconds
+
+            Returns empty DataFrame if no data is available (e.g., not yet fetched).
+
+        Examples:
+            # Top 50 most liquid Binance spot symbols
+            df = await api.data.get_ticker_24h("BINANCE", limit=50, market_type="spot")
+
+            # All BTC pairs with at least $10M daily volume
+            df = await api.data.get_ticker_24h("BINANCE",
+                                                base_asset_contains="BTC",
+                                                min_std_quote_volume=10_000_000)
+
+            # Build a scanner universe: all Binance symbols, sorted by volume
+            universe = await api.data.get_ticker_24h("BINANCE")
+            top_100 = universe.head(100)["ticker"].tolist()
+        """
+        pass
+
 ```
 
 

gateway/knowledge/usage-examples.md

@@ -92,6 +92,61 @@ All columns below are fully populated for Binance data. Other exchanges provide
 - `"ticker"` - Market identifier
 - `"period_seconds"` - Period in seconds
 
+## Building a Scanner Universe with get_ticker_24h
+
+**Always pre-filter symbols before fetching OHLC data for scanners.** Fetching OHLC for all ~1800 Binance symbols would exhaust the 2M-bar per-script budget instantly. Use `get_ticker_24h` to get a ranked list of all symbols for free (no OHLC budget cost), then run per-symbol analysis only on the filtered set.
+
+```python
+from dexorder.api import get_api
+import asyncio
+
+api = get_api()
+
+# Get top 50 most liquid Binance spot symbols (no OHLC budget used)
+universe = asyncio.run(api.data.get_ticker_24h(
+    "BINANCE",
+    limit=50,
+    market_type="spot",
+    min_std_quote_volume=10_000_000  # $10M+ daily volume
+))
+print(f"Universe: {len(universe)} symbols")
+print(universe[["ticker", "std_quote_volume", "price_change_pct"]].head(10))
+
+# Now fetch OHLC only for these symbols
+tickers = universe["ticker"].tolist()
+results = {}
+for ticker in tickers:
+    df = asyncio.run(api.data.historical_ohlc(
+        ticker=ticker,
+        period_seconds=3600,
+        start_time="2024-01-01",
+        end_time="2025-01-01",
+        extra_columns=["volume"]
+    ))
+    print(f"[Data] {ticker}: {len(df)} bars")
+    results[ticker] = df
+```
+
+### get_ticker_24h filter parameters
+
+```python
+# All BTC pairs on Binance (spot + perp)
+df = asyncio.run(api.data.get_ticker_24h("BINANCE", base_asset_contains="BTC"))
+
+# Top 100 perp markets with at least $50M daily volume
+df = asyncio.run(api.data.get_ticker_24h(
+    "BINANCE",
+    limit=100,
+    market_type="perp",
+    min_std_quote_volume=50_000_000
+))
+
+# All Coinbase symbols (for a cross-exchange scan)
+df = asyncio.run(api.data.get_ticker_24h("COINBASE"))
+```
+
+The returned DataFrame is sorted by `std_quote_volume` (USD-normalized volume) descending. Symbols without a USD conversion path have `std_quote_volume = NaN` and appear last. 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`.
+
 ## Using the Charting API
 
 The charting API provides styled financial charts with OHLC candlesticks and technical indicators.