Introduction
Conventions shared by every REST endpoint.
The REST API is the set of Next.js route handlers in app/api that the Stargaze app uses for its own screens. Every public endpoint is a read-only GET that returns JSON. There is no authentication and no API key — requests are served from the same origin as the app.
Base URL
Endpoints are relative to the origin the app is deployed on (NEXT_PUBLIC_SITE_URL, http://localhost:3000 in development). All route handlers are force-dynamic: they run on every request and read from the server-side cache described below.
curl "http://localhost:3000/api/market/tokens?category=trending"Endpoints
| Endpoint | Purpose | Reference |
|---|---|---|
GET /api/market/overview | Ethereum-ecosystem totals + Stargaze platform counters | Market & search |
GET /api/market/tokens | Token lists by category | Market & search |
GET /api/search | Token search by name, symbol or address | Market & search |
GET /api/token/{chainId}/{address} | Token detail | Tokens |
GET /api/token/{chainId}/{address}/ohlcv | Candles for a pool (mainnet only) | Tokens |
GET /api/token/{chainId}/{address}/trades | Recent pool trades (mainnet only) | Tokens |
GET /api/launches | Stargaze launches from contract events | Launches & analytics |
GET /api/analytics | Platform + market analytics | Launches & analytics |
GET /api/portfolio/{address} | Wallet balances, valuation, transactions | Portfolio |
GET /api/eth-price | ETH/USD and 24h change | ETH price & $STFI |
GET /api/stfi | $STFI status and market data | ETH price & $STFI |
Response envelope
Successful responses wrap the payload in an envelope (the Envelope<T> type in lib/types.ts). updatedAt is when the data was fetched from its provider — not when you requested it.
type Envelope<T> = { data: T; updatedAt: number; // ms epoch of the underlying fetch stale: boolean; // true = provider failed, this is the last good value source: string; // human-readable provider description error?: string; // provider error message when stale};Not every endpoint returns every field. The table lists exactly what each handler sends:
| Endpoint | Fields |
|---|---|
/api/market/overview, /ohlcv, /trades, /api/eth-price | data, updatedAt, stale, source, error? (via ok() in lib/server/respond.ts) |
/api/market/tokens | data, updatedAt, stale, source, error? |
/api/launches | data, updatedAt, stale, source |
/api/token/{chainId}/{address}, /api/portfolio/{address}, /api/analytics | data, updatedAt, stale |
/api/search | data, updatedAt (only data when the query is shorter than 2 characters) |
/api/stfi | data (+ updatedAt once $STFI is live) |
Errors
Failures use the fail() helper from lib/server/respond.ts and keep the same shape, with data: null:
{ "data": null, "error": "429 from api.geckoterminal.com", "updatedAt": 1731974400000, "stale": true}| Status | When |
|---|---|
400 | Invalid input: unknown category, invalid pool or tf, invalid wallet address. |
404 | Token is not an ERC-20 on that network, or a mainnet-only endpoint was called with another chain id. |
502 | Default for any upstream/provider failure when there is no cached value to fall back on. |
Networks and chainId
Endpoints that take a chainId query parameter (/api/market/overview, /api/market/tokens, /api/launches, /api/analytics, /api/portfolio/{address}) accept 1 (Ethereum) and 11155111 (Sepolia). Any other or missing value silently falls back to the deployment's default chain — NEXT_PUBLIC_DEFAULT_CHAIN_ID, which is Sepolia unless it is set to 1. It does not return an error.
| Endpoint | Mainnet only? |
|---|---|
/ohlcv, /trades | Yes — any chainId other than 1 returns 404. |
/api/market/tokens | Every category except launched is Ethereum-mainnet market data regardless of chainId. |
/api/search | Yes — results are always mainnet rows (chainId: 1). |
/api/token/{chainId}/{address} | Works on both; on Sepolia only on-chain fields are filled and market fields are null. |
/api/portfolio/{address} | Works on both; prices, totalValueUsd and history are mainnet only. |
/api/analytics | platform follows chainId; tradingVolume24h / totalLiquidity are mainnet only; ethereum is always mainnet. |
Common types
Most list endpoints return TokenRow objects. null always means unknown — values are never estimated or fabricated.
type TokenRow = { chainId: number; address: `0x${string}`; // checksummed name: string; symbol: string; // upper-case logo: string | null; priceUsd: number | null; change1h: number | null; // percent change24h: number | null; // percent marketCap: number | null; fdv: number | null; liquidity: number | null; // USD volume24h: number | null; // USD txns24h: number | null; createdAt: number | null; // ms epoch (pool / launch creation) poolAddress: string | null; dex: string | null; listed: boolean; // listed on CoinGecko or a trusted token list sparkline?: number[] | null; // CoinGecko rows only (7d, every 4th point) source: "coingecko" | "geckoterminal" | "dexscreener" | "onchain" | "stargaze"; stargaze?: boolean; // launched through Stargaze};Caching
Each provider call is wrapped in cached(key, ttl, fn) from lib/server/cache.ts: an in-process map (up to 2,000 entries) plus Redis when REDIS_URL is set. Concurrent requests for the same key share one upstream call. Per-endpoint TTLs are listed on each reference page; see Data sources & caching for the full model.
Some routes also send an HTTP Cache-Control header for CDNs. Routes not listed set no Cache-Control header of their own.
| Endpoint | Cache-Control |
|---|---|
/api/market/overview | public, s-maxage=60, stale-while-revalidate=240 |
/api/market/tokens | public, s-maxage=30, stale-while-revalidate=120 |
/api/token/…/ohlcv | public, s-maxage=30, stale-while-revalidate=120 |
/api/token/…/trades | public, s-maxage=15, stale-while-revalidate=60 |
/api/eth-price | public, s-maxage=60, stale-while-revalidate=240 |
Rate limits
The API has no built-in rate limiting — the route handlers do not count or reject requests per client. It is, however, subject to the limits of its upstream providers (CoinGecko, GeckoTerminal, DexScreener, Etherscan and your RPC provider). To stay within them, lib/server/http.ts spaces outgoing calls per host within each server process:
| Provider host | Minimum gap between calls | Comment in code |
|---|---|---|
api.coingecko.com | 1,300 ms | public/demo ≈ 30 req/min |
api.geckoterminal.com | 2,100 ms | 30 req/min |
api.dexscreener.com | 220 ms | 300 req/min |
api.etherscan.io | 220 ms | 5 req/s |
Upstream 429 and 5xx responses are retried up to 2 times, honouring Retry-After when present (otherwise 800 ms × 2ⁿ back-off); each attempt times out after 10 s. On a cold cache a burst of requests therefore queues behind the throttle rather than failing — expect latency, and cache on your side.
