coinhunter-cli/README.md

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

---

What's New in 3.0

• Split decision models — portfolio (add/hold/trim/exit) and opportunity (enter/watch/skip) now use independent scoring logic.
• Configurable ticker windows — market tickers supports --window 1h, 4h, or 1d.
• Live / dry-run audit logs — audit logs are written to separate subdirectories; use catlog --dry-run to review simulations.
• Flattened commands — account, opportunity, and config are now top-level for fewer keystrokes.
• Runtime config management — config get, config set, and config key/secret let you edit settings without touching files manually.

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.

init interactively prompts for your Binance API key and secret if they are missing. Use --no-prompt to skip this.

config.toml stores runtime and strategy settings. .env stores:

BINANCE_API_KEY=
BINANCE_API_SECRET=

Strategy settings are split into three blocks:

• [signal] for shared market-signal weights and lookback interval
• [opportunity] for scan thresholds, liquidity filters, and top-N output
• [portfolio] for add/hold/trim/exit thresholds and max position weight

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
coinhunter account --agent
coin a

# Market (aliases: m)
coinhunter market tickers BTCUSDT ETH/USDT sol-usdt --window 1h
coinhunter market klines BTCUSDT ETHUSDT --interval 1h --limit 50
coin m tk BTCUSDT ETHUSDT -w 1d
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

# Portfolio (aliases: pf, p)
coinhunter portfolio
coinhunter portfolio --agent
coin pf

# Opportunity scanning (aliases: o)
coinhunter opportunity
coinhunter opportunity --symbols BTCUSDT ETHUSDT SOLUSDT
coin o -s BTCUSDT ETHUSDT

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

# Configuration management (aliases: cfg, c)
coinhunter config get                    # show all config
coinhunter config get binance.recv_window
coinhunter config set opportunity.top_n 20
coinhunter config set signal.lookback_interval 4h
coinhunter config set portfolio.max_position_weight 0.25
coinhunter config set trading.dry_run_default true
coinhunter config set market.universe_allowlist BTCUSDT,ETHUSDT
coinhunter config key YOUR_API_KEY       # or omit value to prompt interactively
coinhunter config secret YOUR_SECRET     # or omit value to prompt interactively
coin c get opportunity.top_n
coin c set trading.dry_run_default false

# 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/signal_service.py, services/opportunity_service.py, services/portfolio_service.py, services/trade_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