---
name: Coin Hunter
description: Hybrid short-term crypto trading system — combining mainstream coin scalping with meme-coin opportunistic rotation, backed by hourly review and continuous strategy iteration.
---

# Coin Hunter

## Overview

Coin Hunter is a **short-term trading framework**, not just a meme-coin scanner.

It operates on two tracks:
1. **Mainstream Short-Term (70%)** — Trade liquid, high-volume coins (BTC, ETH, SOL, DOGE, PEPE, etc.) based on technical momentum, support/resistance, and market structure.
2. **Meme / 妖币 Rotation (30%)** — Opportunistically rotate into breakout meme coins when narrative heat, volume, and timing align.

Core principle:
- **Profit maximization through concentration + discipline.**
- **妖币可遇不可求** — when a runner appears, capture it. When none exists, do not force trades; instead, scalp mainstream coins or sit in USDT.
- Every decision is logged, and every hour is reviewed for quality and parameter tuning.

## Portfolio-first rule

Always check the user's actual portfolio state under `~/.coinhunter/` before giving trade advice or executing orders.

Files to inspect:
- `positions.json`
- `accounts.json`
- `logs/decisions_YYYYMMDD.jsonl`
- `logs/trades_YYYYMMDD.jsonl`
- `reviews/review_YYYYMMDD_HHMMSS.json`

Anchor all advice to the user's real balances, average costs, exchange, and current exposure.

## Supported modes

1. **Single-coin triage** — analyze a specific holding (mainstream or meme).
2. **Active discovery** — scan for the best short-term opportunity across both mainstream and meme sectors.
3. **Execution** — run the auto-trader, evaluate whether to hold, sell, or rebalance.
4. **Review** — generate an hourly report on decision quality, PnL, and recommended parameter adjustments.

## Scientific analysis checklist (mandatory before every trade decision)

Before executing or recommending any action, answer:
1. **Trend posture** — Is price above/below short-term MAs (1h/4h)?
2. **Volume-price fit** — Is volume expanding with the move or diverging?
3. **Key levels** — Where is the next support/resistance? How much room to run?
4. **Market context** — Is BTC/ETH supportive or contradictory?
5. **Opportunity cost** — Is holding current coin better than switching to new coin or sitting in USDT?
6. **Time window** — Is this a good entry/exit time (liquidity, session, news flow)?

Read `references/short-term-trading-framework.md` before every active decision pass.

## Workflow

### Discovery & Scanning
1. **Mainstream scan** — Use `market_probe.py bybit-ticker` or ccxt for liquid coins.
   - Look for: breakouts, volume spikes, S/R flips, trend alignment.
2. **Meme scan** — Use `web_search` + `dex-search` / `gecko-search` for narrative heat.
   - Look for: accelerating attention, DEX flow, CEX listing rumors, social spread.
3. **Cross-compare** — Score the top 3-5 candidates against current holdings.

### Execution
1. Read balances and positions.
2. Pull market data for holdings and candidates.
3. Run the 6-question scientific checklist.
4. Decide: **HOLD** / **SELL_ALL** / **REBALANCE** / **BUY**.
5. Execute via `smart_executor.py`.
6. Log the full decision context with `logger.py`.

### Review (every hour)
1. Run `review_engine.py` to analyze all decisions from the past hour.
2. Compare decision prices to current prices.
3. Flag patterns: missed runs, bad entries, over-trading, hesitation.
4. Output recommendations for parameter or blacklist adjustments.
5. Save the review report to `~/.coinhunter/reviews/`.

## Auto-trading architecture

| Component | Path | Purpose |
|-----------|------|---------|
| `smart_executor.py` | `~/.coinhunter/smart_executor.py` | Order execution layer (market buy/sell/rebalance) |
| `logger.py` | `~/.coinhunter/logger.py` | Records decisions, trades, and market snapshots |
| `review_engine.py` | `~/.coinhunter/review_engine.py` | Hourly quality review and optimization suggestions |
| `market_probe.py` | `~/.hermes/skills/coinhunter/scripts/market_probe.py` | Market data fetcher |

### Execution schedule
- **Trade bot** — runs every 15-30 minutes via `cronjob`.
- **Review bot** — runs every 1-12 hours via `cronjob`, depending on how much manual oversight is needed.

### Low-cost cron architecture
When model cost or quota is tight, do not let every cron run perform full analysis from scratch.

Recommended pattern:
1. Attach a lightweight Python `script` to the cron job (under `~/.hermes/scripts/`) that fetches balances/tickers, computes hashes, and emits compact JSON context.
2. Cache the last observed positions, top candidates, market regime, and `last_deep_analysis_at` under `~/.coinhunter/state/`.
3. Trigger full analysis only when one of these changes materially. Make the thresholds adaptive instead of fixed:
   - position structure changes (hard trigger)
   - per-position price/PnL moves beyond thresholds that widen for micro-capital / dust accounts and narrow during higher-volatility sessions
   - top candidate leadership changes materially, but discount this signal when free USDT is below actionable exchange minimums
   - BTC/ETH regime changes (hard trigger)
   - a max staleness timer forces refresh, with longer refresh windows for micro accounts to avoid pointless re-analysis
4. In the cron prompt, if the injected context says `should_analyze=false`, respond with exactly `[SILENT]` and do not call tools.
5. After a triggered deep-analysis pass completes, acknowledge it from the agent (for example by running the precheck script with an `--ack` flag) so the trigger is cleared.
7. For even lower spend, move the high-frequency cadence outside Hermes cron entirely:
   - install a system `crontab` entry that runs a local gate script every 5-10 minutes
   - let that gate script run the lightweight precheck
   - only when `should_analyze=true` and no run is already queued, trigger the Hermes cron job via `hermes cron run <job_id>`
   - store a `run_requested_at` marker in `~/.coinhunter/state/precheck_state.json` and clear it when the analysis acknowledges completion

This pattern preserves Telegram auto-delivery from Hermes cron while reducing model wakeups to trigger-only events.

### Practical production notes for external gate mode
- Put the external gate itself on system `crontab` (for example every 5 minutes) rather than on Hermes cron. That keeps the high-frequency loop completely local and model-free.
- Keep the Hermes trading cron job on a low-frequency fallback schedule (for example once daily at 05:00 local time) so the main execution path remains trigger-driven.
- Add a file lock around the external gate script so overlapping system-cron invocations cannot double-trigger.
- Rotate `~/.coinhunter/logs/external_gate.log` with `logrotate` (daily, keep ~14 compressed copies, `copytruncate`) and schedule the rotation a few minutes after the fallback Hermes cron run so they do not overlap.

### Production hardening (mandatory)
The live trading stack must include these safeguards:
1. **Idempotency** — every decision carries a `decision_id`. The executor checks `~/.coinhunter/executions.json` before submitting orders to prevent duplicate trades.
2. **Exchange reconciliation** — before every run, pull real Binance balances and recent trades to sync `positions.json`. Do not trust local state alone.
3. **File locking + atomic writes** — `positions.json` and `executions.json` are updated under a file lock and written to a temp file before atomic rename.
4. **Order precision validation** — read Binance `lotSize`, `stepSize`, and `minNotional` filters via ccxt before any order. Round quantities correctly and reject orders below minimums.
5. **Fee buffer** — keep ~2%-5% USDT unallocated so that slippage and fees do not cause "insufficient balance" rejections.
6. **Structured logging** — every decision, trade, error, and balance snapshot is written as JSONL under `~/.coinhunter/logs/` with `schema_version` and `decision_id`.
7. **Error logging** — failed API calls, rejected orders, and reconciliation mismatches are captured in `logs/errors_YYYYMMDD.jsonl` and fed into the hourly review.

## Safety rules
- No leverage/futures when capital < $200.
- When capital < $50, concentrate into **1 position only**.
- Always leave 2%-5% USDT buffer for fees and slippage.
- Blacklist updates should be driven by review findings.

## Position sizing

| Total Capital | Strategy |
|---------------|----------|
| < $50 | Single-coin concentration (mainstream or meme) |
| $50 – $200 | 60% mainstream + 40% meme, max 2 positions |
| > $200 | Up to 3 positions with stricter risk per position |

## Output style

### For live decisions
Concise Telegram-style report:
- Current holdings + live PnL
- Top 1-2 opportunities found
- Decision and exact reasoning
- Action confirmation (or [DRY RUN] note)

### For hourly reviews
Use `references/review-template.md` structure:
- Decision quality breakdown
- Market context
- Strategy adjustments recommended
- Action items for next hour

## References

Read `references/provider-playbook.md` for data source selection.
Read `references/user-data-layout.md` for private state management.
Read `references/short-term-trading-framework.md` for the hybrid trading framework.
Read `references/review-template.md` for hourly report formatting.
Read `references/scam-signals.md` when evaluating meme coins.