coinhunter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development commands

• Install (dev): pip install -e ".[dev]" or conda env create -f environment.yml && conda activate coinhunter
• Run CLI locally: python -m coinhunter --help
• Run tests: pytest or python -m pytest tests/
• Run single test file: pytest tests/test_cli.py -v
• Lint: ruff check src tests
• Format: ruff format src tests
• Type-check: mypy src

Architecture

CoinHunter V2 is a Binance-first crypto trading CLI with a flat, direct architecture:

• src/coinhunter/cli.py — Single entrypoint (main()). Uses argparse to parse commands and directly dispatches to service functions. There is no separate commands/ adapter layer. Top-level commands include init, config, account, market, buy, sell, portfolio, opportunity, strategy, backtest, catlog, upgrade, and completion.
• src/coinhunter/services/ — Contains all domain logic:
  • account_service.py — balances, positions, overview
  • market_service.py — tickers, klines, scan universe, symbol normalization
  • signal_service.py — shared market signal scoring used by scan and portfolio analysis
  • portfolio_service.py — held-position review and add/hold/trim/exit recommendations
  • trade_service.py — spot order execution only
  • opportunity_service.py — market scanning and entry/watch/skip recommendations
  • opportunity_dataset_service.py — historical kline dataset collection for backtesting
  • opportunity_evaluation_service.py — walk-forward evaluation and model-weight optimization
  • research_service.py — external research signal providers for opportunity scoring
  • strategy_service.py — combines opportunity scanning and portfolio analysis into unified buy/sell/hold trade signals
  • backtest_service.py — walk-forward backtest engine using historical kline datasets with virtual cash and positions
• src/coinhunter/binance/spot_client.py — Thin wrapper around binance.spot.Spot. Normalizes request errors into RuntimeError and handles single/multi-symbol ticker responses.
• src/coinhunter/config.py — load_config(), get_binance_credentials(), ensure_init_files().
• src/coinhunter/runtime.py — RuntimePaths, get_runtime_paths(), print_json().
• src/coinhunter/audit.py — Writes JSONL audit events to dated files.

Runtime and environment

User data lives in ~/.coinhunter/ by default (override with COINHUNTER_HOME):

• config.toml — runtime, binance, trading, signal, opportunity, and portfolio settings
• .env — BINANCE_API_KEY and BINANCE_API_SECRET
• logs/audit_YYYYMMDD.jsonl — structured audit log
• logs/dry-run/audit_YYYYMMDD.jsonl — dry-run audit log

Run coinhunter init to generate the config and env templates.

Key conventions

• Symbol normalization: market_service.normalize_symbol() strips /, -, _, and uppercases the symbol. CLI inputs like ETH/USDT, eth-usdt, and ETHUSDT are all normalized to ETHUSDT.
• Dry-run behavior: Trade commands support --dry-run. If omitted, the default falls back to trading.dry_run_default in config.toml.
• Client injection: Service functions accept spot_client as a keyword argument. This enables easy unit testing with mocks.
• Error handling: spot_client.py catches requests.exceptions.SSLError and RequestException and re-raises as human-readable RuntimeError. The CLI catches all exceptions in main() and prints error: {message} to stderr with exit code 1.
• Ticker API fallback: spot_client.ticker_stats() uses rolling_window_ticker for symbol-specific queries and ticker_24hr for full-market scans (no symbols).
• Output modes: All commands support --agent for JSON output and --doc to print the command's output schema.

Testing

Tests live in tests/ and use unittest.TestCase with unittest.mock.patch. The test suite covers:

• test_cli.py — parser smoke tests and dispatch behavior
• test_config_runtime.py — config loading, env parsing, path resolution
• test_account_market_services.py — balance/position/ticker/klines logic with mocked clients
• test_trade_service.py — spot trade execution paths
• test_opportunity_service.py — portfolio and scan scoring logic
• test_opportunity_dataset_service.py — dataset collection and walk-forward evaluation
• test_opportunity_evaluation_service.py — model weight optimization
• test_strategy_service.py — combined signal generation logic
• test_backtest_service.py — historical backtest engine

Notes

• AGENTS.md in this repo is stale and describes a prior V1 architecture (commands/, smart executor, precheck, review engine). Do not rely on it.