A Binance-first crypto trading CLI for balances, market data, opportunity scanning, and execution.
---
## Install
For end users, install from PyPI with [pipx](https://pipx.pypa.io/) (recommended) to avoid polluting your system Python:
```bash
pipx install coinhunter
coinhunter --help
```
Check the installed version:
```bash
coinhunter --version
```
To update later:
```bash
pipx upgrade coinhunter
```
## Initialize runtime
```bash
coinhunter init
coinhunter init --force
```
This creates:
- `~/.coinhunter/config.toml`
- `~/.coinhunter/.env`
- `~/.coinhunter/logs/`
If you are using **zsh** or **bash**, `init` will also generate and install shell completion scripts automatically, and update your rc file (`~/.zshrc` or `~/.bashrc`) if needed.
`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
By default, CoinHunter prints human-friendly TUI tables. Add `--agent` to any command to get JSON output (or compact pipe-delimited tables for large datasets).
```bash
# Account
coinhunter account overview
coinhunter account overview --agent
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
# Self-upgrade
coinhunter upgrade
# Shell completion (manual)
coinhunter completion zsh > ~/.zsh/completions/_coinhunter
coinhunter completion bash > ~/.local/share/bash-completion/completions/coinhunter
```
`upgrade` will try `pipx upgrade coinhunter` first, and fall back to `pip install --upgrade coinhunter` if pipx is not available.
## 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, TUI/JSON/compact output | `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
Clone the repo and install in editable mode:
```bash
git clone https://git.tacitlab.cc/TacitLab/coinhunter-cli.git
cd coinhunter-cli
pip install -e ".[dev]"
```
Run quality checks:
```bash
pytest tests/ # run tests
ruff check src tests # lint
mypy src # type check
```