Skip to content

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.

50.1 KB
Raw Blame

Global Markets & Coin Detail Pages

three.ws has always had deep coverage of pump.fun launches (/launches, /coin-intel, /oracle). The Markets surface extends that to the whole crypto market: a CoinGecko-style index of the top assets, and a rich, shareable detail page for every coin. The design is adopted from the cryptocurrency.cv coin pages — editorial headings, hairline borders, mono numerals, light/dark themes (the port's Source Serif 4 headings were retired 2026-07 for the sitewide Space Grotesk display face).

The pages

/coins — markets index

  • Global stats bar — total market cap (with 24h change), 24h volume, the top-2 dominance shares, the Fear & Greed index, and the active-coin count.
  • Top coins table — rank, name, live price, 24h %, 7d %, market cap, 24h volume, and a 7-day sparkline per coin. Every column sorts (click or Enter/Space on a header); every row links to its detail page. "Load more" appends the next 100 ranks.
  • Search — a debounced type-ahead over the full CoinGecko catalog with keyboard navigation (↑/↓/Enter/Escape); selecting a result opens its detail page.
  • Responsive: lower-priority columns collapse at small widths, the coin-name column stays sticky while the table scrolls horizontally.
  • Liquidations pulse — a strip under the global stats bar showing a dominant-side badge (LONG PAIN / SHORT SQUEEZE / BALANCED), 1h long-vs-short liquidated USD bars, and the 3 largest recent liquidations, fed by /api/coin/liquidations and polled every 30s (paused while the tab is hidden). Optional enrichment: degrades to a quiet single-line offline state — never fabricated data — when its collector isn't reachable. See services/liquidation-collector/README.md and api-reference.md → Liquidations.

/coin/:id — coin detail

:id accepts either a CoinGecko slug or a base58 Solana mint address (resolved through the contract lookup).

  • Header — icon, name, symbol, market-cap-rank badge, live price, and 24h / 7d / 30d change chips, plus the coin's categories.

  • Interactive chart with a source switcher — the default is a lightweight native SVG line chart across 24H / 7D / 30D / 90D / 1Y (data by CoinGecko) with a crosshair tooltip showing exact price and time. A pill switcher next to the time ranges swaps in a full third-party terminal, and each option only appears when it can actually chart the coin:

    • CoinGecko — the native line chart (always available).
    • TradingView — the advanced candlestick widget (indicators, drawing tools), for any coin with a ticker symbol.
    • DexScreener, Birdeye, GMGN: on-chain charts keyed by the token's contract address, for coins with a Solana mint or a supported EVM contract (GMGN indexes Solana, Ethereum, Base and BSC only, so it is offered only there).
    • DEXTools and GeckoTerminal: on-chain charts keyed by the token's most-liquid pool rather than the token, resolved server-side via GET /api/coin/pool (below). Each resolves the pool its own way (resolveChartPool() in the shared module): GeckoTerminal is also asked whether it has indexed that pool, because its embed is a 404 page until it has, while DEXTools charts any pair it is handed. DEXTools is embedded through its published /widget-chart/ route only; its normal /app/ pages refuse framing and are used just for the "Open in DEXTools" link.

    The picked source is remembered across coins and visits (localStorage tws_coin_chart_source), and the embeds follow the site's light/dark theme. Every embed URL shape lives once in src/shared/chart-embeds.js, so this page, the launch coin page /launches/<mint>, the /trades deep-dive, Mission Control, the Oracle coin page /oracle/coin/<mint> and the /pump-dashboard market chart (the last four through the compact switcher in src/shared/chart-switcher.js) build identical embeds and a provider changing its format is a one-file fix. Adding a provider there adds its tab on all six surfaces. A surface that already draws a chart of its own keeps it: it hands the switcher its views through nativeViews (the Oracle page's Line and Agent trades views, the dashboard's canvas chart) and the providers line up behind them, styled with the host's own segmented-control classes. The Oracle page is buildless, so it loads the switcher from the stable /chart-switcher.js URL the build publishes. The $THREE page at /three is the one surface with no switcher, because its chart is already the DEXTools widget. Providers that refuse cross-origin framing or need a key are left out rather than offered as a tab that can only fail.

    A third-party terminal that never renders is caught, not left as an empty box: src/shared/embed-guard.js gives each embed a 12 s deadline (started when it first scrolls into view, since a lazy iframe below the fold has not begun loading), and a TradingView script that is blocked outright or loads without ever injecting its chart trips the same path. The panel that replaces it says the provider did not load (an ad blocker, an extension or the network usually ate it), links to the same chart on the provider's own site, and offers a "Try again" that remounts the embed.

  • Price performance matrix — colored 1h / 24h / 7d / 14d / 30d / 60d / 200d / 1y change cells, so the whole return curve is legible at a glance.

  • Market stats — market cap, 24h volume, circulating/total supply, all-time high and low (dated), 24h high/low.

  • Supply — a circulating-vs-max (or total) supply bar with the percentage in circulation, the market-cap / FDV ratio, and 24h market-cap change.

  • All-time high / low — value and date for each, the drawdown from ATH, and the recovery multiple from ATL.

  • Community sentiment — the CoinGecko bullish/bearish vote split and the number of users watching the coin. Hidden when the coin has no votes.

  • Community & development — Twitter / Reddit / Telegram followings and GitHub stars, forks, watchers, issues, merged PRs, contributors, and commits in the last four weeks. Each block hides when untracked.

  • Markets — a paginated exchange-listings table (from /api/coin/tickers): exchange (linking to its detail page), pair (deep-linking to the live trade page on that venue), price, spread, +2% / −2% order-book depth, 24h volume, and a color-coded trust rating. Stale/anomalous rows are dimmed.

  • Related news — live articles mentioning the coin, from the native three.ws aggregator (api/_lib/news.js; 197 publisher feeds in the api/_lib/news-sources.js registry).

  • About + links — plain-text description, official site / social / explorer pills, plus whitepaper, forum, chat, announcement, and extra-repo links, and per-chain contract addresses with one-click copy.

  • three.ws integration — coins with a Solana contract cross-link into Alpha Copilot and the live trade feed. A mint-shaped id that isn't on the market data source points to its launch profile and Coin Intelligence instead.

  • Domain names: live-availability suggestions for the project name, mounted at the foot of the page by src/domains/suggest-panel.js and backed by the web domains service.

The detail endpoint (api/coin/detail.js) requests CoinGecko's community and developer blocks and slims the multi-hundred-KB payload to exactly these fields; all-zero developer/community blocks (coins with no tracked repo or socials) collapse to null so the page hides the whole section rather than render a wall of zeros. A single follower count of exactly 0 is treated the same way: it means the channel isn't tracked, not that it's empty (Solana's subreddit has ~170k members and still reports 0), so the stat is omitted rather than stated falsely. Developer counters keep their zeros — "0 commits in 4 weeks" is a real reading about a real repo.

Unknown ids, upstream outages, loading, and empty news/markets all have designed states — the page never renders a blank void. When a datapoint is answered by a backup provider, the page footer names it ("Served from CoinPaprika") so a missing field reads as degraded right now rather than this coin has no FDV.

Data sources & failover

No market datapoint depends on a single upstream. CoinGecko's keyless tier rate-limits hard under load, so the reads that used to blank on a CoinGecko blip now fail over across free, keyless public APIs before surfacing an error, all through the shared failover-fetch primitive (a dead upstream is skipped, cooled down for a minute, and the chain moves on):

  • Global stats bar (/api/coin/global) — CoinGecko → CoinPaprika → CoinLore. Each is normalized to the same shape in api/_lib/market-fallbacks.js; a fallback that only carries BTC dominance (CoinPaprika) simply shows one dominance chip. The Fear & Greed reading is fetched with one retry and keeps its last good value for a day (the index updates once daily), so an alternative.me blip never blanks the gauge.
  • Market table (/api/coin/markets) — CoinGecko → CoinLore. CoinLore backs up the ranked top-N list (7d sparklines and category scoping stay CoinGecko-only and degrade to an empty chart / CoinGecko-only when it's down).
  • Headline prices — the ETH figure on /gas and the BTC figure on /exchanges fail over CoinGecko → DefiLlama (keyed by the same CoinGecko id), then to live exchange tickers (Kraken → Coinbase → Bitfinex) for the mapped majors (BTC, ETH, SOL).
  • Coin profile (/api/coin/detail) — CoinGecko /coins/{id} → CoinPaprika (api/_lib/coin-fallbacks.js). CoinPaprika uses its own <symbol>-<name-slug> ids, so the module resolves the CoinGecko id in two stages and caches the result for a week. First an exact id-slug or name-slug match (solana → sol-solana), which covers a little over half the top 50. The rest miss because the two catalogues list the same asset under different names — one by ticker, the other by product name, or one with a disambiguating suffix. For those, identity is proven, not guessed: DefiLlama supplies the authoritative symbol and price for the requested CoinGecko id, and a same-symbol candidate is accepted only when its own price agrees within 2%. Two different coins sharing a ticker and a price to within 2% is vanishingly unlikely, so agreement is evidence; a name heuristic would only be a hunch, and serving a different coin's market cap is worse than serving an error. Fields this source doesn't carry (FDV, 24h high/low, developer stats, per-chain contract addresses) come back null and the page hides those sections. Circulating supply isn't published either, but market cap ÷ price recovers it exactly. The lookup by Solana mint (?contract=) has no fallback: CoinPaprika is addressed by coin id, not by mint.
  • Exchange listings (/api/coin/tickers): CoinGecko /coins/{id}/tickers → CoinPaprika /coins/{id}/markets → the coin's DEX pairs from DexScreener's keyless token index. Derivatives venues are filtered out of the CoinPaprika rung (the CoinGecko endpoint it stands in for is spot-only, and perps would otherwise head the table by volume). The DEX rung covers coins CoinPaprika does not list (young DEX-only tokens above all): the page passes the contract addresses it already holds from /api/coin/detail as ?contracts= (up to 8, EVM or base58), and the handler keeps only pairs where the coin is the base token, ranked by 24h volume, cached and single-flighted like the CoinPaprika rung. DexScreener has no pagination, so page 1 is the whole answer. Without contracts, or with nothing trading, the 502 stands. The response's source names the rung that answered (coingecko, coinpaprika, dexscreener). Spread and ±2% order-book depth don't exist in either backup feed, so the client drops those three columns rather than render a wall of empty cells.
  • Price chart (/api/coin/ohlc) — CoinGecko market_chart, backed up for BTC/ETH/SOL by exchange candles (Kraken OHLC → Coinbase Exchange) — real trade prints, so they lead — and for every other coin by DefiLlama's coins oracle, which is addressed as coingecko:<id> and therefore needs no id mapping at all. The long tail keeps its chart through a CoinGecko outage instead of blanking. A 404 (unknown coin) never falls back: that is an answer.
  • Derivatives table (/api/coin/derivatives) — CoinGecko's cross-venue perp feed, falling back to Hyperliquid's keyless info API (api/_lib/hyperliquid.js): one venue instead of dozens, but live price/funding/OI/volume for ~200 perps beats a 502. Because no other venue reports the same contracts, each Hyperliquid info query is retried once and keeps its last good answer for ten minutes (keyed by the query body), so a throw there never empties the derivatives view. The response carries a source marker. Riding alongside whichever source answered is a deribit block (api/_lib/deribit.js): index prices, funding-carrying perp tickers, and per-asset options aggregates from Deribit's keyless public API. It is fetched in parallel and fails soft to null, so an unreachable Deribit never delays or blanks the perp table.
  • SOL spot — seven sources server-side (CoinGecko, Jupiter, Kraken, Coinbase, DefiLlama, DIA, Bitfinex) and four browser-side, CORS-safe ones.
  • Solana token panels: Birdeye → Tokens API → DexScreener → GeckoTerminal → DefiLlama → Raydium (see api/_lib/market/token-market.js). The Tokens API rung (api.tokens.xyz, the Solana Foundation's canonical asset index) carries the same full field set as Birdeye, holder count and circulating supply included, so it is a like-for-like second rather than a degraded fallback; it sits behind Birdeye only because Birdeye is our own direct read. The Raydium rung is price-only and covers only Raydium-pooled tokens, but it indexes its own AMM, so it stays up when every aggregator is rate-limited.
  • Trending (/api/coin/trending) — CoinGecko /search/trending → GeckoTerminal on-chain trending. CoinGecko ranks by search interest across all chains; the free fallback ranks by on-chain pool activity, scoped to Solana so every token's mint resolves on the /coin/:id detail page. It's a different signal (the response carries a source marker so the client can badge it) and only fills the coins list — categories and NFTs have no on-chain analogue and come back empty, which the page hides. A populated list still beats a blank page.

Every fallback is free and keyless (Binance, Bybit and OKX are excluded — they geo-block US datacenter IPs, so from Cloud Run they would be permanently dead rungs).

Budgeting the CoinPaprika rungs

CoinPaprika's free tier allows 60 requests per hour (25k/month) and returns 402 payment_required with a one-hour block once that is spent. A fallback is hot exactly when CoinGecko is throttling, which is the worst possible moment to burn the only other profile source — so the per-coin rungs are budgeted rather than called per request:

  • Normalized payloads are cached in the shared cache for 120s. One round-trip serves the whole fleet for the window, so 500 visitors to /coin/solana during an outage cost one request, not 500. This is what makes the budget survivable.
  • Concurrent misses single-flight. A cold cache under load resolves to one upstream call, not one per in-flight request.
  • The id mapping is cached for a week, so a coin costs its resolution once.
  • Paging is served from the cached response — CoinPaprika returns every market in one payload, so "Load more exchanges" spends nothing.
  • A 402/429 benches the source for an hour. A spent budget then costs zero further requests instead of one wasted round-trip per request until it resets.

DefiLlama carries no comparable limit and is addressed by CoinGecko id, which is why it — not CoinPaprika — takes the high-volume chart job.

The market tools

Five more surfaces extend Markets, all sharing the same design system (src/coin-pages.css) and real, key-free data. Every one cross-links back into the markets table and the coin detail pages.

/heatmap — market heatmap

Every top coin as a tile in a squarified treemap, sized by market cap and colored by its price move (green up, red down, brightness scaling with the move). Toggle the color between 24h and 7d, and the set between top 50 and top 100. Hover any tile for a price · 24h · 7d · market-cap tooltip; click it to open the coin's detail page. The layout is computed client-side from the existing /api/coin/markets feed — no extra endpoint.

/fear-greed — Fear & Greed index

The market's mood as a single 0 to 100 score on a live semicircle gauge, with a week-over-week delta and its classification (Extreme Fear → Extreme Greed). The delta is only drawn when the requested window actually contains a reading a full week old: otherwise previous_week comes back null and the page omits the comparison rather than score the current reading against itself. Below it, an interactive history chart (30D / 90D / 1Y) with a crosshair tooltip, and a labelled scale. Data is the alternative.me index — the same source the /coins stats bar uses — served through /api/coin/fear-greed.

/gas — Ethereum gas tracker

Live Ethereum gas in three tiers (slow / standard / fast), each in gwei with a USD cost estimate, plus a cost-by-action table (ETH transfer, token transfer, DEX swap, NFT mint). The page auto-refreshes every 15s and pauses when the tab is hidden. Fees are read straight from the chain — /api/coin/gas calls eth_feeHistory on a public RPC (with failover across four providers) and prices each tier with the live ETH price (CoinGecko → DefiLlama failover). No third-party gas API, no key.

/screener: the Token Screener

A live filtering workbench over the top 250 coins by market cap. The page loads the whole set once (/api/coin/markets?page=1&per_page=250&sparkline=0, the same cached endpoint behind the markets table, so no new endpoint; the screener draws no sparkline column, and dropping the 7-day series cuts that 250-row response from roughly 215 KB to 70 KB), then every keystroke, filter change, and sort runs instantly in the browser with no further network traffic.

The filter controls, all composable (a coin must pass every active one):

  • Search: a debounced (200 ms) substring match against name and symbol.
  • Direction: an All / Gainers / Losers segmented control. Gainers keeps only coins whose 24h change is above zero, Losers only those below; a coin flat at exactly 0 matches neither.
  • Min market cap: Any, $10M+, $100M+, $1B+, $10B+, $100B+.
  • Min 24h volume: Any, $1M+, $10M+, $100M+, $1B+.
  • Reset restores every control and the default sort in one click (the zero-results empty state offers the same reset inline).

The results table renders through the shared market-table primitives (src/shared/market-table.js), the same rows, columns, sorting and row navigation the markets index, the token page and the coin lobby use, so those surfaces cannot disagree about what a row or a stale value looks like: rank, coin (icon, name, symbol), price, 24h %, 7d %, market cap, and 24h volume. Every column sorts: click a header, or focus it and press Enter/Space (headers are keyboard-reachable and announce aria-sort). The first activation sorts name and rank ascending and every numeric column descending; activating the already-active column flips the direction. Rows link to their /coin/:id detail page, and clicking anywhere on a row navigates. A live match counter ("N of 250 coins", aria-live) and an "Updated HH:MM:SS" stamp keep the state legible, and lower-priority columns collapse at narrow widths while the coin column stays readable.

Every state is designed: a 14-row skeleton while the single fetch is in flight, a plain-language error state when the markets feed is unavailable, and a zero-match empty state that suggests widening the floors and offers the one-click reset.

Files: pages/screener.html (shell, controls, SEO), src/screener.js (state, filtering, sorting, rendering), src/filter-controls.css (the labelled filter row, shared with /yields), with shared formatters from src/shared/coin-format.js and the rows, columns and sorting from src/shared/market-table.js.

/compare — side-by-side comparison

Up to four coins head to head: an overlay chart of normalized price performance (% change from the window start) over 7D / 30D / 90D / 1Y with a multi-series crosshair and a date axis, and a stats table lining up price, 24h/7d/30d change, market cap, volume, FDV, supply, and all-time high. Add coins with the search type-ahead; the selection is mirrored to ?ids=… so any matchup is a shareable link. Reuses /api/coin/markets (search), /api/coin/detail, and /api/coin/ohlc, no new endpoint.

Three details the table and chart depend on:

  • Sign wins the colour, the row winner wins the weight. Gains render green and losses red; the best value in a row is bold on a tinted cell and carries a screen-reader-only "(best)", so a 37% drawdown that happens to be the smallest one is never painted as a gain.
  • The overlay is measured, not scaled. Its viewBox is taken from the panel width on every render (and on resize), so a 320 px column draws a full-height chart with legible axis labels instead of a squashed desktop chart.
  • A slow range answer is discarded. Each reload carries a monotonic id; clicking 1Y then 7D can no longer paint a year of history under a 7D axis.

More market tools

Thirteen further tools round out the suite, same design system, same "real key-free data" rule:

  • /screener: filter the top 250 coins by search, gainers/losers, minimum market cap, and minimum 24h volume; every column sorts. Reuses /api/coin/markets (no new endpoint). Documented in full in its own section above.
  • /categories — every crypto sector ranked by market cap with 24h change, volume, and the top coins in each. New /api/coin/categories (CoinGecko /coins/categories). Each row opens a category detail page. CoinGecko reports 750+ categories, so the table opens with the top 50 and pages in 50 more per click, and the search box filters the full set by name or slug before you page. Every column sorts, and the three no-rows outcomes read differently: a failed fetch offers a retry that refetches, an upstream reporting nothing says so, and a search with no match offers to clear itself.
  • /exchanges — top exchanges by trust score and 24h volume (USD, derived from the live BTC price). New /api/coin/exchanges. Each row opens an exchange detail page.
  • /derivatives — perpetual-futures markets: price, funding rate, open interest, volume, filterable by index, plus a Derivatives Exchanges table (open interest, perp/futures counts) whose rows open the exchange detail page. /api/coin/derivatives (?view=exchanges for the venues). Every perp row opens a contract detail page.
  • /converter — convert any crypto ⇄ any major fiat at live rates (USD-anchored math covers all four directions). New /api/coin/rates (CoinGecko /exchange_rates) + /api/coin/markets/detail.
  • /defi — total DeFi TVL and the top protocols by TVL (CEX reserves excluded), category-filterable. New /api/defi/protocols (DeFiLlama).
  • /chains: every chain ranked by TVL with a dominance share bar and a sortable Turnover column (24h DEX volume divided by TVL: high means capital is trading, low means it is parked; n/a when a chain reports no TVL or no DEX volume). New /api/defi/chains (DeFiLlama; the volume side is summed per chain from the same /overview/dexs feed /dex-volumes uses).
  • /stablecoins — stablecoins by circulating market cap with live peg health and backing mechanism. New /api/defi/stablecoins (DeFiLlama).
  • /yields — an explorer over ~15,000 live DeFi yield pools: filter by chain, project, stablecoin exposure, and minimum TVL; sort by APY or TVL (the APY sort ignores sub-$10k dust pools to keep the ranking honest); open any row for its full APY + TVL history in a dual-axis chart. Filters sync to the URL for shareable views; project and chain link to their detail pages. New /api/defi/yields (DeFiLlama yields.llama.fi/pools + /chart/{pool}).
  • /fees — fees paid by users and revenue kept by protocols across all of DeFi, with 24h/7d/30d totals, an aggregate history chart, and a Fees|Revenue toggle. New /api/defi/fees (DeFiLlama /overview/fees).
  • /dex-volumes — every DEX ranked by volume with 24h/7d totals, 7-day change, market share, and an aggregate volume chart. New /api/defi/dex-volumes (DeFiLlama /overview/dexs).
  • /hacks — a searchable database of every major DeFi exploit: amount stolen, classification, technique, chains, bridge flag, and source, with all-time and trailing-12-month totals. New /api/defi/hacks (DeFiLlama /hacks).
  • /markets/trending — the most-searched coins, categories, and NFTs on CoinGecko over the last 24h, auto-refreshing; coins and categories link to their detail pages. New /api/coin/trending (CoinGecko /search/trending).

Detail pages

Beyond /coin/:id, several list surfaces have their own rich detail pages, reached by clicking a row.

/exchange/:id — exchange detail

A full profile for one exchange (or derivatives venue): logo, trust-score badge, rank, country, year established, centralized/DEX flag, and description; stat cards for 24h volume (BTC + USD), normalized 24h volume (adjusted to discount wash trading), markets count, and trust rank; an interactive BTC-volume history chart (7D–365D, crosshair with BTC + USD); and a markets table of the venue's pairs (each pair deep-linking to /coin/:id and to the live trade page), with price, spread, 24h volume, and trust. Derivatives venues show open interest and perp/futures pair counts with a contract table instead. New /api/coin/exchange (CoinGecko /exchanges/{id} + /volume_chart, falling back to /derivatives/exchanges/{id}). The fallback fires on an empty spot record as well as on a 404: CoinGecko keeps a stub in the spot namespace for some derivatives venues (/exchanges/whitebit_futures answers 200 with zero tickers and zero volume), and honouring that 200 rendered an empty profile for a venue listing several hundred contracts. Both ticker tables are ranked by 24h volume before the 50-row cap, so "top 50 by volume" is what they are.

/derivative/:venue/:symbol: perpetual contract detail

One perpetual futures contract in full, reached from any row of /derivatives and from the contracts table on a derivatives venue's /exchange/:id profile. /derivative/whitebit_futures/ETH_PERP is a worked example.

The table row states what a contract is worth. The page answers what that means:

  • Hero: venue logo and name (linking to the venue profile), contract symbol, mark price, 24h move, and whether the contract is trading above or below its own index, with a link out to the venue's trade screen.
  • Stat cards: mark vs index, basis, funding rate and its annualized equivalent, open interest and 24h volume (each with the contract's rank among every venue listing that underlying), bid/ask spread, and 24h volume denominated in the underlying.
  • What funding costs: the funding rate turned into money. Type a position size and the page shows what that position pays (or is paid) per interval, per day and per year at the rate quoted right now, and says which side pays.
  • Underlying price chart: the spot price of the index the contract tracks (1D to 1Y, crosshair readout), via /api/coin/ohlc.
  • Cross-venue comparison: every venue listing a perpetual on the same underlying, ranked by volume, with the current contract pinned and marked. Above it, four callouts: the cheapest venue to hold a long, the best paid venue to hold a short, the funding spread across venues, and price dispersion. Those four only count venues clearing $1M in 24h volume, because a dormant book prints the widest funding and the widest price every time.
  • How big this contract is: share meters for the contract's slice of the venue's open interest and volume, and of all open interest in that underlying, plus the venue's other contracts (each linking to its own page).
  • The underlying: the spot asset's market cap, volume, 24h range and ATH, linking through to /coin/:id.

New /api/coin/derivative (CoinGecko /derivatives/exchanges/{venue} for the contract, /derivatives for the cross-venue set, /coins/markets for spot). Only the venue read is load-bearing; the rest degrade to empty sections.

Contract symbols are not path-safe (ETH/USDT), so the slash is folded to ~ in the URL by src/shared/derivative-slug.js, which is vendored byte-identically to api/_lib/derivative-slug.js because the server build context excludes src/. tests/api/derivative-contract.test.js fails if the copies drift.

/category/:id — category detail

A sector page: rank ("#N by market cap"), description, and stat cards for market cap, 24h change, 24h volume, and share of the categorized market; the full sortable coins table for that category (reusing the shared markets table, so every row deep-links to /coin/:id); and a strip of related categories. Reuses /api/coin/markets?category=<id> for the table and new /api/coin/category for the header + neighbours.

/protocol/:slug — DeFi protocol detail

A full profile for one protocol, reached from a /defi, /fees, /dex-volumes, or /yields row: hero (logo, category, audit badge, forked-from/parent chips, website + twitter); stat cards for TVL, Mcap/TVL, 24h fees, 24h revenue, and 24h DEX volume (null cards hidden); a full TVL history chart with 30D/90D/1Y/All ranges and event (hallmark) markers; a per-chain TVL breakdown (each chain linking to /chain/:name); a funding-rounds table; and a methodology section. New /api/defi/protocol (DeFiLlama /protocol/{slug} enriched with /summary/fees and /summary/dexs).

/chain/:name — chain detail

A per-chain page reached from /chains: hero (native token, chain id, rank, dominance); stat cards for TVL, share of DeFi, stablecoin supply, 24h DEX volume, 24h fees, and protocol count; interactive TVL, stablecoin-supply, and DEX-volume history charts; and the top protocols on that chain (each linking to /protocol/:slug). New /api/defi/chain (a fan-out over DeFiLlama's chains, historical-TVL, protocols, stablecoin-charts, and dimensions endpoints).

/stablecoin/:id — stablecoin detail

A per-issuer page reached from /stablecoins: hero (peg, mechanism, price with a basis-point peg-deviation badge, audits, and a cross-link to the coin's /coin/:id market data); circulating-supply history chart; and a per-chain distribution table (each chain linking to /chain/:name). New /api/defi/stablecoin (DeFiLlama stablecoins.llama.fi/stablecoin/{id}).

News & the markets hub

The suite's news wing and its front door, added 2026-07-10:

/markets — the markets hub

Everything in one place: the global stats bar (market cap, volume, dominance, Fear & Greed, active coins), every markets surface as its own hero card with live stats hydrated in (top 24h mover on the Heatmap card, current gwei on Gas, live story count on News, and so on), a sortable top-100 coins table, and a latest-news rail with an archive teaser. Five already-cached endpoints feed it: /api/coin/global, /api/coin/markets, /api/coin/gas, /api/news/feed, /api/news/archive?stats=true.

/markets/news — "Your briefing"

The front page of the news wing, laid out as a daily briefing over headlines aggregated natively by three.ws from the publisher RSS/Atom registry (CoinDesk, The Block, Decrypt, CoinTelegraph, Blockworks, SEC press, Forkast, and more — api/_lib/news-sources.js):

  • Primary tabs — Featured (the majors, via /api/news/feed?featured=1), Headlines, Trending (the digest's coverage-ranked narratives), DeFi, Bitcoin, Ethereum, Analysis, Saved, and All, which unfolds the full category registry.
  • Breaking ticker — stories under 45 minutes old scroll in a marquee (paused on hover, static under prefers-reduced-motion); hidden when nothing is fresh.
  • Today's AI Briefing — the top digest narratives as a collapsible numbered card, linking into /markets/digest.
  • Top stories — a lead-story hero beside a compact headline rail, then the Latest grid with offset pagination.
  • Saved stories — a ☆ on every card bookmarks the article to localStorage; the Saved tab renders the collection.
  • Debounced search, language + per-source filters, sentiment dots, and ticker chips that pivot the feed to that symbol carry over from the flat layout.

Preview images never break: feed images load with no-referrer, retry once through the same-origin /api/img proxy, and articles whose feed ships no image resolve their publisher's og:image in the background via /api/news/image — falling back to a designed source-initials tile only when no preview exists anywhere. Each source is cached server-side for 5 minutes with serve-stale-on-error, so one dead feed never blanks the page.

/markets/news/article — rich article reader

Opens any story with server-side extraction (/api/news/article): full paragraphs, publisher metadata, an AI summary + key points via the platform LLM chain (api/_lib/llm.js, free providers first, paid keys only as a tail backstop) with an extractive fallback when no provider is reachable, bullish/bearish/neutral sentiment, detected tickers, and a related-coverage rail. When an LLM provider answers, the page also shows a Trading read: the assets the story moves (direct, indirect or sector exposure, with direction), whether it is priced in, the horizon, and a required counter-argument (a read without one is discarded; the extractive fallback carries no trading read). Publishers that block server fetches degrade through an honest ladder (api/_lib/article-extract.js): page extraction → a reader service → the Internet Archive snapshot of the same URL → the SEC EDGAR filing the headline names → other outlets' coverage of the same story → the publisher's own feed body (content:encoded) → a labelled preview with a read-at-source CTA. Recovered text carries a badge ("full text recovered", "from web archive", "from SEC filing", "from other outlets") and links its sources. Never a dead end, never fabricated text.

/markets/digest — the day in stories, not headlines

Groups the last N hours of coverage (6h → 72h) into the handful of narratives that actually moved, each with a summary, a market stance, the tickers involved, and an expandable list of every outlet that covered it. Two real engines, reported honestly in the response and on the page:

  • engine: "llm" — the platform LLM chain (api/_lib/llm.js, free tiers first) groups the headlines semantically. Every narrative must cite indices that resolve to articles the aggregator actually fetched; a hallucinated citation is dropped, and a digest where nothing resolves falls through.
  • engine: "heuristic" — agglomerative clustering on Jaccard similarity over each headline's significant tokens plus its detected tickers, with an extractive summary from the lead article. Not a placeholder: it produces genuine clusters from the same articles, and runs whenever no LLM provider key is configured or the chain fails.

Cached 30 min per window in-process; ?refresh=1 regenerates. Backed by /api/news/digest.

/markets/archive — the historical archive

The largest open crypto-news archive: 660,000+ enriched articles from September 2017 to today (the CryptoPanic english corpus + the Odaily chinese corpus + the cryptocurrency.cv live archiver), kept current by an hourly archiver (api/cron/news-archive-append.js, Cloud Scheduler 17 * * * *) that appends the live feed's articles to the current month's JSONL — idempotent by content-addressed id, generation-guarded against concurrent runs. Every record carries tickers, tags, sentiment, language, and market context at capture time. Hosted on the platform's own GCS bucket (gs://three-ws-news-archive, public, gzip at rest) as monthly JSONL plus indexes and corpus stats. The explorer filters by keyword, ticker, source, date range, sentiment, and language (EN/中文), with year quick-jump buttons and trending-ticker chips. The API scans months newest→oldest and reports exactly which months it covered, so the UI can be honest about how deep a search went.

Where the data comes from

All data is real and fetched at runtime — nothing is hardcoded or sampled:

Endpoint Upstream Cache
/api/coin/detail CoinGecko /coins/{id} or /coins/solana/contract/{mint} (with community + developer blocks) 60 s
/api/coin/tickers CoinGecko /coins/{id}/tickers (exchange listings, ±2% depth), CoinPaprika markets, then DexScreener pairs when contracts= is passed 120 s
/api/coin/ohlc CoinGecko /coins/{id}/market_chart 120 s
/api/coin/pool Top-pool lookup by token address (feeds the pool-keyed chart embeds: DEXTools, GeckoTerminal) 60 s + 300 s CDN
/api/coin/markets CoinGecko /coins/markets (optional category=), /search 60 s / 300 s
/api/coin/categories CoinGecko /coins/categories 300 s
/api/coin/category CoinGecko /coins/categories (one category + rank + neighbours) 600 s
/api/coin/exchanges CoinGecko /exchanges + /simple/price (BTC) 300 s
/api/coin/exchange CoinGecko /exchanges/{id} (+ /volume_chart) or /derivatives/exchanges/{id} fallback 120 s
/api/coin/derivatives CoinGecko /derivatives (?view=exchanges → /derivatives/exchanges) 60 s / 300 s
/api/coin/derivative CoinGecko /derivatives/exchanges/{venue} + /derivatives + /coins/markets (one perpetual contract) 60 s
/api/defi/yields DeFiLlama yields.llama.fi/pools (+ /chart/{pool}) 300 s / 600 s
/api/coin/trending CoinGecko /search/trending (coins + categories + NFTs) 120 s
/api/defi/protocol DeFiLlama /protocol/{slug} (+ /summary/fees + /summary/dexs) 300 s
/api/defi/chain DeFiLlama /v2/chains + /v2/historicalChainTvl + /protocols + stablecoin/DEX/fees per chain 300 s
/api/defi/stablecoin DeFiLlama stablecoins.llama.fi/stablecoin/{id} 300 s
/api/defi/fees DeFiLlama /overview/fees (?type=fees|revenue) 600 s
/api/defi/dex-volumes DeFiLlama /overview/dexs 600 s
/api/defi/hacks DeFiLlama /hacks (exploit database) 600 s
/api/coin/rates CoinGecko /exchange_rates 300 s
/api/defi/protocols DeFiLlama /protocols (CEX excluded) 300 s
/api/defi/chains DeFiLlama /v2/chains 300 s
/api/defi/stablecoins DeFiLlama stablecoins.llama.fi/stablecoins 300 s
/api/coin/global CoinGecko /global + alternative.me Fear & Greed 120 s
/api/coin/fear-greed alternative.me /fng (current + history) 300 s
/api/coin/gas public Ethereum RPC eth_feeHistory + CoinGecko ETH price 15 s
/api/coin/news native aggregator (api/_lib/news.js, 197 publisher feeds; a hosted news API is asked only if the native merge is empty) 300 s
/api/news/feed native aggregator: 197 publisher RSS/Atom feeds (api/_lib/news-sources.js), per-source cache + serve-stale 120 s
/api/news/article publisher page fetch (SSRF-guarded) → reader → web archive → SEC filing → sibling coverage → publisher feed body → preview; LLM analysis via the platform chain (api/_lib/llm.js) with extractive fallback 1800 s
/api/news/archive gs://three-ws-news-archive (662k-article JSONL corpus + indexes on GCS) 300 s / 3600 s
/api/coin/liquidations services/liquidation-collector (Binance/Bybit/OKX public liquidation WebSocket streams) 15 s, 503 no-fallback offline

The /api/defi/* handlers have DeFiLlama as their only upstream, so a TTL cache alone would still 502 the moment it expired during an outage. Every DeFiLlama read goes through the shared upstream-fetch helper (one retry on a transient failure, attempts: 2) and each handler keeps its last good payload past the TTL: /api/defi/chain, /api/defi/protocol, /api/defi/yields and /api/defi/hacks hold theirs for six hours, the rest for the 30 minutes that mem-cache's cached() mirrors every value into its last-known-good tier. A response served from that copy carries an x-three-stale: 1 header so the page can say the numbers are not live rather than pass them off as current; the header disappears the moment the loader succeeds again.

Full request/response shapes: api-reference.md → Coin Market Data API.

The proxies live in api/coin/ over the shared api/_lib/coingecko.js fetcher (optional COINGECKO_API_KEY env lifts the public rate limit; everything works key-free). Payloads are slimmed server-side — the markets endpoint downsamples sparklines so 100 rows stay light, and coin descriptions are stripped to plain text before they reach the client.

Code map

Piece Location
Markets page pages/coins.html + src/coins-index.js
Detail page pages/coin.html + src/coin-page.js
Heatmap pages/heatmap.html + src/heatmap.js
Fear & Greed pages/fear-greed.html + src/fear-greed.js
Gas tracker pages/gas.html + src/gas.js
Compare pages/compare.html + src/compare.js
Screener / Categories pages/screener.html, pages/categories.html (+ src/*.js, src/*.css)
Category detail pages/category.html + src/category-page.js + src/category-page.css, API api/coin/category.js
Exchanges / Derivatives pages/exchanges.html, pages/derivatives.html (+ src/*.js, src/*.css)
Exchange detail pages/exchange.html + src/exchange-page.js + src/exchange-page.css, API api/coin/exchange.js
Perpetual contract detail pages/derivative.html + src/derivative-page.js + src/derivative-page.css, API api/coin/derivative.js, slug helper src/shared/derivative-slug.js (vendored to api/_lib/derivative-slug.js), venue directory api/_lib/derivative-venues.js
Converter pages/converter.html + src/converter.js + src/converter.css
DeFi / Chains / Stablecoins pages/{defi,chains,stablecoins}.html (+ src/*.js, src/*.css), APIs in api/defi/
DeFi Yields pages/yields.html + src/yields.js + src/yields.css + src/filter-controls.css, API api/defi/yields.js
Protocol detail pages/protocol.html + src/protocol-page.js + src/protocol-page.css, API api/defi/protocol.js
Chain detail pages/chain.html + src/chain-page.js + src/chain-page.css, API api/defi/chain.js
Stablecoin detail pages/stablecoin.html + src/stablecoin-page.js + src/stablecoin-page.css, API api/defi/stablecoin.js
Fees / DEX volumes pages/{fees,dex-volumes}.html (+ src/*.js, src/*.css), APIs api/defi/fees.js, api/defi/dex-volumes.js
Hacks database pages/hacks.html + src/hacks.js + src/hacks.css, API api/defi/hacks.js
Trending pages/markets-trending.html + src/markets-trending.js, API api/coin/trending.js
Markets hub pages/markets.html + src/markets-page.js
Crypto news pages/markets-news.html + src/markets-news.js
News digest pages/news-digest.html + src/news-digest.js, API api/news/digest.js
Article reader pages/news-article.html + src/news-article.js
News archive pages/news-archive.html + src/news-archive.js
News engine + sources api/_lib/news.js + api/_lib/news-sources.js, endpoints in api/news/
Shared news renderers src/shared/news-render.js; table primitives in src/shared/market-table.js
Shared chart embeds src/shared/chart-embeds.js: the third-party embed URLs every chart surface builds from; src/shared/chart-switcher.js: the compact source switcher /trades and Mission Control mount
Shared design system src/coin-pages.css (Inter, Space Grotesk, JetBrains Mono self-hosted in public/fonts/). Colour pairs that clear WCAG AA live here as tokens: --cv-green / --cv-red are the chart and fill hues, --cv-green-text / --cv-red-text the darker shades for body copy on the page surface, and --cv-green-on-tint / --cv-red-on-tint the darker-still shades for text drawn ON a tinted badge fill, where the tint lifts the background. Dark maps every pair to one value; only light needs the split. Use the text or on-tint token whenever the colour is carrying words.
Shared formatters src/shared/coin-format.js — unit-tested in tests/coin-format.test.js
API proxies api/coin/: one file per /api/coin/* endpoint in the table above (detail.js, ohlc.js, pool.js, markets.js, tickers.js, categories.js, category.js, exchanges.js, exchange.js, derivatives.js, derivative.js, rates.js, trending.js, global.js, fear-greed.js, gas.js, news.js, liquidations.js)
Liquidations collector services/liquidation-collector/ — standalone always-on Node service (not a Vercel function)

Routing: vercel.json rewrites /coins, /coin/<id>, /heatmap, /fear-greed, /gas, and /compare to their pages in production; the Vite dev server mirrors each (including the dynamic /coin/:id path). The pre-existing /coin (no id) redirect to /demo/coin is untouched.