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.

docs(markets): document the pair resolver and the perpetual contract page

ni3ab41a7adc22c3
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 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.md
index 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, 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).
+ `/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 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}`).
+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`,