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

You can also use the shorter coin alias:

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

Add --doc to any command to see its output schema and field descriptions (great for AI agents):

coin buy --doc
coin market klines --doc

Examples

# Account (aliases: a, acc)
coinhunter account overview
coinhunter account overview --agent
coin a ov
coin acc bal
coin a pos

# Market (aliases: m)
coinhunter market tickers BTCUSDT ETH/USDT sol-usdt
coinhunter market klines BTCUSDT ETHUSDT --interval 1h --limit 50
coin m tk BTCUSDT ETHUSDT
coin m k BTCUSDT -i 1h -l 50

# Trade (buy / sell are now top-level commands)
coinhunter buy BTCUSDT --quote 100 --dry-run
coinhunter sell BTCUSDT --qty 0.01 --type limit --price 90000
coin b BTCUSDT -Q 100 -d
coin s BTCUSDT -q 0.01 -t limit -p 90000

# Opportunities (aliases: opp, o)
coinhunter opportunity portfolio
coinhunter opportunity scan
coinhunter opportunity scan --symbols BTCUSDT ETHUSDT SOLUSDT
coin opp pf
coin o scan -s BTCUSDT ETHUSDT

# Audit log
coinhunter catlog
coinhunter catlog -n 20
coinhunter catlog -n 10 -o 10

# Self-upgrade
coinhunter upgrade
coin 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
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

Use coinhunter catlog to read recent entries in the terminal. It aggregates across all days and supports pagination with -n/--limit and -o/--offset.

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]"

Or use the provided Conda environment:

conda env create -f environment.yml
conda activate coinhunter

Run quality checks:

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