Skip to content

Tokens

Token detail, price history and recent trades.

Per-token endpoints. Token detail works on both supported networks and always starts from the chain: if the address has no bytecode or does not answer symbol() and decimals(), it is not treated as a token. Price history and trades come from GeckoTerminal and are Ethereum mainnet only.

GET /api/token/{chainId}/{address}

GET/api/token/{chainId}/{address}
PathTypeDescription
chainId1 or 11155111Unsupported values return 404.
addressaddressAny casing; normalised to checksum.

Returns 404 with "Not an ERC-20 token on this network" when the chain is unsupported, the address is invalid, there is no contract code, or symbol() / decimals() cannot be read. Server cache: 45 s per token.

lib/types.ts
type TokenDetail = {  row: TokenRow;  description: string | null;   // HTML stripped, max 2,000 chars  links: { website?: string; x?: string; telegram?: string; discord?: string };  totalSupply: string | null;   // decimal string, whole tokens  circulatingSupply: number | null;  decimals: number | null;  holders: number | null;       // GeckoTerminal token info  contractVerified: boolean | null; // null without ETHERSCAN_API_KEY or if Etherscan is down  coingeckoId: string | null;  pools: { address: string; name: string; dex: string; liquidity: number | null; volume24h: number | null }[]; // max 8  stargaze: StargazeLaunch | null; // set when launched through Stargaze};
  • name, symbol, decimals and totalSupply are always read on-chain via multicall.
  • On mainnet, price and market fields come from CoinGecko (by contract) first, then the best DexScreener pair; pools and holders from GeckoTerminal.
  • On Sepolia, CoinGecko, GeckoTerminal and DexScreener are skipped — market fields are null and pools is [].
  • Description and social links prefer the Stargaze launch metadata (metadataURI), then GeckoTerminal, then CoinGecko.

GET /api/token/{chainId}/{address}/ohlcv

GET/api/token/1/{address}/ohlcv?pool={pool}&tf={tf}Ethereum mainnet only
ParamInDefaultDescription
chainIdpath—Must be 1; otherwise 404 "Price history is only available on Ethereum mainnet".
addresspath—Not used by the handler — candles are keyed by pool.
poolqueryrequiredPool address (e.g. row.poolAddress). Invalid → 400 "Invalid pool or timeframe".
tfquery1hOne of the timeframes below. Invalid → 400.
sidequerybasebase or quote — which token of the pool to price (passed to GeckoTerminal as token).
tfCandle sizeCandlesServer TTL
5m5 minutes30030 s
15m15 minutes30060 s
1h1 hour300120 s
4h4 hours300300 s
24h15 minutes9660 s
7d1 hour168300 s
30d4 hours180600 s
all1 day1,0003,600 s
200 OK
{  "data": [    { "time": 1731970800, "open": 7.38, "high": 7.45, "low": 7.36, "close": 7.41, "volume": 182340.5 }  ],  "updatedAt": 1731974400000,  "stale": false,  "source": "GeckoTerminal OHLCV"}

time is a Unix timestamp in seconds (as delivered by GeckoTerminal), prices and volume are in USD, sorted oldest first.

GET /api/token/{chainId}/{address}/trades

GET/api/token/1/{address}/trades?pool={pool}Ethereum mainnet only
ParamInDescription
chainIdpathMust be 1; otherwise 404 "Trade history is only indexed on Ethereum mainnet".
addresspathThe token whose side of each trade is reported. Invalid → 400 "Invalid pool".
poolqueryRequired pool address. Invalid → 400 "Invalid pool".
lib/types.ts
type Trade = {  hash: string;  kind: "buy" | "sell";  timestamp: number;          // ms epoch  priceUsd: number | null;    // price of {address} in this trade  volumeUsd: number | null;  tokenAmount: number | null; // amount of {address}  wallet: string;             // tx sender};

Up to 60 of the pool's most recent trades. Server cache: 20 s per pool; source "GeckoTerminal trades".