Add Ticker24h support: hourly market snapshots with USD-normalized volume filtering
This commit is contained in:
@@ -89,7 +89,7 @@ After patching, confirm the change to the user.
|
||||
|
||||
## Symbol Resolution
|
||||
|
||||
Always use `SymbolLookup` to resolve tickers before passing them to research or chart tools. Symbols must be in `SYMBOL.EXCHANGE` format (e.g., `BTC/USDT.BINANCE`). If the user says "ETHUSDT", "ETH", or any ambiguous ticker, resolve it first. If not specified by the user, prefer to use the most prominent exchange available (e.g. BINANCE not KRAKEN)
|
||||
Always use `SymbolLookup` to resolve tickers before passing them to research or chart tools. Symbols must be in `SYMBOL.EXCHANGE` format (e.g., `BTC/USDT.BINANCE`). If the user says "ETHUSDT", "ETH", or any ambiguous ticker, resolve it first. `SymbolLookup` results are sorted by 24h volume descending — pick the top result when the user hasn't specified an exchange.
|
||||
|
||||
## Raw Data Retrieval
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -22,6 +22,7 @@ Available to all agents:
|
||||
| `PythonList` | List existing scripts by category (`strategy`, `indicator`, or `research`) |
|
||||
| `SymbolLookup` | Resolve a ticker to the correct `SYMBOL.EXCHANGE` format |
|
||||
| `GetChartData` | Fetch raw OHLC data (casual retrieval only — use `Spawn` research for analysis) |
|
||||
| `GetTicker24h` | Fetch 24h market stats for all symbols on an exchange, sorted by USD volume — use this to build scanner universes without burning OHLC bar budget |
|
||||
| `WebSearch` | Search the web (Tavily) |
|
||||
| `FetchPage` | Fetch and read a web page or PDF |
|
||||
| `ArxivSearch` | Search arXiv for academic papers |
|
||||
|
||||
Reference in New Issue
Block a user