Tacit Lab
c841c92c30
- Add Decision calibration and Multi-source confirmation to Why it works - Fix remaining Hermes-only wording in command descriptions - Add platform.json example in Quick Start - Expand Directory Layout and References to include all reference docs - Add Decision calibration, Multi-source confirmation, and Prediction tracking to Safety table
278 lines
10 KiB
Markdown
278 lines
10 KiB
Markdown
# 🪙 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.
|
||
|
||
[](https://python.org)
|
||
[](LICENSE)
|
||
[](https://github.com/TacitLab/coinhunter)
|
||
|
||
---
|
||
|
||
## ✨ 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.
|
||
- **Decision calibration** — every trade decision must output a JSON skeleton with `confidence`, `risk_reward`, `stop_loss`, and `take_profit` before execution. No gut-feeling entries.
|
||
- **Multi-source confirmation** — signals are trusted only when confirmed by 2+ independent data sources (e.g. price action + DEX flow, or CEX rumor + on-chain growth).
|
||
- **Hourly self-review** — the bot critiques its own decisions, flags over-trading / hesitation, and tunes parameters.
|
||
- **Prediction tracking** — every decision writes an auditable prediction to `logs/predictions_YYYYMMDD.jsonl`; the review loop scores accuracy and surfaces systematic bias.
|
||
- **Ultra-low running cost** — a lightweight local **gate** filters noise; the LLM only wakes up when the market actually changes.
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture
|
||
|
||
```mermaid
|
||
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 cross-platform 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 the platform cron |
|
||
| `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
|
||
|
||
```bash
|
||
git clone https://github.com/TacitLab/coinhunter.git
|
||
cd coinhunter
|
||
```
|
||
|
||
### 2. Install the CLI tool
|
||
|
||
```bash
|
||
pipx install coinhunter
|
||
# verify
|
||
coinhunter --help
|
||
```
|
||
|
||
### 3. Set up your runtime directory
|
||
|
||
```bash
|
||
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`:
|
||
|
||
```json
|
||
{
|
||
"exchange": "binance",
|
||
"balances": { "USDT": { "free": 150.0, "locked": 0.0 } },
|
||
"positions": [],
|
||
"account_total_usdt": 150.0
|
||
}
|
||
```
|
||
|
||
*(Optional)* If you use OpenClaw (or another non-Hermes runtime), create `platform.json`:
|
||
|
||
```json
|
||
{
|
||
"platform": "openclaw",
|
||
"scripts_dir": "~/.openclaw/scripts",
|
||
"env_file": "~/.openclaw/.env",
|
||
"cron_command": ["openclaw", "trigger"],
|
||
"delivery": "webhook"
|
||
}
|
||
```
|
||
|
||
### 4. Deploy the shims
|
||
|
||
Copy the unified shim into your platform's scripts directory. It accepts the subcommand as its first argument:
|
||
|
||
```bash
|
||
# 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):**
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```cron
|
||
*/5 * * * * /usr/bin/env coinhunter gate >> /home/user/.coinhunter/logs/external_gate.log 2>&1
|
||
```
|
||
|
||
> The gate reads `~/.coinhunter/platform.json` to know which command triggers your platform's cron. If the file is absent, it defaults to `hermes cron run`.
|
||
|
||
---
|
||
|
||
## 🛡️ 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 |
|
||
| **Decision calibration** | Every trade requires a JSON skeleton with confidence ≥ 0.55 and explicit stop-loss / take-profit |
|
||
| **Multi-source confirmation** | Signals must be confirmed by 2+ independent sources; single-source narratives are downgraded |
|
||
| **Prediction tracking** | Predictions are logged and scored during hourly review to surface systematic bias |
|
||
|
||
---
|
||
|
||
## 📊 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`](./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
|
||
├── auto-trading-guide.md
|
||
├── output-templates.md
|
||
├── search-workflow.md
|
||
└── shim-templates.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
|
||
│ ├── predictions_YYYYMMDD.jsonl
|
||
│ ├── errors_YYYYMMDD.jsonl
|
||
│ └── external_gate.log
|
||
└── reviews/
|
||
└── review_YYYYMMDD_HHMMSS.json
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 References
|
||
|
||
- [`references/short-term-trading-framework.md`](./references/short-term-trading-framework.md) — Hybrid trading strategy
|
||
- [`references/review-template.md`](./references/review-template.md) — Hourly report format
|
||
- [`references/provider-playbook.md`](./references/provider-playbook.md) — Data source selection
|
||
- [`references/scam-signals.md`](./references/scam-signals.md) — Meme-coin red flags
|
||
- [`references/auto-trading-guide.md`](./references/auto-trading-guide.md) — Binance API auto-trading setup
|
||
- [`references/output-templates.md`](./references/output-templates.md) — Triage and report templates
|
||
- [`references/search-workflow.md`](./references/search-workflow.md) — Proactive discovery workflow
|
||
- [`references/shim-templates.md`](./references/shim-templates.md) — Shim usage guide
|
||
- [`SKILL.md`](./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.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
Made with ☕, 🧠, and a healthy respect for risk management.
|
||
**Happy hunting.** 🪙
|
||
|
||
</div>
|