Initial commit: coin-hunter skill

references/provider-playbook.md

@@ -0,0 +1,92 @@
+# Provider Playbook
+
+Use this reference when the user wants fresher crypto market data instead of relying only on web search.
+
+## Source roles
+
+### Bybit
+Use for:
+- real-time-ish price
+- 24h turnover / volume
+- tradability check
+- kline context for listed pairs
+
+Prefer Bybit first when the coin has a clear CEX symbol like `BTCUSDT`, `ETHUSDT`, `BONKUSDT`, etc.
+
+### DexScreener
+Use for:
+- meme-coin discovery
+- DEX liquidity / pair context
+- chain and pool identification
+- faster read on small-cap or newly-hot coins
+
+Prefer DexScreener when:
+- the coin is meme-heavy
+- it may not be on major CEXs
+- you need pair/liquidity context more than exchange execution context
+
+### Birdeye
+Use for:
+- Solana meme-coin discovery
+- Solana token activity and pair context
+- confirming whether a Solana coin has genuine participation
+
+Birdeye is especially useful when Solana names appear early in discovery.
+
+### CoinGecko
+Use for:
+- market-cap cross-check
+- ranking / metadata / basic overview
+- fallback verification when exchange or DEX data is messy
+
+Use CoinGecko to sanity-check whether the coin is a real market object with broad coverage.
+
+## Recommended order
+
+### For a known Bybit-listed coin
+1. Bybit
+2. CoinGecko
+3. DexScreener if meme angle matters
+
+### For a meme / 妖币 candidate
+1. DexScreener
+2. Birdeye if Solana
+3. CoinGecko
+4. Bybit only if it is also listed there
+
+### For discovery mode
+1. web_search to gather candidate names
+2. DexScreener to confirm pair/liquidity reality
+3. Birdeye for Solana candidates
+4. CoinGecko for market-cap verification
+5. Bybit to see whether the name graduated into a major tradable venue
+
+## What each source answers
+
+- **Bybit** → "Can I trade it on a major venue, and what does the market look like right now?"
+- **DexScreener** → "Does it actually have live DEX flow and liquidity?"
+- **Birdeye** → "Is the Solana on-chain activity real enough to care about?"
+- **CoinGecko** → "How big is it, and is it broadly recognized?"
+
+## Practical rule
+
+Do not make conviction from a single source.
+
+For high-risk coins, prefer at least two independent checks:
+- one trading/liquidity source
+- one metadata/market-cap source
+
+## Token identity hygiene
+
+DexScreener search can return clones, stale pairs, and same-name distractions.
+
+Before treating a result as the real target, prefer the pair that has:
+- the strongest 24h volume and usable liquidity
+- a market cap / FDV that roughly matches CoinGecko or other broad coverage sources
+- a chain and venue context that fits the narrative you are checking
+
+If search results show multiple same-name tokens, explicitly say which contract or pair you are treating as the primary one.
+
+## Script usage
+
+Use `scripts/market_probe.py` for deterministic lookups instead of redoing provider URLs by hand.