273 lines
9.9 KiB
Markdown
273 lines
9.9 KiB
Markdown
<!--
|
|
╔══════════════════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ ██████╗ ██╗ ██╗██╗███╗ ██╗██╗ ██╗██╗ ██╗███╗ ██╗████████╗███████╗██████╗ ║
|
|
║ ██╔════╝ ██║ ██║██║████╗ ██║██║ ██║██║ ██║████╗ ██║╚══██╔══╝██╔════╝██╔══██╗ ║
|
|
║ ██║ ██║ ██║██║██╔██╗ ██║███████║██║ ██║██╔██╗ ██║ ██║ █████╗ ██████╔╝ ║
|
|
║ ██║ ╚██╗ ██╔╝██║██║╚██╗██║██╔══██║██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██╔══██╗ ║
|
|
║ ╚██████╗ ╚████╔╝ ██║██║ ╚████║██║ ██║╚██████╔╝██║ ╚████║ ██║ ███████╗██║ ██║ ║
|
|
║ ╚═════╝ ╚═══╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ║
|
|
║ ║
|
|
║ The Executable CLI Layer for CoinHunter ║
|
|
║ ║
|
|
╚══════════════════════════════════════════════════════════════════════════════╝
|
|
-->
|
|
|
|
<h1 align="center">
|
|
<br>
|
|
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=28&duration=3000&pause=1000&color=F7B93E¢er=true&vCenter=true&width=435&lines=CoinHunter+CLI;Trade+Smarter+%E2%9A%A1+Execute+Faster" alt="CoinHunter CLI" />
|
|
</h1>
|
|
|
|
<p align="center">
|
|
<strong>Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/status-active%20development-22c55e?style=flat-square" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/architecture-cli%20%2B%20commands%20%2B%20services-8b5cf6?style=flat-square" /></a>
|
|
<a href="#"><img src="https://img.shields.io/badge/tests-needed-ef4444?style=flat-square" /></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## What is this?
|
|
|
|
`coinhunter-cli` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.
|
|
|
|
| Layer | Responsibility | Location |
|
|
|-------|----------------|----------|
|
|
| **CLI** | Top-level command router | `cli.py` |
|
|
| **Commands** | Thin argument adapters | `commands/` |
|
|
| **Services** | Orchestration & execution logic | `services/` |
|
|
| **Runtime** | Paths, env, locks, config | `runtime.py` |
|
|
| **User Data** | State, logs, reviews, positions | `~/.coinhunter/` |
|
|
|
|
> **Separation of concerns:** Code lives in this repo. Your data lives in `~/.coinhunter/`. Strategy and prompting live in Hermes skills.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```text
|
|
src/coinhunter/
|
|
├── cli.py # Unified command router
|
|
├── runtime.py # Runtime paths + env loading
|
|
├── logger.py # Structured logging utilities
|
|
├── commands/ # CLI adapters (thin, stateless)
|
|
│ ├── precheck.py
|
|
│ ├── smart_executor.py
|
|
│ ├── check_api.py
|
|
│ ├── doctor.py
|
|
│ ├── external_gate.py
|
|
│ ├── init_user_state.py
|
|
│ ├── market_probe.py
|
|
│ ├── paths.py
|
|
│ ├── review_context.py
|
|
│ ├── review_engine.py
|
|
│ └── rotate_external_gate_log.py
|
|
├── services/ # Orchestration & domain logic
|
|
│ ├── exchange_service.py
|
|
│ ├── portfolio_service.py
|
|
│ ├── trade_execution.py
|
|
│ ├── smart_executor_service.py
|
|
│ ├── smart_executor_parser.py
|
|
│ ├── execution_state.py
|
|
│ ├── precheck_service.py
|
|
│ ├── precheck_constants.py # thresholds & paths
|
|
│ ├── time_utils.py # UTC/local time helpers
|
|
│ ├── data_utils.py # json, hash, float, symbol norm
|
|
│ ├── state_manager.py # state load/save/sanitize
|
|
│ ├── market_data.py # exchange, OHLCV, metrics
|
|
│ ├── candidate_scoring.py # coin selection & scoring
|
|
│ ├── snapshot_builder.py # precheck snapshot construction
|
|
│ ├── adaptive_profile.py # trigger profile builder
|
|
│ ├── trigger_analyzer.py # trigger analysis core
|
|
│ ├── precheck_analysis.py # failure payloads
|
|
│ ├── precheck_snapshot.py # snapshot facade
|
|
│ ├── precheck_state.py # state facade
|
|
│ └── precheck_core.py # backward-compat export facade
|
|
├── precheck.py # Backward-compat root facade
|
|
├── smart_executor.py # Backward-compat root facade
|
|
└── *.py # Other compat / utility modules
|
|
```
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Quick user install
|
|
|
|
```bash
|
|
./scripts/install_local.sh
|
|
```
|
|
|
|
Creates:
|
|
- Virtualenv: `~/.local/share/coinhunter-cli/venv`
|
|
- Launcher: `~/.local/bin/coinhunter`
|
|
|
|
### Editable dev install
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
coinhunter --help
|
|
coinhunter --version
|
|
```
|
|
|
|
---
|
|
|
|
## Command Reference
|
|
|
|
### Short aliases (recommended)
|
|
|
|
```bash
|
|
coinhunter diag # runtime diagnostics
|
|
coinhunter paths # print resolved paths
|
|
coinhunter api-check # validate exchange credentials
|
|
coinhunter precheck # run precheck snapshot + trigger analysis
|
|
coinhunter exec bal # print balances as JSON
|
|
coinhunter exec overview # account overview as JSON
|
|
coinhunter exec hold # record a HOLD decision
|
|
coinhunter exec buy ENJUSDT 50 # buy $50 of ENJUSDT
|
|
coinhunter exec flat ENJUSDT # sell entire ENJUSDT position
|
|
coinhunter exec rotate PEPEUSDT ETHUSDT # rotate exposure
|
|
coinhunter gate # external gate orchestration
|
|
coinhunter review 12 # generate review context (last 12h)
|
|
coinhunter recap 12 # generate review report (last 12h)
|
|
coinhunter probe bybit-ticker BTCUSDT # market probe
|
|
coinhunter rotate-log # rotate external gate logs
|
|
```
|
|
|
|
### Legacy long forms (still supported)
|
|
|
|
```bash
|
|
coinhunter doctor
|
|
coinhunter check-api
|
|
coinhunter smart-executor bal
|
|
coinhunter review-context 12
|
|
coinhunter review-engine 12
|
|
coinhunter market-probe bybit-ticker BTCUSDT
|
|
coinhunter external-gate
|
|
coinhunter rotate-external-gate-log
|
|
```
|
|
|
|
### All supported commands
|
|
|
|
| Canonical | Aliases |
|
|
|-----------|---------|
|
|
| `check-api` | `api-check` |
|
|
| `doctor` | `diag` |
|
|
| `external-gate` | `gate` |
|
|
| `init` | — |
|
|
| `market-probe` | `probe` |
|
|
| `paths` | — |
|
|
| `precheck` | — |
|
|
| `review-context` | `review` |
|
|
| `review-engine` | `recap` |
|
|
| `rotate-external-gate-log` | `rotate-gate-log`, `rotate-log` |
|
|
| `smart-executor` | `exec` |
|
|
|
|
---
|
|
|
|
## Quickstart
|
|
|
|
Initialize runtime state:
|
|
|
|
```bash
|
|
coinhunter init
|
|
```
|
|
|
|
Inspect the environment:
|
|
|
|
```bash
|
|
coinhunter paths
|
|
coinhunter diag
|
|
```
|
|
|
|
Validate API keys:
|
|
|
|
```bash
|
|
coinhunter api-check
|
|
```
|
|
|
|
Run the precheck workflow:
|
|
|
|
```bash
|
|
coinhunter precheck
|
|
coinhunter precheck --ack "analysis completed"
|
|
```
|
|
|
|
Run the external gate:
|
|
|
|
```bash
|
|
coinhunter gate
|
|
```
|
|
|
|
---
|
|
|
|
## Runtime Model
|
|
|
|
Default data layout:
|
|
|
|
```text
|
|
~/.coinhunter/
|
|
├── config.json
|
|
├── positions.json
|
|
├── accounts.json
|
|
├── watchlist.json
|
|
├── notes.json
|
|
├── executions.json
|
|
├── logs/
|
|
├── reviews/
|
|
├── cache/
|
|
└── state/
|
|
├── precheck_state.json
|
|
└── external_gate.lock
|
|
```
|
|
|
|
Credential resolution:
|
|
|
|
- Binance API keys are read from `~/.hermes/.env` by default.
|
|
- Override with `COINHUNTER_ENV_FILE`.
|
|
- Override home with `COINHUNTER_HOME` or `HERMES_HOME`.
|
|
- `hermes` binary is resolved from `PATH`, then `~/.local/bin/hermes`, unless `HERMES_BIN` is set.
|
|
|
|
---
|
|
|
|
## Development Status
|
|
|
|
The codebase is actively maintained and refactored in small, safe steps.
|
|
|
|
**Recently completed:**
|
|
- ✅ Unified CLI entrypoint with short aliases
|
|
- ✅ Extracted `smart-executor` into `commands/` + `services/`
|
|
- ✅ Extracted `precheck` into 9 focused service modules
|
|
- ✅ Migrated all active command modules into `commands/`
|
|
- ✅ Removed dead `auto-trader` command
|
|
- ✅ Backward-compatible root facades preserved
|
|
|
|
**Next priorities:**
|
|
- 🧪 Add pytest coverage for runtime paths, state manager, and trigger analyzer
|
|
- 🔧 Extract `review_engine.py` core logic into `services/`
|
|
- 🔧 Unify output contract (JSON-first with `--pretty` option)
|
|
- 🔧 Add basic CI (lint + compileall + pytest)
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
CoinHunter is evolving toward:
|
|
|
|
- **Professional execution** — scientific position sizing, not moonshot gambling
|
|
- **Maintainable architecture** — clear boundaries between CLI, services, and domain logic
|
|
- **Safer operations** — dry-run, validation gates, and explicit decision logging
|
|
- **Agent-friendly interfaces** — stable JSON outputs and predictable command contracts
|
|
- **Less dependence on prompt-only correctness** — logic belongs in code, not just in system prompts
|
|
|
|
This repo is where that evolution happens.
|