# Sluice — SPEC v1.1

## Problem
Fresh Solana launches print huge charts on thin pools. On 2026-10-02, $www showed $2.6M mcap on ~$200K liquidity (+5290% 24h, $24.6M vol); $CATGPT $191K mcap on $49K liq; $SOCKET $288K on $54K. A holder sees "mcap × my %" and believes it. The exit door is much smaller, and a large share of volume is non-organic.

## User
Trench trader holding or about to ape a <7-day-old coin. Wants: "what does my bag actually sell for right now?"

## Core loop
1. Exit Board → hot fresh launches ranked by the haircut on a $1K/$10K/$50K sell.
2. Tap a coin / paste a mint + bag → Exit Receipt: quotes over a ladder of sizes, haircut %, where the door narrows. Copy, share, post to public feed, AI one-liner.
3. Call the Haircut: 5 rounds, guess the % lost, quote reveals, score → leaderboard.

## Features (live)
- index.html Exit Board: fresh (<7d), liq ≥ $10K, sorted by haircut. Columns mcap, liq, vol 24h, liq/mcap, organic (Jupiter only), haircut, you get. Worst-exit headline. Public receipts feed (_api/receipts).
- exit.html Exit Receipt: mint + USD bag; ladder $100/$1K/$5K/$10K/$25K/$50K; route DEXes; copy receipt/link; POST _api/receipts {mint,sym,usd,real,hc,mcap,est}; AI verdict via _ai (numbers-only prompt, no advice). Hot-now chips.
- game.html Call the Haircut: 5 rounds, random token + size ($1K–$25K), slider 0–90%, score/round = 100×(1−miss/25pp), max 500. POST _api/scores {name,score,avgMiss,rounds,est}; leaderboard = best per name.

## Resilience (v1.1)
Jupiter lite-api 429s through the shared proxy often. Circuit breaker: after a 429, skip Jupiter for 60 s.
- List fallback: DexScreener boosted + latest profiles as candidates → /tokens/v1 batch → fresh, vol>$50K, liq≥$10K, ranked by 24h volume.
- Quote fallback: constant-product estimate. Q = summed SOL/USDC/USDT pool liquidity / 2; realized = Q·X/(Q+X)·(1−0.3%). Always tagged "est." in UI, feed and leaderboard. Concentrated pools can be worse — said in UI.

## Data sources (verified via fetch_url)
- lite-api.jup.ag/tokens/v2/toptraded/24h?limit=100 → tokens {id,symbol,icon,decimals,usdPrice,mcap,liquidity,firstPool{createdAt},stats24h{buyVolume,sellVolume,buyOrganicVolume,sellOrganicVolume}}
- lite-api.jup.ag/tokens/v2/search?query=<mint> → same shape, array
- lite-api.jup.ag/swap/v1/quote?inputMint=<mint>&outputMint=So111…112&amount=<raw>&slippageBps=5000 → {outAmount, routePlan[{swapInfo{label}}]}
- lite-api.jup.ag/price/v3?ids=So111…112 → {<mint>:{usdPrice}}
- api.dexscreener.com/latest/dex/tokens/<mint> → {pairs:[{chainId,dexId,baseToken,quoteToken,priceUsd,txns.h24,volume.h24,liquidity.usd,marketCap,pairCreatedAt,info.imageUrl}]}
- api.dexscreener.com/tokens/v1/solana/<m1,m2,…≤30> → array of same pair objects
- api.dexscreener.com/token-boosts/top/v1, /token-boosts/latest/v1, /token-profiles/latest/v1 → [{chainId,tokenAddress}]
- api.dexscreener.com/latest/dex/pairs/solana/Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE → Orca SOL/USDC, SOL price fallback

## Next
- Cache last real Jupiter board snapshot in _api so 429 periods show real quotes with timestamp.
- Wallet paste → read bag via _chain/balance → receipt for the exact bag.
- Coin: holder tiers unlock bigger ladders / seasons on the game.

## Out of scope
Wallet connect, executing trades, non-Solana chains, historical charts.