🪙 Coin Hunter

A low-cost, high-discipline short-term crypto trading framework.
70% mainstream momentum scalping + 30% meme-coin opportunistic rotation, fully automated with hourly review.

---

✨ What is this?

Coin Hunter is not a simple scanner. It is a production-grade trading stack designed for short-term crypto markets, with two parallel tracks:

Track	Allocation	Focus
🏛️ Mainstream Scalping	~70%	BTC, ETH, SOL, DOGE, PEPE — momentum, S/R flips, volume expansion
🐸 Meme Rotation	~30%	Narrative heat, DEX flow, CEX rumors — capture runners, ignore noise

Core philosophy:
Profit maximization through concentration + discipline.
妖币可遇不可求 — when a runner appears, capture it. When none exists, scalp mainstream or sit in USDT.

---

🧠 Why it works

• Portfolio-first rule — every decision anchors to your real balances, average costs, and exchange state.
• Scientific checklist — 6 mandatory questions (trend, volume, levels, BTC context, opportunity cost, time window) before every trade.
• Hourly self-review — the bot critiques its own decisions, flags over-trading / hesitation, and tunes parameters.
• Ultra-low running cost — a lightweight local gate filters noise; the LLM only wakes up when the market actually changes.

---

🏗️ Architecture

flowchart TD
    A[System crontab<br/>every 5 min] -->|coinhunter gate| B[External Gate]
    B --> C{should_analyze?}
    C -->|No| D[Silent exit<br/>zero cost]
    C -->|Yes| E[Trigger platform cron]
    E --> F[LLM Deep Analysis]
    F --> G[coinhunter exec]
    G --> H[Binance API]
    F --> I[coinhunter logs]
    I --> J[~/.coinhunter/logs/]
    K[coinhunter recap<br/>hourly] --> J

Key components

All operations go through the installed coinhunter CLI. This skill provides the framework specification, reference playbooks, and Hermes cron shims.

Command	Purpose
coinhunter probe	Market data fetcher (ccxt + web search)
coinhunter pre	Lightweight gate — computes adaptive thresholds and decides if analysis is needed
coinhunter gate	Optional system-crontab wrapper that runs the gate entirely outside Hermes
coinhunter exec	Order execution layer with idempotency & precision validation
coinhunter review	Generate compact review context for the agent
coinhunter recap	Hourly quality review & parameter optimization

---

🚀 Quick Start

1. Install

git clone https://github.com/TacitLab/coinhunter.git
cd coinhunter

2. Install the CLI tool

pipx install coinhunter
# verify
coinhunter --help

3. Set up your runtime directory

mkdir -p ~/.coinhunter/state ~/.coinhunter/logs
# Also create your platform's scripts directory if needed:
# mkdir -p ~/.hermes/scripts
# mkdir -p ~/.openclaw/scripts

Create your initial positions.json:

{
  "exchange": "binance",
  "balances": { "USDT": { "free": 150.0, "locked": 0.0 } },
  "positions": [],
  "account_total_usdt": 150.0
}

4. Deploy the shims

Copy the unified shim into your platform's scripts directory. It accepts the subcommand as its first argument:

# Hermes
cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py

# OpenClaw
cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py

5. Configure the platform cron job

Hermes example (using the unified shim):

{
  "id": "coinhunter-trade",
  "schedule": "*/15 * * * *",
  "prompt": "You are Coin Hunter. If injected context says should_analyze=false, respond with exactly [SILENT]. Otherwise read positions.json, run the scientific checklist, decide HOLD/SELL/REBALANCE/BUY, and execute.",
  "script": "coinhunter_shim.py pre",
  "deliver": "telegram",
  "model": "kimi-for-coding"
}

OpenClaw example:

{
  "id": "coinhunter-trade",
  "schedule": "*/15 * * * *",
  "prompt": "You are Coin Hunter. If injected context says should_analyze=false, respond with exactly [SILENT]. Otherwise read positions.json, run the scientific checklist, decide HOLD/SELL/REBALANCE/BUY, and execute.",
  "script": "coinhunter_shim.py pre",
  "deliver": "webhook"
}

6. (Optional) Add the external gate

Put this in your system crontab to run the gate every 5 minutes without ever waking the LLM:

*/5 * * * * /usr/bin/env coinhunter gate >> /home/user/.coinhunter/logs/external_gate.log 2>&1

---

🛡️ Safety & Hardening

Coin Hunter enforces production-grade safeguards out of the box:

Safeguard	How
Idempotency	Every trade carries a decision_id; executor checks executions.json before submitting
Exchange reconciliation	Real Binance balances are pulled before every run to sync local state
Atomic writes	positions.json & executions.json are written under file lock + temp-file rename
Precision validation	Lot size, step size, and minNotional filters are read via ccxt before any order
Fee buffer	2%–5% USDT is always left unallocated to prevent "insufficient balance" rejections
Position sizing limits	<$50 → 1 coin only. $50–$200 → max 2 positions. >$200 → max 3 positions.
No leverage for small capital	Leverage/futures are blocked when total capital < $200

---

📊 The Gate: How we cut costs 80-95%

Instead of waking an LLM every 15 minutes to analyze an unchanged market, we run a local Python gate that only fires on true material changes:

Triggers (adaptive thresholds)

• 🔴 Hard triggers — position structure changes, BTC/ETH regime changes
• 🟡 Soft triggers — per-position price/PnL drift beyond adaptive limits (wider for micro accounts, narrower in high volatility)
• 🔵 Candidate triggers — top-opportunity leadership changes materially (ignored when free USDT is below actionable minimums)
• ⏰ Staleness guard — forces refresh after 4h (or 8h for micro accounts) even if nothing else changed

Result

• Routine market noise → filtered locally in milliseconds, $0 cost
• Real opportunities → LLM wakes up and applies full intelligence
• Cost drops from ~96 LLM calls/day to 2-10 calls/day, with no loss in decision quality

See the full step-by-step gate blueprint in SKILL.md.

---

📁 Directory Layout

coinhunter/
├── README.md                     # You are here
├── SKILL.md                      # Full framework spec + gate blueprint
├── CLAUDE.md                     # Guidance for Claude Code
├── scripts/                      # Platform cron shims (call the installed coinhunter CLI)
│   └── coinhunter_shim.py        # Unified cross-platform shim
└── references/
    ├── short-term-trading-framework.md
    ├── review-template.md
    ├── provider-playbook.md
    ├── user-data-layout.md
    └── scam-signals.md

Your private runtime lives under ~/.coinhunter/:

~/.coinhunter/
├── positions.json
├── accounts.json
├── state/
│   ├── precheck_state.json
│   └── external_gate.lock
├── logs/
│   ├── decisions_YYYYMMDD.jsonl
│   ├── trades_YYYYMMDD.jsonl
│   ├── errors_YYYYMMDD.jsonl
│   └── external_gate.log
└── reviews/
    └── review_YYYYMMDD_HHMMSS.json

---

📝 References

• references/short-term-trading-framework.md — Hybrid trading strategy
• references/review-template.md — Hourly report format
• references/provider-playbook.md — Data source selection
• references/scam-signals.md — Meme-coin red flags
• SKILL.md — Complete architecture & step-by-step gate build guide

---

⚠️ Disclaimer

Coin Hunter is an experimental trading framework. It does not guarantee profit. Cryptocurrency trading carries substantial risk, including the loss of all capital. Use at your own risk, start small, and never trade with money you cannot afford to lose.

---

Made with ☕, 🧠, and a healthy respect for risk management.
Happy hunting. 🪙