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}
/api/token/{chainId}/{address}| Path | Type | Description |
|---|---|---|
chainId | 1 or 11155111 | Unsupported values return 404. |
address | address | Any 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.
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,decimalsandtotalSupplyare 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
nullandpoolsis[]. - Description and social links prefer the Stargaze launch metadata (
metadataURI), then GeckoTerminal, then CoinGecko.
GET /api/token/{chainId}/{address}/ohlcv
/api/token/1/{address}/ohlcv?pool={pool}&tf={tf}Ethereum mainnet only| Param | In | Default | Description |
|---|---|---|---|
chainId | path | — | Must be 1; otherwise 404 "Price history is only available on Ethereum mainnet". |
address | path | — | Not used by the handler — candles are keyed by pool. |
pool | query | required | Pool address (e.g. row.poolAddress). Invalid → 400 "Invalid pool or timeframe". |
tf | query | 1h | One of the timeframes below. Invalid → 400. |
side | query | base | base or quote — which token of the pool to price (passed to GeckoTerminal as token). |
| tf | Candle size | Candles | Server TTL |
|---|---|---|---|
5m | 5 minutes | 300 | 30 s |
15m | 15 minutes | 300 | 60 s |
1h | 1 hour | 300 | 120 s |
4h | 4 hours | 300 | 300 s |
24h | 15 minutes | 96 | 60 s |
7d | 1 hour | 168 | 300 s |
30d | 4 hours | 180 | 600 s |
all | 1 day | 1,000 | 3,600 s |
{ "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
/api/token/1/{address}/trades?pool={pool}Ethereum mainnet only| Param | In | Description |
|---|---|---|
chainId | path | Must be 1; otherwise 404 "Trade history is only indexed on Ethereum mainnet". |
address | path | The token whose side of each trade is reported. Invalid → 400 "Invalid pool". |
pool | query | Required pool address. Invalid → 400 "Invalid pool". |
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".
