# 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.