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.

fix(exchange): stop serving an empty profile for a derivatives venue CoinGecko keeps a hollow spot record for

ni3a9b3666c1d013
diff --git a/api/coin/exchange.js b/api/coin/exchange.js
index b87ed8178..824d29ff4 100644
--- a/api/coin/exchange.js
+++ b/api/coin/exchange.js
@@ -82,6 +82,15 @@ function shapeSocials(d) {
};
}
+// Both tables are capped at 50 rows and the page tells the reader they are the
+// top 50 "by volume". Upstream does not order them that way (a derivatives
+// venue comes back roughly alphabetically, so the cap kept 0G_PERP and dropped
+// BTC_PERP), so the ranking is done here and the claim is true.
+function byVolumeDesc(tickers, volumeOf) {
+ return [...tickers].sort((a, b) => (volumeOf(b) ?? 0) - (volumeOf(a) ?? 0));
+}
+const usdVolume = (t) => num(t?.converted_volume?.usd);
+
// CoinGecko's `/exchanges/{id}` detail payload omits the normalized 24h volume
// (only the ranked list carries it), so it is enriched best-effort from the
// same `/exchanges` list the /exchanges page uses — shared geckoFetch cache,
@@ -104,7 +113,7 @@ function shapeSpotDetail(id, d, normalized) {
trade_volume_24h_btc_normalized: normalized,
socials: shapeSocials(d),
tickers_count: tickers.length,
- tickers: tickers.slice(0, 50).map(shapeSpotTicker),
+ tickers: byVolumeDesc(tickers, usdVolume).slice(0, 50).map(shapeSpotTicker),
};
}
@@ -129,10 +138,22 @@ function shapeDerivativesDetail(id, d) {
number_of_futures_pairs: num(d.number_of_futures_pairs),
socials: shapeSocials(d),
tickers_count: tickers.length,
- tickers: tickers.slice(0, 50).map(shapeDerivativeTicker),
+ tickers: byVolumeDesc(tickers, usdVolume).slice(0, 50).map(shapeDerivativeTicker),
};
}
+// CoinGecko keeps a stub record in the SPOT namespace for some derivatives
+// venues: `/exchanges/whitebit_futures` answers 200 with zero tickers, zero
+// volume and a zero trust score while `/derivatives/exchanges/whitebit_futures`
+// carries the real venue and its 398 contracts. The 404-driven fallback below
+// therefore never fired for those ids, and the page rendered an empty profile
+// for a venue that is anything but. A spot record holding nothing at all is a
+// miss, not an answer.
+function isHollowSpotDetail(d) {
+ const tickers = Array.isArray(d?.tickers) ? d.tickers : [];
+ return tickers.length === 0 && !num(d?.trade_volume_24h_btc);
+}
+
// Upstream volume points arrive as [ts_ms, "13421.896…"] — strings.
function shapeVolumeChart(raw) {
if (!Array.isArray(raw)) return [];
@@ -189,7 +210,8 @@ export default wrap(async (req, res) => {
]);
const btcUsd = priceRes.status === 'fulfilled' ? priceRes.value : null;
- if (detailRes.status === 'fulfilled') {
+ const spotOk = detailRes.status === 'fulfilled';
+ const serveSpot = () => {
const list = listRes.status === 'fulfilled' && Array.isArray(listRes.value) ? listRes.value : [];
const normalized = num(list.find((e) => e?.id === id)?.trade_volume_24h_btc_normalized);
return json(res, 200, {
@@ -198,13 +220,16 @@ export default wrap(async (req, res) => {
btc_usd: btcUsd,
updated_at: Date.now(),
}, headers);
- }
+ };
+
+ if (spotOk && !isHollowSpotDetail(detailRes.value)) return serveSpot();
- if (detailRes.reason?.status !== 404) {
+ if (!spotOk && detailRes.reason?.status !== 404) {
return error(res, 502, 'upstream_error', 'exchange data is unavailable right now — retry shortly');
}
- // Spot lookup 404'd — derivatives venues live on a separate CG namespace.
+ // Either the spot lookup 404'd or it answered with an empty shell.
+ // Derivatives venues live on a separate CoinGecko namespace.
try {
const raw = await geckoFetch(`/derivatives/exchanges/${id}?include_tickers=unexpired`, {
ttlMs: DETAIL_TTL_MS,
@@ -216,6 +241,10 @@ export default wrap(async (req, res) => {
updated_at: Date.now(),
}, headers);
} catch (err) {
+ // A venue that is empty in the spot namespace and absent from the
+ // derivatives one is still a real venue. Serve the thin record rather
+ // than turning a page that used to load into a 404.
+ if (spotOk) return serveSpot();
if (err?.status === 404) {
return error(res, 404, 'not_found', `no exchange found for "${id}"`);
}
diff --git a/tests/api/exchange-derivatives-fallback.test.js b/tests/api/exchange-derivatives-fallback.test.js
new file mode 100644
index 000000000..51c485cb1
--- /dev/null
+++ b/tests/api/exchange-derivatives-fallback.test.js
@@ -0,0 +1,157 @@
+// /api/coin/exchange: a derivatives venue must not render as an empty profile.
+//
+// CoinGecko keeps a stub record in the SPOT namespace for some derivatives
+// venues. `/exchanges/whitebit_futures` answers 200 with zero tickers, zero
+// volume and a zero trust score, while `/derivatives/exchanges/whitebit_futures`
+// carries the real venue and its several hundred contracts. Because the
+// namespace fallback was driven by a 404, that 200 shell won and
+// /exchange/whitebit_futures showed "No markets to show for this exchange"
+// about a venue clearing hundreds of thousands of BTC a day.
+//
+// These cases pin the recovery and its edges: the shell loses to a real
+// derivatives record, a populated spot record is still preferred over a second
+// lookup, and a venue that is thin in BOTH namespaces still serves rather than
+// regressing a working page into a 404.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../api/_lib/zauth.js', () => ({ instrument: () => {}, drain: async () => {} }));
+vi.mock('../../api/_lib/sentry.js', () => ({ captureException: () => {} }));
+vi.mock('../../api/_lib/rate-limit.js', () => ({
+ limits: { marketDataIp: async () => ({ success: true }) },
+ clientIp: () => '203.0.113.1',
+}));
+vi.mock('../../api/_lib/market-fallbacks.js', () => ({
+ fetchCoinPriceUsdOrNull: async () => 80000,
+}));
+
+const geckoFetch = vi.fn();
+vi.mock('../../api/_lib/coingecko.js', () => ({
+ geckoFetch: (...args) => geckoFetch(...args),
+ htmlToText: (s) => String(s || '').replace(/<[^>]+>/g, ''),
+}));
+
+const handler = (await import('../../api/coin/exchange.js')).default;
+
+const HOLLOW_SPOT = {
+ name: 'Acme Futures',
+ year_established: 2022,
+ country: 'Lithuania',
+ trust_score: 0,
+ trade_volume_24h_btc: 0,
+ tickers: [],
+};
+
+const REAL_DERIVATIVES = {
+ name: 'Acme Futures',
+ open_interest_btc: 64361,
+ trade_volume_24h_btc: '665745.73',
+ number_of_perpetual_pairs: 398,
+ number_of_futures_pairs: 0,
+ // Upstream order, which is roughly alphabetical rather than by size.
+ tickers: [
+ { symbol: '0G_PERP', last: 1, converted_volume: { usd: '1000' } },
+ {
+ symbol: 'ETH_PERP',
+ last: 2578.4,
+ index: 2577.86,
+ funding_rate: 0.01,
+ open_interest_usd: 1_154_998_184,
+ converted_volume: { usd: '28364964045' },
+ bid_ask_spread: 0.000138,
+ },
+ ],
+};
+
+const REAL_SPOT = {
+ name: 'Acme Exchange',
+ trade_volume_24h_btc: 1234,
+ tickers: [{ base: 'BTC', target: 'USDT', converted_last: { usd: 80000 }, converted_volume: { usd: 10 } }],
+};
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ _h: {},
+ setHeader(k, v) {
+ this._h[k.toLowerCase()] = v;
+ },
+ getHeader(k) {
+ return this._h[k.toLowerCase()];
+ },
+ end(body) {
+ this._body = body;
+ },
+ };
+}
+
+async function call(id) {
+ const res = makeRes();
+ await handler({ url: `/api/coin/exchange?id=${id}`, method: 'GET', headers: {} }, res);
+ return { res, body: JSON.parse(res._body) };
+}
+
+const notFound = () => {
+ const err = new Error('CoinGecko 404');
+ err.status = 404;
+ return err;
+};
+
+beforeEach(() => {
+ geckoFetch.mockReset();
+});
+
+describe('GET /api/coin/exchange namespace choice', () => {
+ it('prefers the derivatives record over an empty spot shell', async () => {
+ geckoFetch.mockImplementation(async (path) => {
+ if (path.startsWith('/exchanges/acme_futures/volume_chart')) throw notFound();
+ if (path.startsWith('/exchanges/acme_futures')) return HOLLOW_SPOT;
+ if (path.startsWith('/derivatives/exchanges/acme_futures')) return REAL_DERIVATIVES;
+ if (path.startsWith('/exchanges?')) return [];
+ throw notFound();
+ });
+ const { res, body } = await call('acme_futures');
+ expect(res.statusCode).toBe(200);
+ expect(body.detail.type).toBe('derivatives');
+ expect(body.detail.tickers_count).toBe(2);
+ expect(body.detail.number_of_perpetual_pairs).toBe(398);
+ // The page calls this table the top contracts by volume, so the biggest
+ // one has to lead regardless of the order upstream sent.
+ expect(body.detail.tickers[0].symbol).toBe('ETH_PERP');
+ });
+
+ it('still serves a populated spot venue from the spot namespace', async () => {
+ geckoFetch.mockImplementation(async (path) => {
+ if (path.startsWith('/exchanges/acme/volume_chart')) return [[1, '10']];
+ if (path.startsWith('/exchanges/acme')) return REAL_SPOT;
+ if (path.startsWith('/exchanges?')) return [];
+ throw new Error('derivatives namespace must not be consulted');
+ });
+ const { res, body } = await call('acme');
+ expect(res.statusCode).toBe(200);
+ expect(body.detail.type).toBe('spot');
+ expect(body.detail.tickers_count).toBe(1);
+ });
+
+ it('falls back to the spot shell when neither namespace has anything better', async () => {
+ geckoFetch.mockImplementation(async (path) => {
+ if (path.startsWith('/exchanges/quiet_venue/volume_chart')) throw notFound();
+ if (path.startsWith('/exchanges/quiet_venue')) return HOLLOW_SPOT;
+ if (path.startsWith('/exchanges?')) return [];
+ throw notFound(); // no derivatives record either
+ });
+ const { res, body } = await call('quiet_venue');
+ expect(res.statusCode).toBe(200);
+ expect(body.detail.type).toBe('spot');
+ expect(body.detail.name).toBe('Acme Futures');
+ });
+
+ it('404s an id neither namespace knows', async () => {
+ geckoFetch.mockImplementation(async () => {
+ throw notFound();
+ });
+ const { res, body } = await call('nosuchvenue');
+ expect(res.statusCode).toBe(404);
+ expect(body.error).toBe('not_found');
+ });
+});