Data sources & caching
Which provider powers which number, and how freshness works.
Stargaze does not run its own market-data feed. Server code in lib/services calls public providers and the chain, normalises the results into TokenRow / TokenDetail, and caches them. Provider keys stay on the server; the browser only talks to /api.
Providers
| Provider | Used for | Configuration |
|---|---|---|
| CoinGecko | Ethereum-ecosystem ERC-20 markets (top 500 by market cap or volume), category totals, ETH/USD, coin-by-contract detail, 30-day price history for portfolio history | Public API by default; COINGECKO_API_KEY + COINGECKO_PLAN (demo / pro) |
| GeckoTerminal | Trending / new / top Ethereum pools, a token's pools, token info (holders, socials), OHLCV, trades | Public API, no key |
| DexScreener | Best (highest-liquidity) pair per token: liquidity, txns, 1h change, pool; search | Public API, no key |
| Etherscan V2 | Contract verification badge, wallet tx history, fallback token discovery | ETHERSCAN_API_KEY (features are null / empty without it) |
| Ethereum RPC | ERC-20 metadata and balances (multicall), bytecode checks, Stargaze events, block timestamps | MAINNET_RPC_URL / SEPOLIA_RPC_URL, falling back to viem's default public RPC |
| Alchemy | Portfolio token discovery (alchemy_getTokenBalances) | ALCHEMY_API_KEY (optional) |
| Uniswap token list | Logo fallback, keyed by chain id + address | https://tokens.uniswap.org, cached 24 h |
Market providers are queried for Ethereum mainnet only (geckoTerminalNetwork and dexScreenerChain have no Sepolia entry). On Sepolia only RPC-derived data exists.
Cache layers
- In-process map — up to 2,000 entries; the oldest key is evicted first.
- Redis (optional,
REDIS_URL) — shared across instances; keys are prefixedsg:and kept for at least 24 hours so stale copies survive for stale-while-error. - In-flight de-duplication — concurrent misses for the same key share a single upstream request.
- CDN — some routes add
Cache-Control: public, s-maxage=…, stale-while-revalidate=…(see Caching).
Server TTLs
| Data | Cache key | TTL |
|---|---|---|
| Stargaze launch index | sg:launches:{chainId} | 30 s |
| Market overview | mk:overview:{chainId} | 60 s |
| Analytics | analytics:{chainId} | 60 s |
| Token detail | mk:detail:{chainId}:{address} | 45 s |
| Portfolio | pf:{chainId}:{owner} | 45 s |
| CoinGecko markets | cg:markets:{order} | 120 s |
| Volume / gainers / losers enrichment | mk:{category}:enriched | 120 s |
| CoinGecko category stats | cg:category:eth | 600 s |
| ETH price | cg:eth | 60 s |
| CoinGecko coin by contract | cg:contract:{address} | 300 s |
| CoinGecko market chart | cg:chart:{id}:{days} | 900 s |
| CoinGecko platform map | cg:platforms | 12 h |
| GeckoTerminal trending / new / top | gt:trending / gt:new / gt:top | 120 s / 60 s / 180 s |
| GeckoTerminal token pools / info | gt:tokenpools:… / gt:tokeninfo:… | 120 s / 3,600 s |
| OHLCV | gt:ohlcv:{pool}:{tf}:{side} | 30 s – 3,600 s by timeframe |
| Pool trades | gt:trades:{pool} | 20 s |
| DexScreener pairs / search | ds:tokens:… / ds:search:{q} | 60 s |
| Etherscan verification / tx lists | es:verified:… / es:txlist:… / es:tokentx:… | 3,600 s / 60 s / 60 s |
| Launch metadata JSON | meta:{uri} | 3,600 s |
| Uniswap token list | tokenlist:uniswap | 24 h |
Stale-while-error
When a cache entry has expired, cached() calls the provider. If that call fails and an older value exists, the old value is returned with stale: true, its original updatedAt and the provider message in error. Only when there is no previous value does the request fail (502). The app shows a stale warning in that case; your client should too.
type CacheResult<T> = { data: T; updatedAt: number; stale: boolean; error?: string }; // fresh hit -> { data, updatedAt: t, stale: false }// miss, fetch ok -> { data, updatedAt: now, stale: false }// miss, fetch fails -> { data: last good, updatedAt: t, stale: true, error } — or throw if noneUnknown values
- Every number that cannot be sourced is
nullin the API — never0, never an estimate. - The UI renders
nullas—, and sorting puts unknown values last. - Stargaze statistics come only from contract events;
graduatedstays0/[]while the bonding curve is not enabled. - Logos are resolved by chain id + checksummed address, never by ticker: launch metadata → CoinGecko → Uniswap token list → GeckoTerminal / DexScreener profile → neutral fallback.
- $STFI shows
PRE-LAUNCHwith no address, price or supply untilNEXT_PUBLIC_STFI_ADDRESSis set.
