refactor: rewrite Coin Hunter as short-term trading framework with auto-trading architecture
This commit is contained in:
380
SKILL.md
380
SKILL.md
@@ -1,296 +1,164 @@
|
||||
---
|
||||
name: Coin Hunter
|
||||
description: Hunt, triage, and compare speculative crypto coins — especially meme coins, 妖币-style runners, fake-hype pumps, and possible rug/scam setups. Use when a user wants to actively search for coins with breakout potential, rank a shortlist, ask whether a coin still has "妖性", or check whether a token looks late, fragile, manipulated, or likely to be a scam.
|
||||
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
|
||||
|
||||
Use this skill to help a user search for and judge **high-volatility crypto setups** without pretending certainty.
|
||||
Coin Hunter is a **short-term trading framework**, not just a meme-coin scanner.
|
||||
|
||||
Default buckets:
|
||||
- **candidate runner** — has ingredients for further speculative expansion
|
||||
- **watch-only / incomplete** — interesting, but not clean enough yet
|
||||
- **late / overheated** — may still move, but entry quality is already poor
|
||||
- **avoid / scam-risk** — liquidity, distribution, credibility, or structure is too weak
|
||||
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.
|
||||
|
||||
Frame the work as **speculative pattern recognition**, not investment advice.
|
||||
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.
|
||||
|
||||
## Core rule
|
||||
## Portfolio-first rule
|
||||
|
||||
Judge a coin by **attention + liquidity + distribution + timing** first. Narrative matters, but only when it can attract and hold money.
|
||||
Always check the user's actual portfolio state under `~/.coinhunter/` before giving trade advice or executing orders.
|
||||
|
||||
A technically weak project can still become a runner. A sophisticated-looking project can still be dead money.
|
||||
Files to inspect:
|
||||
- `positions.json`
|
||||
- `accounts.json`
|
||||
- `logs/decisions_YYYYMMDD.jsonl`
|
||||
- `logs/trades_YYYYMMDD.jsonl`
|
||||
- `reviews/review_YYYYMMDD_HHMMSS.json`
|
||||
|
||||
## Supported request types
|
||||
Anchor all advice to the user's real balances, average costs, exchange, and current exposure.
|
||||
|
||||
Use this skill for four common modes:
|
||||
- **single-coin triage** — "look at this coin"
|
||||
- **active discovery** — "find me coins that could become 妖币"
|
||||
- **shortlist ranking** — "which of these 5 is most interesting"
|
||||
- **scam / rug check** — "is this coin just fake hype"
|
||||
## Supported modes
|
||||
|
||||
If the request is broad, ask at most **one compact clarifying question**. Prefer:
|
||||
- chain
|
||||
- theme / narrative
|
||||
- risk level
|
||||
- whether the user accepts microcaps or wants only reasonably tradable names
|
||||
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.
|
||||
|
||||
If no preference is given, default to: **liquid speculative candidates, not ultra-illiquid microcaps**.
|
||||
## 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
|
||||
|
||||
### 1. Identify the mode
|
||||
### 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.
|
||||
|
||||
Decide whether the user wants:
|
||||
- discovery
|
||||
- triage
|
||||
- comparison
|
||||
- scam-check
|
||||
### 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`.
|
||||
|
||||
Then bias the workflow accordingly.
|
||||
### 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/`.
|
||||
|
||||
### 2. Choose the data path
|
||||
## Auto-trading architecture
|
||||
|
||||
Use **structured market data first** when available. Use web search to discover names and collect context, not as the only source of truth.
|
||||
| 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 |
|
||||
|
||||
Preferred source order:
|
||||
- **Bybit** for real-time-ish price, 24h turnover, and tradability on a major venue
|
||||
- **DexScreener** for meme-coin pair discovery, DEX liquidity, and small-cap flow
|
||||
- **Birdeye** for Solana token activity and confirmation
|
||||
- **CoinGecko** for market-cap, rank, and metadata cross-check
|
||||
- **web_search** for discovery, narratives, and scam-discussion context
|
||||
### 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.
|
||||
|
||||
Private user state must live outside the skill directory under `~/.coinhunter/`, not inside `skills/coinhunter/`.
|
||||
Read `references/provider-playbook.md` when choosing which source to trust first.
|
||||
Read `references/user-data-layout.md` when adding or updating personal accounts, positions, watchlists, or notes.
|
||||
Use `scripts/market_probe.py` for deterministic provider lookups.
|
||||
Use `scripts/init_user_state.py` to initialize the private user-data directory.
|
||||
### Low-cost cron architecture
|
||||
When model cost or quota is tight, do not let every cron run perform full analysis from scratch.
|
||||
|
||||
### 3. Discovery mode: build a candidate list
|
||||
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
|
||||
|
||||
When the user wants active search rather than analysis of a known ticker, use public web sources to build a shortlist.
|
||||
This pattern preserves Telegram auto-delivery from Hermes cron while reducing model wakeups to trigger-only events.
|
||||
|
||||
Look for evidence of:
|
||||
- rising attention
|
||||
- listing or venue expansion
|
||||
- narrative/theme alignment
|
||||
- market-cap and liquidity context
|
||||
- breakout discussion or unusual participation
|
||||
### 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.
|
||||
|
||||
Useful search patterns include:
|
||||
- `<theme> meme coin trending`
|
||||
- `<chain> meme coin watchlist`
|
||||
- `new meme coin listed`
|
||||
- `<coin> market cap liquidity`
|
||||
- `<coin> holders tokenomics`
|
||||
- `<coin> rug risk`
|
||||
### 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.
|
||||
|
||||
Do not trust a single source or a single viral thread. Build the list first, then vet the names.
|
||||
## 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.
|
||||
|
||||
Read `references/search-workflow.md` for the detailed discovery flow.
|
||||
## Position sizing
|
||||
|
||||
### 4. Triage mode: score the coin on six dimensions
|
||||
|
||||
Assess each coin qualitatively across these dimensions.
|
||||
|
||||
#### A. Narrative fit
|
||||
Ask:
|
||||
- Is the story attached to a live theme?
|
||||
- Is the idea easy to repeat in one sentence?
|
||||
- Does the symbol / meme / framing have social spread potential?
|
||||
|
||||
Strong examples:
|
||||
- obvious meme identity
|
||||
- attached to a live chain or hot sector
|
||||
- easy cultural hook
|
||||
|
||||
Weak examples:
|
||||
- vague utility story
|
||||
- no memorable angle
|
||||
- cold or stale narrative
|
||||
|
||||
#### B. Attention acceleration
|
||||
Ask:
|
||||
- Is visibility rising now?
|
||||
- Is the coin spreading beyond its original niche?
|
||||
- Are larger accounts, aggregators, or trading communities starting to notice it?
|
||||
|
||||
Treat **acceleration** as more important than absolute popularity.
|
||||
|
||||
#### C. Liquidity quality
|
||||
Ask:
|
||||
- Can a normal user realistically enter and exit?
|
||||
- Is volume believable relative to market cap and attention?
|
||||
- Are spreads or venue quality obviously problematic?
|
||||
|
||||
If the user can probably buy but may not be able to exit cleanly, score this harshly.
|
||||
|
||||
#### D. Distribution / holder risk
|
||||
Ask:
|
||||
- Is ownership too concentrated?
|
||||
- Are deployer or team wallets still dangerous?
|
||||
- Is there an obvious unlock or dump overhang?
|
||||
|
||||
Ugly distribution does not automatically kill a trade, but it makes the setup fragile.
|
||||
|
||||
#### E. Timing / chart state
|
||||
Ask:
|
||||
- Is it emerging from a base or already vertical?
|
||||
- Has participation expanded recently?
|
||||
- Do pullbacks hold, or do they collapse?
|
||||
|
||||
Prefer:
|
||||
- fresh breakout from longer consolidation
|
||||
- early or mid-stage expansion
|
||||
- resilient retraces
|
||||
|
||||
Be cautious when:
|
||||
- it already went parabolic
|
||||
- volume fades after the first mania burst
|
||||
- price action is mostly wick-and-dump behavior
|
||||
|
||||
#### F. Rug / scam risk
|
||||
Check for:
|
||||
- fake partnerships or fake listing claims
|
||||
- unverifiable team paired with aggressive promotion
|
||||
- suspicious contract / public warning signals
|
||||
- impossible tokenomics promises
|
||||
- unverified liquidity-lock claims
|
||||
- nothing but shill posts and no independent discussion
|
||||
|
||||
One severe scam signal can outweigh several bullish ones.
|
||||
Read `references/scam-signals.md` when the user specifically asks about rugs, scams, fake hype, manipulation, or exit-liquidity bait.
|
||||
|
||||
### 5. Classify the result
|
||||
|
||||
Use these buckets:
|
||||
|
||||
#### Candidate runner
|
||||
Use when most are true:
|
||||
- narrative is live
|
||||
- attention is accelerating
|
||||
- liquidity is usable
|
||||
- timing is not obviously exhausted
|
||||
- no fatal scam / exit-risk signal is present
|
||||
|
||||
#### Watch-only / incomplete
|
||||
Use when:
|
||||
- something is interesting, but evidence is incomplete
|
||||
- narrative is decent but timing is unclear
|
||||
- liquidity or distribution is acceptable but not clean
|
||||
- it deserves monitoring more than action
|
||||
|
||||
#### Late / overheated
|
||||
Use when:
|
||||
- the move is already widely noticed
|
||||
- chart is extended or near blow-off behavior
|
||||
- upside may remain, but entry quality is poor
|
||||
- new buyers are at risk of becoming exit liquidity
|
||||
|
||||
#### Avoid / scam-risk
|
||||
Use when:
|
||||
- liquidity quality is bad
|
||||
- exit risk is high
|
||||
- holder concentration is dangerous
|
||||
- legitimacy claims are weak or fake
|
||||
- the setup feels more fabricated than organic
|
||||
|
||||
## Provider execution patterns
|
||||
|
||||
### Known tradable coin
|
||||
If the user gives a Bybit-listed ticker or asks for current price/tradability:
|
||||
1. run `python3 scripts/market_probe.py bybit-ticker <SYMBOL>`
|
||||
2. optionally run `python3 scripts/market_probe.py bybit-klines <SYMBOL> --interval 60 --limit 10`
|
||||
3. cross-check with CoinGecko when market-cap context matters
|
||||
|
||||
### Meme / 妖币 discovery
|
||||
If the user wants runners, meme coins, or small-cap candidates:
|
||||
1. use `web_search` to gather names
|
||||
2. run `python3 scripts/market_probe.py dex-search <name>` for the strongest candidates
|
||||
3. if Solana, run Birdeye when API access is configured
|
||||
4. use CoinGecko to verify market-cap and ranking
|
||||
5. only use Bybit if the coin is also on a major CEX
|
||||
|
||||
### Birdeye requirement
|
||||
`market_probe.py birdeye-token <address>` requires `BIRDEYE_API_KEY` in the environment. If it is not configured, say so briefly and continue with DexScreener + CoinGecko + web search.
|
||||
|
||||
### Private portfolio state
|
||||
If the user wants account, position, watchlist, or thesis tracking for coinhunter:
|
||||
1. initialize `~/.coinhunter/` with `python3 scripts/init_user_state.py`
|
||||
2. store private data only there
|
||||
3. never place personal holdings inside the skill folder
|
||||
4. treat the skill folder as logic only, and the user-data directory as state only
|
||||
| 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
|
||||
|
||||
Default to **compact, decision-first** answers.
|
||||
### 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 a single coin, include:
|
||||
- **Verdict**
|
||||
- **Radar score** — use the 0-12 checklist when evidence is sufficient
|
||||
- **Why it could run** — 2-4 bullets
|
||||
- **Why it could fail** — 2-4 bullets
|
||||
- **What confirms strength**
|
||||
- **What kills the thesis**
|
||||
- **Risk line** — clearly state this is speculative, not investment advice
|
||||
|
||||
For multiple coins:
|
||||
1. rank the shortlist
|
||||
2. mark each as candidate runner / watch-only / late / avoid
|
||||
3. state the main attraction and main flaw for each
|
||||
|
||||
Prefer bullets, short sections, and hard judgments over long essays.
|
||||
Use `references/output-templates.md` when you want a reusable answer skeleton.
|
||||
|
||||
## Practical heuristics
|
||||
|
||||
### Often bullish for speculative expansion
|
||||
- the meme or story is instantly repeatable
|
||||
- attention is accelerating, not just present
|
||||
- volume expands with the move
|
||||
- pullbacks are bought
|
||||
- exchange accessibility improves
|
||||
- more mainstream crypto accounts begin to mention it
|
||||
|
||||
### Often a sign it is late
|
||||
- everyone is already talking about it
|
||||
- the chart has been vertical for days
|
||||
- promotion is everywhere after the main move already happened
|
||||
- price keeps spiking while structure gets messier
|
||||
|
||||
### Often a sign to avoid
|
||||
- no trustworthy liquidity information
|
||||
- suspicious ownership concentration
|
||||
- clearly manufactured chart behavior
|
||||
- incoherent or constantly shifting explanation
|
||||
- obviously botted or repetitive social activity
|
||||
|
||||
## What not to do
|
||||
|
||||
- Do not describe a coin as safe.
|
||||
- Do not confuse a polished whitepaper with breakout potential.
|
||||
- Do not imply expected returns.
|
||||
- Do not recommend leverage.
|
||||
- Do not ignore slippage and exit risk.
|
||||
- Do not push microcaps on beginners unless the user explicitly asks for extreme risk.
|
||||
|
||||
## Optional deeper pass
|
||||
|
||||
If the user wants more depth, expand in this order:
|
||||
1. narrative and timing
|
||||
2. liquidity and market structure
|
||||
3. holder / tokenomics risk
|
||||
4. why it could become a runner
|
||||
5. why it probably will not
|
||||
6. watch triggers
|
||||
### 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 source selection and provider roles.
|
||||
Read `references/user-data-layout.md` for private state layout under `~/.coinhunter/`.
|
||||
Read `references/radar-checklist.md` for a quick scoring framework.
|
||||
Read `references/search-workflow.md` for active discovery.
|
||||
Read `references/output-templates.md` for compact response structure.
|
||||
Read `references/scam-signals.md` for sharper scam / fake-hype judgment.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user