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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(markets): document the pair resolver and the perpetual contract page
ni3ab41a7adc22c3
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex ba1f9d56e..dcc5636f6 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -5076,6 +5076,46 @@ Cached 60s in-process + 5min at the CDN.---+### Pair resolution (pool address to token)++```+GET /api/coin/pair?address=<pool-address>&network=<gecko-network>+```++The inverse of `/api/coin/pool`. Every DEX terminal names a market by its pair+(pool) address, so a link, a widget parameter or an embed arriving from one+carries a pool and no mint, while three.ws keys everything by mint. Hand this+route the pair and it answers with the token that pair trades:++```json+{+ "network": "solana",+ "pair": "CnK82s8exdsK9nwqQ55kd9wcxoA22NwTchZJCBdu8LDa",+ "token": { "address": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump", "name": "three.ws", "symbol": "three" },+ "quote": { "address": "So11111111111111111111111111111111111111112", "name": "Wrapped SOL", "symbol": "SOL" },+ "dex": "meteora",+ "pairName": "three / SOL"+}+```++```bash+curl -s 'https://three.ws/api/coin/pair?address=CnK82s8exdsK9nwqQ55kd9wcxoA22NwTchZJCBdu8LDa'+```++`network` takes the same GeckoTerminal ids as `/api/coin/pool` and defaults to+`solana`; `address` is validated per-network at the boundary. GeckoTerminal+answers first, DexScreener covers a pair it has not indexed yet (which is every+pair in its first minutes, so the fallback is the normal path for a new coin),+and a value served live once rides out an outage from the shared cache. A pool+no source knows is `404` (`no_pair`), a throttle is `429`, an outage is `502`:+nothing is ever invented. Keyless, CORS-open and cached 60s in-process + 5min at+the CDN, because partner pages call it from the browser.++This is what lets `/coin3d` be addressed by pair as well as by mint. See+[Token in 3D, as an embed](./coin3d-embed.md).++---+### Markets table / coin search```@@ -5240,7 +5280,7 @@ Read-only, key-free proxies powering the `/categories`, `/exchanges`,| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `GET /api/coin/categories` | CoinGecko `/coins/categories` | `{ categories: [{ id, name, market_cap, market_cap_change_24h, volume_24h, top_3_coins }] }` || `GET /api/coin/exchanges` | CoinGecko `/exchanges` + `/simple/price` | `{ exchanges: [{ id, name, image, trust_score, trust_score_rank, volume_24h_btc, volume_24h_usd, year_established, country, url }], btc_usd, updated_at }` |-| `GET /api/coin/derivatives` | CoinGecko `/derivatives` | `{ tickers: [{ market, symbol, index_id, price, change_24h, funding_rate, open_interest, volume_24h }], updated_at }` (perpetuals only, top 100 by volume) |+| `GET /api/coin/derivatives` | CoinGecko `/derivatives` | `{ tickers: [{ market, symbol, index_id, venue_id, slug, price, change_24h, funding_rate, open_interest, volume_24h }], updated_at }` (perpetuals only, top 100 by volume; `venue_id` + `slug` address the row's detail page and are null when it could not be resolved) || `GET /api/coin/rates` | CoinGecko `/exchange_rates` | `{ fiats: [{ code, name, unit, per_btc }], updated_at }` (USD first; `per_btc` = units per 1 BTC) || `GET /api/defi/protocols` | DeFiLlama `/protocols` | `{ total_tvl, protocol_count, protocols: [{ name, logo, symbol, category, chains, chain_count, tvl, change_1d, change_7d, mcap }], updated_at }` (CEX category excluded; top 100) || `GET /api/defi/chains` | DeFiLlama `/v2/chains` | `{ total_tvl, chain_count, chains: [{ name, tvl, token_symbol, share_pct }], updated_at }` (top 100) |@@ -5252,6 +5292,79 @@ rates, DeFi), 120 s (exchanges), 60 s (derivatives). No API key required.---+### One perpetual futures contract++`GET /api/coin/derivative?venue=<exchange-id>&symbol=<venue-symbol>`++Everything about a single perpetual contract, powering the+`/derivative/:venue/:symbol` page that every row of `/derivatives` links into.+`venue` is a CoinGecko derivatives-exchange id (`whitebit_futures`,+`binance_futures`); `symbol` is the venue's own contract symbol, matched+case-insensitively.++```bash+curl -s 'https://three.ws/api/coin/derivative?venue=whitebit_futures&symbol=ETH_PERP'+```++```jsonc+{+ "venue": { "id": "whitebit_futures", "name": "WhiteBIT Futures", "image": "…",+ "url": "…", "description": "…", "country": "Lithuania",+ "year_established": 2022, "open_interest_btc": 64373.64,+ "trade_volume_24h_btc": 665505.06, "perpetual_pairs": 398,+ "futures_pairs": 0, "contracts_listed": 398 },+ "contract": { "symbol": "ETH_PERP", "slug": "ETH_PERP", "base": "ETH",+ "target": "USDT", "coin_id": "ethereum", "price": 2580.19,+ "index": 2579.16, "basis_pct": 0.0399, "change_24h": -2.05,+ "funding_rate": 0.01, "funding_apr": 10.95,+ "open_interest_usd": 1155939517.3, "volume_24h_usd": 28360849777.5,+ "volume_24h_base": 10738205.4, "spread_pct": 0.0139,+ "last_traded_at": 1789883477, "trade_url": "…",+ "venue_oi_share_pct": 22.3, "venue_vol_share_pct": 52.95 },+ "index": { "coin_id": "ethereum", "name": "Ethereum", "price_usd": 2577.12, "…": "…" },+ "peers": [ { "venue_id": "binance_futures", "venue_name": "Binance (Futures)",+ "symbol": "ETHUSDT", "slug": "ETHUSDT", "price": 2576.54,+ "funding_rate": 0.0047, "funding_apr": 5.17,+ "open_interest_usd": 6058585141.87, "volume_24h_usd": 6923448365.3,+ "current": false } ],+ "peer_stats": { "venues": 142, "liquid_venues": 113, "liquid_floor_usd": 1000000,+ "funding_min": -0.3333, "funding_max": 1.0, "funding_median": 0.005,+ "funding_spread": 1.3333, "cheapest_long": { "…": "…" },+ "richest_short": { "…": "…" }, "price_dispersion_pct": 2.15,+ "total_open_interest_usd": 45830000000, "oi_share_pct": 2.52,+ "oi_rank": 14, "vol_rank": 1 },+ "venue_contracts": [ { "symbol": "BTC_PERP", "slug": "BTC_PERP", "…": "…" } ],+ "funding_periods_per_year": 1095,+ "updated_at": 1789883500000+}+```++Field notes:++- **`basis_pct` is the contract's premium over its own index** (`(price - index)+ / index`), which is the direction traders read basis in. CoinGecko publishes+ the opposite sign (`index_basis_percentage`), so it is flipped here.+- **`funding_apr` assumes 8h funding intervals** (`funding_rate * 3 * 365`).+ Venues publish their schedules, the upstream feed does not, so the annualized+ figure is an estimate and every surface that renders it says so.+- **`peer_stats.cheapest_long`, `richest_short`, `price_min/max` and+ `price_dispersion_pct` only count venues clearing `liquid_floor_usd` in 24h+ volume.** A dormant book prints the widest funding and the widest price every+ time, and nominating it as somewhere to act would be wrong. Totals, shares and+ ranks still count every venue.+- **`slug` is the path-safe symbol**: venue symbols include `ETH/USDT`, and the+ slash is folded to `~` because a percent-encoded slash is decoded before+ routing and splits the path. See `api/_lib/derivative-slug.js`.++Only the venue read is load-bearing. If the cross-venue feed, the venue+directory or the spot lookup is unavailable, `peers` comes back empty,+`peer_stats` and `index` come back `null`, and the contract itself still+serves. `404 not_found` means the venue does not list that symbol (delisted,+renamed, or expired); `400 bad_request` means the venue id or symbol is+malformed. Cached 30 s client / 60 s CDN.++---+### DeFi yield pools```diff --git a/docs/coin-pages.md b/docs/coin-pages.mdindex da2da3e3d..fd496a70b 100644--- a/docs/coin-pages.md+++ b/docs/coin-pages.md@@ -367,7 +367,8 @@ key-free data" rule:- **`/derivatives`** — perpetual-futures markets: price, funding rate, openinterest, 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).+ `/api/coin/derivatives` (`?view=exchanges` for the venues). Every perp row+ opens a [contract detail page](#derivativevenuesymbol-perpetual-contract-detail).- **`/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`.@@ -399,7 +400,7 @@ key-free data" rule:## Detail pages-Beyond `/coin/:id`, two list surfaces now have their own rich detail pages,+Beyond `/coin/:id`, several list surfaces have their own rich detail pages,reached by clicking a row.### `/exchange/:id` — exchange detail@@ -413,7 +414,55 @@ table of the venue's pairs (each pair deep-linking to `/coin/:id` and to thelive trade page), with price, spread, 24h volume, and trust. Derivatives venuesshow 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}`).+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`](../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@@ -560,6 +609,7 @@ All data is real and fetched at runtime — nothing is hardcoded or sampled:| `/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 |@@ -617,6 +667,7 @@ text before they reach the client.| Category detail | [`pages/category.html`](../pages/category.html) + `src/category-page.js` + `src/category-page.css`, API [`api/coin/category.js`](../api/coin/category.js) || Exchanges / Derivatives | `pages/exchanges.html`, `pages/derivatives.html` (+ `src/*.js`, `src/*.css`) || Exchange detail | [`pages/exchange.html`](../pages/exchange.html) + `src/exchange-page.js` + `src/exchange-page.css`, API [`api/coin/exchange.js`](../api/coin/exchange.js) |+| Perpetual contract detail | [`pages/derivative.html`](../pages/derivative.html) + `src/derivative-page.js` + `src/derivative-page.css`, API [`api/coin/derivative.js`](../api/coin/derivative.js), slug helper [`src/shared/derivative-slug.js`](../src/shared/derivative-slug.js) (vendored to [`api/_lib/derivative-slug.js`](../api/_lib/derivative-slug.js)), venue directory [`api/_lib/derivative-venues.js`](../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/`](../api/defi) || DeFi Yields | [`pages/yields.html`](../pages/yields.html) + `src/yields.js` + `src/yields.css` + [`src/filter-controls.css`](../src/filter-controls.css), API [`api/defi/yields.js`](../api/defi/yields.js) |@@ -634,9 +685,9 @@ text before they reach the client.| News engine + sources | [`api/_lib/news.js`](../api/_lib/news.js) + [`api/_lib/news-sources.js`](../api/_lib/news-sources.js), endpoints in [`api/news/`](../api/news) || Shared news renderers | [`src/shared/news-render.js`](../src/shared/news-render.js); table primitives in [`src/shared/market-table.js`](../src/shared/market-table.js) || Shared chart embeds | [`src/shared/chart-embeds.js`](../src/shared/chart-embeds.js): the third-party embed URLs every chart surface builds from; [`src/shared/chart-switcher.js`](../src/shared/chart-switcher.js): the compact source switcher `/trades` and Mission Control mount |-| Shared design system | [`src/coin-pages.css`](../src/coin-pages.css) (Inter, Space Grotesk, JetBrains Mono self-hosted in `public/fonts/`) |+| Shared design system | [`src/coin-pages.css`](../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`](../src/shared/coin-format.js) — unit-tested in [`tests/coin-format.test.js`](../tests/coin-format.test.js) |-| API proxies | [`api/coin/`](../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`, `rates.js`, `trending.js`, `global.js`, `fear-greed.js`, `gas.js`, `news.js`, `liquidations.js`) |+| API proxies | [`api/coin/`](../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/`](../services/liquidation-collector) — standalone always-on Node service (not a Vercel function) |Routing: `vercel.json` rewrites `/coins`, `/coin/<id>`, `/heatmap`,