Skip to content

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

ProviderUsed forConfiguration
CoinGeckoEthereum-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 historyPublic API by default; COINGECKO_API_KEY + COINGECKO_PLAN (demo / pro)
GeckoTerminalTrending / new / top Ethereum pools, a token's pools, token info (holders, socials), OHLCV, tradesPublic API, no key
DexScreenerBest (highest-liquidity) pair per token: liquidity, txns, 1h change, pool; searchPublic API, no key
Etherscan V2Contract verification badge, wallet tx history, fallback token discoveryETHERSCAN_API_KEY (features are null / empty without it)
Ethereum RPCERC-20 metadata and balances (multicall), bytecode checks, Stargaze events, block timestampsMAINNET_RPC_URL / SEPOLIA_RPC_URL, falling back to viem's default public RPC
AlchemyPortfolio token discovery (alchemy_getTokenBalances)ALCHEMY_API_KEY (optional)
Uniswap token listLogo fallback, keyed by chain id + addresshttps://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 prefixed sg: 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

DataCache keyTTL
Stargaze launch indexsg:launches:{chainId}30 s
Market overviewmk:overview:{chainId}60 s
Analyticsanalytics:{chainId}60 s
Token detailmk:detail:{chainId}:{address}45 s
Portfoliopf:{chainId}:{owner}45 s
CoinGecko marketscg:markets:{order}120 s
Volume / gainers / losers enrichmentmk:{category}:enriched120 s
CoinGecko category statscg:category:eth600 s
ETH pricecg:eth60 s
CoinGecko coin by contractcg:contract:{address}300 s
CoinGecko market chartcg:chart:{id}:{days}900 s
CoinGecko platform mapcg:platforms12 h
GeckoTerminal trending / new / topgt:trending / gt:new / gt:top120 s / 60 s / 180 s
GeckoTerminal token pools / infogt:tokenpools:… / gt:tokeninfo:…120 s / 3,600 s
OHLCVgt:ohlcv:{pool}:{tf}:{side}30 s – 3,600 s by timeframe
Pool tradesgt:trades:{pool}20 s
DexScreener pairs / searchds:tokens:… / ds:search:{q}60 s
Etherscan verification / tx listses:verified:… / es:txlist:… / es:tokentx:…3,600 s / 60 s / 60 s
Launch metadata JSONmeta:{uri}3,600 s
Uniswap token listtokenlist:uniswap24 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.

lib/server/cache.ts
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 none

Unknown values

  • Every number that cannot be sourced is null in the API — never 0, never an estimate.
  • The UI renders null as —, and sorting puts unknown values last.
  • Stargaze statistics come only from contract events; graduated stays 0 / [] 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-LAUNCH with no address, price or supply until NEXT_PUBLIC_STFI_ADDRESS is set.