Tacit Lab
3855477155
Remove overview/balances/positions subcommands in favor of one `account` command that returns all balances with an `is_dust` flag. Add descriptions to every parser and expose -a/--agent and --doc on all leaf commands for better help discoverability. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
182 lines
5.2 KiB
Markdown
182 lines
5.2 KiB
Markdown
<p align="center">
|
|
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:F7B93E,100:0f0f0f&height=220§ion=header&text=%F0%9F%AA%99%20CoinHunter&fontSize=65&fontColor=fff&animation=fadeIn&fontAlignY=32&desc=Trade%20Smarter%20%C2%B7%20Execute%20Faster%20%C2%B7%20Sleep%20Better&descAlignY=55&descSize=18" alt="CoinHunter Banner" />
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=22&duration=2800&pause=800&color=F7B93E¢er=true&vCenter=true&width=600&lines=Binance-first+Trading+CLI;Account+%E2%86%92+Market+%E2%86%92+Trade+%E2%86%92+Opportunity;Human-friendly+TUI+%7C+Agent+Mode" alt="Typing SVG" />
|
|
</p>
|
|
|
|
<p align="center">
|
|
<strong>A Binance-first crypto trading CLI for balances, market data, opportunity scanning, and execution.</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://pypi.org/project/coinhunter/"><img src="https://img.shields.io/pypi/v/coinhunter?style=flat-square&color=F7B93E&labelColor=1a1a1a&cacheSeconds=60" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white&labelColor=1a1a1a" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/tests-passing-22c55e?style=flat-square&labelColor=1a1a1a" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/lint-ruff%20%2B%20mypy-8b5cf6?style=flat-square&labelColor=1a1a1a" /></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
You can also use the shorter `coin` alias:
|
|
|
|
```bash
|
|
coin --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).
|
|
|
|
Add `--doc` to any command to see its output schema and field descriptions (great for AI agents):
|
|
|
|
```bash
|
|
coin buy --doc
|
|
coin market klines --doc
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Account (aliases: a, acc)
|
|
coinhunter account
|
|
coinhunter account --agent
|
|
coin a
|
|
|
|
# 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:
|
|
|
|
```text
|
|
~/.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:
|
|
|
|
```bash
|
|
git clone https://git.tacitlab.cc/TacitLab/coinhunter-cli.git
|
|
cd coinhunter-cli
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
Or use the provided Conda environment:
|
|
|
|
```bash
|
|
conda env create -f environment.yml
|
|
conda activate coinhunter
|
|
```
|
|
|
|
Run quality checks:
|
|
|
|
```bash
|
|
pytest tests/ # run tests
|
|
ruff check src tests # lint
|
|
mypy src # type check
|
|
```
|