Use cases

Common patterns that combine several endpoints. Use them as a starting point for whatever you're building.

Token scanner

You want to surface interesting tokens as they appear, filter by quality, and let a user drill into one.

Landing list → poll /v1/tokens/new or subscribe to tokens:live for token_created.
Quality filter → each list card already carries score, pump_conditions_met, alpha_hands_pct, chart_nukers_pct, dirty_pct, and duplication. No follow-up fetch needed to sort or gate.
Detail view → /v1/tokens/:mint for one call that returns everything. Use ?fields= to trim.
Recent activity → /v1/tokens/:mint/trades.

You want to alert on interesting wallets — a specific KOL, a smart-money wallet, or every trade above N SOL.

Wallet profile → /v1/traders/:address for the wallet's cached stats.
Live trades → subscribe to frames:live and filter client-side by user_address. Every trade carries the trader's snapshot at trade time, so you don't have to correlate with a separate stats fetch.
Smart-money leaderboard → poll /v1/tokens/pumps and drill in with /v1/tokens/:mint/trades; filter for smart_money: true.

You want a UI that visualises real-time flow — buys vs sells, bundle activity, chart nukers appearing, KOLs entering.

Initial state → /v1/tokens/:mint on page load.
Live delta → subscribe to frames:live, filter to your mint, update UI on each frame.
Lifecycle transitions → subscribe to tokens:live for graduation / DEX-paid banners.
Periodic re-snapshot — optional. If you're maintaining an aggregate view (top holders, cohort distributions), re-poll /v1/tokens/:mint every 30-60s to catch state changes that don't come through the trade firehose.

Question you're answering	Best fit
"What's the state of X right now?"	REST snapshot
"Show me what changed since the last time I looked."	REST poll + client-side diff
"Tell me the instant Y happens."	WebSocket
"I need every trade, in order, with no gaps."	WebSocket (`frames:live`)
"I need a leaderboard / dashboard."	REST poll (~2s cadence)