A Binance-first crypto trading CLI for balances, market data, opportunity scanning, and execution.

---

Install

For end users, install from PyPI with pipx (recommended) to avoid polluting your system Python:

pipx install coinhunter
coinhunter --help

Check the installed version:

coinhunter --version

To update later:

pipx upgrade coinhunter

Initialize runtime

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:

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).

# 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:

~/.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:

git clone https://git.tacitlab.cc/TacitLab/coinhunter-cli.git
cd coinhunter-cli
pip install -e ".[dev]"

Run quality checks:

pytest tests/           # run tests
ruff check src tests     # lint
mypy src                 # type check