A Binance-first crypto trading CLI for balances, market data, opportunity scanning, and execution.
---
## Install
```bash
pip install -e ".[dev]"
coinhunter --help
```
## Initialize runtime
```bash
coinhunter init
coinhunter init --force
```
This creates:
- `~/.coinhunter/config.toml`
- `~/.coinhunter/.env`
- `~/.coinhunter/logs/`
`config.toml` stores runtime and strategy settings. `.env` stores:
```bash
BINANCE_API_KEY=
BINANCE_API_SECRET=
```
Override the default home directory with `COINHUNTER_HOME`.
## Commands
```bash
# Account
coinhunter account overview
coinhunter account balances --spot --futures
coinhunter account positions --spot
# Market
coinhunter market tickers BTCUSDT ETH/USDT sol-usdt
coinhunter market klines BTCUSDT ETHUSDT --interval 1h --limit 50
# Trade (Spot)
coinhunter trade spot buy BTCUSDT --quote 100 --dry-run
coinhunter trade spot sell BTCUSDT --qty 0.01 --type limit --price 90000
# Trade (Futures)
coinhunter trade futures buy BTCUSDT --qty 0.01 --dry-run
coinhunter trade futures sell BTCUSDT --qty 0.01 --reduce-only
coinhunter trade futures close BTCUSDT
# Opportunities
coinhunter opportunity portfolio
coinhunter opportunity scan
coinhunter opportunity scan --symbols BTCUSDT ETHUSDT SOLUSDT
```
## Architecture
CoinHunter V2 uses a flat, direct architecture:
| Layer | Responsibility | Key Files |
|-------|----------------|-----------|
| **CLI** | Single entrypoint, argument parsing | `cli.py` |
| **Binance** | Thin API wrappers with unified error handling | `binance/spot_client.py`, `binance/um_futures_client.py` |
| **Services** | Domain logic | `services/account_service.py`, `services/market_service.py`, `services/trade_service.py`, `services/opportunity_service.py` |
| **Config** | TOML config, `.env` secrets, path resolution | `config.py` |
| **Runtime** | Paths, JSON helpers | `runtime.py` |
| **Audit** | Structured JSONL logging | `audit.py` |
## Logging
Audit logs are written to:
```text
~/.coinhunter/logs/audit_YYYYMMDD.jsonl
```
Events include:
- `trade_submitted`
- `trade_filled`
- `trade_failed`
- `opportunity_portfolio_generated`
- `opportunity_scan_generated`
## Development
```bash
pytest tests/ # run tests
ruff check src tests # lint
mypy src # type check
```