Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
---
## What is this?
`coinhunter` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.
> **Note:** The old package name `coinhunter-cli` is deprecated. Please install `coinhunter` going forward.
| 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
│ ├── review_service.py # review generation logic
│ ├── precheck_constants.py # thresholds
│ ├── 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
### From PyPI (recommended)
```bash
pip install coinhunter
```
This installs the latest stable release and creates the `coinhunter` console script entry point.
Verify:
```bash
coinhunter --help
coinhunter --version
```
### Development install (editable)
If you're working on this repo locally:
```bash
pip install -e ".[dev]"
```
Or use the convenience script:
```bash
./scripts/install_local.sh
```
A thin wrapper that runs `pip install -e .` and verifies the entrypoint is on your PATH.
---
## 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 exec orders # list open spot orders
coinhunter exec order-status ENJUSDT 123456 # check specific order
coinhunter exec cancel ENJUSDT 123456 # cancel an open order
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
```
The gate reads `trigger_command` from `~/.coinhunter/config.json` under `external_gate`.
- By default, no external trigger is configured — gate runs precheck and marks state, then exits cleanly.
- Set `trigger_command` to a command list to integrate with your own scheduler:
```json
{
"external_gate": {
"trigger_command": ["hermes", "cron", "run", "JOB_ID"]
}
}
```
- Set to `null` or `[]` to explicitly disable the external trigger.
### Dynamic tuning via `config.json`
You can override internal defaults without editing code by adding keys to `~/.coinhunter/config.json`:
```json
{
"external_gate": {
"trigger_command": ["hermes", "cron", "run", "JOB_ID"]
},
"exchange": {
"min_quote_volume": 200000,
"cache_ttl_seconds": 3600
},
"logging": {
"schema_version": 2
}
}
```
| Key | Default | Effect |
|-----|---------|--------|
| `exchange.min_quote_volume` | `200000` | Minimum 24h quote volume for a symbol to appear in market snapshots |
| `exchange.cache_ttl_seconds` | `3600` | How long the ccxt exchange instance (and `load_markets()` result) is cached |
| `logging.schema_version` | `2` | Schema version stamped on every JSONL log entry |
---
## 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/`
- ✅ Extracted `review_engine.py` core logic into `services/review_service.py`
- ✅ Removed eager `PATHS` instantiation across services and commands
- ✅ Fixed `smart_executor.py` lazy-loading facade
- ✅ Standardized install to use `pip install -e .`
- ✅ Made `external_gate` trigger_command configurable (no longer hardcodes hermes)
- ✅ Removed dead `auto-trader` command
- ✅ Backward-compatible root facades preserved
**Next priorities:**
- 🔧 Add basic CI (lint + compileall + pytest)
- 🔧 Unify output contract (JSON-first with `--pretty` option)
---
## 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.