Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
api/coin/ - global crypto market data endpoints
Read-only market-data endpoints behind the /coins section and the Markets tools. Each file is its own HTTP route (api/coin/markets.js serves GET /api/coin/markets, see api/README.md for the routing rules). Most proxy CoinGecko through the shared helper ../_lib/coingecko.js, slim the multi-hundred-KB upstream payloads down to exactly what the page renders, and cache in-memory plus at the CDN.
Why this layer exists instead of calling CoinGecko from the browser:
- Rate-limit survival. CoinGecko's keyless/demo tiers cap at roughly 30 req/min. The proxy adds an in-memory cache with a stale buffer, a durable last-good copy in the shared cache, and CDN
s-maxage, so a throttled upstream serves recent data instead of a blank page. - Failover. The load-bearing datapoints read through
../_lib/market-fallbacks.js: CoinGecko first, then CoinPaprika and CoinLore for the stats bar and market table, and Kraken/Coinbase exchange candles for the headline OHLC charts. A single dead upstream no longer blanks /coins. - Payload shaping. Every handler returns only the fields its page renders, coerces non-finite numbers to
null(never NaN in the UI), and sanitizes upstream HTML descriptions to plain text server-side.
All endpoints are GET, CORS-open, and rate-limited per client IP via ../_lib/rate-limit.js. Errors follow the platform shape from ../_lib/http.js.
Endpoints
| Route | Powers | Source |
|---|---|---|
GET /api/coin/markets?page&per_page[&category][&q] |
/coins table, /category/:id table, coin search type-ahead | CoinGecko /coins/markets and /search, CoinLore fallback |
GET /api/coin/global |
/coins stats bar (market cap, volume, dominance, Fear & Greed) | CoinGecko, CoinPaprika, CoinLore failover plus alternative.me |
GET /api/coin/detail?id=<id> or ?contract=<solana-mint> |
/coin/:id profile | CoinGecko /coins/{id} |
GET /api/coin/ohlc?id=<id>&days=<1|7|30|90|365> |
/coin/:id price chart | CoinGecko market_chart, Kraken/Coinbase candle fallback |
GET /api/coin/tickers?id=<id>&page=1[&contracts=<addr,...>] |
/coin/:id exchange listings table | CoinGecko /coins/{id}/tickers, CoinPaprika markets fallback, then the coin's DEX pairs from DexScreener when contracts (up to 8 EVM or base58 addresses, from the detail payload's platforms) is passed; source names the rung that answered |
GET /api/coin/pool?address=<token>&network=<net> |
/coin/:id GeckoTerminal chart embed (pool resolution) | GeckoTerminal via ../_lib/market/ohlcv.js |
GET /api/coin/dextools?address=<token>[&network=<net>][&from=<surface>] |
Every DEXTools link on three.ws (terminal links, coin cards, dashboards). 302s to the token's DEXTools pair page and counts the visit per UTC day, token and sending surface in dextools_referrals (aggregate only, no visitor data). $THREE is pinned to the pair its Social Boost wins are credited to; a token with no resolvable pool lands on its token-keyed DEXTools page. Build links with dextoolsTokenUrl() in src/shared/trading-terminals.js |
Pool from ../_lib/market/ohlcv.js, count in Postgres |
GET /api/coin/news?q=<coin name>&limit=8 |
/coin/:id related-news rail | Native aggregator ../_lib/news.js |
GET /api/coin/trending |
/markets/trending | CoinGecko /search/trending |
GET /api/coin/categories |
/categories leaderboard | CoinGecko /coins/categories |
GET /api/coin/category?id=<slug> |
/category/:id detail | CoinGecko /coins/categories (one cached fetch serves all) |
GET /api/coin/exchanges |
/exchanges table | CoinGecko /exchanges, volumes converted to USD |
GET /api/coin/exchange?id=<slug>[&days][&view=chart] |
/exchange/:id detail (spot and derivatives venues) | CoinGecko /exchanges/{id} plus volume_chart |
GET /api/coin/derivatives[?view=exchanges] |
/derivatives (perp contracts and venues) | CoinGecko /derivatives |
GET /api/coin/fear-greed?limit=<1..365> |
/fear-greed index and history chart | alternative.me /fng |
GET /api/coin/gas |
/gas Ethereum fee tiers with USD estimates | On-chain eth_feeHistory via public RPC, no gas API |
GET /api/coin/rates |
/converter fiat rates | CoinGecko /exchange_rates |
GET /api/coin/liquidations |
/coins liquidations pulse strip | services/liquidation-collector |
GET /api/coin/:mint/cohorts[?cohort&…] |
Holder cohorts for one launched coin or agent token (creator-gated export) | Platform DB snapshot, or a live Helius holder set for agent tokens, see [mint]/cohorts.js |
Two contracts worth knowing before you call them
/api/coin/fear-greed returns current, previous_week, and the full history (oldest first). previous_week is the reading exactly seven days before current, so it is null whenever the requested limit is too small to contain one (limit=7 or less). It is never the oldest point standing in for a week: a client that renders a delta must handle null by omitting it, as src/fear-greed.js does.
/api/coin/:mint/cohorts has two shapes on one route. Without ?cohort, it is public: cohort definitions with live counts, cacheable at the CDN. With ?cohort=<id>, it is a member export restricted to the coin's creator (or an admin), and it answers in this order, before any holder data is fetched: 404 for an unknown cohort id, 401 when signed out, 403 when the caller is not the creator, and 422 for a tenure cohort on an agent token that has not accrued holder history yet. Only after all four pass does it read the holder set, which can itself answer 503 holders_unavailable when Helius is unreachable. Every shape shares one per-IP limiter (limits.cohortsIp).
Frontend consumers live in src/: coins-index.js, coin-page.js, markets-page.js, markets-trending.js, categories.js, category-page.js, exchanges.js, exchange-page.js, derivatives.js, fear-greed.js, gas.js, converter.js, plus the Markets tools heatmap.js, screener.js, and compare.js. The public pages are declared in data/pages.json (/coins, /heatmap, /screener, /compare, /categories, /exchanges, /derivatives, /fear-greed, /gas, /converter, /markets/trending).
Shared internals
../_lib/coingecko.jsexportsgeckoFetch(path, { ttlMs, timeoutMs }), the one CoinGecko fetch: base URL, optionalCOINGECKO_API_KEY(demo tier, works key-free), per-instance memory cache with a 30-minute stale buffer, a durable last-good copy in Upstash, and automatic key benching when an exhausted demo key starts rejecting requests. It throws with.statusset on non-OK responses so callers can tell 404 (unknown coin, a real answer) from 429/5xx (upstream trouble, serve stale). Also exportsisPlausibleCoinIdandhtmlToText.../_lib/market-fallbacks.jsexports the failover reads:fetchGlobalMarket(),fetchMarketsTable({ page, perPage, category }),fetchCoinPriceUsd(coingeckoId), andfetchExchangeChart(id, days).markets.jsitself exportssearchCoins(q), reused by the paid Market Data API in../_lib/market-data/so the x402 market-coins endpoint shares the same id resolver.
Usage
No install step: these deploy with the rest of api/ and run locally under the dev server (npm run dev, port 3000, Vite proxies /api). They work with zero configuration; two env vars are optional:
COINGECKO_API_KEY(demo tier) lifts the public CoinGecko rate limit.LIQUIDATION_COLLECTOR_URLpoints at the liquidation collector; unset,/api/coin/liquidationsanswers503 { "error": "collector_offline" }and the UI shows its designed offline state. No synthetic numbers, ever.
Example, straight from the route contract at the top of markets.js (GET /api/coin/markets?page=1&per_page=100 returns ranked market table rows):
curl -s 'https://three.ws/api/coin/markets?page=1&per_page=10' | head -c 600
Returns { "coins": [ { rows with rank, price, 24h change, market cap, downsampled 7d sparkline } ], "page": 1, "per_page": 10, "category": null }. Add ?q=solana for the search shape instead, or &category=layer-1 to scope the table to one CoinGecko category.
page and per_page are clamped rather than rejected: page to 1..20 and per_page to 10..250, and the response echoes the clamped values it actually used. So per_page=5 returns ten rows and reports "per_page": 10. /api/coin/tickers is the one endpoint here that rejects instead of clamping, because its upstream page ceiling is a real limit rather than a preference: a page outside 1..10, or one that is not an integer, answers 400 bad_page.
Related
api/README.md, how routing,_lib/, and crons work across the whole API surface.services/liquidation-collector/README.md, why the liquidations feed is a standalone long-lived service.STRUCTURE.md, the map of every product surface.