refactor: rewrite Coin Hunter as short-term trading framework with auto-trading architecture

2026-04-16 03:03:25 +08:00
parent 73a3cb6952
commit a4ba9bb64e
5 changed files with 716 additions and 256 deletions
--- a/references/auto-trading-guide.md
+++ b/references/auto-trading-guide.md
@@ -0,0 +1,197 @@
+# Automated Trading Guide for Coin Hunter
+
+Complete guide for building and running a hands-off meme-coin trading bot using the Binance Spot API.
+
+## Scope
+
+This guide covers:
+- Creating a safe Binance API key
+- Installing dependencies (ccxt, pandas, numpy)
+- Setting up `auto_trader.py`
+- Testing in `DRY_RUN` mode
+- Scheduling execution with `cronjob`
+- Critical safety rules and troubleshooting
+
+## What the bot does
+
+1. **Monitors existing positions** for stop-loss (-7%) and take-profit (+15% / +30%) levels
+2. **Scans the market** for new meme-coin candidates (price < $1, 24h volume > $1M, 24h change > 5%)
+3. **Dynamically sizes orders** based on the user's total USDT balance and a configurable allocation percentage
+4. **Runs on a schedule** (default every 15 minutes) and reports actions back via Telegram
+
+## Architecture
+
+```
+~/.coinhunter/
+├── auto_trader.py      # Main trading logic
+├── run_trader.sh       # Shell wrapper (venv + env vars + logging)
+├── check_api.py        # Quick API connectivity validator
+├── logs/trader.log     # Execution logs
+└── positions.json      # Portfolio state (shared with coinhunter)
+```
+
+## Step 1: Binance API Key setup
+
+1. Log in to Binance → **API Management**
+2. Create a new API Key
+3. Enable permissions:
+   - ✅ **Enable Reading**
+   - ✅ **Enable Spot & Margin Trading**
+   - ❌ **Disable Withdrawal** (security red line)
+4. Add an **IP whitelist** (strongly recommended):
+   - Use the public IP of the machine that will run the bot
+   - This prevents key reuse if the credential is ever leaked
+
+**Security reminder:** never paste API keys into chat messages. Write them directly into `~/.hermes/.env`.
+
+## Step 2: Store credentials
+
+Append to `~/.hermes/.env`:
+
+```env
+BINANCE_API_KEY=your_api_key_here
+BINANCE_API_SECRET=your_api_secret_here
+```
+
+## Step 3: Install dependencies
+
+The bot uses `ccxt` for exchange connectivity and `pandas`/`numpy` for data handling.
+
+```bash
+uv pip install ccxt pandas numpy
+```
+
+Or if using a venv:
+
+```bash
+source venv/bin/activate
+pip install ccxt pandas numpy
+```
+
+## Step 4: Deploy the bot
+
+Use `scripts/auto_trader.py` from the coinhunter skill as the template. Copy it into the user's `~/.coinhunter/` directory and customize:
+
+- `MAX_POSITIONS` — max concurrent meme-coin positions (default 2)
+- `CAPITAL_ALLOCATION_PCT` — fraction of total USDT to use (default 0.95; leave ~5% buffer for fees/slippage)
+- `MIN_POSITION_USDT` — minimum single order size (default 50)
+- `STOP_LOSS_PCT` / `TAKE_PROFIT_1_PCT` / `TAKE_PROFIT_2_PCT` — risk levels
+
+Create `run_trader.sh`:
+
+```bash
+#!/bin/bash
+set -e
+cd "$(dirname "$0")"
+python3 check_api.py
+source /path/to/venv/bin/activate
+export DRY_RUN=${DRY_RUN:-true}
+python3 auto_trader.py >> logs/trader.log 2>&1
+```
+
+Make executable:
+
+```bash
+chmod +x run_trader.sh check_api.py
+mkdir -p logs
+```
+
+## Step 5: Validate API connectivity
+
+```bash
+python3 check_api.py
+```
+
+Expected output: `✅ API 配置正常`
+
+If this fails, the bot will exit immediately on each run.
+
+## Step 6: Run a DRY_RUN test
+
+```bash
+DRY_RUN=true python3 auto_trader.py
+```
+
+Expected behavior:
+- Reads current positions from `positions.json`
+- Fetches live Binance prices
+- Prints PnL for each position
+- Prints `[DRY RUN]` instead of real trades
+- Does **not** move money
+
+Only proceed to live trading after at least one dry-run cycle completes without errors.
+
+## Step 7: Schedule with cronjob
+
+Use the `cronjob` tool to run the bot every 15 minutes:
+
+```json
+{
+  "action": "create",
+  "name": "Coin Hunter Auto Trader",
+  "schedule": "*/15 * * * *",
+  "deliver": "telegram",
+  "prompt": "Run the Coin Hunter automatic meme-coin trading bot.\n1. cd /home/<user>/.coinhunter\n2. ./run_trader.sh\n3. Summarize actions and report back."
+}
+```
+
+## Step 8: Switch to live trading
+
+Once DRY_RUN validation succeeds and the user confirms:
+
+1. Edit `run_trader.sh`
+2. Change `DRY_RUN=${DRY_RUN:-true}` to `DRY_RUN=${DRY_RUN:-false}`
+3. The next cron run will execute real orders
+
+**You must always obtain explicit user confirmation before enabling live trading.**
+
+## Key safety rules
+
+1. **Never enable Withdrawal permission** on the API key.
+2. **Always bind an IP whitelist** if possible.
+3. **Never accept API keys in plaintext chat.** Ask the user to write them into `~/.hermes/.env`.
+4. **Do not set allocation to exactly 100%.** Leave at least 3–5% buffer for fees and slippage.
+5. **Start with DRY_RUN.** Run at least one full cycle before going live.
+6. **Check the account balance first.** If USDT is 0 (or held in Earn/Margin/Futures), the bot cannot trade.
+7. **Educate the user about risks.** Automated bots can and will lose money during flash crashes, API errors, or black-swan events.
+
+## Common pitfalls
+
+### Ticker symbol mismatch
+
+ccxt returns tickers with a slash (e.g., `PENGU/USDT`), but `positions.json` may store symbols without a slash (`PENGUUSDT`). If the bot looks up `tickers.get("PENGUUSDT")`, it will get `None` and silently skip stop-loss/take-profit checks.
+
+**Fix:** normalize symbols before lookup:
+
+```python
+sym_ccxt = sym.replace("USDT", "/USDT") if "/" not in sym else sym
+ticker = tickers.get(sym_ccxt)
+```
+
+### .env file is protected
+
+The `patch` tool may reject edits to `~/.hermes/.env`. Use terminal redirection instead:
+
+```bash
+cat >> ~/.hermes/.env << 'EOF'
+BINANCE_API_KEY=xxx
+BINANCE_API_SECRET=yyy
+EOF
+```
+
+### Zero balance surprises
+
+The bot reads **Spot free balance**. If the user holds USDT in:
+- Flexible Savings / Earn
+- Margin account
+- Futures wallet
+- Another sub-account
+
+…it will see $0 and fail to open new positions. Ask the user to transfer funds to Spot before going live.
+
+## Customization ideas
+
+- **Chain bias:** restrict candidate scanning to Solana-only or Base-only by filtering `cand["base"]` or integrating DexScreener chain filters.
+- **Social signal integration:** add a Twitter/X sentiment check before opening a position.
+- **Tiered stops:** replace fixed -7% with trailing stops using recent ATR or swing lows.
+- **Blacklist expansion:** add recently rugged tickers to `BLACKLIST` based on on-chain data.
--- a/references/review-template.md
+++ b/references/review-template.md
@@ -0,0 +1,40 @@
+# Review Report Template
+
+## Header
+- Review Period: [Start] — [End]
+- Total Decisions: N
+- Total Trades Executed: N
+- Portfolio Value Change: +X% / -X%
+
+## Decision Quality Breakdown
+
+### 1. Hold Decisions
+- Count: N
+- Outcome: [mostly correct / neutral / mostly wrong]
+- Key Insight: …
+
+### 2. Sell Decisions
+- Count: N
+- Good exits (avoided further drop): N
+- Missed runs (sold too early): N
+- Avg opportunity cost of early exits: X%
+
+### 3. Buy / Rebalance Decisions
+- Count: N
+- Profitable entries: N
+- Losing entries: N
+- Avg estimated PnL: X%
+
+## Market Context During Period
+- BTC trend: [up / down / sideways]
+- Dominant narrative: …
+- Liquidity condition: [high / normal / low]
+
+## Strategy Adjustments Recommended
+1. …
+2. …
+3. …
+
+## Action Items for Next Hour
+- [ ] …
+- [ ] …
--- a/references/short-term-trading-framework.md
+++ b/references/short-term-trading-framework.md
@@ -0,0 +1,78 @@
+# Short-Term Trading Framework
+
+## Philosophy
+
+不要只狩猎妖币。短线复利的核心是**在高确率/高赔付比的机会上重仓，在不确定时观望**。
+
+妖币是可遇不可求的赚钱机会，遇到了不要错过，没遇到也不要强求。当市场缺乏明确的超短线热点时，主流币的短线波动率交易往往更稳定。
+
+---
+
+## Strategy Mix
+
+### 1. Mainstream Short-Term (70% of focus)
+**Target coins:** BTC, ETH, SOL, BNB, DOGE, PEPE, WIF, BONK 等 Binance 高流动性币种
+
+**Entry triggers:**
+- 突破关键阻力/支撑位，并且放量
+- 1h / 4h 级别出现明确的趋势转折信号
+- 超卖/超买指标出现极端值且开始回归
+- 量价齐升（Volume 放大 + 价格突破）
+
+**Exit triggers:**
+- 达到预设盈亏目标（主流币 +8% 至 +15%）
+- 趋势转弱信号（量缩价跌、失守关键支撑）
+- 出现更好的机会成本（换仓）
+
+**Risk management:**
+- 单次下注不超过总资产的 50%
+- 主流币硬止损放宽至 -5% 至 -8%
+- 使用支撑阻力作为活止损，不用固定百分比
+
+### 2. Meme / 妖币 Rotation (30% of focus)
+**Target coins:** 新兴 meme、热点小币
+
+**Entry triggers:**
+- 社交媒体关注度快速上升
+- 24h 成交量 > $1M
+- 币安可交易（确保能进能出）
+- 故事/narrative 简单易传播
+
+**Exit triggers:**
+- 涨幅过快（+50% in 24h）且量缩
+- 舆论出现转凇信号
+- 新币出现更强势代替
+
+---
+
+## Scientific Analysis Checklist
+
+每次决策前，必须回答以下问题：
+
+1. **趋势态势**：价格在短期均线（1h/4h MA）的上方还是下方？
+2. **量能配合**：最近几个 K 线的成交量是否配合价格走势？
+3. **关键位置**：下一个支撑和阻力在哪里？空间有多大？
+4. **市场情绪**：大盘（BTC/ETH）是否配合？还是独立行情？
+5. **机会成本**：持有现币 vs 换到新币 vs 持有现金，三者中谁的风险收益比最优？
+6. **时间窗口**：现在是否是合适的入市/出市时间点？（注意交易所交易时间段的流动性变化）
+
+---
+
+## Position Sizing
+
+根据总资产动态调整：
+- 当总资产 < $50：**单币重仓**，放弃多元化
+- 当总资产 $50-$200：主流币 60% + 妖币 40%
+- 当总资产 > $200：可考虑 3 个币的轮动
+
+不论资金大小，都要留出至少 2%-5% 的 USDT 缓冲以应对手续费和滑点。
+
+---
+
+## Continuous Improvement
+
+每小时复盘一次，重点关注：
+- 是否有连续出现同类型的决策失误
+- 是否过于频繁交易（摩擦成本过高）
+- 是否在明显的指标背离时仍然入市
+- 新闻/市场视角是否需要更新到黑名单或基准条件中