# 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
  - `trade_service.py` — spot and USDT-M futures order execution
  - `opportunity_service.py` — portfolio recommendations and market scanning
- **`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, and opportunity 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.