hyper/WIKI/SCRIPTS.md

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.