Skip to content

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.

terminal
curl "http://localhost:3000/api/market/tokens?category=trending"

Endpoints

EndpointPurposeReference
GET /api/market/overviewEthereum-ecosystem totals + Stargaze platform countersMarket & search
GET /api/market/tokensToken lists by categoryMarket & search
GET /api/searchToken search by name, symbol or addressMarket & search
GET /api/token/{chainId}/{address}Token detailTokens
GET /api/token/{chainId}/{address}/ohlcvCandles for a pool (mainnet only)Tokens
GET /api/token/{chainId}/{address}/tradesRecent pool trades (mainnet only)Tokens
GET /api/launchesStargaze launches from contract eventsLaunches & analytics
GET /api/analyticsPlatform + market analyticsLaunches & analytics
GET /api/portfolio/{address}Wallet balances, valuation, transactionsPortfolio
GET /api/eth-priceETH/USD and 24h changeETH price & $STFI
GET /api/stfi$STFI status and market dataETH 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.

lib/types.ts
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:

EndpointFields
/api/market/overview, /ohlcv, /trades, /api/eth-pricedata, updatedAt, stale, source, error? (via ok() in lib/server/respond.ts)
/api/market/tokensdata, updatedAt, stale, source, error?
/api/launchesdata, updatedAt, stale, source
/api/token/{chainId}/{address}, /api/portfolio/{address}, /api/analyticsdata, updatedAt, stale
/api/searchdata, updatedAt (only data when the query is shorter than 2 characters)
/api/stfidata (+ updatedAt once $STFI is live)

Errors

Failures use the fail() helper from lib/server/respond.ts and keep the same shape, with data: null:

502 Bad Gateway
{  "data": null,  "error": "429 from api.geckoterminal.com",  "updatedAt": 1731974400000,  "stale": true}
StatusWhen
400Invalid input: unknown category, invalid pool or tf, invalid wallet address.
404Token is not an ERC-20 on that network, or a mainnet-only endpoint was called with another chain id.
502Default 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.

EndpointMainnet only?
/ohlcv, /tradesYes — any chainId other than 1 returns 404.
/api/market/tokensEvery category except launched is Ethereum-mainnet market data regardless of chainId.
/api/searchYes — 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/analyticsplatform 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.

lib/types.ts
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.

EndpointCache-Control
/api/market/overviewpublic, s-maxage=60, stale-while-revalidate=240
/api/market/tokenspublic, s-maxage=30, stale-while-revalidate=120
/api/token/…/ohlcvpublic, s-maxage=30, stale-while-revalidate=120
/api/token/…/tradespublic, s-maxage=15, stale-while-revalidate=60
/api/eth-pricepublic, 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 hostMinimum gap between callsComment in code
api.coingecko.com1,300 mspublic/demo ≈ 30 req/min
api.geckoterminal.com2,100 ms30 req/min
api.dexscreener.com220 ms300 req/min
api.etherscan.io220 ms5 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.

Internal routes