coinhunter-cli/README.md

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

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)

pip install coinhunter

This installs the latest stable release and creates the coinhunter console script entry point.

Verify:

coinhunter --help
coinhunter --version

Development install (editable)

If you're working on this repo locally:

pip install -e ".[dev]"

Or use the convenience script:

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

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)

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:

coinhunter init

Inspect the environment:

coinhunter paths
coinhunter diag

Validate API keys:

coinhunter api-check

Run the precheck workflow:

coinhunter precheck
coinhunter precheck --ack "analysis completed"

Run the external gate:

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:

{
  "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:

{
  "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:

~/.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.