Scripts and How to Use Them

This file documents the main scripts in the repository and their purpose, typical runtime parameters, and key notes.

list_coins.py
- Purpose: Fetches asset metadata from Hyperliquid (name and size/precision) and saves `_data/coin_precision.json`.
- Usage: `python list_coins.py`
- Notes: Reads `hyperliquid.info.Info` and writes a JSON file. Useful to run before market feeders.

market.py (MarketDataFeeder)
- Purpose: Fetches live prices from Hyperliquid and writes `_data/current_prices.json` while printing a live table.
- Usage: `python market.py --log-level normal`
- Notes: Expects `_data/coin_precision.json` to exist.

data_fetcher.py (CandleFetcherDB)
- Purpose: Fetches historical 1m candles and stores them in `_data/market_data.db` using a table-per-coin naming convention.
- Usage: `python data_fetcher.py --coins BTC ETH --interval 1m --days 7`
- Notes: Can be run regularly by a scheduler to keep the DB up to date.

resampler.py (Resampler)
- Purpose: Reads 1m candles from SQLite and resamples to configured timeframes (e.g. 5m, 15m, 1h), appending new candles to tables.
- Usage: `python resampler.py --coins BTC ETH --timeframes 5m 15m 1h --log-level normal`

market_cap_fetcher.py (MarketCapFetcher)
- Purpose: Pulls CoinGecko market cap numbers and maintains historical daily tables in the same SQLite DB.
- Usage: `python market_cap_fetcher.py --coins BTC ETH --log-level normal`
- Notes: Optional `COINGECKO_API_KEY` in `.env` avoids throttling.

strategy_sma_cross.py (SmaCrossStrategy)
- Purpose: Run an SMA-based trading strategy. Reads candles from `_data/market_data.db` and writes status to `_data/strategy_status_<name>.json`.
- Usage: `python strategy_sma_cross.py --name sma_cross_1 --params '{"coin":"BTC","timeframe":"1m","fast":5,"slow":20}' --log-level normal`

trade_executor.py (TradeExecutor)
- Purpose: Orchestrates agent-based order execution using agent private keys found in environment variables. Uses `_data/strategies.json` to determine active strategies.
- Usage: `python trade_executor.py --log-level normal`
- Notes: Requires `MAIN_WALLET_ADDRESS` and agent keys. See `create_agent.py` to authorize agents on-chain.

create_agent.py
- Purpose: Authorizes a new on-chain agent using your main wallet (requires `MAIN_WALLET_PRIVATE_KEY`).
- Usage: `python create_agent.py`
- Notes: Prints the new agent private key to stdout — save it securely.

trade_log.py
- Purpose: Provides a thread-safe CSV trade history logger. Used by the executor and strategies to record actions.

Other utility scripts
- import_csv.py, fix_timestamps.py, list_coins.py, etc. — see file headers for details.