coinhunter-cli/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]"
• 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.
• 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 and USDT-M futures order execution
  • opportunity_service.py — market scanning and entry/watch/skip recommendations
• src/coinhunter/binance/ — Thin wrappers around official Binance connectors:
  • spot_client.py wraps binance.spot.Spot
  • um_futures_client.py wraps binance.um_futures.UMFutures Both normalize request errors into RuntimeError and handle 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

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 / futures_client as keyword arguments. This enables easy unit testing with mocks.
• Error handling: Binance client wrappers catch requests.exceptions.SSLError and RequestException and re-raise as human-readable RuntimeError. The CLI catches all exceptions in main() and prints error: {message} to stderr with exit code 1.

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 and futures trade execution paths
• test_opportunity_service.py — portfolio and scan scoring logic

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.