Tacit Lab
9395978440
- Replace default JSON output with styled TUI tables and ANSI colors. - Add -a/--agent global flag: small payloads → JSON, large → pipe-delimited compact. - Update README to reflect new output behavior and remove JSON-first references. - Bump version to 2.0.2. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
146 lines
4.3 KiB
Markdown
146 lines
4.3 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
|
|
```
|
|
|
|
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/`
|
|
|
|
`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-update
|
|
coinhunter update
|
|
```
|
|
|
|
`update` 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
|
|
```
|