Documentation · GodzeraFi

Asset keys

Assets are addressed as chain:address. Contract-addressed tokens use their chain slug and contract or mint address; natives and other CoinGecko-listed coins use the coingecko pseudo-chain with the CoinGecko id.

ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48   → /asset/ethereum/0xa0b8…
solana:So11111111111111111111111111111111111111112 → /asset/solana/So111…
coingecko:bitcoin                                  → /asset/coingecko/bitcoin

Chains: ethereum · base · arbitrum · solana · robinhood · bsc · polygon · optimism · avalanche · coingecko

Response envelope

200  { "ok": true,  "data": { … }, "meta": { "generatedAt": ISO, "cacheSeconds": n } }
4xx  { "ok": false, "error": { "code": "VALIDATION" | "NOT_FOUND" | "RATE_LIMITED" | "PROVIDER_NOT_CONFIGURED" | "PROVIDER_ERROR", "message": "…" } }

Routes

Route	Query	Returns
GET /api/markets	chain, category, q, sort, dir, page, perPage, minVolume, minLiquidity, change	Paged AssetMarketData rows + universe description + provider notes
GET /api/ticker	—	Top assets by market cap for the live strip
GET /api/search	q (≥ 2 chars)	TOKEN / PAIR / POOL results from CoinGecko, DexScreener, Jupiter
GET /api/asset	chain + address, or ids=key,key (≤ 12)	Full AssetView (pools, on-chain, risk, pulse, mass, sources) or snapshots
GET /api/history	chain, address, tf = 1H \| 4H \| 1D \| 7D \| 30D	Candles (GeckoTerminal) or line (CoinGecko / DefiLlama), or ok:false with the providers tried
GET /api/scan	address, chain (optional)	Chain candidates, AssetView, or on-chain-only reads
GET /api/pulse	limit, chain, minLiquidity	Ranked Pulse entries with full breakdowns and weights
GET /api/gravity	limit	Nodes for the Market Gravity Map
GET /api/trending	limit	Trending, gainers, losers, volume surge, liquidity leaders
GET /api/signals	—	BTC / ETH / SOL live signal modules
GET /api/portfolio	address	Wallet holdings, prices, allocation, per-chain status
GET /api/status	—	Provider configuration flags (booleans only)
GET /api/token	—	$GDZR plate: SOON until GDZR_TOKEN_ADDRESS is set, then identity read live from the chain

AssetMarketData

{
  id: "chain:address", name, symbol, chain, address,
  priceUsd, change1h, change24h, change7d,
  marketCap, fdv, volume24h, liquidityUsd, high24h, low24h,
  txns24h, poolCount, createdAt, logoUrl, rank, category, sparkline7d,
  source: "coingecko" | "dexscreener" | "geckoterminal" | "jupiter" | "rpc",
  sources: [{ id, label, url, fields[] }],
  updatedAt: ISO
}
// null always means "the provider did not return it", never zero.

Caching and rate limits

Server routes use a process-local TTL cache with stale-while-revalidate (see src/lib/utils/cache.ts) and emit s-maxage headers so Vercel’s edge absorbs repeat hits. Expensive routes are token-bucket limited per client IP:

Route	Burst	Refill
/api/search	30	1 / s
/api/asset	40	2 / s
/api/history	40	2 / s
/api/scan	12	1 per ~3 s
/api/portfolio	10	1 per 5 s

Environment

NEXT_PUBLIC_SITE_URL=            # canonical URL (OpenGraph, sitemap)
COINGECKO_API_KEY=               # optional Demo key
ALCHEMY_API_KEY=                 # optional — EVM wallet token discovery
SOLANA_RPC_URL= EVM_RPC_URL= BASE_RPC_URL= ARBITRUM_RPC_URL= ROBINHOOD_RPC_URL=   # optional overrides
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=   # optional — enables WalletConnect
RESOLVE_OVERRIDE=                # local dev only — DNS pin for hijacked hosts
GDZR_TOKEN_ADDRESS= GDZR_TOKEN_CHAIN= GDZR_TOKEN_ACQUIRE_URL=   # $GDZR plate — set with: npm run token:ca -- ADDRESS

The app is fully functional with an empty environment: every core provider is key-free. Keys only add optional accelerators; nothing on the site depends on them.

Deployment

Vercel

npm install
npm run build          # next build
vercel --prod          # framework preset: Next.js (pinned in vercel.json)

Set NEXT_PUBLIC_SITE_URL to the production domain. No database, cron or edge config is required.

Local

cp .env.example .env.local
npm run dev            # http://localhost:9700