Metadata-Version: 2.4
Name: coinhunter
Version: 2.0.7
Summary: Binance-first trading CLI for balances, market data, opportunity scanning, and execution.
Author-email: Tacit Lab <ouyangcarlos@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: binance-connector>=3.9.0
Requires-Dist: shtab>=1.7.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:F7B93E,100:0f0f0f&height=220&section=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&center=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/`

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

```bash
# Account
coinhunter account overview
coinhunter account overview --agent
coinhunter account balances
coinhunter account positions

# Market
coinhunter market tickers BTCUSDT ETH/USDT sol-usdt
coinhunter market klines BTCUSDT ETHUSDT --interval 1h --limit 50

# Trade
coinhunter trade buy BTCUSDT --quote 100 --dry-run
coinhunter trade sell BTCUSDT --qty 0.01 --type limit --price 90000

# 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` |
| **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
```
